Android蓝牙开发兼容性指南：新旧API差异与解决方案

1. 为什么需要关注Android蓝牙的旧版本兼容性

在Android开发中，蓝牙功能一直是设备间通信的重要手段。但Android系统的碎片化问题导致不同版本间的蓝牙API存在显著差异。根据最新统计，目前仍有约15%的Android设备运行在Android 6.0（API 23）及以下版本，这些设备使用的都是传统的蓝牙API。

我曾在实际项目中遇到过这样的情况：一个蓝牙打印功能在Android 10设备上运行良好，但在Android 5.0设备上完全无法连接。经过排查发现，问题出在蓝牙权限的声明方式上——新版本使用运行时权限，而旧版本需要在Manifest中静态声明。这种兼容性问题如果不提前预防，往往会在项目后期造成大量返工。

2. 新旧版本蓝牙API的核心差异解析

2.1 权限系统的演变

Android 6.0引入的运行时权限系统对蓝牙开发影响最大。在旧版本中，只需要在AndroidManifest.xml中声明：

xml复制<uses-permission android:name="android.permission.BLUEToOTH" />
<uses-permission android:name="android.permission.BLUEToOTH_ADMIN" />

而从Android 6.0开始，还需要在运行时请求以下权限：

java复制if (ContextCompat.checkSelfPermission(this, Manifest.permission.ACCESS_FINE_LOCATION) 
    != PackageManager.PERMISSION_GRANTED) {
    ActivityCompat.requestPermissions(this, 
        new String[]{Manifest.permission.ACCESS_FINE_LOCATION}, 
        REQUEST_LOCATION_PERMISSION);
}

注意：即使你的应用不需要位置信息，从Android 6.0开始，扫描蓝牙设备也必须请求ACCESS_FINE_LOCATION权限，这是很多开发者容易忽略的点。

2.2 蓝牙设备发现机制的变化

在Android 4.3及以下版本，设备发现使用的是startDiscovery()方法：

java复制BluetoothAdapter.getDefaultAdapter().startDiscovery();

而从Android 5.0开始，推荐使用BluetoothLeScanner进行低功耗蓝牙扫描：

java复制BluetoothLeScanner scanner = BluetoothAdapter.getDefaultAdapter().getBluetoothLeScanner();
scanner.startScan(scanCallback);

3. 实现向后兼容的蓝牙连接方案

3.1 版本检测与分支处理

首先需要检测设备运行的Android版本：

java复制if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
    // 使用新API
    setupModernBluetooth();
} else {
    // 使用兼容API
    setupLegacyBluetooth();
}

3.2 统一封装蓝牙操作类

建议创建一个BluetoothCompatHelper类来封装版本差异：

java复制public class BluetoothCompatHelper {
    public static void startScan(Context context, ScanCallback callback) {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
            BluetoothLeScanner scanner = BluetoothAdapter.getDefaultAdapter()
                .getBluetoothLeScanner();
            scanner.startScan(callback);
        } else {
            BluetoothAdapter.getDefaultAdapter().startDiscovery();
        }
    }
    
    // 其他兼容方法...
}

3.3 处理不同的回调机制

旧版本使用BroadcastReceiver接收扫描结果：

java复制private final BroadcastReceiver receiver = new BroadcastReceiver() {
    public void onReceive(Context context, Intent intent) {
        String action = intent.getAction();
        if (BluetoothDevice.ACTION_FOUND.equals(action)) {
            BluetoothDevice device = intent.getParcelableExtra(BluetoothDevice.EXTRA_DEVICE);
            // 处理发现的设备
        }
    }
};

新版本则使用ScanCallback：

java复制private ScanCallback scanCallback = new ScanCallback() {
    @Override
    public void onScanResult(int callbackType, ScanResult result) {
        BluetoothDevice device = result.getDevice();
        // 处理发现的设备
    }
};

4. 实际开发中的兼容性陷阱与解决方案

4.1 蓝牙配对方式的差异

在Android 4.2及以下版本，配对需要手动调用createBond()方法：

java复制device.createBond();

而从Android 4.3开始，可以通过BluetoothDevice.EXTRA_PAIRING_VARIANT获取配对方式，并自动处理不同配对类型（PIN码、密码等）。

4.2 蓝牙Socket连接的线程问题

无论是新老版本，蓝牙Socket操作都必须在子线程中执行。一个常见的错误是在主线程直接调用connect()：

java复制// 错误示例 - 会导致ANR
BluetoothSocket socket = device.createRfcommSocketToServiceRecord(MY_UUID);
socket.connect();  // 可能阻塞主线程

