# @dunx/http 中文文档

规范地址：https://npmcn.com/package/%40dunx/http/

版本：3\.10\.6
npm 元数据更新时间：2026-10-30T04:57:29.389Z
中文译文更新时间：2026-11-13T00:26:06.675Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：443 kB，117 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：@dunx/core ^3\.10\.6，@types/bun \>=1\.4\.3，@bufbuild/protobuf ^2\.15\.0，@connectrpc/connect ^2\.2\.0
- 首次发布：2026-08-02T08:01:35.189Z
- 最新版本发布：2026-10-30T04:57:29.028Z
- 近 30 天下载量：5054（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：83（近 12 个月 83 个）

## 中文简介

Bun.serve dunx 框架的适配器:控制器、中间软件和WebSocket网关

## 安装

```sh
npm install @dunx/http
```

也可以使用：`pnpm add @dunx/http`、`yarn add @dunx/http`、`bun add @dunx/http`

## README

# 翻译:

基于类的控制器和 **网络安全网关** 页:1 [双关](https://github.com/petarzarkov/dunx),服务于 `Bun.serve` 有标准 作装饰. 没有 JavaScript 路由器: Bun 内置 `routes` 处理路径 参数和 HTTP 方法.

HTTP 和 WebSockets 共享一个 `listen()`一个服务器和一个端口,没有 `express`, (中文(简体) ), `ws` 或者说 `socket.io`。 。 。 .

## 安装

```bash
bun add @dunx/http @dunx/core @dunx/transform
```

添加 `preload = ["@dunx/transform/preload"]` 改为 `bunfig.toml` 用于构造器 注射,一次在顶级,一次在下 `[test]`。 。 。 .

## 使用量

```ts
import { inject, Module } from '@dunx/core';
import { Controller, Get, HttpFactory, Post, type Input } from '@dunx/http';
import { z } from 'zod'; // or Valibot, or ArkType, or none at all

const createUser = { body: z.object({ name: z.string() }) } as const;
const oneUser = { params: z.object({ id: z.coerce.number() }) } as const;

@Controller('users')
export class UsersController {
  readonly #users = inject(UsersService);

  @Get('/')
  list() {
    return this.#users.findAll(); // plain values become Response.json()
  }

  @Get('/:id', oneUser)
  one(input: Input<typeof oneUser>) {
    return this.#users.find(input.params.id); // a number, already validated
  }

  @Post('/', createUser)
  create(input: Input<typeof createUser>) {
    return this.#users.create(input.body.name); // 201, no Response.json()
  }
}

@Module({ controllers: [UsersController], providers: [UsersService] })
export class UsersModule {}

const app = await HttpFactory.create(AppModule);
app.enableShutdownHooks();
await app.listen(3000);
```

## 这是什么

每行链接到覆盖它的向导.

| 区域 | 它包含什么 | 指南 |
| --- | --- | --- |
| 主计长和路线 | 单词装饰器、路径参数、前缀、状态代码 | [主计长](https://npmcn.com/package/docs/guide/05-controllers.md) |
| 输入 | `body`, (中文(简体) ), `query`, (中文(简体) ), `params` 超过标准Schema | [验证](https://npmcn.com/package/docs/guide/06-validation.md) |
| 中间软件和警卫 | 一个延伸点, `@UseGuards`, (中文(简体) ), `@Roles`, (中文(简体) ), `@Public` | [中间软件和警卫](https://npmcn.com/package/docs/guide/08-middleware-and-guards.md) |
| 网络安全网关 | `@Gateway`管理者们, `PubSub`,多节点继电器 | [网络软件](https://npmcn.com/package/docs/guide/09-websockets.md) |
| 服务器发送事件 | `@Sse`, (中文(简体) ), `SseStream`画作 心跳, `Last-Event-ID` | [主计长](https://npmcn.com/package/docs/guide/05-controllers.md) |
| 请求日志 | 每个请求一个结构化条目,默认情况下 | [日志](https://npmcn.com/package/docs/guide/13-logging.md) |
| 跟踪上下文 | W3C 战车 `traceparent` 默认通过和宣传 | [日志](https://npmcn.com/package/docs/guide/13-logging.md) |
| 西班牙语 | 每个请求的SERVER间隔和每个呼叫的CLIENT间隔 `OtelModule` | [追踪](https://npmcn.com/package/docs/guide/31-tracing.md) |
| 计量 | 每道计数和计时,默认关闭 | [计量](https://npmcn.com/package/docs/guide/24-metrics.md) |
| 卫生和排水 | `/health/live`, (中文(简体) ), `/health/ready`准备在推出期间 | [健康检查](https://npmcn.com/package/docs/guide/22-health-checks.md) |
| 调弦 | `@Throttle`, (中文(简体) ), `@SkipThrottle`,内存和 Redis 计数器 | [中间软件和警卫](https://npmcn.com/package/docs/guide/08-middleware-and-guards.md) |
| 境外复原能力 | `HttpRetryClassifier`: 哪个状态重试,以及 `Retry-After` | [复原力](https://npmcn.com/package/docs/guide/26-resilience.md) |
| 静态文件 | `Bun.file` 在挂载后带有缓存策略 | [部署](https://npmcn.com/package/docs/guide/21-deployment.md) |
| 压缩 | bun自己的压缩机上的克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克克特克特克特克特克克特克特克特克特克特克特克克克特克克克特克特克特克特克特克克 | [部署](https://npmcn.com/package/docs/guide/21-deployment.md) |
| 难民保护委员会 | 连接和gRPC-Web上的原生软件 | [难民保护委员会](https://npmcn.com/package/docs/guide/28-rpc.md) |

## 子路径

| 子路径 | 包含 |
| --- | --- |
| `@dunx/http` | 上面的东西 |
| `@dunx/http/client` | 外出的一半: `HttpService`重试与后退, `HttpModule` |
| `@dunx/http/connect` | 连接和gRPC-Web上的原生服务,作为中间软件安装 |
| `@dunx/http/internal` | 框架本身的管道。 没有稳定的承诺 |

`@dunx/http/internal` 用于 dunx 自己的软件包 : `@dunx/dashboard`, (中文(简体) ), `@dunx/mcp` 财务报告和审定财务报表 `@dunx/openapi`。不要从应用程序导入它,因为它可以改变任何 释放.

## 页:1

-   路线在靴子上找到,包括从基类继承的路线,所以 抽象控制器的子类服务于其父的 `@Get` 方法也一样.
-   两个相同方法和路径的处理器在启动时失败, 错误名称 都一样 否则Bun会不说就留着其中一个.
-   处理器可以返回一个 `Response`,任何JSON可循环值,或 `undefined` 一个204.
-   `Authorize` 财务报告和审定财务报表 `gate()` 保护管理员页面。 他们收到原始请求 当拒绝访问时回答404,或发送 `Response` 你继续往前走, 例如,登录页. `@dunx/dashboard` 财务报告和审定财务报表 `@dunx/openapi` 都接受一个, 所以你写了一次访问规则.
-   Schemas,解析器和状态代码在启动时一出. 处理a 请求中没有元数据查询.
-   每个请求都加入呼叫者的W3C跟踪(`traceparent`) (中文(简体) ). 它的日志线携带 `traceId`, (中文(简体) ), `spanId`, (中文(简体) ), `parentSpanId` 财务报告和审定财务报表 `traceFlags`,而反应包含 (单位:千美元) `traceresponse` 头曰. `requestLogging: { trace: false }` 关掉两个. `{ traceResponse: false }` 保留跟踪字段,只放信头, 它可以保存大约500纳秒的请求。 没有单独的关联 id.
-   `metrics: true` 添加请求数和每个路线的直径图,用于 大约35纳斯请求.
-   `@dunx/http/connect` 为连接和gRPC-Web服务,但不是本地的gRPC. 土著 gRPC将其状态发送到HTTP拖车中 `Bun.serve` 无法发送, 所以 请求与 `content-type: application/grpc` 得到一个415 解释原因. `@connectrpc/connect` 财务报告和审定财务报表 `@bufbuild/protobuf` 是可选的同伴依赖关系, 你留着你自己的 `.proto` 工具链. `ThrottleGuard` 适用于 RPC 路径 还有.

## 许可证

麻省理工学院

## 常见问题

### @dunx/http 是什么？

Bun\.serve dunx 框架的适配器:控制器、中间软件和WebSocket网关

### 如何安装 @dunx/http？

在项目目录运行 npm install @dunx/http，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@dunx/core（^3\.10\.6）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @dunx/http 支持 TypeScript 吗？

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

### @dunx/http 支持 ESM 还是 CommonJS？

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

### @dunx/http 可以商用吗？

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

### @dunx/http 的下载量有多少？

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

### @dunx/http 还在维护吗？

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