JavaScript SDK
概述
官方 TypeScript SDK — 框架无关、零依赖、完整类型安全。
@raisfast/sdk 是一个零依赖的 TypeScript 客户端，用于访问 RaisFast API。支持 React、Vue、Svelte、Next.js、Nuxt、React Native 和原生 JS。
安装
pnpm add @raisfast/sdk
# 或
npm install @raisfast/sdk
# 或
bun add @raisfast/sdk初始化
import { RaisFast } from "@raisfast/sdk";
const client = new RaisFast("http://localhost:9898/api/v1");首次使用时调用 init() 自动检测 API 风格（RESTful vs Simple）：
await client.init();构造选项
const client = new RaisFast("http://localhost:9898/api/v1", {
authStore: store, // 自定义认证存储（默认 LocalAuthStore）
});Auth Store
SDK 通过 IAuthStore 接口存储认证令牌。默认使用 localStorage。
import { RaisFast, LocalAuthStore } from "@raisfast/sdk";
// 自定义存储键
const store = new LocalAuthStore("my_app_auth");
const client = new RaisFast("http://localhost:9898/api/v1", {
authStore: store,
});自定义 Store（SSR / React Native）
为非浏览器环境实现 BaseAuthStore：
import { BaseAuthStore } from "@raisfast/sdk";
class CookieAuthStore extends BaseAuthStore {
save(auth) {
super.save(auth);
document.cookie = `auth=${super.exportToStorage()}; path=/`;
}
clear() {
super.clear();
document.cookie = "auth=; path=/; max-age=0";
}
}监听认证状态变化
client.authStore.onChange((token, user) => {
console.log("已认证:", !!token);
console.log("用户:", user?.email);
});RaisFast 类
const client = new RaisFast(baseUrl);
// 动态内容类型访问
client.collection<Portfolio>("portfolios"); // 公开 API
client.adminCollection<Portfolio>("portfolios"); // 管理 API
// 内置模块
client.auth // 认证 & OAuth & SMS
client.users // 用户资料
client.posts // 博客文章
client.pages // 静态页面
client.comments // 评论
client.categories // 分类
client.tags // 标签
client.media // 文件上传
client.products // 商品
client.cart // 购物车
client.orders // 订单
client.payment // 支付
client.wallets // 钱包
client.events // SSE 实时事件
client.health // 健康检查
// 管理模块
client.admin // 23 个管理子模块
// 单条记录内容类型
const settings = await client.single<SiteSettings>("site_settings");
// RSS 订阅 URL
client.getRssFeedURL();请求钩子
Before Send
添加自定义请求头、日志或修改请求：
client.beforeSend = (url, options) => {
options.headers = {
...options.headers,
"X-Custom-Header": "value",
};
return { url, options };
};After Send
转换响应或添加全局错误处理：
client.afterSend = (response, data) => {
console.log(`${response.status} ${response.url}`);
return data;
};请求取消
// 按 key 取消特定请求
client.cancelRequest("search_query");
// 取消所有待处理请求
client.cancelAllRequests();请求支持 requestKey 选项。相同 key 的新请求会自动取消上一个：
const result = await portfolios.getList(1, 20, {
requestKey: "portfolio_list",
});错误处理
import { SDKError } from "@raisfast/sdk";
try {
await portfolios.getOne("invalid-id");
} catch (e) {
if (e instanceof SDKError) {
console.log(e.status); // 404
console.log(e.code); // 后端错误码
console.log(e.message); // "not found"
console.log(e.url); // 请求 URL
console.log(e.isAbort); // 是否被取消？
}
}多租户
client.setTenantId("tenant-123"); // 添加 X-Tenant-ID 请求头
client.setTenantId(null); // 重置原始请求
用于 SDK 未覆盖的端点：
const data = await client.send("/custom/endpoint", {
method: "POST",
body: { key: "value" },
});