3. Room数据库设计与创建：Entity定义、DAO接口编写、Database类构建、数据库版本管理配置

本章核心目标是掌握Room持久化库在跨进程ContentProvider场景下的完整设计流程。将从数据库表结构（Entity）的定义开始，依次完成数据访问对象（DAO）的接口声明、RoomDatabase抽象类的构建，以及数据库版本迁移与降级方案配置。学完本章后，你将能独立搭建一个支持多表关联、类型转换器、并发查询且可安全升级的Room数据库层，为后续封装ContentProvider提供稳定的数据底座。

3.1 Entity定义：表结构与字段约束

Entity对应数据库中的一张表，每个字段映射为列。在跨进程场景中，所有暴露给ContentProvider的Entity必须实现Parcelable接口，确保数据能通过Binder在进程间传递。

3.1.1 基础Entity示例：User

@Entity(tableName = "user")
public class User implements Parcelable {
    @PrimaryKey(autoGenerate = true)
    private long id;

    @NonNull
    @ColumnInfo(name = "user_name", typeAffinity = ColumnInfo.TEXT)
    private String userName;

    @ColumnInfo(name = "avatar_uri")
    private String avatarUri;

    @ColumnInfo(name = "created_at")
    private long createdAt;

    @Ignore
    private String tempToken;  // 不持久化

    // 构造器、Parcelable、getter/setter ...
    protected User(Parcel in) {
        id = in.readLong();
        userName = in.readString();
        avatarUri = in.readString();
        createdAt = in.readLong();
    }

    @Override
    public void writeToParcel(Parcel dest, int flags) {
        dest.writeLong(id);
        dest.writeString(userName);
        dest.writeString(avatarUri);
        dest.writeLong(createdAt);
    }

    public static final Creator<User> CREATOR = new Creator<User>() {
        @Override
        public User createFromParcel(Parcel in) {
            return new User(in);
        }
        @Override
        public User[] newArray(int size) {
            return new User[size];
        }
    };
}

3.1.2 Entity设计对照表

3.2 DAO接口编写：查询、插入、更新、删除

DAO是Room数据访问的核心抽象层，所有数据库操作都通过接口方法声明。配合LiveData或Flow，可以实现跨进程数据变化的实时推送。下面给出一个同时支持同步和异步返回的典型DAO。

@Dao
public interface UserDao {

    @Query("SELECT * FROM user ORDER BY created_at DESC")
    LiveData<List<User>> getAllUsersLive();

    @Query("SELECT * FROM user WHERE id = :userId")
    User getUserByIdSync(long userId);

    @Insert(onConflict = OnConflictStrategy.REPLACE)
    long insertUser(User user);

    @Update
    int updateUser(User user);

    @Delete
    int deleteUser(User user);

    @Query("DELETE FROM user WHERE created_at < :timestamp")
    int deleteOldUsers(long timestamp);

    @Transaction
    @Query("SELECT * FROM user WHERE id IN " +
           "(SELECT user_id FROM user_group WHERE group_id = :groupId)")
    List<User> getUsersByGroupId(long groupId);
}

3.2.1 DAO方法返回值选择

3.3 Database类构建：抽象类与单例模式

RoomDatabase是数据库的入口，必须定义为抽象类，并声明包含所有DAO的抽象方法。单例模式保证应用内只有一个数据库实例，避免资源竞争。跨进程场景下，ContentProvider将持有该单例。

@Database(
    entities = {User.class, UserGroup.class, Group.class},
    version = 3,
    exportSchema = true
)
@TypeConverters({TimestampConverter.class, ListConverter.class})
public abstract class AppDatabase extends RoomDatabase {

    public abstract UserDao userDao();
    public abstract UserGroupDao userGroupDao();
    public abstract GroupDao groupDao();

    private static volatile AppDatabase INSTANCE;

    public static AppDatabase getInstance(Context context) {
        if (INSTANCE == null) {
            synchronized (AppDatabase.class) {
                if (INSTANCE == null) {
                    INSTANCE = Room.databaseBuilder(
                            context.getApplicationContext(),
                            AppDatabase.class,
                            "app_database.db")
                        .addCallback(sRoomCallback)
                        .fallbackToDestructiveMigration()  // 开发期简化降级
                        .build();
                }
            }
        }
        return INSTANCE;
    }

    private static final Callback sRoomCallback = new Callback() {
        @Override
        public void onCreate(@NonNull SupportSQLiteDatabase db) {
            super.onCreate(db);
            // 首次创建时预置数据或创建视图
        }
        @Override
        public void onOpen(@NonNull SupportSQLiteDatabase db) {
            super.onOpen(db);
            // 启用外键约束
            db.execSQL("PRAGMA foreign_keys = ON;");
        }
    };
}

3.4 数据库版本管理配置

随着业务迭代，数据库表结构必然发生变化。Room通过版本号和Migration对象提供安全升级路径。跨进程集成时，版本不匹配会导致ContentProvider启动异常，必须谨慎处理。

3.4.1 版本迁移——从v2到v3

