第4章 设计蓝牙设备数据实体：BluetoothDeviceEntity

在 Room 数据库中管理蓝牙多设备数据，首先需要定义清晰的数据实体（Entity）。实体对应数据库中的表，每个字段映射为表的一列。本章以 BluetoothDeviceEntity 为核心，详细设计其字段结构、数据类型、索引策略，并给出完整的 Kotlin 代码实现。

4.1 字段设计原则

蓝牙设备的关键属性应全部纳入实体，同时满足 Room 对主键、索引、空值、默认值的约束。常见必须字段包括：

• 地址（address）：蓝牙 MAC 地址，全球唯一，作为主键。
• 名称（name）：设备广播名或缓存名，可为空。
• 信号强度（rssi）：扫描时的 RSSI 值，整型，允许负值。
• 最后连接时间（lastConnectedTime）：时间戳，长整型，用于排序和淘汰逻辑。
• 设备类型（type）：枚举或整数，区分经典蓝牙 / BLE。
• 额外元数据：可通过 JSON 字符串存储厂商信息、服务 UUID 等。

4.2 字段定义与数据类型对照表

4.3 Room Entity 代码实现

使用 Kotlin 数据类，配合 Room 注解标记主键、列名、索引。代码如下：

@Entity(
    tableName = "bluetooth_device",
    indices = [
        Index(value = ["rssi"], orders = [Index.Order.DESC])
    ]
)
data class BluetoothDeviceEntity(
    @PrimaryKey
    @ColumnInfo(name = "address")
    val address: String,

    @ColumnInfo(name = "name")
    val name: String? = null,

    @ColumnInfo(name = "rssi")
    val rssi: Int = -100,

    @ColumnInfo(name = "last_connected_time")
    val lastConnectedTime: Long? = null,

    @ColumnInfo(name = "type")
    val type: Int = 2,   // 默认 BLE

    @ColumnInfo(name = "metadata_json")
    val metadataJson: String? = null
)

4.4 Entity 与蓝牙扫描数据的映射关系

当蓝牙设备被扫描到时，Android 的 ScanResult 对象包含所有原始数据。映射关系如下表：

4.5 内联 SVG：BluetoothDeviceEntity 字段结构图

下图为实体与数据库表字段的对应架构，展示了主键、索引、数据类型及与扫描数据源的映射关系：

4.6 常见设计陷阱与优化建议

• 主键选择：不要使用自增 ID，因为同一设备的多次扫描应合并为一条记录，使用 address 作主键可避免重复插入（使用 @Insert(onConflict = OnConflictStrategy.REPLACE)）。
• 信号强度索引：如果应用需要按信号强弱显示设备列表，必须为 rssi 建立降序索引。对于大量设备（>1000），索引能显著提升排序性能。
• 最后连接时间的空值处理：在查询中需要按未连接设备排序时，可使用 COALESCE(lastConnectedTime, 0) 或 Kotlin 中自定义 TypeConverter 将 null 映射为 0。
• 元数据 JSON 存储：推荐使用 Room 的 @TypeConverter 自动序列化和反序列化，避免手动拼接字符串。示例 TypeConverter 如下：

class Converters {
    @TypeConverter
    fun fromMetadataJson(value: String?): Metadata? {
        return value?.let { Gson().fromJson(it, Metadata::class.java) }
    }

    @TypeConverter
    fun toMetadataJson(metadata: Metadata?): String? {
        return metadata?.let { Gson().toJson(it) }
    }
}

4.7 调试：查看生成的数据库表结构

使用 Android Studio 的 Database Inspector 或运行以下 SQL 查询验证实体字段是否生效：

SELECT name, type, `notnull`, pk
FROM pragma_table_info("bluetooth_device");

预期输出应包含 6 行字段，其中 address 的 pk=1（主键），rssi 的 notnull=1。若需要检查索引，执行：

PRAGMA index_list("bluetooth_device");