簡介本資源是一套面向Android開發(fā)者與移動通信學(xué)習(xí)者的Kotlin藍(lán)牙開發(fā)實戰(zhàn)示例聚焦短距離無線通信場景解決藍(lán)牙設(shè)備發(fā)現(xiàn)、配對、數(shù)據(jù)傳輸?shù)群诵墓δ艿墓こ袒瘜崿F(xiàn)問題適用于具備基礎(chǔ)Android開發(fā)能力的學(xué)習(xí)者進(jìn)階實踐。壓縮包共326個文件總大小24.36MB涵蓋62個Kotlin源文件含協(xié)程與擴(kuò)展函數(shù)等現(xiàn)代語法實踐、34個Java文件保障Java/Kotlin混合項目兼容性、133個XML布局與配置文件支撐UI與Manifest定義、17個AAR庫含多個版本ppblutoothkit藍(lán)牙SDK體現(xiàn)迭代適配過程以及14個SO本地庫支撐底層藍(lán)牙協(xié)議棧調(diào)用。已有423人學(xué)習(xí)下載資源結(jié)構(gòu)清晰、模塊完整提供從權(quán)限申請、掃描連接到數(shù)據(jù)收發(fā)的全鏈路代碼參考并附帶Gradle構(gòu)建配置、Markdown說明文檔及多分辨率PNG資源便于快速理解架構(gòu)設(shè)計與移植集成。1. 項目緣起為什么我們需要一個Kotlin藍(lán)牙庫示例如果你是一名Android開發(fā)者最近在項目中需要集成藍(lán)牙功能尤其是低功耗藍(lán)牙BLE你大概率會和我有同樣的感受官方文檔的示例代碼要么是Java的要么是過時的要么就是過于零散難以直接上手。更別提那些隱藏在BluetoothLeGatt示例項目中混雜著AsyncTask和Handler的老舊代碼了。當(dāng)你想用現(xiàn)代、簡潔的Kotlin來重構(gòu)時會發(fā)現(xiàn)網(wǎng)上能找到的要么是零碎的代碼片段要么是封裝得過于復(fù)雜、難以理解的第三方庫。這就是我決定動手整理并開源一個“基于Kotlin語言的藍(lán)牙庫示例程序Android版設(shè)計源碼”的直接原因。這個項目不是一個功能大而全的通用藍(lán)牙框架它的核心定位非常明確一個清晰、現(xiàn)代、可直接復(fù)用的Kotlin BLE操作模板。它剝離了業(yè)務(wù)邏輯專注于展示在Android平臺上如何使用Kotlin協(xié)程、Flow等現(xiàn)代語言特性優(yōu)雅、安全地處理藍(lán)牙掃描、連接、數(shù)據(jù)讀寫、通知監(jiān)聽等核心流程。在開始之前我們先明確一下這個示例程序的價值。它不僅僅是幾行代碼而是解決了一系列實際開發(fā)中的痛點架構(gòu)清晰采用MVVM模式或更準(zhǔn)確的一個簡化的MVI思想分離了UI、業(yè)務(wù)邏輯和藍(lán)牙底層操作便于理解和擴(kuò)展?，F(xiàn)代Kotlin實踐全程使用Kotlin編寫大量運用協(xié)程處理異步回調(diào)用StateFlow管理UI狀態(tài)避免了回調(diào)地獄和內(nèi)存泄漏。生命周期安全與Android的Lifecycle深度集成確保藍(lán)牙操作在頁面銷毀時自動清理杜絕資源泄露。錯誤處理完備對藍(lán)牙權(quán)限、位置服務(wù)、藍(lán)牙開關(guān)狀態(tài)、連接超時、服務(wù)發(fā)現(xiàn)失敗等常見異常場景進(jìn)行了封裝和處理?？砂尾逶O(shè)計核心的藍(lán)牙管理器BluetoothManager接口化方便你替換為其他藍(lán)牙庫如RxAndroidBle或進(jìn)行單元測試。這個項目適合所有正在或即將進(jìn)行Android藍(lán)牙開發(fā)的同行無論你是想快速搭建一個BLE功能原型還是想學(xué)習(xí)如何用Kotlin現(xiàn)代化地處理硬件交互它都能提供一個扎實的起點。接下來我將從環(huán)境搭建開始帶你一步步拆解這個示例程序的設(shè)計與實現(xiàn)。2. 環(huán)境準(zhǔn)備與項目結(jié)構(gòu)概覽在深入代碼之前我們需要把環(huán)境搭建好。這個示例基于Android Studio進(jìn)行開發(fā)對SDK版本和依賴庫有明確要求。2.1 開發(fā)環(huán)境與依賴配置首先確保你的build.gradle (Module: app)文件中的配置如下。這里的關(guān)鍵是Kotlin協(xié)程和Lifecycle相關(guān)庫它們是實現(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 // 測試依賴 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ī)制。在實際大型項目中你可能會選擇RxAndroidBle等庫來簡化操作但掌握底層原理是有效使用和調(diào)試高級庫的前提。2.2 項目模塊與包結(jié)構(gòu)設(shè)計一個清晰的項目結(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)牙管理器具體實現(xiàn)核心 │ ├── model/ │ │ ├── BleDevice.kt // 藍(lán)牙設(shè)備數(shù)據(jù)類 │ │ ├── ConnectionState.kt // 連接狀態(tài)枚舉類 │ │ └── GattAction.kt // GATT操作類型讀、寫、通知等 │ └── callback/ │ └── SimplifiedBluetoothGattCallback.kt // 簡化的GATT回調(diào)封裝 ├── utils/ │ ├── PermissionsHelper.kt // 權(quán)限請求工具 │ └── Extensions.kt // Kotlin擴(kuò)展函數(shù) └── di/ (可選) └── 依賴注入相關(guān)設(shè)置如使用Koin或Hilt這種結(jié)構(gòu)的好處一目了然ui層只關(guān)心界面和用戶輸入viewmodel作為中間層將bluetooth層的復(fù)雜操作轉(zhuǎn)換為UI可觀察的簡單狀態(tài)bluetooth層是真正的引擎負(fù)責(zé)所有與系統(tǒng)藍(lán)牙API的交互。model包定義了數(shù)據(jù)傳輸對象callback包處理系統(tǒng)回調(diào)的轉(zhuǎn)換。當(dāng)你需要替換藍(lán)牙實現(xiàn)或修改UI時影響范圍被嚴(yán)格控制在了單個模塊內(nèi)。3. 核心實現(xiàn)從權(quán)限到連接的完整鏈路一切就緒我們進(jìn)入最核心的部分。藍(lán)牙開發(fā)的第一步永遠(yuǎn)不是打開藍(lán)牙而是處理權(quán)限。Android的權(quán)限模型在不斷演進(jìn)處理BLE需要格外小心。3.1 運行時權(quán)限與藍(lán)牙開關(guān)檢測從Android 12 (API 31) 開始藍(lán)牙掃描需要BLUETOOTH_SCAN權(quán)限并且該權(quán)限可以是neverForLocation的這解決了長期以來BLE掃描必須請求精確定位權(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中我們這樣使用它class 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 - { // 請求用戶打開藍(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)鍵點在于我們將權(quán)限狀態(tài)和藍(lán)牙開關(guān)狀態(tài)都通過ViewModel中的StateFlow來管理。UIActivity/Fragment只負(fù)責(zé)發(fā)起請求和展示結(jié)果狀態(tài)變化的邏輯集中在ViewModel中這使得代碼更易于測試也避免了在生命周期復(fù)雜的Activity中埋下狀態(tài)管理的隱患。3.2 藍(lán)牙掃描的現(xiàn)代化封裝傳統(tǒng)的藍(lán)牙掃描需要注冊一個BroadcastReceiver來接收BluetoothDevice.ACTION_FOUND廣播對于BLE則使用BluetoothLeScanner.startScan(scanCallback)。這些API都是基于回調(diào)的在Kotlin協(xié)程時代我們可以將其封裝成更易用的Flow。在BluetoothManagerImpl中我們實現(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é)果這里簡單去重按地址 _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(掃描失敗錯誤碼: $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, 停止掃描時出錯, e) } } scanCallback null _isScanning.value false } }在ViewModel中我們暴露一個簡單的狀態(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這個StateFlow列表就會自動更新。這種響應(yīng)式編程模式極大地簡化了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中實現(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 以快速連接實際可根據(jù)場景調(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è)置一個連接超時 scope.launch { delay(CONNECTION_TIMEOUT_MS) if (_connectionState.value ConnectionState.CONNECTING) { disconnectGatt() continuation.resume(Result.failure(TimeoutException(連接超時))) } } // 在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)通常在連接成功后自動或手動觸發(fā)。在我們的設(shè)計中連接成功后會自動開始發(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對象為空))) 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(寫入請求發(fā)送失敗))) } }在SimplifiedBluetoothGattCallback的onCharacteristicWrite回調(diào)中我們需要取出對應(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封裝成了線性的、可讀性極強的協(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)動的實戰(zhàn)技巧將底層藍(lán)牙操作封裝好后如何優(yōu)雅地在UI上反映狀態(tài)變化是提升用戶體驗的關(guān)鍵。我們使用StateFlow和ViewModel來構(gòu)建響應(yīng)式UI。4.1 使用Sealed Class定義清晰的UI狀態(tài)對于連接狀態(tài)一個簡單的枚舉可能不夠。我們使用密封類Sealed Class來定義所有可能的UI狀態(tài)這比使用多個獨立的LiveData或Flow更清晰也便于Compose或DataBinding使用。// 在 BleViewModel 或一個獨立的狀態(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() // 錯誤狀態(tài) object Disconnected : BleUiState() // 已斷開 } // 在ViewModel中合并多個狀態(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ū)動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 } } // 單獨收集錯誤流 viewModelScope.launch { bluetoothManager.errorMessages.collect { errorMsg - if (errorMsg.isNotBlank()) { _uiState.value BleUiState.Error(errorMsg) } } } } }在UI層Activity/Fragment觀察這個統(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)牙連接是長時操作且持有系統(tǒng)資源BluetoothGatt。必須妥善處理配置變更如屏幕旋轉(zhuǎn)和進(jìn)程死亡。1. 使用ViewModel保存關(guān)鍵狀態(tài)ViewModel在配置變更時不會銷毀因此我們將設(shè)備地址、連接狀態(tài)等保存在ViewModel中。旋轉(zhuǎn)屏幕后ViewModel可以嘗試重新連接。2. 在onCleared中釋放資源當(dāng)ViewModel不再需要時如Activity被finish必須斷開藍(lán)牙連接并釋放資源。override fun onCleared() { super.onCleared() viewModelScope.launch { bluetoothManager.disconnect() bluetoothManager.stopScan() } }3. 處理進(jìn)程死亡可選高級場景如果你的應(yīng)用需要后臺保持連接可以考慮使用Foreground Service并將關(guān)鍵狀態(tài)如設(shè)備地址保存到SharedPreferences或DataStore中。當(dāng)應(yīng)用從進(jìn)程死亡中恢復(fù)時ViewModel會重新創(chuàng)建此時可以從持久化存儲中讀取設(shè)備地址并嘗試重新連接。本示例程序聚焦于前臺交互暫不涉及此復(fù)雜場景。4.3 通知Notification的啟用與數(shù)據(jù)監(jiān)聽對于需要設(shè)備主動上報數(shù)據(jù)的特征如心率測量需要啟用通知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ù)會觸發(fā)SimplifiedBluetoothGattCallback的onCharacteristicChanged回調(diào)我們在這里將數(shù)據(jù)通過Flow發(fā)送出去// 在 SimplifiedBluetoothGattCallback 中 override fun onCharacteristicChanged(gatt: BluetoothGatt, characteristic: BluetoothGattCharacteristic) { val data characteristic.value _receivedData.tryEmit(data) }在ViewModel中收集這個receivedDataFlow并合并到uiState中UI就能實時更新了。5. 避坑指南與性能優(yōu)化紙上得來終覺淺絕知此事要躬行。下面分享幾個我在實際開發(fā)中踩過的坑和總結(jié)的優(yōu)化點這些在官方文檔里往往不會細(xì)說。5.1 連接失敗與“133”錯誤碼這是BLE開發(fā)中最常見的錯誤之一。當(dāng)你調(diào)用connectGatt后onConnectionStateChange回調(diào)中的status參數(shù)可能會返回133或其他非0值緊接著狀態(tài)變?yōu)镾TATE_DISCONNECTED?？赡艿脑蚝徒鉀Q方案系統(tǒng)層面限制部分手機(jī)廠商特別是國內(nèi)定制ROM對后臺掃描和連接有嚴(yán)格限制。確保你的應(yīng)用在前臺運行并且用戶給予了所有必要權(quán)限包括后臺位置權(quán)限如果需要。設(shè)備端拒絕有些BLE設(shè)備有連接間隔、安全要求等限制。檢查設(shè)備文檔確認(rèn)你的手機(jī)兼容性。Gatt對象未及時關(guān)閉同一個設(shè)備在斷開連接后必須調(diào)用gatt.close()釋放資源否則再次連接可能會失敗。確保你的disconnect邏輯里包含了close()。連接超時像我們上面實現(xiàn)的添加一個連接超時機(jī)制如30秒是非常必要的。超時后主動斷開并清理給用戶明確的反饋。重試策略對于偶發(fā)的連接失敗可以實現(xiàn)一個簡單的指數(shù)退避重試機(jī)制但不要無限重試通常2-3次后就應(yīng)該提示用戶檢查設(shè)備和環(huán)境。5.2 掃描耗電與后臺限制持續(xù)掃描是耗電大戶。我們的示例中使用了SCAN_MODE_LOW_LATENCY這在前臺快速發(fā)現(xiàn)設(shè)備時是合適的。但在實際應(yīng)用中需要考慮更多場景前臺掃描使用SCAN_MODE_LOW_LATENCY或SCAN_MODE_BALANCED。后臺掃描如果應(yīng)用需要在后臺持續(xù)掃描如Beacon應(yīng)用必須使用SCAN_MODE_LOW_POWER并且從Android 8.0開始后臺掃描有嚴(yán)格的限制時間窗口、發(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 讀寫操作超時與隊列管理Android的BLE棧內(nèi)部有一個操作隊列。如果你在前一個寫操作的回調(diào)onCharacteristicWrite收到之前又發(fā)起了下一個寫操作可能會導(dǎo)致第二個操作失敗或行為異常。解決方案實現(xiàn)一個簡單的操作隊列。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) { // 處理單個操作失敗不影響隊列繼續(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) { // 這里使用我們之前實現(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() }這樣所有讀寫操作都會按順序執(zhí)行避免了并發(fā)問題。對于需要高吞吐量的場景你可能需要更復(fù)雜的隊列優(yōu)先級管理但對于大多數(shù)應(yīng)用一個FIFO隊列已經(jīng)足夠。5.4 內(nèi)存泄漏預(yù)防藍(lán)牙相關(guān)的回調(diào)持有Context或Activity引用是內(nèi)存泄漏的常見根源。在BluetoothManager中持有Application Context在初始化BluetoothManagerImpl時傳入Application Context通過依賴注入或context.applicationContext而不是Activity Context。及時取消協(xié)程所有在viewModelScope或自定義scope中啟動的協(xié)程都會在ViewModel的onCleared或scope取消時自動取消。確保你的藍(lán)牙操作如連接超時是可取消的使用suspendCancellableCoroutine。解除回調(diào)引用在BluetoothManager的disconnect和cleanup方法中不僅要將bluetoothGatt置為null還要將gattCallback內(nèi)部對continuation等臨時引用也置為null。這個基于Kotlin的藍(lán)牙庫示例程序從權(quán)限處理、掃描、連接到數(shù)據(jù)讀寫完整地展示了一套現(xiàn)代化、健壯且易于理解的Android BLE開發(fā)實踐。它沒有追求大而全的功能而是力求在每一個環(huán)節(jié)都做到清晰和可靠。你可以直接將它作為新項目的基礎(chǔ)模塊也可以從中抽取思想來改造現(xiàn)有的藍(lán)牙代碼。最重要的是希望它能幫助你避開那些我曾經(jīng)踩過的坑更順暢地開發(fā)出穩(wěn)定可靠的藍(lán)牙應(yīng)用。本文還有配套的精品資源點擊獲取