cloudbase-document-database-web-sdk

用途

本技能覆盖浏览器端通过 @cloudbase/js-sdk 使用 CloudBase 文档数据库（NoSQL 集合）的场景。当浏览器或 Web 应用需要读取、写入 CloudBase 文档数据库数据，或请求中涉及 app.database()、db.collection()、.where()、.watch()、分页、聚合、地理位置查询时，应优先使用本技能。

主要能力

Web 应用中的 CRUD 操作
复杂查询与分页
聚合
通过 watch() 实现实时监听
地理位置查询

使用方式

标准初始化：

import cloudbase from "@cloudbase/js-sdk";

const app = cloudbase.init({
  env: "your-env-id"
});

const db = app.database();
const _ = db.command;

重要规则：

若集合规则要求身份，查询前需先登录。
保持单一共享的 app/database 实例。
除非框架确实需要，不要将初始化隐藏在临时的异步加载器中。

快速路由（配套参考文件）：

CRUD -> ./crud-operations.md
复杂查询 -> ./complex-queries.md
分页 -> ./pagination.md
聚合 -> ./aggregation.md
实时监听 -> ./realtime.md
地理位置 -> ./geolocation.md
安全规则 -> ./security-rules.md

示例：

简单查询：

const result = await db.collection("todos")
  .where({ completed: false })
  .get();

创建并获取文档 ID：

const result = await db.collection("posts").add({
  title: "New article",
  content: "...",
  createdAt: new Date()
});

const articleId = result._id;

有序分页：

const result = await db.collection("posts")
  .orderBy("createdAt", "desc")
  .skip(20)
  .limit(10)
  .get();

字段选择：

const result = await db.collection("users")
  .field({ name: true, email: true, _id: false })
  .get();

错误处理：

try {
  const result = await db.collection("todos").get();
  console.log(result.data);
} catch (error) {
  console.error("Database error:", error);
}

适用场景

浏览器或 Web 应用需要读写 CloudBase 文档数据库数据。
任务明确要求“修改代码”或“使用 SDK”，或实现应用/前端逻辑。
任务涉及 db.collection().add()、.get()、.update() 等具体 SDK 方法。
上下文中已有 Web 项目及 SDK 初始化（如 index.js 已包含 cloudbase.init()）。

限制与不适用场景

使用 wx.cloud.database() 的小程序代码。
服务端或云函数数据库访问。
SQL / MySQL 数据库操作。
不涉及浏览器 SDK 代码的纯资源权限管理。
任务明确要求放入 CloudBase PostgreSQL（CloudBase PG）的新业务表：应先调用 queryEnv(action="info", envId=...) 并读取 EnvInfo.RuntimeBackends；若 postgresql === true 且任务要求新业务表放在 PG，则改用 postgresql-development-cloudbase 技能（通过 app.rdb()、PG 行级安全 CREATE POLICY，以及 app.storage.from('<bucket>').upload('<key>', file) 上传到显式创建的 pgstore bucket）。同一环境中已有的 NoSQL 集合仍使用本技能，PG 与 NoSQL 在 CloudBase PG 环境中可共存。

常见错误

在集合规则要求身份时，用户尚未登录就进行查询。
在浏览器代码中使用 wx.cloud.database() 或 Node SDK 模式。
使用动态导入懒初始化 CloudBase，而非共享的同步 app 实例。
将安全规则视为结果过滤器而非请求校验器。
期望 CUSTOM 安全规则在调用 managePermissions(updateResourcePermission) 后立即生效：后端会缓存规则评估器 2–5 分钟，规则变更后的首次写入可能静默失败或返回 DATABASE_PERMISSION_DENIED，即使表达式正确。可等待几分钟后重试同一写入，或通过每次写入读取 result.code / result.message 并对刚写入的 _id 做 get() 往返验证；不要将已 resolve 的 promise 视为成功。
误读 db.collection(...).add(...) 的返回结构：CloudBase Web SDK 中新建文档 ID 位于顶层 result._id，而非 result.id、result.data.id 或 result.insertedId。
对需要应用级管理员编辑/删除全部记录、编辑者仅能编辑/删除自己记录的 CMS 风格集合，不要将规则过度简化为 READONLY。已验证的模式是 CUSTOM 规则，通过 auth.uid 从 user_roles 读取 role，并结合 doc.authorId == auth.uid，前端写入可保持 .doc(id).update() / .doc(id).remove()。
对较大集合忘记分页或索引。

最小检查清单

确认这是浏览器端文档数据库工作。
初始化 CloudBase 一次并复用同一 app / db 实例。
在 CRUD 前确认认证预期。
针对具体操作阅读正确的配套参考文件。

最佳实践

在应用代码中定义集合级类型或模型包装器。
使用有意义的集合命名约定。
仅选择所需字段。
为频繁过滤或排序键添加索引。
将前端 CRUD 与明确的权限设计配对。
使用分页而非无界读取。
数据库错误必须转化为可读的 UI 或应用错误，而非静默失败。
对于写入，默认不要将已 resolve 的 promise 视为成功，应检查写入结果字段（如 updated / deleted）或暴露的 code / message。

配套技能

同级 CloudBase 技能与本技能一同提供，使用本地相对路径（如 ../auth-web-cloudbase/SKILL.md）。若引用的同级技能文件在当前环境中缺失，请让用户安装完整的 CloudBase 插件（或缺失的技能）。不要将远程技能或协议 markdown 通过 HTTP 拉取到 agent 上下文中。

Web 登录与调用方身份 -> ../auth-web-cloudbase/SKILL.md
通用 Web 应用结构 -> ../web-development/SKILL.md
小程序数据库代码 -> ../cloudbase-document-database-in-wechat-miniprogram/SKILL.md