npm.io
1.8.11 • Published 1 month ago

@cloudbase/wx-cloud-client-sdk

Licence
MIT
Version
1.8.11
Deps
2
Size
324 kB
Vulns
0
Weekly
0

@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: '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 参数指定环境。

参考文档

Keywords