Kotbase

Kotlin 多平台 Couchbase Lite 库

介绍

Kotbase 将 Kotlin 多平台 与嵌入式 NoSQL JSON 文档数据库 Couchbase Lite 配对使用。Couchbase Lite 可以用作独立的客户端数据库，或与 Couchbase Server 和 Sync Gateway 或 Capella 应用服务 配合，实现云端到边缘的数据同步。功能包括：

• SQL++、键/值、全文搜索和向量搜索查询
• 可观察的查询、文档、数据库和复制器
• 二进制文档附件（Blob）
• 点对点及云到边缘的数据同步

Kotbase 为 Android 和 JVM（通过 Java SDK）、原生 iOS 和 macOS（通过 Objective-C SDK）提供完整的企业版和社区版 API 支持，并对原生 Linux 和 Windows（通过 C SDK）提供实验性支持。

安装

在共享模块的 build.gradle.kts 的 commonMain 源集依赖中添加社区版或企业版依赖：

kotlin {
    sourceSets {
        commonMain.dependencies {
            // Community Edition
            implementation("dev.kotbase:couchbase-lite:3.2.4-1.2.0")
            // or Enterprise Edition
            implementation("dev.kotbase:couchbase-lite-ee:3.2.4-1.2.0")
        }
    }
}

注意

Couchbase Lite 社区版是免费且开源的。企业版在开发和测试阶段免费使用，

但生产环境使用需要从 Couchbase 获取许可证。

参见社区版与企业版对比。

Kotbase 已发布到 Maven Central。Couchbase Lite 企业版依赖项还需要 Couchbase Maven 仓库。

repositories {
    mavenCentral()
    maven("https://mobile.maven.couchbase.com/maven2/dev/")
}

原生平台

原生平台目标还应链接到 Couchbase Lite 依赖的原生二进制文件。详情请参见 支持的平台。

Linux

针对运行在 Linux 上的 JVM 或原生 Linux，均需要特定版本的 libicu 依赖。（如果出现类似 libLiteCore.so: libicuuc.so.71: cannot open shared object file: No such file or directory 的错误，表示所需版本未找到。） 如果您的发行版包管理器中没有该版本，可以从 GitHub 下载。

文档

Kotbase 文档可在 kotbase.dev 查阅，包括 入门示例、使用指南 和 API 参考。

与 Java SDK 的差异

Kotbase 的 API 与 Couchbase Lite 的 Java 和 Android KTX SDK 保持一致。迁移现有 Kotlin 代码通常只需将导入包从 com.couchbase.lite 改为 kotbase，但有些例外：

• Java 回调函数接口被实现为 Kotlin 函数类型。
• File、URL 和 URI API 使用字符串表示。
• Date API 使用 Kotlin 的 Instant。
• InputStream API 使用 kotlinx-io 的 Source。
• Executor API 使用 Kotlin 的 CoroutineContext。
• 证书 API 以原始 ByteArray 或平台特定代码形式提供。
• 无需显式调用 CouchbaseLite.init()。JVM 和 Android 平台代码中仍可用自定义参数调用初始化函数。
• 已努力检测并抛出 Kotlin 异常以处理常见错误，但在苹果平台上仍可能泄漏 NSError。

请报告 任何需要处理的情况。

• 一些已弃用的 API 被省略。
• 虽然 Java SDK 不支持操作符重载，因此不可用，但 Fragment 下标 API 在 Kotbase 中可用，类似于 Swift、Objective-C 和 .NET。
  • Android KTX SDK 的配置工厂 API 已被弃用，建议直接使用构造函数，
  它们本身支持 Kotlin 命名参数。

  扩展库

  Kotbase 在 Couchbase Lite 官方 API 之上包含了一些方便的扩展，作为附加的库构件。

  Kotbase KTX

  KTX 扩展 包含了优秀的 MOLO17 的 Kotlin 扩展， 以及用于组合查询、映射查询结果、创建文档和观察变更 Flow 的其他便利函数。

  #### 安装

  // Community Edition
  implementation("dev.kotbase:couchbase-lite-ktx:3.2.4-1.2.0")
  // or Enterprise Edition
  implementation("dev.kotbase:couchbase-lite-ee-ktx:3.2.4-1.2.0")

  Kotbase Kermit

  Kotbase Kermit 是一个 Couchbase Lite 自定义日志记录器，日志记录到 Kermit。Kermit 可以将日志输出到多个日志目标，包括控制台。

  #### 安装

  // Community Edition
  implementation("dev.kotbase:couchbase-lite-kermit:3.2.4-1.2.0")
  // or Enterprise Edition
  implementation("dev.kotbase:couchbase-lite-ee-kermit:3.2.4-1.2.0")

  Kotbase 分页

  paging 扩展 基于 Google 的 AndroidX Paging 构建。Kotbase 分页提供了一个 PagingSource，它基于用户提供的数据库查询执行 limit/offset 分页查询。

  #### 安装

  // Community Edition
  implementation("dev.kotbase:couchbase-lite-paging:3.2.4-1.2.0")
  // or Enterprise Edition
  implementation("dev.kotbase:couchbase-lite-ee-paging:3.2.4-1.2.0")

  路线图

  • [x] 文档网站 (kotbase.dev)
  • [x] NSInputStream 互操作 ~~(Okio #1123)~~ (kotlinx-io #174)
    • [x] Linux ARM64 支持
    • [x] 公开发布
    • [ ] 示例应用
    • [x] 入门指南
    • [x] 入门指南 Compose 多平台
    • [x] Kotbase 笔记
    • [ ] Kotbase 笔记的 SwiftUI
    • [x] Couchbase Lite 3.1 API - 范围和集合
    • [x] 版本化文档
    • [x] Couchbase Lite 3.2 API - 向量搜索
      • [ ] Couchbase Lite 3.3 API - 多点复制器
      • [ ] Couchbase Lite 4.0 API - 版本向量
      • [ ] Linux 和 MinGW 平台上的 URLEndpointListener
      • [ ] 通过 Swift 导出、@ObjCName 和/或 @ShouldRefineInSwift 改善 Swift API 与 Couchbase Lite 的一致性
      • [ ] 异步协程 API

      开发

      • 在 Linux 上构建项目时，请确保安装 libicu 依赖。
      • 在 Windows 上检出 git 仓库时，启用 开发者模式 并使用 git config --global core.symlinks true 启用 git 中的符号链接。

        --- Tranlated By Open Ai Tx | Last indexed: 2026-01-20 ---