本文档介绍了如何将现有 Room 实现迁移到使用 Kotlin 多平台 (KMP) 的 Room 实现。
将现有 Android 代码库中的 Room 使用情况迁移到通用共享 KMP 模块的难度可能很大，具体取决于使用的 Room API 或代码库是否已使用协程。本部分针对尝试将 Room 的使用迁移到通用模块提供了一些指导和提示。
请务必先熟悉 Android 版本 Room 与 KMP 版本之间的区别和缺少的功能，以及所涉及的设置。实质上，成功迁移涉及重构 SupportSQLite* API 的用法，将其替换为 SQLite 驱动程序 API，并将 Room 声明（带 @Database 注解的类、DAO、实体等）移到通用代码中。
继续操作前，请再次查看以下信息：
以下部分将介绍成功迁移所需的各种步骤。
从支持 SQLite 迁移到 SQLite 驱动程序
androidx.sqlite.db 中的 API 仅适用于 Android，其任何用法都需要使用 SQLite 驱动程序 API 进行重构。为了实现向后兼容性，并且只要 RoomDatabase 配置了 SupportSQLiteOpenHelper.Factory（即未设置 SQLiteDriver），Room 就会处于“兼容模式”，在该模式下，支持 SQLite 和 SQLite 驱动程序 API 都会按预期运行。这样可以实现增量迁移，因此您无需在一次更改中将支持 SQLite 使用情况全部转换为 SQLite 驱动程序。
以下示例是支持 SQLite 及其对应 SQLite 驱动程序的常见用法：
支持 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 可通过 beginTransaction()、setTransactionSuccessful() 和 endTransaction() 直接在 SupportSQLiteDatabase 中使用。您也可以使用 runInTransaction() 通过 Room 使用它们。请将这些用法迁移到 SQLite 驱动程序 API。
支持 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")
}
各种回调替换也需要迁移到对应的驱动程序替换项：
支持 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 等）中时，请将 SQLiteDatabase 的使用替换为 SQLiteConnection。如果有 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 函数都需要是挂起函数。返回响应式类型的 DAO 函数（例如 LiveData 或 RxJava 的 Flowable）不应转换为挂起函数。不过，某些类型的（如 LiveData）与 KMP 不兼容。必须将具有响应式返回值类型的 DAO 函数迁移到协程流。
不兼容的 KMP 类型（来源）
@Query("SELECT * FROM Todo")
fun getTodosLiveData(): LiveData<List<Todo>>
兼容的 KMP 类型 (to)
@Query("SELECT * FROM Todo")
fun getTodosFlow(): Flow<List<Todo>>
请参阅 Android 中的数据流，开始在代码库中使用数据流。
设置协程上下文（可选）
可以视情况为 RoomDatabase 配置共享应用执行器，使用 RoomDatabase.Builder.setQueryExecutor() 来执行数据库操作。由于执行器与 KMP 不兼容，因此 Room 的 setQueryExecutor() API 不适用于常见源代码。相反，必须为 RoomDatabase 配置 CoroutineContext。您可以使用 RoomDatabase.Builder.setCoroutineContext() 设置上下文，如果未设置，则 RoomDatabase 将默认使用 Dispatchers.IO。
设置 SQLite 驱动程序
将支持 SQLite 用法迁移到 SQLite 驱动程序 API 后，必须使用 RoomDatabase.Builder.setDriver 配置驱动程序。建议使用 BundledSQLiteDriver 驱动程序。如需了解可用的驱动程序实现，请参阅驱动程序实现。
使用 RoomDatabase.Builder.openHelperFactory() 配置的自定义 SupportSQLiteOpenHelper.Factory 在 KMP 中不受支持，自定义 Open Helper 提供的功能需要使用 SQLite 驱动程序接口重新实现。
“会议室”声明
完成大多数迁移步骤后，即可将 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
}