@ fastify/ type- professor- zod
类型提供者 佐德语Name。 。 。 .
安装
npm i zod
npm i @fastify/type-provider-zod
Zod 兼容性
@fastify/type-provider-zod 只与Zod v4.2 或以后工作.
重要 (v0+)
从 页:1这个图书馆使用Zod的
.encode()编号 :.decode()引入的 API 佐德4.1号。 。 。 . 由于这个变化, 响应序列化现在基于z.output<T>改为z.input<T>。 。 。 .
怎样用?
import type { ZodTypeProvider } from '@fastify/type-provider-zod';
import {
serializerCompiler,
validatorCompiler,
} from '@fastify/type-provider-zod';
import { z } from 'zod/v4';
const app = Fastify();
// Add schema validator and serializer
app.setValidatorCompiler(validatorCompiler);
app.setSerializerCompiler(serializerCompiler);
app.withTypeProvider<ZodTypeProvider>().route({
method: 'GET',
url: '/',
// Define your schema
schema: {
querystring: z.object({
name: z.string().min(4),
}),
response: {
200: z.string(),
},
},
handler: (req, res) => {
res.send(req.query.name);
},
});
app.listen({ port: 4949 });
您也可以将选项传递给 serializerCompiler 函数 :
type ZodSerializerCompilerOptions = {
replacer?: ReplacerFunction;
};
import Fastify from 'fastify';
import {
createSerializerCompiler,
validatorCompiler,
} from '@fastify/type-provider-zod';
const app = Fastify();
const replacer = function (key, value) {
if (this[key] instanceof Date) {
return { _date: value.toISOString() };
}
return value;
};
// Create a custom serializer compiler
const customSerializerCompiler = createSerializerCompiler({ replacer });
// Add schema validator and serializer
app.setValidatorCompiler(validatorCompiler);
app.setSerializerCompiler(customSerializerCompiler);
// ...
app.listen({ port: 4949 });
如何与 @ fastify/ swagger 一起使用
import fastify from 'fastify';
import fastifySwagger from '@fastify/swagger';
import fastifySwaggerUI from '@fastify/swagger-ui';
import { z } from 'zod/v4';
import type { ZodTypeProvider } from '@fastify/type-provider-zod';
import {
jsonSchemaTransform,
createJsonSchemaTransform,
serializerCompiler,
validatorCompiler,
} from '@fastify/type-provider-zod';
const app = fastify();
app.setValidatorCompiler(validatorCompiler);
app.setSerializerCompiler(serializerCompiler);
app.register(fastifySwagger, {
openapi: {
info: {
title: 'SampleApi',
description: 'Sample backend service',
version: '1.0.0',
},
servers: [],
},
transform: jsonSchemaTransform,
// You can also create transform with custom skiplist of endpoints that should not be included in the specification:
//
// transform: createJsonSchemaTransform({
// skipList: [ '/documentation/static/*' ]
// })
});
app.register(fastifySwaggerUI, {
routePrefix: '/documentation',
});
const LOGIN_SCHEMA = z.object({
username: z.string().max(32).describe('Some description for username'),
password: z.string().max(32),
});
app.after(() => {
app.withTypeProvider<ZodTypeProvider>().route({
method: 'POST',
url: '/login',
schema: { body: LOGIN_SCHEMA },
handler: (req, res) => {
res.send('ok');
},
});
});
async function run() {
await app.ready();
await app.listen({
port: 4949,
});
console.log(`Documentation running at http://localhost:4949/documentation`);
}
run();
自定义错误响应
您可以将自定义处理请求和响应验证错误添加到您的固化错误处理器中 :
import { hasZodFastifySchemaValidationErrors } from '@fastify/type-provider-zod';
fastifyApp.setErrorHandler((err, req, reply) => {
if (hasZodFastifySchemaValidationErrors(err)) {
return reply.code(400).send({
error: 'Response Validation Error',
message: 'Request doesn't match the schema',
statusCode: 400,
details: {
issues: err.validation,
method: req.method,
url: req.url,
},
});
}
if (isResponseSerializationError(err)) {
return reply.code(500).send({
error: 'Internal Server Error',
message: 'Response doesn't match the schema',
statusCode: 500,
details: {
issues: err.cause.issues,
method: err.method,
url: err.url,
},
});
}
// the rest of the error handler
});
如何创造回旋装置?
提供后,此软件包将使用 jsonSchemaTransformObject 函数。 您将计划与全球 Zod 注册注册, 并指定它们 id。 。 。 . fastifySwagger 之后将创建一个OpenAPI文档,该文档将引用计划.
以下例子对 User 计划,包括 User openAPI 文档中的 schema.
import fastifySwagger from '@fastify/swagger';
import fastifySwaggerUI from '@fastify/swagger-ui';
import fastify from 'fastify';
import { z } from 'zod/v4';
import type { ZodTypeProvider } from '@fastify/type-provider-zod';
import {
jsonSchemaTransformObject,
jsonSchemaTransform,
serializerCompiler,
validatorCompiler,
} from '@fastify/type-provider-zod';
const USER_SCHEMA = z.object({
id: z.number().int().positive(),
name: z.string().describe('The name of the user'),
});
z.globalRegistry.add(USER_SCHEMA, { id: 'User' });
const app = fastify();
app.setValidatorCompiler(validatorCompiler);
app.setSerializerCompiler(serializerCompiler);
app.register(fastifySwagger, {
openapi: {
info: {
title: 'SampleApi',
description: 'Sample backend service',
version: '1.0.0',
},
servers: [],
},
transform: jsonSchemaTransform,
transformObject: jsonSchemaTransformObject,
});
app.register(fastifySwaggerUI, {
routePrefix: '/documentation',
});
app.after(() => {
app.withTypeProvider<ZodTypeProvider>().route({
method: 'GET',
url: '/users',
schema: {
response: {
200: USER_SCHEMA.array(),
},
},
handler: (req, res) => {
res.send([]);
},
});
});
async function run() {
await app.ready();
await app.listen({
port: 4949,
});
console.log(`Documentation running at http://localhost:4949/documentation`);
}
run();
如何创建插件 ?
import { z } from 'zod/v4';
import type { FastifyPluginAsyncZod } from '@fastify/type-provider-zod';
const plugin: FastifyPluginAsyncZod = async function (fastify, _opts) {
fastify.route({
method: 'GET',
url: '/',
// Define your schema
schema: {
querystring: z.object({
name: z.string().min(4),
}),
response: {
200: z.string(),
},
},
handler: (req, res) => {
res.send(req.query.name);
},
});
};
如何指定不同的 OpenAPI 目标
您可以使用 : createJsonSchemaTransform 函数与 zodToJsonConfig.target 选项.
默认目标为"openapi-3.0",用于将“openapi”字段设置为"3.0.x"的文档;而将“trop-2020-12”用于将“openapi”字段设置为"3.1.x"的文档.
使用量
import { createJsonSchemaTransform } from '@fastify/type-provider-zod';
// For OpenAPI 3.0.x compatibility
const transform = createJsonSchemaTransform({
zodToJsonConfig: { target: 'openapi-3.0' },
});
// For OpenAPI 3.1+
const transform = createJsonSchemaTransform({
zodToJsonConfig: { target: 'draft-2020-12' },
});
许可证
许可证根据 麻省理工学院。 。 。 .