Android 架构组件之 Room

Room 是 Google 推出的一个在 SQLite 上提供抽象层的持久存储库。本文将从以下几个方面对 Room 进行介绍：

• 为什么要使用 Room？
• 通过一个案例，介绍如何使用 Room
• 分析 Room 的组成及使用原理
• 总结一下 Room 的使用

1. 为什么要使用 Room？

在 Android 中直接使用 SQLite 数据库存在多个缺点：

• 必须编写大量的样板代码；
• 必须为编写的每一个查询实现对象映射；
• 很难实施数据库迁移；
• 很难测试数据库；
• 如果不小心，很容易在主线程上执行长时间运行的操作。

为了解决这些问题，Google 创建了 Room，一个在 SQLite 上提供抽象层的持久存储库。

Room 是一个稳健的、基于对象关系映射(ORM)模型的、数据库框架。Room 提供了一套基于 SQLite 的抽象层，在完全实现 SQLite 全部功能的同时实现更强大的数据库访问。

针对 SQLite数据库的上述缺点，Room 框架具有如下特点：

• 由于使用了动态代理，减少了样板代码；
• 在 Room 框架中使用了编译时注解，在编译过程中就完成了对 SQL 的语法检验；
• 相对方便的数据库迁移；
• 方便的可测试性；
• 保持数据库的操作远离了主线程。
• 此外 Room 还支持 RxJava2 和 LiveData。

2. 通过一个案例，介绍如何使用 Room

介绍 Room 先从一个真实的案例开始，我们从最开始的 ER 图的设计，到数据库的增删改查操作，到考虑数据库的迁移上线。

总结起来，这个使用 Room 框架的案例要经历以下几个过程：

• 1. 设计数据库的 ER 图(非必须)；
• 2. 添加对 Room 的依赖；
• 3. 创建数据库实体 Entity；
• 4. 创建数据库访问的 DAO；
• 5. 创建数据库 Database；
• 6. 封装数据库与业务逻辑交互的 Repository；
• 7. 创建数据库中使用到的类型转换器；
• 8. 考虑数据库迁移；
• 9. 数据库的测试。

接下来，我们将分别从这几个步骤，介绍 Room 的使用。

2.1 数据库 ER 图

我们要完成将 NBA 的球队和球员信息存储到数据库中，具体涉及到两张表，球队表（team）和球员表（player），为了能够筛选出各项数据指标靠前的球员，我们又创建了一张明星球员表（star），三张表的 ER 图如下：

其中：

• 一个球队拥有多名球员；
• 一名球星属于某支球队，球星表中的球星可以来自多只不同的球队；
• 球星是从球员中选择出来的。

2.2 添加 Room 的依赖

明确了三张数据表之间的关系之后，我们开始引入 Room，添加依赖关系：

implementation "androidx.room:room-runtime:$rootProject.roomVersion"
implementation "androidx.room:room-ktx:$rootProject.roomVersion"
kapt "androidx.room:room-compiler:$rootProject.roomVersion"

由于 Room框架中使用了注解处理器，因此需要使用 kapt 依赖，需要在 build.gradle 文件中引入 kapt 插件。

apply plugin: 'kotlin-kapt'

如果是 Java工程，需要使用 annotationProcessor 关键字。

这里我们使用官方最新的版本2.1.0。

roomVersion : '2.1.0',

2.3 创建实体

开始创建实体（数据表）这里以 Player 为例：

/**
 * 球员表
 */
@Entity(tableName = "player")
data class PlayerModel(
    @ColumnInfo(name = "player_code") var code: String,
    @ColumnInfo(name = "player_country") var country: String, //国家
    @ColumnInfo(name = "player_country_en") var countryEn: String,//国家英文名称
    @ColumnInfo(name = "player_display_name") var displayName: String,//球员名称
    @ColumnInfo(name = "player_display_name_en") var displayNameEn: String,//球员英文名称
    @ColumnInfo(name = "player_dob") var dob: Calendar = Calendar.getInstance(),//出生日期
    ...
    @ColumnInfo(name = "player_team_name") var teamName: String,//所属球队
    @Embedded var statAverage: StatAverageModel,//平均数据
    @Embedded var statTotal: StatTotalModel//总数据
) {
    @PrimaryKey(autoGenerate = true)
    @ColumnInfo(name = "id")
    var id: Long = 0
}

