# @efebia/fastify-zod-reply 中文文档

规范地址：https://npmcn.com/package/%40efebia/fastify-zod-reply/

版本：1\.6\.0
npm 元数据更新时间：2026-11-10T11:29:49.393Z
中文译文更新时间：2026-11-13T08:05:49.237Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40efebia/fastify-zod-reply
原文对照：https://npmcn.com/package/%40efebia/fastify-zod-reply/?lang=original
项目主页：https://github.com/efebia-com/be-libs#readme
源码仓库：https://github.com/efebia-com/be-libs

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

- 包体积（解压后）：90.4 kB，42 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2025-04-07T16:15:41.640Z
- 最新版本发布：2026-11-10T11:29:48.921Z
- 近 30 天下载量：3395（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：22（近 12 个月 5 个）

## 中文简介

Fastify 5 插件提供类型安全的 HTTP 回复帮助和 Zod v4 路由的 schema 验证,并有自动生成的 OpenAPI schemas 和 SSE 支持.

## 安装

```sh
npm install @efebia/fastify-zod-reply
```

也可以使用：`pnpm add @efebia/fastify-zod-reply`、`yarn add @efebia/fastify-zod-reply`、`bun add @efebia/fastify-zod-reply`

## README

# @efebia/ fastify-zod-reply (英语)

Fastify 5 插件提供类型安全的 HTTP 回复帮助和 Zod v4 路由的 schema 验证,并有自动生成的 OpenAPI schemas 和 SSE 支持.

## 安装

```bash
npm install @efebia/fastify-zod-reply
```

## 使用量

### 1\. 注册插件

```ts
import Fastify from 'fastify';
import fastifyZodReply from '@efebia/fastify-zod-reply';

const fastify = Fastify();
await fastify.register(fastifyZodReply);
```

### 2\. 界定路线 `routeV4`

```ts
import { z } from 'zod';
import { routeV4 } from '@efebia/fastify-zod-reply';

fastify.get('/users/:id', routeV4(
  {
    Params: z.object({ id: z.string() }),
    Reply: z.object({
      200: z.object({ id: z.string(), name: z.string() }),
      404: z.object({ message: z.string() }),
    }),
  },
  async (request, reply) => {
    const user = await findUser(request.params.id);
    if (!user) return reply.notFound('User not found');
    return reply.ok(user);
  }
));
```

`routeV4` 自动 :

-   验证 `Body`, (中文(简体) ), `Params`, (中文(简体) ), `Query`,以及 `Headers` 通过 处理器运行前的 Zod
-   校正和序列化针对 `Reply` 计划
-   生成 JSON Schema 用于 Fastify 的 OpenAPI 集成

### 3\. 答复助手

插件装饰 `FastifyReply` 使用语义方法:

```ts
reply.ok({ id: '1', name: 'Alice' })   // 200
reply.created({ id: '2' })              // 201
reply.accepted()                        // 202
reply.noContent()                       // 204

reply.badRequest('Validation failed')   // 400 — throws FastifyError
reply.unauthorized()                    // 401
reply.forbidden()                       // 403
reply.notFound('User not found')        // 404
reply.notAcceptable()                   // 406
reply.conflict()                        // 409
reply.internalServerError()             // 500
```

将字符串传递到错误方法中 `FastifyError` 和那个信息。 传出一个物体就当作JSON.

## SSE( 仆人事件)

使用 `sseRouteV4` 用于流出端点:

```ts
import { sseRouteV4 } from '@efebia/fastify-zod-reply';

fastify.get('/events', sseRouteV4(
  {
    Reply: z.object({
      SSE: z.object({ data: z.object({ count: z.number() }) }),
    }),
  },
  async (request, reply) => {
    async function* generate() {
      for (let i = 0; i < 10; i++) {
        yield { data: { count: i } };
      }
    }
    return reply.sse({ stream: generate() });
  }
));
```

这个 `SSE` 键 `Reply` 计划地图 `200` 状态代码为 `text/event-stream` 内容类型. `request.abortController` 自动连接到套接字 `close` 活动.

## 自定义验证错误

何时 `Body`, (中文(简体) ), `Params` 或者说 `Query` 佐德验证失败, `routeV4` 财务报告和审定财务报表 `sseRouteV4` 回复 `400` 与 `{ "message": "Error at <source>-><path>-><message>" }` (每期一行). 送别的东西,提供 `validationErrorFormatter` 接收原始Zod问题和来源:

```ts
import {
  createRouteV4,
  type ValidationErrorFormatter,
} from '@efebia/fastify-zod-reply';

const formatter: ValidationErrorFormatter = (issues, source) => ({
  statusCode: 400,
  body: {
    code: 'VALIDATION_ERROR',
    message: 'Invalid request data',
    errors: issues.map((issue) => ({
      source,
      path: issue.path.join('.'),
      rule: issue.code === 'invalid_type' ? 'type' : 'invalid',
      code: issue.code,
      message: issue.message,
    })),
  },
});

// plugin-wide default
await fastify.register(fastifyZodReply, { validationErrorFormatter: formatter });
// or per factory
const routeV4 = createRouteV4({ validationErrorFormatter: formatter });
// or per route
fastify.post('/x', routeV4(schema, handler, { validationErrorFormatter: formatter }));
```

-   签署: `(issues: ValidationIssue[], source: 'body' | 'query' | 'params' | 'headers') => { statusCode?: number; body: unknown }`。 。 。 . `statusCode` 默认为 `400`。 。 。 .
-   优先性:路线选项,然后 `createRouteV4`编号 :`createSSERouteV4` 选项,然后是插件选项,然后是内置文本.
-   每个失败源一次调用 formatter; 第一个失败源 in `body`, (中文(简体) ), `params`, (中文(简体) ), `query` 命令获胜.
-   字符串 `body` 被逐字发送,任何其它作为 JSON 与 `application/json`自定义机构绕过路线 `400` 故你应当说:你们用计谋吧!他们不被它剥除或拒绝.
-   `defaultValidationErrorFormatter` 导出并复制内置输出.
-   `'headers'` 是源类型的一部分, 但今天没有发布 : 信头只能通过 Fastify 的 JSON- schema 验证来检查, 而不是 Zod 预处理器 .
-   只有请求验证受到影响. 答复确认(`500`)和SSE流项目错误保留其文本格式.

## API 密码

### `routeV4(schema, handler, options?)`

预建路线工厂 `strict: false`。 。 。 .

### `createRouteV4(options?)`

创建自定义的工厂 `routeV4` 带有共享默认值.

```ts
import { createRouteV4 } from '@efebia/fastify-zod-reply';

const routeV4 = createRouteV4({ strict: true });
```

**选项( E)`RouteV4Options`:**

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `strict` | `boolean | { body, query, params, headers }` | `false` | 从请求输入中去除未知字段 |

**司马场( S)`BaseZodV4Schema`:**

| 外地 | 类型 | 说明 |
| --- | --- | --- |
| `Body` | `z.ZodTypeAny` | 请求体图a |
| `Params` | `z.ZodTypeAny` | 路线参数方案 |
| `Query` | `z.ZodTypeAny` | 查询字符串计划 |
| `Headers` | `z.ZodTypeAny` | 页眉计划 |
| `Reply` | `z.ZodObject` | 由 HTTP 状态代码键入的响应计划 |
| `Tags` | `(keyof RouteTag)[]` | OpenAPI 标签 |
| `Security` | `RouteSecurity[]` | OpenAPI 安全计划 |
| `Summary` | `string` | OpenAPI 摘要 |
| `Description` | `string` | OpenAPI 描述 |
| `Notes` | `string` | 补充说明 |

### `sseRouteV4(schema, handler, options?)`

预建SSE路线工厂. 这个 `Reply` 计划必须包括 `SSE` 键.

### `createSSERouteV4(options?)`

创建自定义的工厂 `sseRouteV4`接受 `SSERouteV4Options`数字 :

| 选项 | 类型 | 说明 |
| --- | --- | --- |
| `strict` | `boolean | object` | 与 `routeV4` |
| `sse.keepAliveInterval` | `number` | 恒活键的间隔( ms) |
| `sse.onError` | `(error) => void` | 流的全局错误处理器 |
| `sse.validateStream` | `boolean` | 对照方案验证每个SSE事件 |

### `buildHTTPErrorObject(statusCode, message)`

构建一个简单的 HTTP 错误对象.

### `FastifyZodReplyError`

当响应序列化失败时会抛出错误类 .

### `RouteTag` 编号 : `RouteSecurity`

空接口——通过模块增强来扩展以添加您自己的 OpenAPI 标签和安全方案:

```ts
declare module '@efebia/fastify-zod-reply' {
  interface RouteTag {
    users: never;
    orders: never;
  }
  interface RouteSecurity {
    bearerAuth: never;
  }
}
```

## 许可证

麻省理工学院

## 常见问题

### @efebia/fastify-zod-reply 是什么？

Fastify 5 插件提供类型安全的 HTTP 回复帮助和 Zod v4 路由的 schema 验证,并有自动生成的 OpenAPI schemas 和 SSE 支持\.

### 如何安装 @efebia/fastify-zod-reply？

在项目目录运行 npm install @efebia/fastify-zod-reply，或使用 pnpm add / yarn add / bun add。

### @efebia/fastify-zod-reply 支持 TypeScript 吗？

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

### @efebia/fastify-zod-reply 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @efebia/fastify-zod-reply 可以商用吗？

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

### @efebia/fastify-zod-reply 的下载量有多少？

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

### @efebia/fastify-zod-reply 还在维护吗？

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