Node.js 适配器

提示

自 v3.1 版本起，@cloudbase/js-sdk已默认集成了 Node.js 适配器，无需额外安装，如果需要进行适配器扩展，可以按下面步骤进行安装使用。

概览

Node.js 适配器是为 Node.js 环境设计的，提供了对云开发服务的访问能力。它允许开发者在 Node.js 应用中使用云开发的功能，如数据库、存储、函数等。

安装

使用 npm 安装 Node.js 适配器：

npm i @cloudbase/adapter-node

快速开始

使用

const cloudbase = require("@cloudbase/js-sdk");
const adapter = require("@cloudbase/adapter-node");

// 使用 Node.js 适配器
cloudbase.useAdapters(adapter);

const app = cloudbase.init({
  env: "your-env", // 需替换为实际使用环境 id
});

使用示例

云函数调用示例

// 云函数调用示例
const result = await app.callFunction({
  name: "your-function-name",
  data: {
    key: "value",
  },
});

数据库操作示例

// 数据库操作示例
const db = app.database();
// 创建测试集合
const testCollection = db.collection("test_collection");
// 插入测试数据
const insertResult = await testCollection.add({
  name: "Node.js 测试",
  timestamp: new Date().toISOString(),
});

文件上传示例

// 上传文件示例
const fileName = `test-files/app-upload-${Date.now()}.jpg`;

const fs = require("fs");
const testFilePath = "/your/local/path/XXX.jpg"; // 替换为你的本地文件路径
// 读取文件内容
const fileBuffer = fs.readFileSync(testFilePath);

const uploadResult = await app.uploadFile({
  cloudPath: fileName,
  filePath: fileBuffer,
  onUploadProgress: function (progressEvent) {
    console.log("上传进度:", progressEvent);
    var percentCompleted = Math.round(
      (progressEvent.loaded * 100) / progressEvent.total
    );
  },
});

扩展适配器

Node.js 适配器导出了核心模块，你可以基于此构建自定义适配器，满足特殊环境或业务需求。

适配器结构说明

适配器通过 genAdapter 函数生成，返回的对象包含以下核心属性：

属性	类型	说明
reqClass	SDKRequestInterface	HTTP 请求类，负责所有网络请求（GET/POST/上传/下载/流式）
wsClass	WebSocketConstructor	WebSocket 构造函数
sessionStorage	StorageInterface	会话存储实现
localStorage	StorageInterface	本地存储实现
primaryStorage	StorageType	默认使用的存储类型
root	object	全局对象引用
getSecretInfo	function	获取腾讯云临时密钥信息
nodeTool	function	Node.js 端工具方法（auth、模板消息等）
captchaOptions	object	验证码处理回调

自定义请求类

通过继承 NodeRequest 类，可以扩展或覆盖请求行为，例如添加自定义请求头、修改签名逻辑、拦截请求/响应等。

const { NodeRequest } = require("@cloudbase/adapter-node");

class CustomRequest extends NodeRequest {
  // 覆盖 getReqOptions 以添加自定义请求头
  getReqOptions = async (url, options) => {
    const reqOptions = await super.getReqOptions(url, options);
    reqOptions.headers = {
      ...reqOptions.headers,
      "X-Custom-Header": "my-value",
    };
    return reqOptions;
  };

  // 覆盖 fetch 以添加请求/响应拦截
  fetch = async (options) => {
    console.log("[请求拦截]", options.url);
    const result = await super.fetch(options);
    console.log("[响应拦截]", result.statusCode);
    return result;
  };
}

自定义存储实现

默认的内存存储仅在进程生命周期内有效。如需持久化存储（如 Redis、文件系统等），可自行实现 StorageInterface：

const customStorage = {
  mode: "async", // "sync" 或 "async"
  setItem(key, value) {
    // 写入你的存储后端
  },
  getItem(key) {
    // 从你的存储后端读取
  },
  removeItem(key) {
    // 从你的存储后端删除
  },
  clear() {
    // 清空存储
  },
};

完整自定义适配器示例

const cloudbase = require("@cloudbase/js-sdk");
const nodeAdapter = require("@cloudbase/adapter-node");
const { NodeRequest } = nodeAdapter;

// 1. 自定义请求类
class CustomRequest extends NodeRequest {
  getReqOptions = async (url, options) => {
    const reqOptions = await super.getReqOptions(url, options);
    reqOptions.headers["X-Custom-Header"] = "my-value";
    return reqOptions;
  };
}

// 2. 自定义存储
const redisStorage = {
  mode: "async",
  async setItem(key, value) {
    /* redis.set(key, value) */
  },
  async getItem(key) {
    /* return redis.get(key) */
  },
  async removeItem(key) {
    /* redis.del(key) */
  },
  async clear() {
    /* redis.flushdb() */
  },
};

// 3. 组装自定义适配器
const customAdapter = {
  genAdapter(options) {
    // 获取默认适配器
    const defaultAdapter = nodeAdapter.default.genAdapter(options);
    return {
      ...defaultAdapter,
      // 替换请求类
      reqClass: CustomRequest,
      // 替换存储实现
      localStorage: redisStorage,
      sessionStorage: redisStorage,
    };
  },
  isMatch: nodeAdapter.default.isMatch,
  runtime: "custom-node-adapter",
};

// 4. 使用自定义适配器
cloudbase.useAdapters(customAdapter);
const app = cloudbase.init({
  env: "your-env",
});

导出的工具函数

适配器还导出了一些工具函数，可在自定义适配器中复用：

导出项	说明
NodeRequest	HTTP 请求类，可继承扩展
parseQueryString(search)	解析查询字符串为对象，支持重复 key 自动转数组
createWebStreamFromNodeReadableStream(stream)	将 Node.js ReadableStream 转换为 Web ReadableStream

类型导出

类型	说明
ICreateTicketOpts	自定义登录 Ticket 创建选项
IGetUserInfoResult	用户信息查询结果
IGetEndUserInfoResult	终端用户信息查询结果
IUserInfoQuery	用户信息查询请求参数
IContextParam	云函数入口 context 参数结构
ICompleteCloudbaseContext	云函数运行时完整环境变量类型
ICredentialsInfo	自定义登录凭证信息（RSA 私钥）