Realm Kotlin for Kotlin: 完整指南与示例

\n\n

1. 什么是 Realm Kotlin？为什么需要它？

Realm Kotlin 是一个现代、快速且面向对象的移动数据库，专为 Kotlin Multiplatform (KMP) 生态系统而构建。与 SQLite 或 Room 等传统解决方案不同，Realm 不处理表和行，而是直接处理 Kotlin 对象。这意味着您可以像处理普通类一样处理数据，无需编写 SQL 查询或手动映射数据。Realm Kotlin 是流行的 Realm Java 库的直接继承者，但为 Kotlin 从头重写，支持协程、Flow 和多平台（Android、iOS、macOS、JVM）。

为什么需要它？首先，是为了加速移动应用程序的开发。Realm 减少了处理本地存储时的样板代码。您只需声明一个数据模型，Realm 就会自动生成保存、读取、更新和删除对象所需的一切。凭借对响应式流（来自 kotlinx.coroutines 库的 Flow）的内置支持，数据库中的任何更改都会立即反映在 UI 中，这使其非常适合 MVVM 架构。Realm 还以其高性能而闻名：它运行在自己的 C++ 引擎上，提供接近原生的读写速度。

主要使用场景：缓存服务器数据、离线工作、存储复杂的嵌套结构（例如，网上商店的购物车或聊天记录）、通过 Realm Sync（MongoDB Atlas 云服务）在设备之间同步数据。Realm Kotlin 不仅仅是“另一个 ORM”，它是一个完整的数据库引擎，改变了应用程序中状态管理的方式。

\n\n

2. 安装

Realm Kotlin 通过 Gradle 构建系统安装。由于该库针对 Kotlin Multiplatform，其配置与标准的 Android 依赖项略有不同。

重要提示： Realm Kotlin 不能通过 pip (Python) 或 npm (JavaScript) 安装。它是一个用于 JVM/Android/iOS 的原生库。

将以下代码添加到您的根 build.gradle.kts 文件（项目级别）：

// 根 build.gradle.kts\nplugins {\n    id("io.realm.kotlin") version "1.16.0" apply false\n}

然后，在您模块的 build.gradle.kts 文件（app 或 shared）中：

// 模块的 build.gradle.kts\nplugins {\n    kotlin("multiplatform")\n    id("io.realm.kotlin")\n}\n\nkotlin {\n    // 配置目标（Android、iOS 等）\n    androidTarget()\n    listOf(\n        iosX64(),\n        iosArm64(),\n        iosSimulatorArm64()\n    ).forEach {\n        it.binaries.framework {\n            baseName = "shared"\n        }\n    }\n\n    sourceSets {\n        val commonMain by getting {\n            dependencies {\n                implementation("io.realm.kotlin:library-base:1.16.0")\n                // 用于协程支持\n                implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.0")\n            }\n        }\n        // ... 其他 source sets\n    }\n}

对于纯 Android 项目（无 KMP），配置更简单：

// build.gradle.kts (Module :app)\nplugins {\n    id("com.android.application")\n    kotlin("android")\n    id("io.realm.kotlin")\n}\n\nandroid {\n    // ... 标准配置\n}\n\ndependencies {\n    implementation("io.realm.kotlin:library-base:1.16.0")\n}

Gradle 同步后，该库即可使用。

\n\n