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 图(非必须)；
1. 添加对 Room 的依赖；
1. 创建数据库实体 Entity；
1. 创建数据库访问的 DAO；
1. 创建数据库 Database；
1. 封装数据库与业务逻辑交互的 Repository；
1. 创建数据库中使用到的类型转换器；
1. 考虑数据库迁移；
1. 数据库的测试。

接下来，我们将分别从这几个步骤，介绍 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
}

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

序号	注解名称	描述
1	@Entity	声明所标记的类是一个数据表，@Entity 包括的参数有：tableName(表名），indices（表的索引），primaryKeys（主键），foreignKeys（外键），ignoredColumns（忽略实体中的属性，不作为数据表中的字段），inheritSuperIndices（是否集成父类的索引，默认 false）
2	@ColumnInfo	用来声明数据库中的字段名
3	@PrimaryKey	被修饰的属性作为数据表的主键，@PrimaryKey 包含一个参数：autoGenerate(是否允许自动创建，默认false)
4	@Embedded	用来修饰嵌套字段，被修饰的属性中的所有字段都会存在数据表中

关于@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 框架还包括以下的注解：

序号	注解名称	描述
1	@ColumnInfo.SQLiteTypeAffinity	可以在typeAffinity（）中使用的SQLite列类型常量，包括：UNDEFINED, TEXT, INTEGER, REAL, BLOB，其中 UNDEFINED 未定义类型关联，将根据类型解析；TEXT SQLite列类型为 String；INTEGER SQLite列类型为 Integer 或 Boolean; REAL SQLite列类型为 Float 或 Double；BLOB SQLite列类型为二进制类型
2	@Dao	将类标记为数据访问对象（Data Access Object）
3	@Database	将类标记为RoomDatabase
4	@Delete	将 DAO 中的方法标记为与删除相关的方法
5	@Embedded	可以用作实体或Pojo字段上的注释，以指示嵌套字段
6	@ForeignKey	在另一个实体上声明外键
7	@ForeignKey.Action	可以在onDelete（）和onUpdate（）中使用的值的常量定义。包括：NO_ACTION, RESTRICT, SET_NULL, SET_DEFAULT, CASCADE
8	@Ignore	忽略Room的处理逻辑中标记的元素
9	@Index	声明实体的索引
10	@Insert	将Dao注释类中的方法标记为插入方法
11	@OnConflictStrategy	Dao方法处理冲突的策略集合，包括：REPLACE, ROLLBACK, ABORT,FAIL,IGNORE，其中ROLLBACK和FAIL已经被标记为@Deprecated，REPLACE用新的数据行替换旧的数据行；ABORT直接回滚冲突的事务；IGNORE保持现有数据行。
12	@PrimaryKey	将实体中的字段标记为主键
13	@Query	将Dao注释类中的方法标记为查询方法
14	@RawQuery	将Dao注释类中的方法标记为原始查询方法，可以将查询作为SupportSQLiteQuery传递
15	@Relation	一个方便的注释，可以在Pojo中用于自动获取关系实体。
16	@SkipQueryVerification	跳过带注释元素的数据库验证
17	@Transaction	将Dao类中的方法标记为事务方法
18	@TypeConverter	将方法标记为类型转换器
19	@TypeConverters	指定Room可以使用的其他类型转换器
20	@Update	将Dao注释类中的方法标记为更新方法

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 的组成和实现原理，按照惯例我们梳理了一张类图：

android_compoment_room_CD.jpg_watermarkl

在类图中，画出了我们常用的一些注解，按照数据库、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