# @faiber/sdk-core 中文文档

规范地址：https://npmcn.com/package/%40faiber/sdk-core/

版本：2\.8\.0
npm 元数据更新时间：2026-11-14T09:43:05.895Z
中文译文更新时间：2026-11-14T08:56:10.873Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40faiber/sdk-core
原文对照：https://npmcn.com/package/%40faiber/sdk-core/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：104 kB，44 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-07-18T14:28:34.219Z
- 最新版本发布：2026-11-14T09:43:05.689Z
- 近 30 天下载量：9023（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：67（近 12 个月 67 个）

## 中文简介

每个Faiber TypeScript SDK共享的框架中性运输和认证原始.

## 安装

```sh
npm install @faiber/sdk-core
```

也可以使用：`pnpm add @faiber/sdk-core`、`yarn add @faiber/sdk-core`、`bun add @faiber/sdk-core`

## README

# @faiber/ sdk- core (中文(简体) )

每个Faiber TypeScript SDK共享的框架中性运输和认证原始.

## 安装和配置

```bash
npm install @faiber/sdk-core
```

```ts
import { FaiberClient, MemoryTokenProvider } from "@faiber/sdk-core";

const tokens = new MemoryTokenProvider({ accessToken: session.accessToken });
const client = new FaiberClient("profile", {
  domains: { profile: import.meta.env.FAIBER_PROFILE_URL },
  authMode: "bearer",
  tokenProvider: tokens,
  axios: { timeout: 15_000, withCredentials: true },
});
```

`FaiberClient` 只解决配置的服务源, 默认拒绝绝对 URL, 添加 Bearer 令牌 `TokenProvider`,并保留 Axios 的全部响应。 设定 `authMode: "cookie"` 以自动启用认证请求并抑制Bearer注射. `auto` 是向后兼容的默认值,并在可用时使用一个符号,同时尊重明确的Axios cookie设置. `MemoryTokenProvider` 选择进入 `StorageTokenProvider` ; 自定义提供者可以绑定服务器侧会话或加密存储.

## 请求和编码

```ts
import { multipart, urlEncoded } from "@faiber/sdk-core";

await client.post("/api/v1/login", urlEncoded({ username, password }), {
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
});

await client.post("/api/v1/profile/avatar", multipart({ file, alt: "Avatar" }));
```

客户端提供打字 `get`, (中文(简体) ), `post`, (中文(简体) ), `put`, (中文(简体) ), `patch`, (中文(简体) ), `delete`,并通用 `request` 方法。 。 。 查询值,请求标题,超时,适配器,截取器, `AbortSignal`,多部分数据,和 URL 编码表仍可通过 Axios 兼容选项提供.

土著 `FormData` 上传自动清除配置的 JSON 内容类型, Axios 可以 提供多段边界。 过 `onUploadProgress` 关于字节进展和 `signal` 改为 撤销。 在将上传处理为完整之前等待回复; 存储失败可以 已发送所有字节后到达 .

## 资源和产生的业务

`RestResource` 列表/显示/创建/更新/替换/删除帮助者。 每个资源都声明其后端实际挂载操作; 不支持的调用 `UnsupportedOperationError` 本地而不是发出返回的请求 `405`。更新动词为每个服务可配置.

`OpenApiClient<paths>` 生成路径、查询、页眉、正文和响应类型 `openapi-typescript` 合同。 服务包还暴露出生成的命名操作,这些操作保存了每个挂载后端动词,路径参数,查询对象,请求正文,响应信封,运输编码,以及许可注释.

## 认证刷新和错误

配置 `refreshAuth` 当同时接到电话时共享刷新 `401`。复选的电话获得新令牌;在 cookie 模式下,回调可能返回 `null` 在服务器旋转了它的 HttpOnly cookie 之后,受保护的请求仍然被重试一次. 失败会刷新清晰的陈旧证书 。 刷新失败保留了原始保护请求 Axios 错误(并将刷新错误作为附件) `cause` 因此应用程序保留了操作状态,响应正文,信头,请求ID,取消和超时细节.

## Sockudo 实时订阅

`subscribeRealtime` 在 Pusher 兼容的 WebSocket 协议上连接一个私有的 Sockudo 频道。 从自有服务中获取浏览器安全配置,并通过其认证的Faiber客户端授权. 聊天拥有对话频道; 信使拥有通知频道. 浏览器中没有应用程序秘密 .

```ts
import { FaiberClient, subscribeRealtime } from '@faiber/sdk-core';
import { ChatApi } from '@faiber/faiber-chat';
const chat = new ChatApi(new FaiberClient('chat', {
  domains: { chat: 'https://chat.example.com' }, authMode: 'cookie',
}));
const conversationId = 'your-conversation-id';
const config = (await chat.realtimeConfig(conversationId)).data.data;
const reloadMessages = async () => {
  const response = await chat.messages(conversationId);
  console.log(response.data.data);
};
const subscription = subscribeRealtime({
  config,
  authorize: async input => (await chat.realtimeAuth(conversationId, input)).data,
  onEvent: () => { void reloadMessages(); },
  onSubscribed: () => { void reloadMessages(); },
  onError: error => console.error(error.message),
});
// On logout or component teardown:
subscription.close();
```

重新连接时重复订阅授权. `onSubscribed` 每次成功订阅后运行 : 重新装入持续数据以恢复离线时丢失的事件 。 事件是无效提示,其特定服务有效载荷是故意的 `unknown`;服务HTTP响应仍然具有权威性. `onError` 报告连接/授权失败; HTTP 授权失败保留了您回调中的 Axios 正常行为。 关闭取消连接并忽略后期授权结果. HTTPS 页面要求 `wss:`; 允许您的内容安全政策中精确的WebSocket来源.

`RequestOptions<D>` 保存 Axios 信头、信号、超时、适配器和 `withXSRFToken` 上观相. 它的出口 `RequestOptionsContext<D>` 描述 被编码的线体和请求元数据,不包括上游本身. 贾森 请求保留其命名的输入类型; URL 编码的登录/实时操作 提供 `URLSearchParams` 到那个上游。 一个通用元数据上游可以是 重新用于打字请求,而不丢弃机体类型.

## 短身份证

```ts
import { shortIdFromUuid } from "@faiber/sdk-core";
const code = shortIdFromUuid("550e8400-e29b-41d4-a716-446655440000"); // GDCN7L
```

此同步、 离线的帮助器接受 Canonic 或 紧凑的 UUID并投掷 `TypeError` 输入错误。 它产生六个大写字符,没有 `0`, (中文(简体) ), `1`, (中文(简体) ), `I`,或 `O`。使用课堂 UUID 或配置行的 `id` (无) `user_id`) (中文(简体) ). 别名不能保证独有;为操作保留UUID.

## 常见问题

### @faiber/sdk-core 是什么？

每个Faiber TypeScript SDK共享的框架中性运输和认证原始\.

### 如何安装 @faiber/sdk-core？

在项目目录运行 npm install @faiber/sdk-core，或使用 pnpm add / yarn add / bun add。

### @faiber/sdk-core 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @faiber/sdk-core 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @faiber/sdk-core 可以商用吗？

@faiber/sdk-core 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @faiber/sdk-core 的下载量有多少？

根据 npm 官方下载统计，@faiber/sdk-core 在 2026/10/14 – 2026/11/12 这 30 天内被下载 9,023 次，日均约 301 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @faiber/sdk-core 还在维护吗？

最新版本 2\.8\.0 发布于 2026/11/14（今天）；至今共发布 67 个版本，其中过去 12 个月发布了 67 个；首次发布于 2026/07/18。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。