static final Migration MIGRATION_2_3 = new Migration(2, 3) {
    @Override
    public void migrate(@NonNull SupportSQLiteDatabase database) {
        // 在user表中新增 age 列
        database.execSQL(
            "ALTER TABLE user ADD COLUMN age INTEGER NOT NULL DEFAULT 0"
        );
        // 创建新表 user_profile
        database.execSQL(
            "CREATE TABLE IF NOT EXISTS user_profile (" +
            "profile_id INTEGER PRIMARY KEY AUTOINCREMENT, " +
            "user_id INTEGER NOT NULL, " +
            "bio TEXT, " +
            "FOREIGN KEY(user_id) REFERENCES user(id) ON DELETE CASCADE)"
        );
        // 为user_profile.user_id建立索引
        database.execSQL(
            "CREATE INDEX idx_user_profile_user_id ON user_profile(user_id)"
        );
    }
};

3.4.2 降级策略与配置

3.4.3 在Database构建时注册迁移

INSTANCE = Room.databaseBuilder(context, AppDatabase.class, "app_database.db")
    .addMigrations(
        MIGRATION_1_2,
        MIGRATION_2_3,
        MIGRATION_3_4
    )
    // 可选：为未注册的版本差异提供安全降级
    .fallbackToDestructiveMigration(false)
    .build();

android {
    defaultConfig {
        javaCompileOptions {
            annotationProcessorOptions {
                arguments += ["room.schemaLocation": "$projectDir/schemas".toString()]
            }
        }
    }
}

3.5 整体结构图解

下图展示了Room数据库层从Entity定义到Database暴露的完整组件关系，以及版本迁移在构建时的接入位置。

3.6 常见错误与避坑指南

• Entity未实现Parcelable： 跨进程传输时会抛出RuntimeException: Parcelable protocol requires a Parcelable.Creator。即使ContentProvider内部不直接传递Entity，但Room配合LiveData/ForegroundService时仍可能触发Parcel序列化。
• DAO方法参数类型不匹配： Room在编译时检查参数与SQL绑定。例如long userId传null会导致NullPointerException，应使用Long包装类型配合@Nullable注解。
• 版本迁移未覆盖跳跃升级： 用户从v1直接升级到v3时，Room不会自动执行v1→v2和v2→v3的组合。必须为每个相邻版本对提供Migration，或者配置.fallbackToDestructiveMigration()（不推荐生产使用）。
• @TypeConverters未注册： 如果Entity使用了List<String>或Date等非基本类型，必须通过@TypeConverters在Database类上注册转换器，否则编译时报error: cannot find method。
• 跨进程并发写入死锁： ContentProvider的多个Binder线程同时调用DAO方法，若Room未开启enableWriteAheadLogging()，可能导致SQLite数据库锁异常。建议在构建时调用.enableWriteAheadLogging()。

3.7 调试与验证方法

1. 在build.gradle中启用room.schemaLocation，编译后检查schemas/目录下的JSON文件，确认每张表的列名、类型、索引和约束是否正确。
2. 使用Android Studio的Database Inspector（工具 → View → Tool Windows → App Inspection → Database Inspector）在运行时查看表结构和数据。
3. 编写单元测试：用Room.inMemoryDatabaseBuilder()创建内存数据库，验证DAO的增删改查和迁移逻辑。
4. 在ContentProvider的query()和insert()方法入口/出口添加日志，打印SQLite语句的执行耗时和受影响行数，便于定位跨进程性能瓶颈。

// 单元测试示例（JUnit + Room）:
@Test
public void testMigration_2_3() {
    SupportSQLiteDatabase db = helper.createDatabase(TEST_DB_NAME, 2);
    // 插入v2数据
    db.execSQL("INSERT INTO user (id, user_name, avatar_uri, created_at) " +
               "VALUES (1, 'test', 'https://example.com/avatar.png', 1000)");
    db.close();

    // 迁移到v3
    RoomDatabase.TestHelper helper_v3 = Room.databaseBuilder(
        context, AppDatabase.class, TEST_DB_NAME)
        .addMigrations(AppDatabase.MIGRATION_2_3)
        .build();
    AppDatabase db_v3 = (AppDatabase) helper_v3.getDatabase();
    User user = db_v3.userDao().getUserByIdSync(1);
    assertEquals(0, user.getAge());  // 默认值0
    db_v3.close();
}

3.8 性能考量与索引策略

跨进程场景中，每次ContentProvider调用都会触发一次DAO查询。合理的索引设计能显著减少Binder线程的等待时间。以下是为高频查询优化的索引案例：

-- 在Entity类中通过 @Index 声明复合索引
@Entity(
    tableName = "user_group",
    indices = {
        @Index(value = {"user_id", "group_id"}, unique = true),
        @Index("group_id")
    },
    foreignKeys = {
        @ForeignKey(entity = User.class, parentColumns = "id",
                    childColumns = "user_id", onDelete = ForeignKey.CASCADE),
        @ForeignKey(entity = Group.class, parentColumns = "gid",
                    childColumns = "group_id", onDelete = ForeignKey.CASCADE)
    }
)
public class UserGroup implements Parcelable {
    @PrimaryKey(autoGenerate = true)
    private long id;
    private long userId;
    private long groupId;
    // ...
}

完成本章的学习后，你已经具备了搭建生产级Room数据库层的所有关键技能。在下一阶段的课程中，我们将基于这部分构建的数据库，封装出支持跨进程增删改查的ContentProvider接口。