JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 4114
  • Score
    100M100P100Q143510F

wx cloud client sdk

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

参考文档