Room（Kotlin 多平台）

Room 持久性库在 SQLite 上提供了一个抽象层，让用户能够在充分利用 SQLite 的强大功能的同时，获享更强健的数据库访问机制。本页重点介绍如何在 Kotlin Multiplatform (KMP) 项目中使用 Room。如需详细了解如何使用 Room，请参阅使用 Room 将数据保存到本地数据库或我们的官方示例。

设置依赖项

目前支持 KMP 的 Room 版本为 2.7.0-alpha01 或更高版本。

如需在 KMP 项目中设置 Room，请在模块的 build.gradle.kts 文件中添加工件的依赖项：

• androidx.room:room-gradle-plugin - 用于配置 Room 架构的 Gradle 插件
• androidx.room:room-compiler - 用于生成代码的 KSP 处理器
• androidx.room:room-runtime - 库的运行时部分
• androidx.sqlite:sqlite-bundled -（可选）捆绑的 SQLite 库

此外，您还需要配置 Room 的 SQLite 驱动程序。这些驱动程序因目标平台而异。如需了解可用驱动程序实现的说明，请参阅驱动程序实现。

如需了解更多设置信息，请参阅以下内容：

• 使用 Room Gradle 插件设置架构位置。
• 将 KSP 与 Kotlin Multiplatform 搭配使用。
• 添加运行时依赖项。

警告： 如果您使用的是 Kotlin 1.9.x 版，则必须将 kotlin.native.disableCompilerDaemon = true 属性添加到 gradle.properties 配置文件，以便 Room 的 KSP 处理器正常运行。使用 Kotlin 2.0 或更高版本时，不需要此属性。如需了解详情，请参阅 https://youtrack.jetbrains.com/issue/KT-65761。

定义数据库类

您需要创建一个带有 @Database 注解的数据库类，以及共享 KMP 模块的公共源代码集中的 DAO 和实体。将这些类放置在公共源代码中，便可在所有目标平台之间共享这些类。

使用接口 RoomDatabaseConstructor 声明 expect 对象时，Room 编译器会生成 actual 实现。Android Studio 可能会发出警告 "Expected object 'AppDatabaseConstructor' has no actual declaration in module"；您可以使用 @Suppress("NO_ACTUAL_FOR_EXPECT") 抑制该警告。

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

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

// The Room compiler generates the `actual` implementations.
@Suppress("NO_ACTUAL_FOR_EXPECT")
expect object AppDatabaseConstructor : RoomDatabaseConstructor<AppDatabase> {
    override fun initialize(): AppDatabase
}

@Dao
interface TodoDao {
  @Insert
  suspend fun insert(item: TodoEntity)

  @Query("SELECT count(*) FROM TodoEntity")
  suspend fun count(): Int

  @Query("SELECT * FROM TodoEntity")
  fun getAllAsFlow(): Flow<List<TodoEntity>>
}

@Entity
data class TodoEntity(
  @PrimaryKey(autoGenerate = true) val id: Long = 0,
  val title: String,
  val content: String
)

请注意，您可以选择使用实际 / 预期声明来创建特定于平台的 Room 实现。例如，您可以使用 expect 添加在通用代码中定义的平台专用 DAO，然后在平台专用源代码集中使用其他查询指定 actual 定义。

创建数据库构建器

您需要定义一个数据库构建器，以便在每个平台上实例化 Room。由于文件系统 API 存在差异，因此这是 API 中唯一需要在平台专用源代码集中的部分。例如，在 Android 中，通常通过 Context.getDatabasePath() API 获取数据库位置，而在 iOS 中，则使用 NSFileManager 获取数据库位置。

Android

如需创建数据库实例，请指定上下文以及数据库路径。

// shared/src/androidMain/kotlin/Database.kt

fun getDatabaseBuilder(ctx: Context): RoomDatabase.Builder<AppDatabase> {
  val appContext = ctx.applicationContext
  val dbFile = appContext.getDatabasePath("my_room.db")
  return Room.databaseBuilder<AppDatabase>(
    context = appContext,
    name = dbFile.absolutePath
  )
}

iOS

如需创建数据库实例，请使用 NSFileManager 提供数据库路径，该路径通常位于 NSDocumentDirectory 中。

// shared/src/iosMain/kotlin/Database.kt

fun getDatabaseBuilder(): RoomDatabase.Builder<AppDatabase> {
    val dbFilePath = documentDirectory() + "/my_room.db"
    return Room.databaseBuilder<AppDatabase>(
        name = dbFilePath,
    )
}

private fun documentDirectory(): String {
  val documentDirectory = NSFileManager.defaultManager.URLForDirectory(
    directory = NSDocumentDirectory,
    inDomain = NSUserDomainMask,
    appropriateForURL = null,
    create = false,
    error = null,
  )
  return requireNotNull(documentDirectory?.path)
}

JVM（桌面设备）

如需创建数据库实例，请使用 Java 或 Kotlin API 提供数据库路径。

// shared/src/jvmMain/kotlin/Database.kt

fun getDatabaseBuilder(): RoomDatabase.Builder<AppDatabase> {
    val dbFile = File(System.getProperty("java.io.tmpdir"), "my_room.db")
    return Room.databaseBuilder<AppDatabase>(
        name = dbFile.absolutePath,
    )
}

缩减和混淆

