3. 特征读写操作API封装：Android/iOS平台原生BluetoothGatt特征读写接口、回调机制

3.1 原理概述

在BLE（Bluetooth Low Energy）应用中，GATT特征（Characteristic）是数据交换的最小单元。Android和iOS平台均提供原生API实现对特征的读写操作，但两者的回调机制和线程模型存在显著差异。核心原理包括：

• 读取操作：客户端（Central）向服务端（Peripheral）请求特征值，服务端通过回调返回数据。
• 写入操作：客户端将数据写入特征，服务端确认接收。写入模式分为带响应（Write with Response）和无响应（Write Without Response）两种。
• 回调机制：Android使用BluetoothGattCallback接口，iOS使用CBPeripheralDelegate协议。所有操作结果通过异步回调通知应用层。

3.2 Android平台API封装与回调实现

3.2.1 核心API与回调接口

Android使用BluetoothGatt类执行读写操作，通过BluetoothGattCallback接收结果。主要方法如下：

3.2.2 封装示例：特征读取

将特征读取封装为独立方法，并通过回调返回结果：

public void readCharacteristic(BluetoothGatt gatt, BluetoothGattCharacteristic characteristic, 
                                final CharacteristicReadCallback callback) {
    if (gatt == null || characteristic == null) {
        callback.onReadFailed("Gatt or characteristic is null");
        return;
    }
    
    boolean success = gatt.readCharacteristic(characteristic);
    if (!success) {
        callback.onReadFailed("readCharacteristic failed immediately");
        return;
    }
    
    // 设置内部回调，在onCharacteristicRead中触发callback
    this.readCallback = callback;
}

private CharacteristicReadCallback readCallback;

// 在BluetoothGattCallback中：
@Override
public void onCharacteristicRead(BluetoothGatt gatt, BluetoothGattCharacteristic characteristic, 
                                  byte[] value, int status) {
    if (status == BluetoothGatt.GATT_SUCCESS) {
        readCallback.onReadSuccess(value);
    } else {
        readCallback.onReadFailed("GATT status: " + status);
    }
}

3.2.3 封装示例：特征写入

支持带响应和无响应两种写入模式：

public void writeCharacteristic(BluetoothGatt gatt, BluetoothGattCharacteristic characteristic, 
                                 byte[] value, int writeType, 
                                 final CharacteristicWriteCallback callback) {
    if (gatt == null || characteristic == null) {
        callback.onWriteFailed("Gatt or characteristic is null");
        return;
    }
    
    // 设置写入值
    characteristic.setValue(value);
    characteristic.setWriteType(writeType); // WRITE_TYPE_DEFAULT 或 WRITE_TYPE_NO_RESPONSE
    
    boolean success = gatt.writeCharacteristic(characteristic);
    if (!success) {
        callback.onWriteFailed("writeCharacteristic failed immediately");
        return;
    }
    
    this.writeCallback = callback;
}

// 在BluetoothGattCallback中：
@Override
public void onCharacteristicWrite(BluetoothGatt gatt, BluetoothGattCharacteristic characteristic, 
                                   int status) {
    if (status == BluetoothGatt.GATT_SUCCESS) {
        writeCallback.onWriteSuccess();
    } else {
        writeCallback.onWriteFailed("GATT status: " + status);
    }
}

3.3 iOS平台API封装与回调实现

3.3.1 核心API与回调协议

iOS使用CBPeripheral类执行读写操作，通过CBPeripheralDelegate接收结果。主要方法如下：

3.3.2 封装示例：特征读取

将读取操作封装到Manager类中，并通过闭包回调：

class BLEManager: NSObject, CBPeripheralDelegate {
    private var readCompletion: ((Data?, Error?) -> Void)?
    
    func readCharacteristicFromPeripheral(_ peripheral: CBPeripheral, 
                                           characteristic: CBCharacteristic,
                                           completion: @escaping (Data?, Error?) -> Void) {
        peripheral.delegate = self
        self.readCompletion = completion
        peripheral.readValue(for: characteristic)
    }
    
    // CBPeripheralDelegate
    func peripheral(_ peripheral: CBPeripheral, 
                    didUpdateValueFor characteristic: CBCharacteristic, 
                    error: Error?) {
        guard let completion = readCompletion else { return }
        completion(characteristic.value, error)
        readCompletion = nil // 一次性回调
    }
}

3.3.3 封装示例：特征写入

支持两种写入类型，带响应方式需要处理回调：

func writeCharacteristicToPeripheral(_ peripheral: CBPeripheral,
                                      characteristic: CBCharacteristic,
                                      data: Data,
                                      type: CBCharacteristicWriteType,
                                      completion: ((Error?) -> Void)? = nil) {
    peripheral.delegate = self
    if type == .withResponse {
        self.writeCompletion = completion
        peripheral.writeValue(data, for: characteristic, type: .withResponse)
    } else {
        // 无响应模式，直接写入，无回调
        peripheral.writeValue(data, for: characteristic, type: .withoutResponse)
        completion?(nil)
    }
}

// CBPeripheralDelegate
func peripheral(_ peripheral: CBPeripheral, 
                didWriteValueFor characteristic: CBCharacteristic, 
                error: Error?) {
    guard let completion = writeCompletion else { return }
    completion(error)
    writeCompletion = nil
}

3.4 跨平台API对比

3.5 内联SVG流程图：特征读写回调流程

3.6 调试与部署注意事项

• Android调试：启用Bluetooth HCI Snoop Log，使用/sdcard/btsnoop_hci.log捕获原始BLE数据包，结合Wireshark分析读写交互。
• iOS调试：使用Xcode的Core Bluetooth调试模板，或通过PacketLogger.app捕获蓝牙HCI日志。
• 特征并发读写：避免同时向同一特征发起多个读写操作，可能导致状态混乱。建议维护操作队列，顺序执行。
• MTU协商：写入大数据前，先通过negotiateMTU协商最大字节数，避免写入长度超过设备支持范围。

3.7 常见错误与稳定性优化