簡(jiǎn)介本資源是一套面向Android開發(fā)者與移動(dòng)通信學(xué)習(xí)者的Kotlin藍(lán)牙開發(fā)實(shí)戰(zhàn)示例聚焦短距離無線通信場(chǎng)景解決藍(lán)牙設(shè)備發(fā)現(xiàn)、配對(duì)、數(shù)據(jù)傳輸?shù)群诵墓δ艿墓こ袒瘜?shí)現(xiàn)問題適用于具備基礎(chǔ)Android開發(fā)能力的學(xué)習(xí)者進(jìn)階實(shí)踐。壓縮包共326個(gè)文件總大小24.36MB涵蓋62個(gè)Kotlin源文件含協(xié)程與擴(kuò)展函數(shù)等現(xiàn)代語法實(shí)踐、34個(gè)Java文件保障Java/Kotlin混合項(xiàng)目兼容性、133個(gè)XML布局與配置文件支撐UI與Manifest定義、17個(gè)AAR庫含多個(gè)版本ppblutoothkit藍(lán)牙SDK體現(xiàn)迭代適配過程以及14個(gè)SO本地庫支撐底層藍(lán)牙協(xié)議棧調(diào)用。已有423人學(xué)習(xí)下載資源結(jié)構(gòu)清晰、模塊完整提供從權(quán)限申請(qǐng)、掃描連接到數(shù)據(jù)收發(fā)的全鏈路代碼參考并附帶Gradle構(gòu)建配置、Markdown說明文檔及多分辨率PNG資源便于快速理解架構(gòu)設(shè)計(jì)與移植集成。1. 項(xiàng)目緣起為什么我們需要一個(gè)Kotlin藍(lán)牙庫示例如果你是一名Android開發(fā)者最近在項(xiàng)目中需要集成藍(lán)牙功能尤其是低功耗藍(lán)牙BLE你大概率會(huì)和我有同樣的感受官方文檔的示例代碼要么是Java的要么是過時(shí)的要么就是過于零散難以直接上手。更別提那些隱藏在BluetoothLeGatt示例項(xiàng)目中混雜著AsyncTask和Handler的老舊代碼了。當(dāng)你想用現(xiàn)代、簡(jiǎn)潔的Kotlin來重構(gòu)時(shí)會(huì)發(fā)現(xiàn)網(wǎng)上能找到的要么是零碎的代碼片段要么是封裝得過于復(fù)雜、難以理解的第三方庫。這就是我決定動(dòng)手整理并開源一個(gè)“基于Kotlin語言的藍(lán)牙庫示例程序Android版設(shè)計(jì)源碼”的直接原因。這個(gè)項(xiàng)目不是一個(gè)功能大而全的通用藍(lán)牙框架它的核心定位非常明確一個(gè)清晰、現(xiàn)代、可直接復(fù)用的Kotlin BLE操作模板。它剝離了業(yè)務(wù)邏輯專注于展示在Android平臺(tái)上如何使用Kotlin協(xié)程、Flow等現(xiàn)代語言特性優(yōu)雅、安全地處理藍(lán)牙掃描、連接、數(shù)據(jù)讀寫、通知監(jiān)聽等核心流程。在開始之前我們先明確一下這個(gè)示例程序的價(jià)值。它不僅僅是幾行代碼而是解決了一系列實(shí)際開發(fā)中的痛點(diǎn)架構(gòu)清晰采用MVVM模式或更準(zhǔn)確的一個(gè)簡(jiǎn)化的MVI思想分離了UI、業(yè)務(wù)邏輯和藍(lán)牙底層操作便于理解和擴(kuò)展?，F(xiàn)代Kotlin實(shí)踐全程使用Kotlin編寫大量運(yùn)用協(xié)程處理異步回調(diào)用StateFlow管理UI狀態(tài)避免了回調(diào)地獄和內(nèi)存泄漏。生命周期安全與Android的Lifecycle深度集成確保藍(lán)牙操作在頁面銷毀時(shí)自動(dòng)清理杜絕資源泄露。錯(cuò)誤處理完備對(duì)藍(lán)牙權(quán)限、位置服務(wù)、藍(lán)牙開關(guān)狀態(tài)、連接超時(shí)、服務(wù)發(fā)現(xiàn)失敗等常見異常場(chǎng)景進(jìn)行了封裝和處理。可拔插設(shè)計(jì)核心的藍(lán)牙管理器BluetoothManager接口化方便你替換為其他藍(lán)牙庫如RxAndroidBle或進(jìn)行單元測(cè)試。這個(gè)項(xiàng)目適合所有正在或即將進(jìn)行Android藍(lán)牙開發(fā)的同行無論你是想快速搭建一個(gè)BLE功能原型還是想學(xué)習(xí)如何用Kotlin現(xiàn)代化地處理硬件交互它都能提供一個(gè)扎實(shí)的起點(diǎn)。接下來我將從環(huán)境搭建開始帶你一步步拆解這個(gè)示例程序的設(shè)計(jì)與實(shí)現(xiàn)。2. 環(huán)境準(zhǔn)備與項(xiàng)目結(jié)構(gòu)概覽在深入代碼之前我們需要把環(huán)境搭建好。這個(gè)示例基于Android Studio進(jìn)行開發(fā)對(duì)SDK版本和依賴庫有明確要求。2.1 開發(fā)環(huán)境與依賴配置首先確保你的build.gradle (Module: app)文件中的配置如下。這里的關(guān)鍵是Kotlin協(xié)程和Lifecycle相關(guān)庫它們是實(shí)現(xiàn)異步操作和生命周期感知的基石。android { compileSdk 34 defaultConfig { minSdk 21 // BLE需要API 18但為了更好的權(quán)限模型和現(xiàn)代API建議21 targetSdk 34 ... } buildFeatures { viewBinding true // 或使用Compose這里以ViewBinding為例 } kotlinOptions { jvmTarget 1.8 } } dependencies { implementation androidx.core:core-ktx:1.12.0 implementation androidx.appcompat:appcompat:1.6.1 implementation com.google.android.material:material:1.11.0 implementation androidx.constraintlayout:constraintlayout:2.1.4 implementation androidx.lifecycle:lifecycle-viewmodel-ktx:2.7.0 implementation androidx.lifecycle:lifecycle-runtime-ktx:2.7.0 implementation androidx.lifecycle:lifecycle-livedata-ktx:2.7.0 implementation org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3 implementation org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3 // 測(cè)試依賴 testImplementation junit:junit:4.13.2 androidTestImplementation androidx.test.ext:junit:1.1.5 androidTestImplementation androidx.test.espresso:espresso-core:3.5.1 }注意這里沒有引入任何第三方藍(lán)牙庫。我們直接使用Android官方的android.bluetooth包目的是為了讓你透徹理解原生API的工作機(jī)制。在實(shí)際大型項(xiàng)目中你可能會(huì)選擇RxAndroidBle等庫來簡(jiǎn)化操作但掌握底層原理是有效使用和調(diào)試高級(jí)庫的前提。2.2 項(xiàng)目模塊與包結(jié)構(gòu)設(shè)計(jì)一個(gè)清晰的項(xiàng)目結(jié)構(gòu)是代碼可維護(hù)性的第一道保障。本示例采用了按功能分層的包結(jié)構(gòu)而非按類型如把所有Activity放一起。以下是核心的包目錄com.example.blekotlindemo/ ├── ui/ │ ├── MainActivity.kt // 主界面負(fù)責(zé)UI展示和用戶交互 │ └── DeviceListFragment.kt // 設(shè)備列表Fragment ├── viewmodel/ │ └── BleViewModel.kt // 持有和處理藍(lán)牙相關(guān)狀態(tài)與邏輯 ├── bluetooth/ │ ├── manager/ │ │ ├── IBluetoothManager.kt // 藍(lán)牙管理器接口 │ │ └── BluetoothManagerImpl.kt // 藍(lán)牙管理器具體實(shí)現(xiàn)核心 │ ├── model/ │ │ ├── BleDevice.kt // 藍(lán)牙設(shè)備數(shù)據(jù)類 │ │ ├── ConnectionState.kt // 連接狀態(tài)枚舉類 │ │ └── GattAction.kt // GATT操作類型讀、寫、通知等 │ └── callback/ │ └── SimplifiedBluetoothGattCallback.kt // 簡(jiǎn)化的GATT回調(diào)封裝 ├── utils/ │ ├── PermissionsHelper.kt // 權(quán)限請(qǐng)求工具 │ └── Extensions.kt // Kotlin擴(kuò)展函數(shù) └── di/ (可選) └── 依賴注入相關(guān)設(shè)置如使用Koin或Hilt這種結(jié)構(gòu)的好處一目了然ui層只關(guān)心界面和用戶輸入viewmodel作為中間層將bluetooth層的復(fù)雜操作轉(zhuǎn)換為UI可觀察的簡(jiǎn)單狀態(tài)bluetooth層是真正的引擎負(fù)責(zé)所有與系統(tǒng)藍(lán)牙API的交互。model包定義了數(shù)據(jù)傳輸對(duì)象callback包處理系統(tǒng)回調(diào)的轉(zhuǎn)換。當(dāng)你需要替換藍(lán)牙實(shí)現(xiàn)或修改UI時(shí)影響范圍被嚴(yán)格控制在了單個(gè)模塊內(nèi)。3. 核心實(shí)現(xiàn)從權(quán)限到連接的完整鏈路一切就緒我們進(jìn)入最核心的部分。藍(lán)牙開發(fā)的第一步永遠(yuǎn)不是打開藍(lán)牙而是處理權(quán)限。Android的權(quán)限模型在不斷演進(jìn)處理BLE需要格外小心。3.1 運(yùn)行時(shí)權(quán)限與藍(lán)牙開關(guān)檢測(cè)從Android 12 (API 31) 開始藍(lán)牙掃描需要BLUETOOTH_SCAN權(quán)限并且該權(quán)限可以是neverForLocation的這解決了長(zhǎng)期以來BLE掃描必須請(qǐng)求精確定位權(quán)限的尷尬。我們的PermissionsHelper需要智能地處理不同API版本。object PermissionsHelper { // 定義所需的權(quán)限數(shù)組 RequiresApi(Build.VERSION_CODES.S) fun getBlePermissions(): ArrayString arrayOf( Manifest.permission.BLUETOOTH_SCAN, Manifest.permission.BLUETOOTH_CONNECT ) SuppressLint(InlinedApi) fun getBlePermissionsLegacy(): ArrayString arrayOf( Manifest.permission.ACCESS_FINE_LOCATION, // API 31 需要位置權(quán)限 Manifest.permission.BLUETOOTH, Manifest.permission.BLUETOOTH_ADMIN ) fun checkAndRequestBlePermissions(activity: FragmentActivity): Boolean { val permissions if (Build.VERSION.SDK_INT Build.VERSION_CODES.S) { getBlePermissions() } else { getBlePermissionsLegacy() } val deniedPermissions permissions.filter { ContextCompat.checkSelfPermission(activity, it) ! PackageManager.PERMISSION_GRANTED }.toTypedArray() return if (deniedPermissions.isNotEmpty()) { activity.requestPermissions(deniedPermissions, REQUEST_CODE_BLE_PERMISSIONS) false } else { true } } }在MainActivity中我們這樣使用它c(diǎn)lass MainActivity : AppCompatActivity() { private lateinit var viewModel: BleViewModel override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) // ... 初始化UI和ViewModel lifecycleScope.launch { repeatOnLifecycle(Lifecycle.State.STARTED) { // 監(jiān)聽權(quán)限檢查結(jié)果 viewModel.permissionGranted.collect { granted - if (granted) { checkBluetoothAndStartScan() } else { showPermissionRationale() } } } } } private fun checkBluetoothAndStartScan() { val bluetoothAdapter: BluetoothAdapter? BluetoothAdapter.getDefaultAdapter() when { bluetoothAdapter null - { // 設(shè)備不支持藍(lán)牙 showError(設(shè)備不支持藍(lán)牙) } !bluetoothAdapter.isEnabled - { // 請(qǐng)求用戶打開藍(lán)牙 val enableBtIntent Intent(BluetoothAdapter.ACTION_REQUEST_ENABLE) startActivityForResult(enableBtIntent, REQUEST_ENABLE_BT) } else - { // 一切就緒通知ViewModel開始掃描 viewModel.startScan() } } } override fun onRequestPermissionsResult(requestCode: Int, permissions: Arrayout String, grantResults: IntArray) { super.onRequestPermissionsResult(requestCode, permissions, grantResults) if (requestCode REQUEST_CODE_BLE_PERMISSIONS) { val allGranted grantResults.all { it PackageManager.PERMISSION_GRANTED } viewModel.onPermissionResult(allGranted) } } }這里的關(guān)鍵點(diǎn)在于我們將權(quán)限狀態(tài)和藍(lán)牙開關(guān)狀態(tài)都通過ViewModel中的StateFlow來管理。UIActivity/Fragment只負(fù)責(zé)發(fā)起請(qǐng)求和展示結(jié)果狀態(tài)變化的邏輯集中在ViewModel中這使得代碼更易于測(cè)試也避免了在生命周期復(fù)雜的Activity中埋下狀態(tài)管理的隱患。3.2 藍(lán)牙掃描的現(xiàn)代化封裝傳統(tǒng)的藍(lán)牙掃描需要注冊(cè)一個(gè)BroadcastReceiver來接收BluetoothDevice.ACTION_FOUND廣播對(duì)于BLE則使用BluetoothLeScanner.startScan(scanCallback)。這些API都是基于回調(diào)的在Kotlin協(xié)程時(shí)代我們可以將其封裝成更易用的Flow。在BluetoothManagerImpl中我們實(shí)現(xiàn)掃描功能class BluetoothManagerImpl Inject constructor( private val context: Context, private val scope: CoroutineScope ) : IBluetoothManager { private val _scanResults MutableStateFlowListBleDevice(emptyList()) override val scanResults: StateFlowListBleDevice _scanResults.asStateFlow() private var bluetoothLeScanner: BluetoothLeScanner? null private var scanCallback: ScanCallback? null override fun startScan() { val bluetoothAdapter: BluetoothAdapter? BluetoothAdapter.getDefaultAdapter() bluetoothLeScanner bluetoothAdapter?.bluetoothLeScanner if (bluetoothLeScanner null) { _scanError.tryEmit(藍(lán)牙適配器不可用) return } // 停止之前的掃描如果存在 stopScan() // 清空舊結(jié)果 _scanResults.value emptyList() // 配置掃描過濾器這里不過濾掃描所有設(shè)備 val filters listOfScanFilter() // 空列表表示不過濾 val settings ScanSettings.Builder() .setScanMode(ScanSettings.SCAN_MODE_LOW_LATENCY) // 低延遲模式發(fā)現(xiàn)設(shè)備快但耗電 .build() scanCallback object : ScanCallback() { override fun onScanResult(callbackType: Int, result: ScanResult?) { result?.device?.let { device - val bleDevice BleDevice( name device.name ?: Unknown, address device.address, rssi result.rssi ) // 更新掃描結(jié)果這里簡(jiǎn)單去重按地址 _scanResults.update { list - if (list.any { it.address bleDevice.address }) { list.map { if (it.address bleDevice.address) bleDevice else it } } else { list bleDevice } } } } override fun onScanFailed(errorCode: Int) { _scanError.tryEmit(掃描失敗錯(cuò)誤碼: $errorCode) } } try { bluetoothLeScanner?.startScan(filters, settings, scanCallback) _isScanning.value true } catch (e: SecurityException) { _scanError.tryEmit(無藍(lán)牙掃描權(quán)限: ${e.message}) } catch (e: IllegalStateException) { _scanError.tryEmit(藍(lán)牙適配器狀態(tài)異常: ${e.message}) } } override fun stopScan() { scanCallback?.let { callback - try { bluetoothLeScanner?.stopScan(callback) } catch (e: Exception) { Log.e(BluetoothManager, 停止掃描時(shí)出錯(cuò), e) } } scanCallback null _isScanning.value false } }在ViewModel中我們暴露一個(gè)簡(jiǎn)單的狀態(tài)給UIclass BleViewModel Inject constructor( private val bluetoothManager: IBluetoothManager ) : ViewModel() { // UI可以直接觀察這些StateFlow val scanResults: StateFlowListBleDevice bluetoothManager.scanResults val isScanning: StateFlowBoolean bluetoothManager.isScanning val connectionState: StateFlowConnectionState bluetoothManager.connectionState fun startScan() { viewModelScope.launch { bluetoothManager.startScan() } } fun stopScan() { viewModelScope.launch { bluetoothManager.stopScan() } } }這樣在Fragment中我們只需要監(jiān)聽scanResults這個(gè)StateFlow列表就會(huì)自動(dòng)更新。這種響應(yīng)式編程模式極大地簡(jiǎn)化了UI邏輯。3.3 設(shè)備連接、服務(wù)發(fā)現(xiàn)與數(shù)據(jù)通信掃描到設(shè)備后下一步就是連接。這是BLE開發(fā)中最復(fù)雜的一環(huán)涉及BluetoothGatt的一系列異步回調(diào)。我們的目標(biāo)是將其封裝成順序執(zhí)行的協(xié)程掛起函數(shù)。首先在IBluetoothManager接口中定義連接函數(shù)interface IBluetoothManager { suspend fun connect(deviceAddress: String): ResultUnit fun disconnect() suspend fun writeCharacteristic(serviceUuid: UUID, characteristicUuid: UUID, data: ByteArray): ResultUnit suspend fun readCharacteristic(serviceUuid: UUID, characteristicUuid: UUID): ResultByteArray fun enableNotification(serviceUuid: UUID, characteristicUuid: UUID, enable: Boolean) // ... 其他狀態(tài)Flow }在BluetoothManagerImpl中實(shí)現(xiàn)connect函數(shù)。這里的關(guān)鍵是使用suspendCancellableCoroutine將回調(diào)轉(zhuǎn)換為協(xié)程override suspend fun connect(deviceAddress: String): ResultUnit suspendCancellableCoroutine { continuation - val bluetoothAdapter BluetoothAdapter.getDefaultAdapter() val device bluetoothAdapter?.getRemoteDevice(deviceAddress) if (device null) { continuation.resume(Result.failure(IllegalArgumentException(設(shè)備地址無效或未找到設(shè)備))) returnsuspendCancellableCoroutine } // 先斷開之前的連接如果有 disconnectGatt() _connectionState.value ConnectionState.CONNECTING currentDeviceAddress deviceAddress // 注意這里使用 autoConnect false 以快速連接實(shí)際可根據(jù)場(chǎng)景調(diào)整 val gatt if (Build.VERSION.SDK_INT Build.VERSION_CODES.M) { device.connectGatt(context, false, gattCallback, BluetoothDevice.TRANSPORT_LE) } else { device.connectGatt(context, false, gattCallback) } this.bluetoothGatt gatt // 設(shè)置一個(gè)連接超時(shí) scope.launch { delay(CONNECTION_TIMEOUT_MS) if (_connectionState.value ConnectionState.CONNECTING) { disconnectGatt() continuation.resume(Result.failure(TimeoutException(連接超時(shí)))) } } // 在GattCallback中處理連接結(jié)果 gattCallback.onConnected { gatt - _connectionState.value ConnectionState.CONNECTED continuation.resume(Result.success(Unit)) } gattCallback.onConnectionFailed { exception - _connectionState.value ConnectionState.DISCONNECTED continuation.resume(Result.failure(exception ?: Exception(連接失敗))) } }這里的gattCallback是我們封裝的SimplifiedBluetoothGattCallback它內(nèi)部處理了onConnectionStateChange、onServicesDiscovered、onCharacteristicRead/Write、onCharacteristicChanged等所有回調(diào)并將它們轉(zhuǎn)換為更易處理的事件或掛起函數(shù)的續(xù)體continuation。服務(wù)發(fā)現(xiàn)通常在連接成功后自動(dòng)或手動(dòng)觸發(fā)。在我們的設(shè)計(jì)中連接成功后會(huì)自動(dòng)開始發(fā)現(xiàn)服務(wù)// 在 SimplifiedBluetoothGattCallback 的 onConnectionStateChange 中 override fun onConnectionStateChange(gatt: BluetoothGatt, status: Int, newState: Int) { when (newState) { BluetoothProfile.STATE_CONNECTED - { // 連接成功開始發(fā)現(xiàn)服務(wù) gatt.discoverServices() onConnected?.invoke(gatt) } BluetoothProfile.STATE_DISCONNECTED - { onDisconnected?.invoke() gatt.close() } } }發(fā)現(xiàn)服務(wù)成功后我們就可以進(jìn)行讀寫操作了。以寫特征值為例override suspend fun writeCharacteristic(serviceUuid: UUID, characteristicUuid: UUID, data: ByteArray): ResultUnit suspendCancellableCoroutine { continuation - val gatt bluetoothGatt if (gatt null || _connectionState.value ! ConnectionState.CONNECTED) { continuation.resume(Result.failure(IllegalStateException(未連接或Gatt對(duì)象為空))) returnsuspendCancellableCoroutine } val service gatt.getService(serviceUuid) val characteristic service?.getCharacteristic(characteristicUuid) if (characteristic null) { continuation.resume(Result.failure(IllegalArgumentException(未找到指定的服務(wù)或特征))) returnsuspendCancellableCoroutine } // 設(shè)置特征值并指定寫類型 characteristic.value data // 根據(jù)特征屬性決定寫入類型 val writeType when { characteristic.properties and BluetoothGattCharacteristic.PROPERTY_WRITE_NO_RESPONSE 0 - { BluetoothGattCharacteristic.WRITE_TYPE_NO_RESPONSE } characteristic.properties and BluetoothGattCharacteristic.PROPERTY_WRITE 0 - { BluetoothGattCharacteristic.WRITE_TYPE_DEFAULT } else - { continuation.resume(Result.failure(UnsupportedOperationException(該特征不支持寫入))) returnsuspendCancellableCoroutine } } characteristic.writeType writeType // 將回調(diào)與本次掛起關(guān)聯(lián)起來 gattCallback.pendingWriteContinuation continuation if (!gatt.writeCharacteristic(characteristic)) { gattCallback.pendingWriteContinuation null continuation.resume(Result.failure(IOException(寫入請(qǐng)求發(fā)送失敗))) } }在SimplifiedBluetoothGattCallback的onCharacteristicWrite回調(diào)中我們需要取出對(duì)應(yīng)的continuation并恢復(fù)它override fun onCharacteristicWrite(gatt: BluetoothGatt, characteristic: BluetoothGattCharacteristic, status: Int) { val cont pendingWriteContinuation pendingWriteContinuation null if (status BluetoothGatt.GATT_SUCCESS) { cont?.resume(Result.success(Unit)) } else { cont?.resume(Result.failure(IOException(寫入失敗狀態(tài)碼: $status))) } }通過這種方式我們將所有異步、基于回調(diào)的藍(lán)牙API封裝成了線性的、可讀性極強(qiáng)的協(xié)程掛起函數(shù)。在ViewModel或業(yè)務(wù)層你可以像調(diào)用普通函數(shù)一樣使用它們viewModelScope.launch { when (val result bluetoothManager.connect(deviceAddress)) { is Result.Success - { // 連接成功可以開始讀寫操作 val writeResult bluetoothManager.writeCharacteristic( serviceUuid SERVICE_UUID_HEART_RATE, characteristicUuid CHAR_UUID_HEART_RATE_MEASUREMENT, data byteArrayOf(0x01) // 例如使能通知 ) if (writeResult.isSuccess) { // 寫入成功 } } is Result.Failure - { // 處理連接失敗 showError(result.exception.message) } } }4. 狀態(tài)管理與UI聯(lián)動(dòng)的實(shí)戰(zhàn)技巧將底層藍(lán)牙操作封裝好后如何優(yōu)雅地在UI上反映狀態(tài)變化是提升用戶體驗(yàn)的關(guān)鍵。我們使用StateFlow和ViewModel來構(gòu)建響應(yīng)式UI。4.1 使用Sealed Class定義清晰的UI狀態(tài)對(duì)于連接狀態(tài)一個(gè)簡(jiǎn)單的枚舉可能不夠。我們使用密封類Sealed Class來定義所有可能的UI狀態(tài)這比使用多個(gè)獨(dú)立的LiveData或Flow更清晰也便于Compose或DataBinding使用。// 在 BleViewModel 或一個(gè)獨(dú)立的狀態(tài)類中 sealed class BleUiState { object Idle : BleUiState() // 初始空閑狀態(tài) object Scanning : BleUiState() // 掃描中 data class ScanResults(val devices: ListBleDevice) : BleUiState() // 掃描結(jié)果 object Connecting : BleUiState() // 連接中 data class Connected(val deviceName: String) : BleUiState() // 已連接 data class DataReceived(val data: ByteArray) : BleUiState() // 收到數(shù)據(jù) data class Error(val message: String) : BleUiState() // 錯(cuò)誤狀態(tài) object Disconnected : BleUiState() // 已斷開 } // 在ViewModel中合并多個(gè)狀態(tài)流 class BleViewModel Inject constructor( private val bluetoothManager: IBluetoothManager ) : ViewModel() { private val _uiState MutableStateFlowBleUiState(BleUiState.Idle) val uiState: StateFlowBleUiState _uiState.asStateFlow() init { viewModelScope.launch { // 合并掃描狀態(tài)和連接狀態(tài)驅(qū)動(dòng)UI combine( bluetoothManager.isScanning, bluetoothManager.connectionState, bluetoothManager.scanResults, bluetoothManager.receivedData ) { isScanning, connState, devices, data - when { isScanning - BleUiState.Scanning connState ConnectionState.CONNECTED - BleUiState.Connected(bluetoothManager.connectedDeviceName ?: Unknown) connState ConnectionState.CONNECTING - BleUiState.Connecting connState ConnectionState.DISCONNECTED devices.isEmpty() - BleUiState.Idle connState ConnectionState.DISCONNECTED - BleUiState.ScanResults(devices) data ! null - BleUiState.DataReceived(data) else - BleUiState.Idle } }.collect { newState - _uiState.value newState } } // 單獨(dú)收集錯(cuò)誤流 viewModelScope.launch { bluetoothManager.errorMessages.collect { errorMsg - if (errorMsg.isNotBlank()) { _uiState.value BleUiState.Error(errorMsg) } } } } }在UI層Activity/Fragment觀察這個(gè)統(tǒng)一的uiState即可// 在Fragment中 lifecycleScope.launch { repeatOnLifecycle(Lifecycle.State.STARTED) { viewModel.uiState.collect { state - when (state) { is BleUiState.Scanning - { binding.progressBar.visibility View.VISIBLE binding.scanButton.text 停止掃描 } is BleUiState.ScanResults - { binding.progressBar.visibility View.GONE adapter.submitList(state.devices) } is BleUiState.Connecting - { showToast(正在連接...) } is BleUiState.Connected - { showToast(已連接到 ${state.deviceName}) // 更新UI顯示數(shù)據(jù)交互界面 } is BleUiState.Error - { showErrorDialog(state.message) } // ... 處理其他狀態(tài) } } } }4.2 處理屏幕旋轉(zhuǎn)與進(jìn)程死亡藍(lán)牙連接是長(zhǎng)時(shí)操作且持有系統(tǒng)資源BluetoothGatt。必須妥善處理配置變更如屏幕旋轉(zhuǎn)和進(jìn)程死亡。1. 使用ViewModel保存關(guān)鍵狀態(tài)ViewModel在配置變更時(shí)不會(huì)銷毀因此我們將設(shè)備地址、連接狀態(tài)等保存在ViewModel中。旋轉(zhuǎn)屏幕后ViewModel可以嘗試重新連接。2. 在onCleared中釋放資源當(dāng)ViewModel不再需要時(shí)如Activity被finish必須斷開藍(lán)牙連接并釋放資源。override fun onCleared() { super.onCleared() viewModelScope.launch { bluetoothManager.disconnect() bluetoothManager.stopScan() } }3. 處理進(jìn)程死亡可選高級(jí)場(chǎng)景如果你的應(yīng)用需要后臺(tái)保持連接可以考慮使用Foreground Service并將關(guān)鍵狀態(tài)如設(shè)備地址保存到SharedPreferences或DataStore中。當(dāng)應(yīng)用從進(jìn)程死亡中恢復(fù)時(shí)ViewModel會(huì)重新創(chuàng)建此時(shí)可以從持久化存儲(chǔ)中讀取設(shè)備地址并嘗試重新連接。本示例程序聚焦于前臺(tái)交互暫不涉及此復(fù)雜場(chǎng)景。4.3 通知Notification的啟用與數(shù)據(jù)監(jiān)聽對(duì)于需要設(shè)備主動(dòng)上報(bào)數(shù)據(jù)的特征如心率測(cè)量需要啟用通知Notification或指示Indication。fun enableNotification(serviceUuid: UUID, characteristicUuid: UUID, enable: Boolean) { val gatt bluetoothGatt ?: return val service gatt.getService(serviceUuid) ?: return val characteristic service.getCharacteristic(characteristicUuid) ?: return // 1. 先設(shè)置客戶端特征配置描述符CCCD val descriptor characteristic.getDescriptor(CCC_DESCRIPTOR_UUID) // UUID: 0x2902 descriptor?.value if (enable) { BluetoothGattDescriptor.ENABLE_NOTIFICATION_VALUE } else { BluetoothGattDescriptor.DISABLE_NOTIFICATION_VALUE } // 2. 寫入描述符 gatt.writeDescriptor(descriptor) // 3. 如果寫入成功在onDescriptorWrite回調(diào)中再設(shè)置特征值的通知 gattCallback.onDescriptorWriteSucceeded { desc - if (desc.uuid CCC_DESCRIPTOR_UUID) { gatt.setCharacteristicNotification(characteristic, enable) } } }啟用后設(shè)備發(fā)送的數(shù)據(jù)會(huì)觸發(fā)SimplifiedBluetoothGattCallback的onCharacteristicChanged回調(diào)我們?cè)谶@里將數(shù)據(jù)通過Flow發(fā)送出去// 在 SimplifiedBluetoothGattCallback 中 override fun onCharacteristicChanged(gatt: BluetoothGatt, characteristic: BluetoothGattCharacteristic) { val data characteristic.value _receivedData.tryEmit(data) }在ViewModel中收集這個(gè)receivedDataFlow并合并到uiState中UI就能實(shí)時(shí)更新了。5. 避坑指南與性能優(yōu)化紙上得來終覺淺絕知此事要躬行。下面分享幾個(gè)我在實(shí)際開發(fā)中踩過的坑和總結(jié)的優(yōu)化點(diǎn)這些在官方文檔里往往不會(huì)細(xì)說。5.1 連接失敗與“133”錯(cuò)誤碼這是BLE開發(fā)中最常見的錯(cuò)誤之一。當(dāng)你調(diào)用connectGatt后onConnectionStateChange回調(diào)中的status參數(shù)可能會(huì)返回133或其他非0值緊接著狀態(tài)變?yōu)镾TATE_DISCONNECTED?？赡艿脑蚝徒鉀Q方案系統(tǒng)層面限制部分手機(jī)廠商特別是國(guó)內(nèi)定制ROM對(duì)后臺(tái)掃描和連接有嚴(yán)格限制。確保你的應(yīng)用在前臺(tái)運(yùn)行并且用戶給予了所有必要權(quán)限包括后臺(tái)位置權(quán)限如果需要。設(shè)備端拒絕有些BLE設(shè)備有連接間隔、安全要求等限制。檢查設(shè)備文檔確認(rèn)你的手機(jī)兼容性。Gatt對(duì)象未及時(shí)關(guān)閉同一個(gè)設(shè)備在斷開連接后必須調(diào)用gatt.close()釋放資源否則再次連接可能會(huì)失敗。確保你的disconnect邏輯里包含了close()。連接超時(shí)像我們上面實(shí)現(xiàn)的添加一個(gè)連接超時(shí)機(jī)制如30秒是非常必要的。超時(shí)后主動(dòng)斷開并清理給用戶明確的反饋。重試策略對(duì)于偶發(fā)的連接失敗可以實(shí)現(xiàn)一個(gè)簡(jiǎn)單的指數(shù)退避重試機(jī)制但不要無限重試通常2-3次后就應(yīng)該提示用戶檢查設(shè)備和環(huán)境。5.2 掃描耗電與后臺(tái)限制持續(xù)掃描是耗電大戶。我們的示例中使用了SCAN_MODE_LOW_LATENCY這在前臺(tái)快速發(fā)現(xiàn)設(shè)備時(shí)是合適的。但在實(shí)際應(yīng)用中需要考慮更多場(chǎng)景前臺(tái)掃描使用SCAN_MODE_LOW_LATENCY或SCAN_MODE_BALANCED。后臺(tái)掃描如果應(yīng)用需要在后臺(tái)持續(xù)掃描如Beacon應(yīng)用必須使用SCAN_MODE_LOW_POWER并且從Android 8.0開始后臺(tái)掃描有嚴(yán)格的限制時(shí)間窗口、發(fā)現(xiàn)次數(shù)限制。通常需要結(jié)合AlarmManager或WorkManager進(jìn)行周期掃描。掃描過濾器使用ScanFilter可以大幅減少不必要的回調(diào)節(jié)省電量。例如只掃描特定服務(wù)UUID或設(shè)備名稱的設(shè)備。val filter ScanFilter.Builder() .setServiceUuid(ParcelUuid(SERVICE_UUID_HEART_RATE)) .build() val filters listOf(filter)5.3 讀寫操作超時(shí)與隊(duì)列管理Android的BLE棧內(nèi)部有一個(gè)操作隊(duì)列。如果你在前一個(gè)寫操作的回調(diào)onCharacteristicWrite收到之前又發(fā)起了下一個(gè)寫操作可能會(huì)導(dǎo)致第二個(gè)操作失敗或行為異常。解決方案實(shí)現(xiàn)一個(gè)簡(jiǎn)單的操作隊(duì)列。class BluetoothManagerImpl { private val operationQueue ChannelGattOperation(capacity Channel.UNLIMITED) private val operationScope CoroutineScope(Dispatchers.IO SupervisorJob()) init { operationScope.launch { for (op in operationQueue) { try { when (op) { is GattOperation.Write - { performWrite(op.serviceUuid, op.charUuid, op.data) } is GattOperation.Read - { performRead(op.serviceUuid, op.charUuid) } } } catch (e: Exception) { // 處理單個(gè)操作失敗不影響隊(duì)列繼續(xù)執(zhí)行 _errorMessages.tryEmit(操作失敗: ${e.message}) } } } } suspend fun writeCharacteristicQueued(serviceUuid: UUID, characteristicUuid: UUID, data: ByteArray) { operationQueue.send(GattOperation.Write(serviceUuid, characteristicUuid, data)) } private suspend fun performWrite(serviceUuid: UUID, characteristicUuid: UUID, data: ByteArray) { // 這里使用我們之前實(shí)現(xiàn)的掛起函數(shù) writeCharacteristic // 但確保它是順序執(zhí)行的 writeCharacteristic(serviceUuid, characteristicUuid, data).fold( onSuccess { /* 成功處理 */ }, onFailure { throw it } ) } } sealed class GattOperation { data class Write(val serviceUuid: UUID, val charUuid: UUID, val data: ByteArray) : GattOperation() data class Read(val serviceUuid: UUID, val charUuid: UUID) : GattOperation() }這樣所有讀寫操作都會(huì)按順序執(zhí)行避免了并發(fā)問題。對(duì)于需要高吞吐量的場(chǎng)景你可能需要更復(fù)雜的隊(duì)列優(yōu)先級(jí)管理但對(duì)于大多數(shù)應(yīng)用一個(gè)FIFO隊(duì)列已經(jīng)足夠。5.4 內(nèi)存泄漏預(yù)防藍(lán)牙相關(guān)的回調(diào)持有Context或Activity引用是內(nèi)存泄漏的常見根源。在BluetoothManager中持有Application Context在初始化BluetoothManagerImpl時(shí)傳入Application Context通過依賴注入或context.applicationContext而不是Activity Context。及時(shí)取消協(xié)程所有在viewModelScope或自定義scope中啟動(dòng)的協(xié)程都會(huì)在ViewModel的onCleared或scope取消時(shí)自動(dòng)取消。確保你的藍(lán)牙操作如連接超時(shí)是可取消的使用suspendCancellableCoroutine。解除回調(diào)引用在BluetoothManager的disconnect和cleanup方法中不僅要將bluetoothGatt置為null還要將gattCallback內(nèi)部對(duì)continuation等臨時(shí)引用也置為null。這個(gè)基于Kotlin的藍(lán)牙庫示例程序從權(quán)限處理、掃描、連接到數(shù)據(jù)讀寫完整地展示了一套現(xiàn)代化、健壯且易于理解的Android BLE開發(fā)實(shí)踐。它沒有追求大而全的功能而是力求在每一個(gè)環(huán)節(jié)都做到清晰和可靠。你可以直接將它作為新項(xiàng)目的基礎(chǔ)模塊也可以從中抽取思想來改造現(xiàn)有的藍(lán)牙代碼。最重要的是希望它能幫助你避開那些我曾經(jīng)踩過的坑更順暢地開發(fā)出穩(wěn)定可靠的藍(lán)牙應(yīng)用。本文還有配套的精品資源點(diǎn)擊獲取