将 Room 迁移到 Kotlin 多平台

本文档介绍如何将现有的 Room 实现迁移到使用 Kotlin 多平台 (KMP) 的实现。

将现有 Android 代码库中的 Room 使用情况迁移到通用的共享 KMP 模块，难度可能会有很大差异，具体取决于使用的 Room API，或代码库是否已使用协程。本节在尝试将 Room 的使用情况迁移到通用模块时提供了一些指导和提示。

首先，务必熟悉 Android 版 Room 和 KMP 版 Room 之间的差异和缺失功能，以及相关的设置。本质上，成功的迁移涉及重构 SupportSQLite* API 的使用情况，并将它们替换为 SQLite 驱动程序 API，并将 Room 声明（@Database 注释类、DAO、实体等）移到通用代码中。

在继续之前，请重新审阅以下信息

接下来的部分描述了成功迁移所需的各种步骤。

从 Support SQLite 迁移到 SQLite 驱动程序

androidx.sqlite.db 中的 API 仅限于 Android，任何使用情况都需要使用 SQLite 驱动程序 API 进行重构。为了向后兼容，只要 RoomDatabase 配置了 SupportSQLiteOpenHelper.Factory（即未设置 SQLiteDriver），Room 就会处于“兼容模式”，在这种模式下，Support SQLite 和 SQLite 驱动程序 API 都能正常工作。这使得您可以进行增量迁移，因此您不必在一处更改中将所有 Support SQLite 使用情况都转换为 SQLite 驱动程序。

以下示例是 Support SQLite 和其 SQLite 驱动程序对应物的常见使用情况

Support SQLite（从）

执行没有结果的查询

val database: SupportSQLiteDatabase = ...
database.execSQL("ALTER TABLE ...")

执行有结果但没有参数的查询

val database: SupportSQLiteDatabase = ...
database.query("SELECT * FROM Pet").use { cursor ->
  while (cusor.moveToNext()) {
    // read columns
    cursor.getInt(0)
    cursor.getString(1)
  }
}

执行有结果和参数的查询

database.query("SELECT * FROM Pet WHERE id = ?", id).use { cursor ->
  if (cursor.moveToNext()) {
    // row found, read columns
  } else {
    // row not found
  }
}

SQLite 驱动程序（到）

执行没有结果的查询

val connection: SQLiteConnection = ...
connection.execSQL("ALTER TABLE ...")

执行有结果但没有参数的查询

val connection: SQLiteConnection = ...
connection.prepare("SELECT * FROM Pet").use { statement ->
  while (statement.step()) {
    // read columns
    statement.getInt(0)
    statement.getText(1)
  }
}

执行有结果和参数的查询

connection.prepare("SELECT * FROM Pet WHERE id = ?").use { statement ->
  statement.bindInt(1, id)
  if (statement.step()) {
    // row found, read columns
  } else {
    // row not found
  }
}

数据库事务 API 可直接在 SupportSQLiteDatabase 中使用 beginTransaction()、setTransactionSuccessful() 和 endTransaction()。它们也可以通过 Room 使用 runInTransaction() 进行访问。将这些使用情况迁移到 SQLite 驱动程序 API。

Support SQLite（从）

执行事务（使用 RoomDatabase）

val database: RoomDatabase = ...
database.runInTransaction {
  // perform database operations in transaction
}

执行事务（使用 SupportSQLiteDatabase）

val database: SupportSQLiteDatabase = ...
database.beginTransaction()
try {
  // perform database operations in transaction
  database.setTransactionSuccessful()
} finally {
  database.endTransaction()
}

SQLite 驱动程序（到）

执行事务（使用 RoomDatabase）

val database: RoomDatabase = ...
database.useWriterConnection { transactor ->
  transactor.immediateTransaction {
    // perform database operations in transaction
  }
}

执行事务（使用 SQLiteConnection）

val connection: SQLiteConnection = ...
connection.execSQL("BEGIN IMMEDIATE TRANSACTION")
try {
  // perform database operations in transaction
  connection.execSQL("END TRANSACTION")
} catch(t: Throwable) {
  connection.execSQL("ROLLBACK TRANSACTION")
}

各种回调覆盖也需要迁移到其驱动程序对应物

Support SQLite（从）

迁移子类

object Migration_1_2 : Migration(1, 2) {
  override fun migrate(db: SupportSQLiteDatabase) {
    // ...
  }
}

自动迁移规范子类

class AutoMigrationSpec_1_2 : AutoMigrationSpec {
  override fun onPostMigrate(db: SupportSQLiteDatabase) {
    // ...
  }
}

数据库回调子类

object MyRoomCallback : RoomDatabase.Callback {
  override fun onCreate(db: SupportSQLiteDatabase) {
    // ...
  }

  override fun onDestructiveMigration(db: SupportSQLiteDatabase) {
    // ...
  }

