Meet CKTool JS
System & Services 进阶 20m

CKTool JS 入门

Meet CKTool JS

2022年6月6日

在 Apple 官方观看视频

一句话判断

Apple 给 CloudKit 做了一个 Node.js 命令行工具——CKTool JS 让你在 CI/CD 管线里直接操作 CloudKit 数据库，不需要写 Swift 代码或打开网页控制台。

这场 Session 讲了什么

这场 Session 介绍了 CKTool JS，一个基于 Node.js 的 CloudKit 命令行工具。它的定位是：让 CloudKit 的日常管理操作可以通过脚本自动化，而不是依赖 Xcode 或网页控制台。

CKTool JS 是什么。 它是一个 npm 包（@apple/cktool），安装后提供一个 cktool 命令行工具。你可以用它来执行所有常见的 CloudKit 操作：查询 record、创建/修改/删除 record、管理 schema、查看 zone 信息等。所有操作都通过 CloudKit Web Services API 完成。

和 CloudKit Console 的区别。 CloudKit Console 是一个网页界面，适合手动操作和快速查看数据。CKTool JS 是命令行工具，适合脚本自动化和 CI/CD 集成。比如你可以在 GitHub Actions 里用 CKTool JS 在每次部署前检查 Production schema 是否和代码匹配，或者在集成测试里用 CKTool JS 准备测试数据。

认证方式。 CKTool JS 支持 Apple ID 认证和 API Token 认证。Apple ID 认证适合个人开发者在本地使用（需要登录），API Token 认证适合 CI/CD 环境（不需要交互式登录）。API Token 通过 App Store Connect 的 Integrations 页面生成，可以设置读写权限范围。

常用操作。 Session 里演示了几个典型用例：

  • cktool records query：查询指定 record type 的数据
  • cktool records create：创建新 record
  • cktool records delete：删除 record
  • cktool schema list：查看当前 schema
  • cktool schema export：导出 schema 为 JSON

脚本集成。 CKTool JS 的输出是 JSON 格式，方便和其他命令行工具（jq、grep）配合使用。你也可以在 Node.js 脚本里直接 import CKTool JS 的 API 模块来做更复杂的操作。

环境管理。 CKTool JS 支持在 Development 和 Production 环境之间切换。你可以用 --environment 参数指定目标环境，或者用 cktool environment set 设置默认环境。

值得深挖的点

CI/CD 中的 Schema 验证。 一个很实用的场景是：在 CI 管线里用 CKTool JS 导出当前 CloudKit schema，然后和代码里定义的 schema 做对比。如果不一致（比如代码里新增了一个字段但 CloudKit 里还没有），就标记构建失败。这避免了”代码改了 schema 但忘记 deploy 到 CloudKit”的常见错误。

测试数据管理。 集成测试经常需要在 CloudKit 里准备特定的测试数据。CKTool JS 可以在测试开始前创建测试 record，测试结束后删除。这比在测试代码里用 CloudKit API 操作数据库更干净——测试代码只关心业务逻辑，数据准备和清理交给 CI 脚本。

代码片段

安装和基本使用：

# 安装 CKTool JS
npm install -g @apple/cktool

# 登录（交互式，需要 Apple ID）
cktool account login

# 设置默认容器和环境
cktool config set container iCloud.com.example.myapp
cktool config set environment development

# 查询 record
cktool records query \
    --record-type MyRecord \
    --filter 'name == "Test"' \
    --limit 10

# 创建 record
cktool records create \
    --record-type MyRecord \
    --fields '{"name": "New Item", "score": 42}'

# 删除 record
cktool records delete --record-name "ABC123"

在 Node.js 脚本中使用 API：

const { CKTool } = require('@apple/cktool');

async function main() {
    const tool = new CKTool({
        container: 'iCloud.com.example.myapp',
        environment: 'development'
    });

    // 查询所有测试 record
    const records = await tool.records.query({
        recordType: 'TestRecord',
        filter: { fieldName: 'isTest', comparator: 'EQUALS', value: true }
    });

    console.log(`找到 ${records.length} 条测试数据`);

    // 批量删除
    for (const record of records) {
        await tool.records.delete({ recordName: record.recordName });
        console.log(`已删除: ${record.recordName}`);
    }
}

main().catch(console.error);

在 GitHub Actions 中使用：

- name: Verify CloudKit Schema
  env:
    CKTOOL_TOKEN: ${{ secrets.CKTOOL_API_TOKEN }}
  run: |
    npm install -g @apple/cktool
    # 导出当前 schema
    cktool schema export --format json > current_schema.json
    # 和预期 schema 对比
    diff expected_schema.json current_schema.json || {
      echo "Schema 不匹配！请检查 CloudKit 配置"
      exit 1
    }

最佳实践

在 CI/CD 中使用 API Token 认证，不要用 Apple ID 认证。API Token 可以设置有限的权限和过期时间，比 Apple ID 密码更安全。Token 存在 CI 系统的 secrets 里，不要提交到代码仓库。

查询操作加 --limit 参数，避免一次拉取太多数据。CloudKit 的查询有默认限制（通常是 100 条），但你最好显式指定一个合理的上限。如果需要获取大量数据，用分页查询而不是一次拉全部。

删除操作前先做查询确认。CKTool JS 的 records delete 是即时生效的，没有确认提示。在生产环境操作时，先用 records query 确认要删除的数据，然后在脚本里做二次确认（比如检查 record 数量是否在预期范围内）。

还有什么值得关注

  • CKTool JS 目前只在 macOS 和 Linux 上测试过，Windows 支持可能有问题。
  • cktool schema export 导出的 JSON 格式可以直接用于 cktool schema import，方便在不同环境之间复制 schema。
  • CKTool JS 的版本号和 CloudKit Web Services API 的版本独立更新，升级时注意查看 changelog。
  • 如果你需要操作大量 record（比如几万条），CKTool JS 的性能可能不如直接用 CloudKit API 写批量脚本——它的优势在于便利性而不是极致性能。
WWDC 2022