腾讯云 CloudBase 数据库 CRUD 完整指南

适用环境：

• 小程序 / Web 前端（使用 @cloudbase/js-sdk）

• 云函数 / 云服务器（使用 @cloudbase/node-sdk）

---

一、初始化数据库

1. 前端（小程序 / Web）

import { init } from '@cloudbase/js-sdk';

const app = init({
  env: 'your-env-id'
});

const db = app.database();

2. Node.js 服务端（云函数 / 云主机）

const cloudbase = require('@cloudbase/node-sdk');

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

const db = app.database();

🔐 权限说明：

• 前端受 安全规则 限制
• Node.js 服务端拥有 管理员权限，可绕过安全规则

---

二、Create（创建 / 插入）

1. 插入单条数据（前端 & 服务端通用）

const result = await db.collection('users').add({
  data: {
    name: 'Alice',
    age: 25,
    city: 'Beijing',
    createdAt: db.serverDate() // 服务器时间
  }
});

console.log(result.id); // 返回生成的 _id

2. 批量插入（仅限 Node.js 服务端）

在服务端，add 方法支持传入数组，实现批量插入：

const result = await db.collection('users').add([
  {
    data: { name: 'Alice', age: 20 }
  },
  {
    data: { name: 'Bob', age: 22 }
  },
  {
    data: { name: 'Charlie', age: 24 }
  }
]);

console.log(result); // 返回插入结果

⚠️ 注意：前端 SDK 不支持数组批量插入，需用 Promise.all 并发调用 add。

---

三、Read（查询）

1. 查询所有数据

const res = await db.collection('users').get();
console.log(res.data); // 返回文档数组

2. 条件查询

const res = await db.collection('users')
  .where({
    age: db.command.gt(18),
    city: 'Shanghai',
    tags: db.command.in(['dev', 'web'])
  })
  .get();

console.log(res.data);

3. 字段筛选

// 只返回 name 和 age 字段
await db.collection('users')
  .field({ name: true, age: true, _id: true })
  .get();

// 隐藏 age 字段
await db.collection('users')
  .field({ age: false })
  .get();

4. 分页与排序

// 排序：age 升序
await db.collection('users')
  .orderBy('age', 'asc')
  .get();

// 分页：跳过 10 条，取 10 条
await db.collection('users')
  .skip(10)
  .limit(10)
  .get();

---

四、Update（更新）

1. 更新单条或匹配的文档（前端 & 服务端）

await db.collection('users')
  .where({ name: 'Alice' })
  .update({
    data: {
      age: 26,
      city: 'Shenzhen'
    }
  });

2. 字段操作（服务端更灵活）

await db.collection('users')
  .where({ name: 'Alice' })
  .update({
    data: {
      age: db.command.inc(1),        // 年龄 +1
      tags: db.command.push('new'),  // 数组追加
      status: db.command.set('active') // 明确设置值
    }
  });

3. 批量更新（仅限 Node.js 服务端）

// 更新所有匹配条件的文档
await db.collection('users')
  .where({ city: 'Beijing' })
  .updateMany({
    data: {
      status: 'verified',
      updatedAt: db.serverDate()
    }
  });

✅ updateMany 是服务端 SDK 特有方法，前端无此能力。

---

五、Delete（删除）

1. 删除匹配的文档（前端 & 服务端）

// 删除 name 为 Bob 的文档
await db.collection('users')
  .where({ name: 'Bob' })
  .remove();

2. 批量删除（仅限 Node.js 服务端）

// 删除所有 age < 18 的用户
await db.collection('users')
  .where({ age: db.command.lt(18) })
  .deleteMany();

✅ deleteMany 是服务端方法，语义更清晰，性能更好。

---

六、高级操作（Node.js 服务端专属）

1. 事务（保证数据一致性）

const transaction = await db.startTransaction();

try {
  await transaction.collection('users').doc('uid1').update({
    balance: db.command.inc(-100)
  });

  await transaction.collection('orders').add({
    userId: 'uid1',
    amount: 100,
    createdAt: db.serverDate()
  });

  await transaction.commit(); // 提交事务
} catch (error) {
  await transaction.rollback(); // 回滚
}

2. 聚合查询（Aggregation）

const result = await db.collection('users')
  .aggregate()
  .group({
    _id: '$city',
    count: db.command.sum(1)
  })
  .end();

console.log(result);

---

七、常用操作符对照表

操作	CloudBase 写法
大于	db.command.gt(20)
小于	db.command.lt(30)
大于等于	db.command.gte(18)
小于等于	db.command.lte(60)
等于	db.command.eq('value')
不等于	db.command.neq('value')
在数组中	db.command.in(['a', 'b'])
数值自增	db.command.inc(1)
数组追加	db.command.push('new')
设置字段	db.command.set('value')
服务器时间	db.serverDate()

---

八、环境能力对比总结

操作	前端（小程序/Web）	Node.js 服务端
单条插入	✅ add({data: {...}})	✅
批量插入	❌（需 Promise.all）	✅ add([{data:...}, ...])
查询	✅（受安全规则限制）	✅（可查所有数据）
更新	✅（受规则限制）	✅ update, updateMany
删除	✅（受规则限制）	✅ remove, deleteMany
事务	❌	✅ startTransaction()
聚合	✅（基础）	✅（更完整）

---

🔚 总结

• 前端使用：适合安全直连，CRUD 基础操作，依赖安全规则控制权限。
• Node.js 服务端使用：拥有管理员权限，支持 updateMany、deleteMany、事务、批量插入等高级功能，可构建复杂后端逻辑。