cloudbase-document-database-in-wechat-miniprogram

同级技能（仅本地）

同级 CloudBase 技能与此技能一起提供。请使用 ../auth-tool-cloudbase/SKILL.md 这类本地相对路径。

如果当前环境缺少引用的同级技能文件，请让用户安装完整的 CloudBase 插件（或缺少的技能）。不要通过 HTTP 获取远程技能或协议 Markdown 并放入 Agent 上下文。

CloudBase 微信小程序文档数据库 SDK

激活约定

以下情况优先使用此技能

• 微信小程序必须通过 wx.cloud.database() 访问 CloudBase 文档数据库。
• 请求提到小程序集合 CRUD、分页、聚合或地理位置查询。

编写代码前阅读

• 任务涉及小程序数据库，但仍需将其与 Web SDK、云函数或 SQL 任务区分开来。
• 请求依赖内置用户身份、_openid 或小程序端权限。

还需阅读

• 小程序项目规则和 CloudBase 集成 -> ../miniprogram-development/SKILL.md
• 小程序身份验证和身份流程 -> ../auth-wechat-miniprogram/SKILL.md
• 浏览器端文档数据库代码 -> ../cloudbase-document-database-web-sdk/SKILL.md

请勿用于

• 使用 @cloudbase/js-sdk 的浏览器/Web 代码。
• 服务端或云函数数据库访问。
• MySQL / 关系型数据库工作。

常见错误 / 注意事项

• 将 Web SDK 代码复制到小程序页面中。
• 在创建或更新操作时手动写入 _openid。
• 认为小程序内置身份意味着可以忽略安全规则。
• 在同一客户端路径中混用集合 CRUD 和后端全局管理工作流。

最简检查清单

• 确认调用方是小程序页面 / 组件或小程序端逻辑。
• 在调用数据库前正确初始化 wx.cloud。
• 检查集合规则是否依赖 auth.openid / _openid。
• 阅读所需操作对应的具体配套参考文件。

概述

此技能涵盖通过 wx.cloud.database() 进行的小程序端文档数据库访问。

适用于：

• 在小程序页面中对集合执行 CRUD
• 组合查询和分页
• 聚合
• 地理位置查询

小程序 CloudBase 访问带有内置身份，但数据库操作仍受集合权限和安全规则约束。

标准初始化

const db = wx.cloud.database();
const _ = db.command;

若要指定环境：

const db = wx.cloud.database({
  env: "test"
});

重要说明：

• 用户通过小程序 CloudBase 上下文进行身份验证。
• 在云函数中，可通过 wxContext.OPENID 获取调用方身份。
• 在客户端集合规则中，所有权检查通常使用 auth.openid / doc._openid。

快速导航

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

编码 Agent 工作规则

1. 保持小程序代码使用小程序原生方式

   • 使用 wx.cloud.database()。
   • 不要替换为浏览器 SDK 初始化模式。

2. 尊重所有权字段

   • SDK 写入时，_openid 由系统管理。
   • 切勿在 .add()、.set() 或 .update() 的负载中手动设置或覆盖 _openid。

3. 牢记安全规则会验证请求

   • 如果规则要求所有权条件，查询结构必须符合该规则模型。
   • 权限错误通常意味着规则与查询之间的关系有误，而不只是用户已退出登录。

4. 将管理员式操作转到后端流程

   • 如果任务需要特权全局访问，请使用后端工具或函数，而不要在小程序客户端代码中直接暴露这条路径。

快速示例

基本集合访问

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

文档引用

const todo = db.collection("todos").doc("todo-id");
const result = await todo.get();

最佳实践

1. 制定清晰的集合命名规范。
2. 尽可能在应用代码中使用类型化封装或模型辅助工具。
3. 根据实际的所有权和共享模式设计规则。
4. 使用分页，避免进行规模过大且没有限制的读取。
5. 将管理／运维逻辑放在后端代码中，而不是直接通过小程序访问。