Bmob Database — JavaScript / 跨端 SDK

hydrogen-js-sdk 是 同一个 SDK 文件 Bmob-.min.js 支持以下所有宿主环境，无平台分支代码：

• 浏览器 / 任何 Web 前端（React、Vue 2、Vue 3、Next.js、Nuxt、Vite、Astro、SvelteKit、Solid 等）
• Node.js 服务端（必须源码引入）
• 微信小程序 / 支付宝 / 字节跳动 / QQ / 百度 小程序
• 快应用
• Cocos Creator JS
• Electron / Tauri
• 任意混合 App（WebView 内嵌 H5）

> 本 skill 只覆盖新版 hydrogen-js-sdk（Bmob.Query('X') Promise 风格，3.0+）。基于 Backbone.js 的旧 bmob-min.js（Bmob.Object.extend("X") callback 风格）不要用，也不要回退。

核心原则

1. 初始化支持两种方式（hydrogen-js-sdk 3.0+ 均兼容；按场景二选一，不要混用）：

方式 A — Secret Key + API 安全码（推荐：浏览器 / 小程序 / 公开客户端，SDK 内部走加密授权）：

Bmob.initialize("你的Secret Key", "你的API 安全码");

• Secret Key：控制台 → 应用 → 设置 → 应用密钥 → Secret Key。
• API 安全码：控制台 → 应用 → 应用功能设置 → 安全验证 → API 安全码 自行设置。

方式 B — Application ID + REST API Key（3.0 起正式兼容；适合已有 1.x/2.x 项目迁移、或与服务端 REST 共用同一套 Key）：

Bmob.initialize("你的Application ID", "你的REST API Key");

• Application ID / REST API Key：控制台 → 应用 → 设置 → 应用密钥 同一页。
• REST API 请求域名一般为 https://api.codenow.cn（见 bmob-database-restful）。

> 2.x 时代方式 B 功能受限；3.0+ 两种初始化等价可用。公开 bundle 仍优先方式 A（REST API Key 可被抓包）。

2. 不要 commit 真实密钥进 git；CDN / dist 不要写死 SDK 版本号。 密钥用环境变量（Vite import.meta.env.VITE_BMOB_、Next.js process.env.NEXT_PUBLIC_BMOB_、小程序构建期注入等）。dist 文件名为 Bmob-.min.js，有打包工具时用 npm install hydrogen-js-sdk；纯 CDN 浏览器场景用 jsDelivr API 动态取 tags.latest 再拼 URL（见 references/platform-init.md）。禁止在示例里写 @2.7.3 这类会过期的具体版本。

3. 默认查询返回 100 条，最大 1000。需要更多用 skip + limit 分页或走 BQL（bmob-bql skill）。

4. 三个保留字段不能手动写入：objectId、createdAt、updatedAt。读 objectId 时用 res.objectId（不是 id）。

5. 时间字段比较的精度：createdAt / updatedAt 在服务器是微秒精度，应用层做时间比较时要 +1 秒。

安全清单

• [ ] 密钥分级：浏览器 / 小程序 / 移动端优先 Secret Key + API 安全码（方式 A），永不用 Master Key。若用 Application ID + REST API Key（方式 B），REST API Key 会暴露在 bundle 中。
• [ ] 生产环境关闭调试模式：Bmob.debug(true) 仅在小程序开发时使用，上线前删掉。
• [ ] 小程序必须配置服务器域名白名单：微信后台 request 合法域名至少添加 https://api.bmobcloud.com（见 references/platform-init.md 微信小程序段）。
• [ ] 微信小程序若使用 npm 引入 SDK，需先在开发者工具执行“工具 --> 构建 npm”：未构建时 import Bmob from "hydrogen-js-sdk" 不会生效。
• [ ] 写入的表必须配 ACL：否则任意用户可改任意行。参见 bmob-acl-and-roles（P1）。
• [ ] 批量操作上限 50 条（含批量更新、批量删除）。超出需循环。
• [ ] 批量查询上限 100 条 / 单次 1000 条：避免一次拉全表。
• [ ] Bmob.User.login 在小程序里要先调用 wx.login() 获取 code，否则会话拿不到 sessionToken。

快速开始（80% 场景就这么写）

初始化

默认推荐 方式 A（Secret Key + API 安全码）；3.0+ 亦可用 方式 B（Application ID + REST API Key），见上方核心原则。

