Android 架构组件之 Room

4,503 阅读13分钟

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

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