这里用到了几个注解，说明一下：

关于@Embedded的进一步说明，我们的 Player实体中有两个被@Embedded修饰的属性，我们看其中的一个statTotal，它的类型是StatTotalModel，用来描述球员的数据。

/**
 * 总数据
 */
data class StatTotalModel(
    var assists: Int,//助攻
    var blocks: Int,//盖帽
    var defRebs: Int,//防守篮板
    var fga: Int,
    var fgm: Int,
    var fgpct: Float,
    var fouls: Int,//犯规
    var fta: Int,
    var ftm: Int,
    var ftpct: Float,
    var mins: Int,//上场时间
    var offRebs: Int,//进攻篮板
    var points: Int,//得分
    var rebs: Int,//总篮板
    var secs: Int,
    var steals: Int,//抢断
    var tpa: Int,
    var tpm: Int,
    var tppct: Float,
    var turnovers: Int//失误
)

通常情况下将这些数据存储在数据库中有两种方式：

• 新建一张StatTotalModel表，用 Player 表的 id 作为外键，与 Player表进行一一关联；
• 将StatTotalModel实体中的字段存储在 Player 表中，这种方式减少了数据表的创建，也减少了联合查询的复杂程度。

如果直接将这些字段打散在 Player 表中，显得不够面向对象，这时就可以使用@Embedded注解，即显得面向对象，又不用再创建数据表，非常的优雅。

除了上面说的注解，Room 框架还包括以下的注解：

2.4 创建 Dao

我们开始创建数据访问对象层 Dao，在这里我们需要定义一些对数据库增删改查的方法。

具体来说，就是创建一个使用@Dao 注释的接口。并在其上声明使用该数据库所需的所有函数，并编写相应的 SQL 查询语句，Room 将为你实现这些函数，并在单次事务中运行它们，Room 支持的查询语句包括：插入、更新、删除和查询。查询语句会在编译时被校验，这意味着，如果你编写了一个无效的应用，你会立刻发现错误。

来看 Player 的 Dao：

@Dao
interface PlayerDao {
    @Insert(onConflict = OnConflictStrategy.REPLACE)
    fun insertPlayer(player: PlayerModel)

    @Delete
    fun deletePlayers(players: List<PlayerModel>)

    @Update
    fun updatePlayers(players: List<PlayerModel>)

    @Query("SELECT * FROM player WHERE id=:id")
    fun findPlayerById(id: Long): PlayerModel?
    ……
}

对数据表的增删改查方法对应的注解分别是@Insert、@Delete、@Update和 @Query，其中:

• @Insert、@Update 可设置参数onConflict，处理数据冲突时采取的策略，可以设置包括：REPLACE, ROLLBACK, ABORT,FAIL,IGNORE五种策略，其中ROLLBACK和FAIL已经被标记为@Deprecated，这里只介绍三种策略，REPLACE用新的数据行替换旧的数据行；ABORT直接回滚冲突的事务；IGNORE保持现有数据行。
• @Query 中声明我们要查询的 SQL 语句，使用@Query不仅成完成查，还能进行增删改的操作。

这些查询都是同步的，也就是说，这些查询将在你触发查询的同一个线程上运行。如果这是主线程，你的应用将崩溃，并显示 IllegalStateException，因此，请使用在 Android 中推荐的线程处理方法，并确保其远离主线程。

当使用 LiveData 或 RxJava 时，Room 也支持异步查询，更重要的是，返回 LiveData 或 Flowable 的查询是可观测的查询。也就是说，每当表格中的数据被更新时，就会收到通知。

    @Query("SELECT * FROM player WHERE id=:id")
    fun findPlayerByIdLD(id: Long): LiveData<PlayerModel>

    @Query("SELECT * FROM player WHERE player_team_name=:teamName")
    fun findPlayersByTeamLD(teamName: String): LiveData<List<PlayerModel>>