如果项目经过缩减或混淆处理，则必须添加以下 ProGuard 规则，以便 Room 能够找到数据库定义的生成实现：

-keep class * extends androidx.room.RoomDatabase { <init>(); }

数据库实例化

从特定于平台的构造函数之一获取 RoomDatabase.Builder 后，您可以在常规代码中配置 Room 数据库的其余部分以及实际数据库实例化。

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

fun getRoomDatabase(
    builder: RoomDatabase.Builder<AppDatabase>
): AppDatabase {
  return builder
      .addMigrations(MIGRATIONS)
      .fallbackToDestructiveMigrationOnDowngrade()
      .setDriver(BundledSQLiteDriver())
      .setQueryCoroutineContext(Dispatchers.IO)
      .build()
}

选择 SQLiteDriver

前面的代码段使用了 BundledSQLiteDriver。这是推荐的驱动程序，包含从源代码编译的 SQLite，可在所有平台上提供最一致且最新版本的 SQLite。如果您想使用操作系统提供的 SQLite，请在指定平台专用驱动程序的平台专用源代码集中使用 setDriver API。对于 Android，您可以使用 AndroidSQLiteDriver，对于 iOS，您可以使用 NativeSQLiteDriver。如需使用 NativeSQLiteDriver，您需要提供链接器选项，以便 iOS 应用与系统 SQLite 进行动态链接。

// shared/build.gradle.kts

kotlin {
    listOf(
        iosX64(),
        iosArm64(),
        iosSimulatorArm64()
    ).forEach { iosTarget ->
        iosTarget.binaries.framework {
            baseName = "TodoApp"
            isStatic = true
            // Required when using NativeSQLiteDriver
            linkerOpts.add("-lsqlite3")
        }
    }
}

差异

Room 最初是作为 Android 库开发的，后来迁移到了 KMP，重点是 API 兼容性。不同平台的 Room KMP 版本与 Android 专用版本略有不同。这些差异如下所列和所述。

屏蔽 DAO 函数

使用 Room for KMP 时，除响应式返回类型（例如 Flow）外，为非 Android 平台编译的所有 DAO 函数都需要是 suspend 函数。

// shared/src/commonMain/kotlin/MultiplatformDao.kt

@Dao
interface MultiplatformDao {
  // ERROR: Blocking function not valid for non-Android targets
  @Query("SELECT * FROM Entity")
  fun blockingQuery(): List<Entity>

  // OK
  @Query("SELECT * FROM Entity")
  suspend fun query(): List<Entity>

  // OK
  @Query("SELECT * FROM Entity")
  fun queryFlow(): Flow<List<Entity>>

  // ERROR: Blocking function not valid for non-Android targets
  @Transaction
  fun blockingTransaction() { // … }

  // OK
  @Transaction
  suspend fun transaction() { // … }
}

Room 受益于 Kotlin 为多平台提供的功能丰富的异步 kotlinx.coroutines 库。为了实现最佳功能，系统会强制为在 KMP 项目中编译的 DAO 使用 suspend 函数，但 Android 专用 DAO 除外，以便与现有代码库保持向后兼容性。

与 KMP 的功能差异

本部分介绍了 KMP 版和 Android 平台版 Room 之间的功能差异。

@RawQuery DAO 函数

针对非 Android 平台编译且带有 @RawQuery 注解的函数需要声明类型为 RoomRawQuery 的形参，而不是 SupportSQLiteQuery。

@Dao
interface TodoDao {
  @RawQuery
  suspend fun getTodos(query RoomRawQuery): List<TodoEntity>
}

然后，您可以使用 RoomRawQuery 在运行时创建查询：

suspend fun getTodosWithLowercaseTitle(title: String): List<TodoEntity> {
  val query = RoomRawQuery(
    sql = "SELECT * FROM TodoEntity WHERE title = ?"
    onBindStatement = {
      it.bindText(1, title.lowercase())
    }
  )
  return todosDao.getTodos(query)
}

查询回调

用于配置查询回调的以下 API 在通用平台中不可用，因此在 Android 以外的平台中也不可用。

• RoomDatabase.Builder.setQueryCallback
• RoomDatabase.QueryCallback

我们打算在未来的 Room 版本中添加对查询回调的支持。

用于使用查询回调 RoomDatabase.Builder.setQueryCallback 配置 RoomDatabase 的 API 以及回调接口 RoomDatabase.QueryCallback 在通用平台中不可用，因此在 Android 以外的其他平台中也不可用。

自动关闭数据库

用于在超时后启用自动关闭的 API RoomDatabase.Builder.setAutoCloseTimeout 仅适用于 Android，不适用于其他平台。

预打包数据库

以下用于使用现有数据库（即预打包数据库）创建 RoomDatabase 的 API 在 common 中不可用，因此在 Android 以外的其他平台上也不可用。这些 API 具有以下特点：

• RoomDatabase.Builder.createFromAsset
• RoomDatabase.Builder.createFromFile
• RoomDatabase.Builder.createFromInputStream
• RoomDatabase.PrepackagedDatabaseCallback

我们打算在未来的 Room 版本中添加对预打包数据库的支持。

多实例失效

用于启用多实例失效的 API RoomDatabase.Builder.enableMultiInstanceInvalidation 仅适用于 Android，不适用于常见平台或其他平台。