正确的做法是使用AsyncTask或HandlerThread：

java复制new AsyncTask<Void, Void, Void>() {
    @Override
    protected Void doInBackground(Void... params) {
        try {
            BluetoothSocket socket = device.createRfcommSocketToServiceRecord(MY_UUID);
            socket.connect();
            // 连接成功后的处理
        } catch (IOException e) {
            e.printStackTrace();
        }
        return null;
    }
}.execute();

4.3 不同Android版本的UUID处理

在Android 4.3及以下版本，某些标准UUID需要特殊处理。例如SPP（串口协议）的标准UUID：

java复制// 旧版本可能需要这样处理
UUID MY_UUID = UUID.fromString("00001101-0000-1000-8000-00805F9B34FB");

而在新版本中，可以使用预定义的常量：

java复制UUID MY_UUID = BluetoothAdapter.SERIAL_PORT_PROFILE;

5. 测试策略与真机验证

5.1 建立多版本测试矩阵

建议至少覆盖以下Android版本进行测试：

• Android 4.4 (API 19)
• Android 5.0 (API 21)
• Android 6.0 (API 23)
• Android 8.0 (API 26)
• 最新版本

5.2 使用Android模拟器的限制

需要注意的是，Android模拟器对蓝牙的支持有限：

• 模拟器无法模拟真实的蓝牙硬件
• 部分蓝牙API在模拟器上行为与真机不同
• 建议始终在真机上进行最终测试

5.3 常见问题排查清单

当蓝牙连接出现问题时，可以按照以下步骤排查：

1. 检查蓝牙是否已开启
2. 验证必要的权限是否已授予
3. 确认设备是否在可发现模式
4. 检查UUID是否正确匹配
5. 查看系统日志中的蓝牙相关错误
6. 在不同Android版本设备上复现问题

6. 性能优化与用户体验提升

6.1 蓝牙扫描的最佳实践

长时间持续扫描会显著增加功耗，建议：

• 扫描时间不超过12秒（Android官方建议）
• 扫描间隔至少为扫描时间的2倍
• 在界面不可见时停止扫描

java复制// 示例：周期性扫描
private void startPeriodicScan() {
    handler.postDelayed(new Runnable() {
        @Override
        public void run() {
            if (scanning) {
                stopScan();
            }
            startScan();
            handler.postDelayed(this, SCAN_PERIOD * 2);
        }
    }, SCAN_PERIOD);
}

6.2 连接超时与重试机制

为蓝牙连接添加合理的超时和重试：

java复制private boolean connectWithTimeout(BluetoothSocket socket, int timeoutMs) {
    try {
        socket.connect();  // 阻塞调用
        return true;
    } catch (IOException e) {
        try {
            Thread.sleep(timeoutMs);
            socket.close();
        } catch (Exception ex) {
            ex.printStackTrace();
        }
        return false;
    }
}

6.3 低功耗蓝牙(BLE)的兼容处理

对于同时支持经典蓝牙和BLE的设备，需要额外注意：

• Android 4.3才引入BLE支持
• BLE的API与经典蓝牙完全不同
• 需要检查设备是否支持BLE：

java复制boolean isBLESupported = getPackageManager().hasSystemFeature(
    PackageManager.FEATURE_BLUETOOTH_LE);

7. 第三方库的选择与比较

7.1 常用蓝牙兼容库对比

7.2 自行封装 vs 使用第三方库

选择自行封装的情况：

• 应用只需要基本蓝牙功能
• 需要严格控制APK大小
• 有特殊的安全要求

选择第三方库的情况：

• 需要快速实现复杂功能
• 团队缺乏蓝牙开发经验
• 需要长期维护的项目

7.3 引入第三方库的注意事项

1. 检查库的活跃度（最后更新时间、issue处理速度）
2. 评估方法数（避免65K限制）
3. 测试在不同Android版本上的行为
4. 确认许可证是否兼容

8. 未来兼容性考虑

虽然本文主要讨论向后兼容，但也要为未来做好准备：

1. Android 12引入的新蓝牙权限：

xml复制<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" /> 

2. 逐步淘汰传统蓝牙API的趋势
3. 关注Google的Jetpack Bluetooth库发展

在实际项目中，我通常会创建一个BluetoothCompat层，将所有版本相关的代码隔离在这一层中。这样当需要支持新API时，只需修改这一层的实现，而不会影响业务逻辑代码。这种架构设计在长期维护的项目中特别有价值。