2.5 创建数据库

将实体和 DAO整合在一起的类是 RoomDatabase，先创建一个扩展 RoomDatabase 的抽象类，对它进行注释，声明实体和相应的 DAO。

数据库的创建是一件非常消耗资源的工作，所以我们将数据库设计为单例，避免创建多个数据库对象。另外对数据库的操作都不能放在 UI 线程中完成，否则会出现异常：

Cannot access database on the main thread since it may potentially lock the UI for a long period of time.

给出我们设计的数据库：

@Database(entities = [PlayerModel::class, TeamModel::class], version = 1, exportSchema = false)
@TypeConverters(Converters::class)
abstract class NBADatabase : RoomDatabase() {

    abstract fun playerDao(): PlayerDao
    abstract fun teamDao(): TeamDao

    companion object {
        @Volatile
        private var INSTANCE: NBADatabase? = null

        fun getInstance(context: Context): NBADatabase {
            return INSTANCE ?: synchronized(this) {
                Room.databaseBuilder(
                    context.applicationContext,
                    NBADatabase::class.java,
                    "nba_db"
                ).addCallback(object : RoomDatabase.Callback() {
                    override fun onCreate(db: SupportSQLiteDatabase) {
                        super.onCreate(db)
                    }

                    override fun onOpen(db: SupportSQLiteDatabase) {
                        super.onOpen(db)
                    }
                }).build().also {
                    INSTANCE = it
                }
            }
        }
    }
}

在创建数据库时需要完成以下几件工作：

• 设计成单例模式，避免创建多个数据库对象消耗资源；
• 创建的数据库类需要继承 RoomDatabase，数据库类声明为抽象类；
• 需要提供方法来获取数据访问对象层(Dao)对象，方法声明为抽象方法；
• 数据库类需要使用@Database注解，@Database包括几个参数：entities（数据库包含的数据表，@entities注解修饰的实体），default（数据库包含的视图），version（数据库的版本号），exportSchema（可以理解为开关，如果开关为 true，Room 框架会通过注解处理器将一些数据库相关的schema输出到指定的目录中，默认 true）

2.6 封装 Repository

先给出封装的与 Player 相关的 Repository：

class PlayerRepository(private val playerDao: PlayerDao) {

    @WorkerThread
    suspend fun insert(players: List<PlayerModel>) {
        playerDao.insertPlayers(players)
    }

    fun findAllPlayers():List<PlayerModel>{
        return playerDao.findAllPlayers()
    }
}

这里只定义了两个方法，insert()用来插入数据，findAllPlayers()查询所有的 Player，可以根据业务逻辑的需要，在Repository中添加方法。

最后调用PlayerRepository中的方法，完成将 NBA 球队和球员信息存储到数据库中。

2.7 类型转换器@TypeConverter

在我们的球员实体PlayerModel中，球员的出生日期 dob类型是 Calendar 类型，但是 SQLite 只支持 5 中类型，分别是NULL、INTEGER、REAL、TEXT和BLOB，这时可以用到@TypeConverters注解。

class Converters {
    @TypeConverter
    fun calendarToDatestamp(calendar: Calendar): Long = calendar.timeInMillis

    @TypeConverter
    fun datestampToCalendar(value: Long): Calendar =
        Calendar.getInstance().apply { timeInMillis = value }
}

在数据库中添加该注解

@TypeConverters(Converters::class)

2.8 数据库迁移 Migration

如果要进行数据库迁移操作，需要在 Database 类中执行以下操作：

首先更新你的数据库版本。

@Database(entities = {User.class}, version = 2)
abstract class MyDatabase extends RoomDatabase {
    public abstract UserDao getUserDao();
}

其次，实现一个 Migration 类，定义如何处理从旧版本到新版本的迁移：

static final Migration MIGRATION_1_2 = new Migration(1, 2)

    @Override
    public void migrate(SupportSQLiteDatabase database) {
        database.execSQL("ALTER TABLE users" +
                "ADD COLUMN address STRING");
    }

第三，将此 Migration 类添加为 Database 构建器的一个参数，