  override fun onOpen(db: SupportSQLiteDatabase) {
    // ...
  }
}

SQLite 驱动程序（到）

迁移子类

object Migration_1_2 : Migration(1, 2) {
  override fun migrate(connection: SQLiteConnection) {
    // ...
  }
}

自动迁移规范子类

class AutoMigrationSpec_1_2 : AutoMigrationSpec {
  override fun onPostMigrate(connection: SQLiteConnection) {
    // ...
  }
}

数据库回调子类

object MyRoomCallback : RoomDatabase.Callback {
  override fun onCreate(connection: SQLiteConnection) {
    // ...
  }

  override fun onDestructiveMigration(connection: SQLiteConnection) {
    // ...
  }

  override fun onOpen(connection: SQLiteConnection) {
    // ...
  }
}

总而言之，当 RoomDatabase 不可用时，例如在回调覆盖中（onMigrate，onCreate 等），请用 SQLiteConnection 替换 SQLiteDatabase 的使用。如果 RoomDatabase 可用，则使用 RoomDatabase.useReaderConnection 和 RoomDatabase.useWriterConnection 访问底层数据库连接，而不是 RoomDatabase.openHelper.writtableDatabase。

将阻塞型 DAO 函数转换为挂起函数

Room 的 KMP 版本依赖于协程在配置的 CoroutineContext 上执行 I/O 操作。这意味着您需要将所有阻塞型 DAO 函数迁移到挂起函数。

阻塞型 DAO 函数（从）

@Query("SELECT * FROM Todo")
fun getAllTodos(): List<Todo>

挂起型 DAO 函数（到）

@Query("SELECT * FROM Todo")
suspend fun getAllTodos(): List<Todo>

如果现有代码库尚未包含协程，将现有 DAO 阻塞函数迁移到挂起函数可能很复杂。请参阅 Android 中的协程，以开始在代码库中使用协程。

将反应式返回类型转换为 Flow

并非所有 DAO 函数都需要是挂起函数。返回反应式类型（例如 LiveData 或 RxJava 的 Flowable）的 DAO 函数不应该转换为挂起函数。但是，某些类型（例如 LiveData）与 KMP 不兼容。具有反应式返回类型的 DAO 函数必须迁移到协程流。

与 KMP 不兼容的类型（从）

@Query("SELECT * FROM Todo")
fun getTodosLiveData(): LiveData<List<Todo>>

与 KMP 兼容的类型（到）

@Query("SELECT * FROM Todo")
fun getTodosFlow(): Flow<List<Todo>>

请参阅 Android 中的 Flow，以开始在代码库中使用 Flow。

设置协程上下文（可选）

可以使用 RoomDatabase.Builder.setQueryExecutor() 为 RoomDatabase 配置共享应用程序执行器，以执行数据库操作。由于执行器与 KMP 不兼容，因此 Room 的 setQueryExecutor() API 在通用源中不可用。相反，必须使用 CoroutineContext 配置 RoomDatabase。可以使用 RoomDatabase.Builder.setCoroutineContext() 设置上下文，如果没有设置上下文，则 RoomDatabase 将默认使用 Dispatchers.IO。

设置 SQLite 驱动程序

一旦将 Support SQLite 的使用迁移到 SQLite 驱动程序 API，就必须使用 RoomDatabase.Builder.setDriver 配置驱动程序。建议使用的驱动程序是 BundledSQLiteDriver。有关可用驱动程序实现的描述，请参阅驱动程序实现。

使用 RoomDatabase.Builder.openHelperFactory() 配置的自定义 SupportSQLiteOpenHelper.Factory 在 KMP 中不受支持，自定义打开帮助程序提供的功能需要使用 SQLite 驱动程序接口重新实现。

移动 Room 声明

完成大部分迁移步骤后，您可以将 Room 定义移动到通用源集。请注意，可以使用 expect / actual 策略来逐步移动 Room 相关定义。例如，如果无法将所有阻塞型 DAO 函数迁移到挂起函数，则可以在通用代码中声明一个 expect @Dao 注释的接口，该接口在通用代码中为空，但在 Android 中包含阻塞函数。

// shared/src/commonMain/kotlin/Database.kt

@Database(entities = [TodoEntity::class], version = 1)
abstract class AppDatabase : RoomDatabase() {
  abstract fun getDao(): TodoDao
  abstract fun getBlockingDao(): BlockingTodoDao
}

@Dao
interface TodoDao {
    @Query("SELECT count(*) FROM TodoEntity")
    suspend fun count(): Int
}

@Dao
expect interface BlockingTodoDao

// shared/src/androidMain/kotlin/BlockingTodoDao.kt

@Dao
actual interface BlockingTodoDao {
    @Query("SELECT count(*) FROM TodoEntity")
    fun count(): Int
}