Package Exports
- @cloudbase/wx-cloud-client-sdk
- @cloudbase/wx-cloud-client-sdk/lib/wxCloudClientSDK.cjs.js
- @cloudbase/wx-cloud-client-sdk/lib/wxCloudClientSDK.esm.js
- @cloudbase/wx-cloud-client-sdk/lib/wxCloudClientSDK.umd.js
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@cloudbase/wx-cloud-client-sdk) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
@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', // 可选,当 cloud 为 new 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: 'test@example.com',
});
// 插入多条
await mysql.from('users').insert([
{ name: 'user1', email: 'user1@example.com' },
{ name: 'user2', email: 'user2@example.com' },
]);
// 插入并返回数据
const { data } = await mysql.from('users').insert({ name: 'test', email: 'test@example.com' }).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: 'new@example.com',
});
// 调用 verifyOtp 回调验证邮箱/手机
if (data?.verifyOtp) {
await data.verifyOtp({
email: 'new@example.com',
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 参数指定环境。