@cloudbase/wx-cloud-client-sdk

@cloudbase/wx-cloud-client-sdk

微信云开发客户端 SDK，提供数据模型、MySQL/RDB 数据库和用户认证能力。

安装

npm install @cloudbase/wx-cloud-client-sdk

快速开始

初始化

SDK 提供两种初始化方式：

1. 微信云开发中使用（默认）

import { init } from '@cloudbase/wx-cloud-client-sdk';

// 使用微信云开发实例初始化
const client = init(wx.cloud, {
  envId: 'your-env-id', // 可选，当 wx.cloud 为 wx.cloud.Cloud() 实例时需要提供
});

2. NodeJs 服务端使用

const adapter = require('@cloudbase/adapter-node');
const cloudbase = require('@cloudbase/js-sdk'); // 内置 @cloudbase/wx-cloud-client-sdk
cloudbase.useAdapters(adapter);

const client = cloudbase.init({
  env,
});

初始化后，client 将拥有以下属性：

• client.models - 数据模型操作接口
• client.mysql() / client.rdb() - MySQL/RDB 数据库客户端
• client.auth - 用户认证接口

数据模型操作

数据模型提供完整的 CRUD 操作，支持生产环境 (envType: 'prod') 和预发环境 (envType: 'pre')。

// 创建数据
const { data } = await client.models.yourModel.create({
  data: { title: 'Hello', content: 'World' },
  envType: 'prod', // 可选，默认 'prod'
});

// 批量创建
const { data } = await client.models.yourModel.createMany({
  data: [
    { title: 'Post 1', content: 'Content 1' },
    { title: 'Post 2', content: 'Content 2' },
  ],
});

// 查询单条数据
const { data } = await client.models.yourModel.get({
  filter: { where: { _id: { $eq: 'record-id' } } },
  select: { $master: true }, // 默认包含主模型字段
});

// 查询列表（支持分页、总数）
const {
  data: { records, total },
} = await client.models.yourModel.list({
  filter: { where: { title: { $eq: 'Hello' } } },
  pageSize: 10,
  pageNumber: 1,
  getCount: true, // 获取总数
});

// 更新数据
await client.models.yourModel.update({
  data: { title: 'Updated' },
  filter: { where: { _id: { $eq: 'record-id' } } },
});

// 批量更新
await client.models.yourModel.updateMany({
  data: { status: 'published' },
  filter: { where: { status: { $eq: 'draft' } } },
});

// 创建或更新（upsert）
await client.models.yourModel.upsert({
  data: { title: 'New or Updated' },
  filter: { where: { _id: { $eq: 'record-id' } } },
});

// 删除数据
await client.models.yourModel.delete({
  filter: { where: { _id: { $eq: 'record-id' } } },
});

// 批量删除
await client.models.yourModel.deleteMany({
  filter: { where: { status: { $eq: 'deleted' } } },
});

// 执行 SQL 模板
const { data } = await client.models.yourModel.runSQLTemplate({
  templateId: 'your-template-id',
  parameters: { param1: 'value1' },
});

MySQL/RDB 数据库

MySQL/RDB 客户端基于 PostgREST 风格，提供链式查询构建器。

获取数据库客户端

// 获取 MySQL 客户端（mysql 和 rdb 是别名）, 参数为可选
const mysql = client.mysql({
  database: 'your-database', // 数据库名，默认为环境 ID
  instance: 'default', // 实例名，默认为 'default'
});

// 或使用 rdb 别名, 参数为可选
const rdb = client.rdb({ database: 'your-database' });

查询数据

// 查询所有字段
const users = await mysql.from('users').select('*');

// 查询指定字段
const users = await mysql.from('users').select('id, name, email');

// 条件查询（支持 eq、neq、gt、gte、lt、lte、in、like 等）
const activeUsers = await mysql
  .from('users')
  .select('*')
  .eq('status', 'active')
  .neq('role', 'admin')
  .gt('age', 18)
  .lt('age', 65)
  .like('name', '%John%')
  .in('id', [1, 2, 3]);

// 排序和分页
const result = await mysql
  .from('users')
  .select('*')
  .eq('status', 'active')
  .gte('age', 18)
  .order('created_at', { ascending: false })
  .limit(10)
  .range(0, 9); // 范围查询

// 计数查询
const { count } = await mysql.from('users').select('*', { count: 'exact', head: true }).eq('status', 'active');

插入数据

// 插入单条
await mysql.from('users').insert({
  name: 'test',
  email: '[e-mail]',
});

// 插入多条
await mysql.from('users').insert([
  { name: 'user1', email: '[e-mail]' },
  { name: 'user2', email: '[e-mail]' },
]);

