Fastify 如何接入 Zod Type Provider 实现路由类型推导【免费下载链接】fastifyFast and low overhead web framework, for Node.js项目地址: https://gitcode.com/GitHub_Trending/fa/fastify如果你在 TypeScript 项目里用 Fastify 写路由并且希望request.query、request.body的类型直接来自内联的 Zod schema而不是每条路由手写一组泛型接口就需要接入 Fastify 官方的 Zod Type Provider。本文按 Type Providers 文档给出的步骤在 Fastify 中安装并配置fastify/type-provider-zod让路由 schema 在运行时由 Zod 校验在编译期自动推导出请求类型。前提先有一个可编译的 TypeScript Fastify 项目Type Provider 依赖 TypeScript 编译来体现推导效果参照 TypeScript 文档的起步步骤npm init -y npm i fastify npm i -D typescript types/node在package.json的scripts中加入{ scripts: { build: tsc -p tsconfig.json, start: node index.js } }初始化 TypeScript 配置npx tsc --init文档要求把tsconfig.json中的target设为es2017或更高否则会出现 Fastify 的弃用警告。安装 Zod Type Providernpm i zod fastify/type-provider-zod官方 Type Provider 包遵循fastify/type-provider-{provider-name}命名约定Fastify 支持的推导包包括json-schema-to-ts、typebox和zod本文使用其中的 Zod 包。配置替换编译器并绑定 Provider按 Type Providers 文档的 Zod 示例在index.ts中做三件事用 Zod 提供的编译器替换 Fastify 的校验/序列化编译器再通过withTypeProviderZodTypeProvider()启用类型推导。import fastify from fastify import { ZodTypeProvider, serializerCompiler, validatorCompiler } from fastify/type-provider-zod import { z } from zod/v4 const server fastify() server.setValidatorCompiler(validatorCompiler) server.setSerializerCompiler(serializerCompiler) server.withTypeProviderZodTypeProvider().get(/route, { schema: { querystring: z.object({ foo: z.number(), bar: z.string() }) } }, (request, reply) { // type Query { foo: number, bar: string } const { foo, bar } request.query // type safe! })说明两点setValidatorCompiler(validatorCompiler)和setSerializerCompiler(serializerCompiler)让 Fastify 在运行时使用 Zod 编译后的校验与序列化逻辑withTypeProviderZodTypeProvider()则负责编译期推导两者缺一不可。schema 中的querystring直接放 Zod schemaz.object(...)不需要像纯 JSON Schema 那样再单独声明一套 TypeScript 接口。路由拆到模块里用带 Provider 泛型的 FastifyInstance当路由注册函数放在单独的模块时传入的实例参数也要带上 Type Provider 泛型否则推导会丢失。文档给出的模式是在FastifyInstance的五个泛型位置中第五位填入 Provider 类型。将示例中的 TypeBox 替换为 Zod 后等价写法为// index.ts import fastify from fastify import { ZodTypeProvider } from fastify/type-provider-zod import { registerRoutes } from ./routes const server fastify().withTypeProviderZodTypeProvider() registerRoutes(server) server.listen({ port: 3000 })// routes.ts import { z } from zod/v4 import { FastifyInstance, FastifyBaseLogger, RawReplyDefaultExpression, RawRequestDefaultExpression, RawServerDefault } from fastify import { ZodTypeProvider } from fastify/type-provider-zod type FastifyZod FastifyInstance RawServerDefault, RawRequestDefaultExpressionRawServerDefault, RawReplyDefaultExpressionRawServerDefault, FastifyBaseLogger, ZodTypeProvider ; export function registerRoutes(fastify: FastifyZod): void { fastify.get(/route, { schema: { querystring: z.object({ foo: z.number(), bar: z.string() }) } }, (req) { // works const { foo, bar } req.query }); }这里的type FastifyZod就是把文档示例中的 Provider 泛型位置换成ZodTypeProvider其余四个泛型保持默认取值。验证接入是否生效运行npm run build即tsc -p tsconfig.json。类型推导发生在编译期如果 handler 里const { foo, bar } request.query能正常解构且访问request.query上不存在的属性会报类型错误说明推导生效。运行npm run start文档示例中的成功输出是控制台打印Server listening at address例如Server listening at http://127.0.0.1:8080。用curl localhost:3000/route?foo1barx确认路由可达。作用域限制Provider 类型不会全局传播文档明确指出Provider 类型不向全局传播。用register引入插件会进入新的作用域新的作用域里必须再次调用withTypeProvider才能让推导工作server.register(plugin1) // wrong没有重新绑定 Provider server.register(plugin2) // correctplugin2的正确做法是在插件内部重新拿一次带 Provider 的实例function plugin2(fastify: FastifyInstance, _opts, done): void { const server fastify.withTypeProviderZodTypeProvider() server.get(/route, { schema: { querystring: z.object({ foo: z.number(), bar: z.string() }) } }, (req) { // works const { foo, bar } req.query }); done() }由于类型不跨作用域传播多个作用域中目前无法避免在每条路由的注册处重复绑定 Provider反过来这也意味着同一个应用的不同作用域可以分别使用不同的 Provider例如一个插件用typebox、另一个用json-schema-to-ts互不干扰。继续深入Type Providers 参考文档json-schema-to-ts、TypeBox、Zod 三种官方 Provider 的完整示例与 Scoped Type-Provider 说明。TypeScript 参考文档不依赖 Type Provider 时通过server.get{ Querystring, Body, Reply }手写泛型的替代方案。TypeProvider 类型定义FastifyTypeProvider接口与CallValidatorTypeProvider等推导逻辑的源码定义自定义 Provider 时可对照阅读。【免费下载链接】fastifyFast and low overhead web framework, for Node.js项目地址: https://gitcode.com/GitHub_Trending/fa/fastify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考