Room.databaseBuilder(context.getApplicationContext(),
    MyDatabase.class,"sample.db").addMigrations(MIGRATION_1_2).build();

当触发迁移后，Room 将为你验证 Schema，以确保迁移已正确完成。

2.9 数据库的测试

我们创建了实体、DAO、数据库和迁移，那么应该怎样对他们进行测试呢？

要测试 DAO，需要实现 AndroidJunitTest 来创建一个内存数据库，内存数据库仅会在进程处于活动状态时保留数据，也就是说，每次测试后，数据库都将被清除。

@RunWith(AndroidJunit4.class)
    public class UserDaoTest {
        private UserDatabase database;

        @Before
        public void initDb() throws Exception {
            database = Room.inMemoryDatabaseBuilder(
                    InstrumentationRegistry.getContext(),
                    UsersDatabase.class).build();
        }

        @After
        public void closeDb() throws Exception {
            database.close();
        }
    }

要测试异步查询，请添加测试规则 InstantTaskExecutorRule，以同步执行每个任务。

@RunWith(AndroidJUnit4.class)
    public class UserDaoTest{
        @Rule
        public InstantTaskExecutorRule rule = new InstantTaskExecutorRule();
    }

在应用的实现中，你最终会在其他类中引用 DAO，要对这些类进行单元测试，只需借助想 Mockito 之类的框架来模拟 DAO。

public class UsersRepository {
        private final UserDao userDao;

        public UsersRepository(UserDao userDao) {
            this.userDao = userDao;
        }
    }

还有一点，扩展 CountingTaskExecutorRule，并在 Espresso 测试中使用它，以便在任务开始和结束时进行计数。

@Rule
public CountingTaskExecutorRule rule = new CountingTaskExecutorRule();

最后，不要忘了迁移测试。我们有另一个非常方便的测试规则 MigrationTestHelper。它允许你使用旧版本创建数据库，然后运行和验证迁移。你只需检查在旧版本中插入的数据在迁移后是否仍然存在。

public MigrationTestHelper testHelper = new MigrationTestHelper(
            InstrumentationRegistry.getInstrumentation(),
            MyDatabase.class.getCanonicalName(),
            new FrameworkSQLiteOpenHelperFactory()
    )

3. 分析 Room 的组成及使用原理

下面我们来分析一下 Room 的组成和实现原理，按照惯例我们梳理了一张类图：

在类图中，画出了我们常用的一些注解，按照数据库、DAO 和实体进行了不同颜色的区分。如果想要了解，Room 是怎样通过注解，实现的数据库创建、SQL语句的生成，可能需要了解动态代理技术和注解处理器的相关知识。

• 动态代理技术
• 注解处理器

再来Room 的原理，Room 实际上是在 SQLite 上，进行了封装，通过注解的方式，方便开发者。

从图中我们可以清晰的看到 Room 各个组成部分（Database、Dao 和 Entity）之间是如何协同工作的，总结起来就是：

• 首先创建数据库，创建的数据库类需要继承 RoomDatabase，并且提供获取 Dao 的抽象方法，Room 框架的注解处理器会实现生成 Dao 的具体方法。
• 在 Dao 中，我们会声明一些操作具体数据库表的增删改查的方法，利用这些方法，就可以操作一些具体的实体 Entity。
• 得到了实体 Entity，就可以处理一些与 app 数据相关的业务逻辑了。

4. 总结一下 Room 的使用

上面通过一个完成的案例，介绍了 Room 的使用，从最初的设计 ER 图开始，通过创建实体、创建 Dao、创建数据库、封装 Repository，如果需要数据类型转换，要使用 @TypeConverter 注解，如果涉及到数据的迁移，还要用到 Migration 类。

Room 框架具有减少样板代码、编译时校验查询、轻松实现迁移、高度的可测试性、让数据库操作远离主线程。Room 的所有这些特性，让使用数据库变得更轻松愉快，从而帮你我们开发更优质的应用。

更多内容，可以订阅 我的博客

参考链接

Save data in a local database using Room
Understanding migrations with Room