// 插入并返回数据
const { data } = await mysql.from('users').insert({ name: 'test', email: '[e-mail]' }).select();

更新数据

// 更新并返回更新后的数据
const { data } = await mysql.from('users').update({ status: 'inactive' }).eq('id', 1).select();

// 批量更新
await mysql.from('users').update({ status: 'inactive' }).in('id', [1, 2, 3]);

删除数据

// 删除并返回删除的数据
const { data } = await mysql.from('users').delete().eq('id', 1).select();

// 批量删除
await mysql.from('users').delete().in('id', [1, 2, 3]);

用户认证

认证模块提供微信小程序 OpenID 静默登录和用户信息管理。在 NodeJs 端提供更多的登录方式，参考JS SDK 文档。

// 获取 auth 实例
const auth = client.auth;

// 微信小程序 OpenID 静默登录，用户不存在则注册成外部注册用户
await auth.signInWithOpenId();

// 更新用户信息（昵称、性别等）
const { data, error } = await auth.updateUser({
  nickname: '新昵称',
  gender: 'MALE',
});

// 更新 email 或 phone（需要验证）
const { data, error } = await auth.updateUser({
  email: '[e-mail]',
});

// 调用 verifyOtp 回调验证邮箱/手机
if (data?.verifyOtp) {
  await data.verifyOtp({
    email: '[e-mail]',
    token: '123456',
  });
}

// 获取当前用户信息
const { data, error } = await auth.getUser();

// 获取登录状态
const { data, error } = auth.getSession();

// 刷新登录状态
await auth.refreshSession();

// 登出
await auth.signOut();

API 参考

初始化函数

init(cloud, options)

使用云函数调用初始化 SDK。

参数	类型	必填	说明
cloud	CloudBaseInstance	是	微信云开发实例
options.envId	string	否	环境 ID，当 cloud 为 new wx.cloud.Cloud() 实例时需要提供
options.adapter	CloudbaseAdapter	否	自定义适配器

数据模型方法

所有数据模型方法都支持 envType 参数（可选，默认 'prod'），用于指定操作环境（'prod' 或 'pre'）。

• create(params) - 创建单条数据
• createMany(params) - 批量创建数据
• update(params) - 更新单条数据
• updateMany(params) - 批量更新数据
• upsert(params) - 创建或更新数据
• delete(params) - 删除单条数据
• deleteMany(params) - 批量删除数据
• get(params) - 获取单条数据
• list(params) - 获取数据列表（支持分页、过滤、排序）
• runSQLTemplate(params) - 执行 SQL 模板

MySQL/RDB 方法

查询构建器方法

• from(tableName) - 指定表名
• select(columns, options) - 选择字段（支持 count: 'exact' 等选项）
• eq(column, value) - 等于
• neq(column, value) - 不等于
• gt(column, value) - 大于
• gte(column, value) - 大于等于
• lt(column, value) - 小于
• lte(column, value) - 小于等于
• like(column, pattern) - LIKE 匹配
• ilike(column, pattern) - ILIKE 不区分大小写匹配
• in(column, values) - IN 查询
• is(column, value) - IS 查询（如 is('deleted_at', null)）
• or(filters) - OR 条件
• not(filter) - NOT 条件
• order(column, options) - 排序（{ ascending: boolean }）
• limit(count) - 限制返回条数
• range(start, end) - 范围查询
• insert(data) - 插入数据
• update(data) - 更新数据
• delete() - 删除数据

认证方法

• signInWithOpenId() - 微信小程序 OpenID 静默登录，用户不存在则注册成外部注册用户
• updateUser(params) - 更新用户信息（返回可能包含 verifyOtp 回调）
• getUser() - 获取当前用户信息
• getSession() - 获取登录状态
• refreshSession() - 刷新登录状态
• signOut() - 登出

类型声明

SDK 提供完整的 TypeScript 类型定义。使用时可以导入相关类型：

import type {
  CloudBaseInstance,
  ExtendedCloudBaseInstance,
  OrmClient,
  Auth,
  IMySqlOptions,
} from '@cloudbase/wx-cloud-client-sdk';

错误处理

SDK 使用统一的错误类型 WxCloudSDKError，包含错误码、请求 ID 和原始错误信息。

try {
  await client.models.yourModel.create({ data: {} });
} catch (error) {
  if (error.code === 'NotSupported') {
    // 处理不支持的操作
  }
  console.error('Request ID:', error.requestId);
  console.error('Original error:', error.originError);
}

环境支持

• 生产环境 (envType: 'prod') - 默认环境，操作生产数据
• 预发环境 (envType: 'pre') - 用于测试，操作预发数据

可以在每个数据模型操作中通过 envType 参数指定环境。

参考文档

• 初始化 SDK
• 类型声明
• 微信云开发文档