import Bmob from "hydrogen-js-sdk";
Bmob.initialize("你的Secret Key", "你的API 安全码");
// 或：Bmob.initialize("你的Application ID", "你的REST API Key");

详细的 8 种宿主环境引入方式见 references/platform-init.md。

新增一行

const query = Bmob.Query("GameScore");
query.set("score", 1337);
query.set("playerName", "bmob");
query.set("cheatMode", false);
query.save().then((res) => {
  console.log(res.objectId, res.createdAt);
});

通过 objectId 取一行

const query = Bmob.Query("GameScore");
query.get("7ecd253a25").then((res) => {
  console.log(res);
});

修改一行

const query = Bmob.Query("GameScore");
query.set("id", "7ecd253a25");          // 注意 set("id", objectId)
query.set("score", 9999);
query.save().then((res) => {
  console.log(res.updatedAt);
});

删除一行

const query = Bmob.Query("GameScore");
query.destroy("7ecd253a25").then((res) => {
  console.log(res);                      // { msg: "ok" }
});

删除某个字段的值

const query = Bmob.Query("GameScore");
query.get("7ecd253a25").then((res) => {
  res.unset("cover");
  res.save();
});

查询全部（默认 100 条）

const query = Bmob.Query("GameScore");
query.find().then((res) => {
  console.log(res);
});

条件查询

equalTo(field, op, value)，op 可以是 "==" / "!=" / ">" / ">=" / "<" / "<="。

const query = Bmob.Query("GameScore");
query.equalTo("score", ">", 100);
query.equalTo("cheatMode", "==", false);   // 多个条件 = AND
query.limit(20);
query.skip(0);
query.order("-score");                      // 降序
query.find().then(console.log);

或查询（OR）

const query = Bmob.Query("GameScore");
const q1 = query.equalTo("score", ">", 150);
const q2 = query.equalTo("score", "<", 5);
query.or(q1, q2);
query.find().then(console.log);

只取部分字段

const query = Bmob.Query("Post");
query.select("title");
query.find().then(console.log);

集合查询

query.containedIn("playerName", ["Bmob", "Codenow", "JS"]);
query.notContainedIn("playerName", ["spam"]);
query.exists("score");           // 含此字段
query.doesNotExist("score");     // 不含此字段

统计

const query = Bmob.Query("diary");
query.count().then((n) => console.log(`共 ${n} 条`));
query.count(100).then((arr) => console.log("最多返回 100 条记录数据 + count"));

原子计数器

const query = Bmob.Query("Post");
query.get("objectId").then((res) => {
  res.increment("likes");        // +1
  res.increment("likes", 5);     // +5（支持负数）
  res.save();
});

数组字段

const query = Bmob.Query("Diary");
query.add("DiaryType", ["public"]);          // 末尾追加
query.addUnique("DiaryType", ["secret"]);    // 去重追加
query.save();

query.get("objectId").then((res) => {
  res.remove("DiaryType", ["secret"]);       // 删除元素
  res.save();
});

进阶能力（按需读 references/）

与 MCP 联动

如果用户在 IDE 里配置了 Bmob MCP，写代码前先调用 get_project_tables 拿到真实 schema，避免：

• 字段名拼错（schemaless 不报错，数据进库后再排查很慢）
• Pointer 字段类型用错（必须是 {"__type":"Pointer","className":"X","objectId":"..."}）
• 把保留字段当业务字段写

sequenceDiagram
    autonumber
    participant Dev as Developer
    participant Agent as Agent
    participant MCP as bmob-mcp
    participant Code as bmob-database-javascript
    Dev->>Agent: "Next.js 项目里加 Bmob 文章列表"
    Agent->>MCP: get_project_tables()
    MCP-->>Agent: {Article: {title:String, content:String, author:Pointer(_User)}}
    Agent->>Code: 按真实 schema 生成 Bmob.Query("Article") 代码
    Code-->>Dev: 完整可运行代码（含 ACL 提示）

排错速查

参考

• 完整 API：BmobDocs/mds/data/wechat_app_new/index.md — 跨端 hydrogen-js-sdk 主文档
• 旧版 API 参考（仍在线）：BmobDocs/mds/data/javascript/develop_doc.md
• SDK 源码：
• 错误码：bmob-error-codes
• MCP 联动：bmob-mcp