用途:在构建或修改 Fastify v5+ REST API 时提供 TypeBox 模式与 @fastify/type-provider-typebox 的实践指引,覆盖类型安全路由、请求/响应推断、OpenAPI 3.0 生成、插件架构与钩子生命周期,以及 inject() 测试、数据库(Drizzle、Prisma)与鉴权集成。
主要能力:定义校准与序列化用的 TypeBox 模式;用 fastify.withTypeProvider<TypeBoxTypeProvider>() 获得编译期类型安全;通过 @fastify/swagger 从 TypeBox 模式生成 OpenAPI;用 fast-json-stringify 序列化响应(资料称 2-3 倍提速并避免字段泄漏);组织插件、装饰器与请求钩子(onRequest、preValidation、preHandler、onSend 等)。
必要用法与要点:始终使用 TypeBoxTypeProvider;为每个状态码定义响应模式;共享插件用 fastify-plugin 包装以暴露装饰器;新项目使用 typebox 包而非已弃用的 @sinclair/typebox;测试用 inject(),不启动真实 HTTP 服务;注册顺序需先共享模式与基础设施插件,CORS/helmet 最先。
限制:不覆盖前端框架、GraphQL、Express 迁移、非 TypeBox 模式库;TypeBox Transform 与 Ajv 不兼容,需 TypeBoxValidatorCompiler 或 Value.Decode/Encode;参考类型不可作装饰器初值(跨请求共享有安全风险)。