@Entity(tableName = "ble_device")
public class BleDeviceEntity {
@PrimaryKey(autoGenerate = true)
private int id;
@NonNull
@ColumnInfo(name = "device_address")
private String address;
private String name;
private int rssi;
@ColumnInfo(name = "last_seen")
private long lastSeenTimestamp;
// 构造函数、Getter、Setter 省略
}
最佳实践：Entity 字段尽量使用基本类型 + String，避免复杂嵌套对象。若必须存储，需配合 TypeConverter。
#### 2.2.2 DAO — 数据操作接口
DAO 是接口或抽象类，使用 `@Dao` 注解。方法上标注 `@Insert`、`@Update`、`@Delete`、`@Query` 等。
@Dao
public interface BleDeviceDao {
@Insert(onConflict = OnConflictStrategy.REPLACE)
void insert(BleDeviceEntity device);
@Update
void update(BleDeviceEntity device);
@Delete
void delete(BleDeviceEntity device);
@Query("SELECT * FROM ble_device ORDER BY last_seen DESC")
LiveData<List<BleDeviceEntity>> getAllDevices();
@Query("SELECT * FROM ble_device WHERE device_address = :address")
BleDeviceEntity getDeviceByAddress(String address);
}public class Converters {
@TypeConverter
public static Date fromTimestamp(Long value) {
return value == null ? null : new Date(value);
}
@TypeConverter
public static Long dateToTimestamp(Date date) {
return date == null ? null : date.getTime();
}
@TypeConverter
public static List<String> fromString(String value) {
if (value == null) return null;
return Arrays.asList(value.split(","));
}
@TypeConverter
public static String fromList(List<String> list) {
if (list == null) return null;
return String.join(",", list);
}
}@Database(
entities = {BleDeviceEntity.class},
version = 1,
exportSchema = false
)
@TypeConverters(Converters.class)
public abstract class BleDeviceDatabase extends RoomDatabase {
public abstract BleDeviceDao bleDeviceDao();
private static volatile BleDeviceDatabase INSTANCE;
public static BleDeviceDatabase getInstance(Context context) {
if (INSTANCE == null) {
synchronized (BleDeviceDatabase.class) {
if (INSTANCE == null) {
INSTANCE = Room.databaseBuilder(
context.getApplicationContext(),
BleDeviceDatabase.class,
"ble_device_db"
)
.fallbackToDestructiveMigration()
.build();
}
}
}
return INSTANCE;
}
}
典型错误 1：Entity 缺少无参构造函数或主键 —— 编译报错 “Entities must have a primary key”。
典型错误 2：TypeConverter 未注册，存储 Date 时出现 “Cannot figure out how to save this field into database”。
典型错误 3：Database 未使用单例模式，造成多次打开数据库连接 — 使用 volatile + synchronized 解决。
### 2.5 性能与稳定性优化
- **DAO 方法使用 `LiveData` 或 `Flow`**，实现自动通知 UI 更新，避免手动刷新。
- **事务操作** 在 DAO 方法上添加 `@Transaction`，保证批量插入/更新的原子性。
- **索引优化**：在查询频繁的字段上添加 `@Index`，例如 `@Entity(indices = {@Index("device_address")})`。
- **预编译 WAL 模式**：Room 默认启用 WAL（Write-Ahead Logging），提高并发读写性能。无需手动配置。
- **迁移策略**：生产环境必须使用 `addMigrations()` 逐步迁移，避免 `fallbackToDestructiveMigration()` 造成数据丢失。
// 迁移示例：从版本 1 升级到 2
static final Migration MIGRATION_1_2 = new Migration(1, 2) {
@Override
public void migrate(@NonNull SupportSQLiteDatabase database) {
database.execSQL("ALTER TABLE ble_device ADD COLUMN battery_level INTEGER DEFAULT 0");
}
};