# @defjs/core 中文文档

规范地址：https://npmcn.com/package/%40defjs/core/

版本：0\.6\.0
npm 元数据更新时间：2026-11-01T19:41:55.168Z
中文译文更新时间：2026-11-11T21:01:09.597Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40defjs/core
原文对照：https://npmcn.com/package/%40defjs/core/?lang=original
项目主页：https://github.com/defjs/defjs#readme
源码仓库：https://github.com/defjs/defjs

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

- 包体积（解压后）：495 kB，6 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2024-08-02T19:36:19.512Z
- 最新版本发布：2026-11-01T19:41:54.882Z
- 近 30 天下载量：9544（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：32（近 12 个月 5 个）

## 中文简介

定义并执行已键入的 HTTP, SSE, 以及 WebSocket API.

## 安装

```sh
npm install @defjs/core
```

也可以使用：`pnpm add @defjs/core`、`yarn add @defjs/core`、`bun add @defjs/core`

## README

# @ defjs/ core (中文(简体) )

设计可重用HTTP,SSE,和WebSocket API作为数据,然后用应用程序拥有的客户端执行.

`def` 表示 `define`. SDK 作者输出操作定义和数据合同. 消耗的应用程序提供终点、证书、拦截器和运输。 导入定义时不会启动请求, 也不会约束客户端 .

## 安装

```sh
bun add @defjs/core
```

该软件包是无害环境管理,并宣布不依赖运行时间。 申报指标 `ES2022` 与 `ESNext.Disposable`, (中文(简体) ), `DOM`,以及 `DOM.Iterable`;这些条目只提供类型,而不是多填充。 Defjs是1.0前,所以使用文档来获取您安装的确切版本.

## 快开始

```ts
// users-sdk.ts — SDK definition
import { defineRequest, struct } from "@defjs/core";

export const getUser = defineRequest({
  method: "GET",
  path: "/users/:id",
  input: struct.object({ id: struct.number() }),
  builder: (input) => ({ path: input }),
  output: struct.object({ id: struct.number(), name: struct.string() }),
  error: struct.object({ message: struct.string() }),
});
```

```ts
// app.ts — application-owned client
import { createClient, withEndpoint } from "@defjs/core";
import { getUser } from "./users-sdk.ts";

const client = createClient(withEndpoint("https://api.example.com"));

async function main() {
  const [error, user] = await getUser(client, { id: 1 });
  if (error) {
    console.error(String(error), error.code);
    return;
  }
  console.log(user.name);
}

void main();
```

通话 `getUser(client, { id: 1 })` 验证、构建和发送请求. `client({ signal })` 返回 a `Client` 一次呼叫的值而不执行 I/O。在读取成功值之前返回 `error` 已经设定。 发布后,导入 `getUser` 从您的 SDK 软件包中取出, 而不是本地文件 —— 见 [构建并发布 SDK](https://defjs.lyz.cloud/recipes/publish-http-sdk)。 。 。 .

## 规则

-   用客户端调用操作执行 I/O. 定义不能抓取客户端 。 没有全球客户端.
-   7个选择 `RequestOptions` 字段 : `signal`, (中文(简体) ), `onUploadProgress`, (中文(简体) ), `onDownloadProgress`, (中文(简体) ), `beforeConnect`, (中文(简体) ), `protocols`, (中文(简体) ), `heartbeat`,以及 `reconnect`。 。 。 . `client(options)` 返回不可调用的客户端值,将这些字段复制到新对象; 设置为 `undefined` 被删除。 嵌入 `heartbeat`, (中文(简体) ), `protocols`,以及 `reconnect` 数值通过参考来保存,因此,在通过这些数值后,将其视为不可改变。 过 `AbortSignal.timeout(ms)` 作为 `signal` 当一个电话需要一个最后期限。 这是因为 `NET_TIMEOUT`; 手动中止 `NET_ABORTED`。投球手从 `client(options)`而不是作为一个错误。 SSE和WebSocket没有只启动的最后期限:信号中止了整个连接.
-   `input` 宣告参数; 同步、 纯度 `builder` 把它们放在 `path`, (中文(简体) ), `query`, (中文(简体) ), `headers`,以及 `body`。每个定义 `input` 需要明确 `builder`。 。 。 .
-   Structs 运行时验证 . `output` 是2xx的身体, `error` 每一个其它状态;略去一面,身体永远不读.
-   失败作为 `Fault` 错误的第一个二进制中的情况 - `HTTP_STATUS`, (中文(简体) ), `REQ_*`, (中文(简体) ), `NET_*`, (中文(简体) ), `RES_*`, (中文(简体) ), `EXT_*`, (中文(简体) ), `CAP_*`, (中文(简体) ), `ENV_UNSUPPORTED`。 。 。 . `String(error)` 发出消息; `error.code` 和因子链的结构为日志.
-   超时或取消不能证明服务器错过了写入 。 在重放出作文前,保留应用程序一能合同.
-   返回的SSE和 WebSocket 手柄是 `AsyncDisposable`; 网页 `closed` 是逻辑终端结果.
-   输入一个与获取兼容的函数 `withHTTPHandle(...)` 测试一个没有服务器的客户端——见 [用手柄进行测试](https://defjs.lyz.cloud/recipes/test-with-handle)。 。 。 .

## 文档

-   [开始](https://defjs.lyz.cloud/docs/start)
-   [客户端](https://defjs.lyz.cloud/docs/client) • 妇女 [错误](https://defjs.lyz.cloud/docs/errors) • 妇女 [结构](https://defjs.lyz.cloud/docs/struct)
-   [HTTP 密码](https://defjs.lyz.cloud/docs/http) • 妇女 [证监会](https://defjs.lyz.cloud/docs/sse) • 妇女 [网络安全套](https://defjs.lyz.cloud/docs/web-socket)

## 许可证

麻省理工学院.

## 常见问题

### @defjs/core 是什么？

定义并执行已键入的 HTTP, SSE, 以及 WebSocket API\.

### 如何安装 @defjs/core？

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

### @defjs/core 支持 TypeScript 吗？

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

### @defjs/core 支持 ESM 还是 CommonJS？

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

### @defjs/core 可以商用吗？

@defjs/core 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @defjs/core 的下载量有多少？

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

### @defjs/core 还在维护吗？

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