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

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

安装

npm install @efebia/fastify-zod-reply

使用量

1. 注册插件

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

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

2. 界定路线 routeV4

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 使用语义方法:

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 用于流出端点:

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问题和来源:

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 带有共享默认值.

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

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

选项( E)RouteV4Options:

司马场( S)BaseZodV4Schema:

sseRouteV4(schema, handler, options?)

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

createSSERouteV4(options?)

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

buildHTTPErrorObject(statusCode, message)

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

FastifyZodReplyError

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

RouteTag 编号 : RouteSecurity

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

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

许可证

麻省理工学院