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,添加依赖关系:

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<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 的查询是可观测的查询。也就是说,每当表格中的数据被更新时,就会收到通知。

1
2
3
4
5
@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 线程中完成,否则会出现异常:

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<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注解。

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


评论

Your browser is out-of-date!

Update your browser to view this website correctly. Update my browser now

×