本文详解如何在 fastify 中全局、无副作用地禁用请求/响应的 json schema 验证逻辑，同时保留 schema 定义以支持 swagger 文档生成，避免破坏 fastify-swagger 或 fastify-openapi-glue 等插件功能。
本文详解如何在 fastify 中全局、无副作用地禁用请求/响应的 json schema 验证逻辑，同时保留 schema 定义以支持 swagger 文档生成，避免破坏 fastify-swagger 或 fastify-openapi-glue 等插件功能。
在 Fastify 应用中，schema 不仅用于运行时验证，更是 OpenAPI/Swagger 文档生成的核心依据。若通过 route.schema = null 等方式移除 schema，虽可跳过验证，但会导致 fastify-swagger、fastify-openapi-glue 等插件无法提取接口元数据，最终文档缺失或报错——这正是许多开发者踩坑的关键点。
正确的解法是保持 schema 原样不动，仅绕过验证执行逻辑。Fastify 提供了高度可定制的 setValidatorCompiler API，它允许你完全接管「如何将 schema 编译为校验函数」的过程。其签名如下：
fastify.setValidatorCompiler<Schema>(compiler: ValidatorCompiler<Schema>): void
其中 ValidatorCompiler 是一个返回校验函数的工厂函数：(schema: Schema) => (data: unknown) => ValidationResult。
因此，要实现「零验证」效果，只需让编译器始终返回一个恒真校验函数即可：
// ✅ 正确：全局禁用验证，不干扰 schema 存在性与文档生成 fastify.setValidatorCompiler(() => () => true);
该写法含义清晰：
- 外层 () => 是 compiler 函数（接收 schema，此处忽略）；
- 内层 () => true 是实际校验函数（接收任意输入，一律返回 true）；
- 返回值符合 Fastify 要求的 ValidationResult 类型（true 表示通过，false 或 { error } 表示失败）。
⚠️ 注意事项：
- 不要使用 { value } 形式：如 () => (value) => ({ value })，这是为支持转换型校验器（如 ajv 的 coerceTypes）设计的，仅当校验器需返回修改后数据时才适用；单纯跳过验证无需此结构，且可能引发类型不匹配或意外行为。
- 生效时机：必须在任何路由注册之前调用 setValidatorCompiler（推荐在 register 插件入口顶部或 FastifyInstance 创建后立即设置）。
- 作用范围：影响所有后续注册的路由（包括子插件），但对已注册路由无效（故务必前置）。
- 性能影响：几乎为零——空函数调用开销可忽略，且避免了 AJV 实例初始化与 schema 编译过程。
完整示例（在插件中安全使用）：
module.exports = async function (fastify, opts) {
// ? 关键：在定义任何路由前设置
if (opts.disableValidation === true) {
fastify.setValidatorCompiler(() => () => true);
}
fastify.get('/stations.json', {
schema: {
response: {
200: {
type: 'object',
properties: {
stations: { type: 'array', items: { type: 'string' } }
}
}
}
}
}, async (req) => {
return { stations: ['A', 'B', 'C'] };
});
};此时：
- 请求体/查询参数/响应体均不再被校验；
- /stations.json 的 schema 仍完整保留在 fastify.swagger() 输出中；
- fastify-swagger UI 可正常加载、渲染文档；
- 未来可通过配置开关灵活启用/禁用（例如开发环境关闭、生产环境开启）。
总结：禁用 Fastify Schema 验证 ≠ 删除 schema，而是「编译出无操作校验器」。fastify.setValidatorCompiler(() => () => true) 是语义准确、兼容性强、副作用最小的标准实践，应作为首选方案。
