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 框架的案例要经历以下几个过程：
-
- 设计数据库的 ER 图(非必须)；
-
- 添加对 Room 的依赖；
-
- 创建数据库实体 Entity；
-
- 创建数据库访问的 DAO；
-
- 创建数据库 Database；
-
- 封装数据库与业务逻辑交互的 Repository；
-
- 创建数据库中使用到的类型转换器；
-
- 考虑数据库迁移；
-
- 数据库的测试。
接下来，我们将分别从这几个步骤，介绍 Room 的使用。
2.1 数据库 ER 图
我们要完成将 NBA 的球队和球员信息存储到数据库中，具体涉及到两张表，球队表（team）和球员表（player），为了能够筛选出各项数据指标靠前的球员，我们又创建了一张明星球员表（star），三张表的 ER 图如下：
其中：
- 一个球队拥有多名球员；
- 一名球星属于某支球队，球星表中的球星可以来自多只不同的球队；
- 球星是从球员中选择出来的。
2.2 添加 Room 的依赖
明确了三张数据表之间的关系之后，我们开始引入 Room，添加依赖关系：
1 2 3 |
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 插件。
1 |
apply plugin: 'kotlin-kapt' |
如果是 Java工程，需要使用 annotationProcessor 关键字。
这里我们使用官方最新的版本2.1.0。
1 |
roomVersion : '2.1.0', |
2.3 创建实体
开始创建实体（数据表）这里以 Player 为例：
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
/**
* 球员表
*/
@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，用来描述球员的数据。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
/**
* 总数据
*/
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：
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
@Dao
interface PlayerDao {
@Insert(onConflict = OnConflictStrategy.REPLACE)
fun insertPlayer(player: PlayerModel)
@Delete
fun deletePlayers(players: List |
对数据表的增删改查方法对应的注解分别是@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 的查询是可观测的查询。也就是说，每当表格中的数据被更新时，就会收到通知。
1 2 3 4 5 |
@Query("SELECT * FROM player WHERE id=:id")
fun findPlayerByIdLD(id: Long): LiveData |
2.5 创建数据库
将实体和 DAO整合在一起的类是 RoomDatabase，先创建一个扩展 RoomDatabase 的抽象类，对它进行注释，声明实体和相应的 DAO。
数据库的创建是一件非常消耗资源的工作，所以我们将数据库设计为单例，避免创建多个数据库对象。另外对数据库的操作都不能放在 UI 线程中完成，否则会出现异常：
1 |
Cannot access database on the main thread since it may potentially lock the UI for a long period of time. |
给出我们设计的数据库：
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 |
@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：
1 2 3 4 5 6 7 8 9 10 11 |
class PlayerRepository(private val playerDao: PlayerDao) {
@WorkerThread
suspend fun insert(players: List |
这里只定义了两个方法，insert()用来插入数据，findAllPlayers()查询所有的 Player，可以根据业务逻辑的需要，在Repository中添加方法。
最后调用PlayerRepository中的方法，完成将 NBA 球队和球员信息存储到数据库中。
2.7 类型转换器@TypeConverter
在我们的球员实体PlayerModel中，球员的出生日期 dob类型是 Calendar 类型，但是 SQLite 只支持 5 中类型，分别是NULL、INTEGER、REAL、TEXT和BLOB，这时可以用到@TypeConverters注解。
1 2 3 4 5 6 7 8 |
class Converters {
@TypeConverter
fun calendarToDatestamp(calendar: Calendar): Long = calendar.timeInMillis
@TypeConverter
fun datestampToCalendar(value: Long): Calendar =
Calendar.getInstance().apply { timeInMillis = value }
}
|
在数据库中添加该注解
1 |
@TypeConverters(Converters::class) |
2.8 数据库迁移 Migration
如果要进行数据库迁移操作，需要在 Database 类中执行以下操作：
首先更新你的数据库版本。
1 2 3 4 |
@Database(entities = {User.class}, version = 2)
abstract class MyDatabase extends RoomDatabase {
public abstract UserDao getUserDao();
}
|
其次，实现一个 Migration 类，定义如何处理从旧版本到新版本的迁移：
1 2 3 4 5 6 7 |
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 构建器的一个参数，
1 2 |
Room.databaseBuilder(context.getApplicationContext(),
MyDatabase.class,"sample.db").addMigrations(MIGRATION_1_2).build();
|
当触发迁移后，Room 将为你验证 Schema，以确保迁移已正确完成。
2.9 数据库的测试
我们创建了实体、DAO、数据库和迁移，那么应该怎样对他们进行测试呢？
要测试 DAO，需要实现 AndroidJunitTest 来创建一个内存数据库，内存数据库仅会在进程处于活动状态时保留数据，也就是说，每次测试后，数据库都将被清除。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
@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，以同步执行每个任务。
1 2 3 4 5 |
@RunWith(AndroidJUnit4.class)
public class UserDaoTest{
@Rule
public InstantTaskExecutorRule rule = new InstantTaskExecutorRule();
}
|
在应用的实现中，你最终会在其他类中引用 DAO，要对这些类进行单元测试，只需借助想 Mockito 之类的框架来模拟 DAO。
1 2 3 4 5 6 7 |
public class UsersRepository {
private final UserDao userDao;
public UsersRepository(UserDao userDao) {
this.userDao = userDao;
}
}
|
还有一点，扩展 CountingTaskExecutorRule，并在 Espresso 测试中使用它，以便在任务开始和结束时进行计数。
1 2 |
@Rule public CountingTaskExecutorRule rule = new CountingTaskExecutorRule(); |
最后，不要忘了迁移测试。我们有另一个非常方便的测试规则 MigrationTestHelper。它允许你使用旧版本创建数据库，然后运行和验证迁移。你只需检查在旧版本中插入的数据在迁移后是否仍然存在。
1 2 3 4 5 |
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
- 本文标题：Android 架构组件之 Room
- 本文作者：GT
- 发布时间：2019-11-30
- 版权声明：本博客所有文章除特别声明外，均采用 CC BY-NC-SA 4.0 许可协议。转载请注明出处！