本文详解如何通过 Fastify 的 setErrorHandler 和 Ajv 配置，将默认的验证错误（如 FST_ERR_VALIDATION）统一转换为结构清晰、符合业务规范的 JSON 错误响应，支持多字段错误聚合与自定义字段映射。
本文详解如何通过 fastify 的 `seterrorhandler` 和 ajv 配置，将默认的验证错误（如 fst_err_validation）统一转换为结构清晰、符合业务规范的 json 错误响应，支持多字段错误聚合与自定义字段映射。
在 Fastify 中，默认的 Schema 验证错误（由内置 Ajv 实例触发）会以 FST_ERR_VALIDATION 形式返回，格式固定且不便于前端统一解析。若需输出如下的标准化错误结构：
{
"message": "Bad request",
"path": "/account/register",
"status": 400,
"timestamp": 1697094987,
"errors": [
{ "key": "email", "value": "This value is not a valid email address." }
]
}
仅靠 schemaErrorFormatter 是不够的——它只能修改 message 字符串内容，无法改变整体响应结构。真正可行的方案需两步协同：
✅ 步骤一：启用 Ajv 的 allErrors 模式
确保 Ajv 返回所有验证失败项（而非默认只返回第一个），便于后端聚合。注意：Fastify 官方标注该选项存在潜在安全风险（如暴露过多字段细节），生产环境应结合业务权衡使用。
const app = require('fastify')({
logger: true,
ajv: {
customOptions: {
allErrors: true // 关键：启用全量错误收集
}
}
});
✅ 步骤二：重写全局错误处理器
通过 app.setErrorHandler() 拦截验证类错误（error.validation 存在即为 Ajv 验证失败），并构造符合要求的响应体：
app.setErrorHandler(function (error, request, reply) {
// 识别 Ajv 验证错误
if (error.validation) {
const errors = error.validation.map(err => ({
key: err.params?.missingProperty ||
err.params?.additionalProperty ||
err.dataPath.replace(/\./g, '').replace(/\//g, '') ||
'unknown',
value: err.message
}));
return reply
.status(400)
.header('Content-Type', 'application/json')
.send({
message: 'Bad request',
path: request.url,
status: 400,
timestamp: Math.floor(Date.now() / 1000), // 秒级时间戳，匹配示例
errors
});
}
// 其他未捕获错误降级为 500
reply.status(500).send({
message: 'Internal server error',
path: request.url,
status: 500,
timestamp: Math.floor(Date.now() / 1000),
errors: [{ key: 'server', value: error.message }]
});
});
? 字段映射说明：
- key 优先取 missingProperty（如 "email"），其次尝试 additionalProperty，最后 fallback 到清洗后的 dataPath（如 /body/email → "email"）；
- value 直接使用 Ajv 原生 err.message，语义清晰；
- timestamp 使用 Math.floor(Date.now() / 1000) 确保秒级整数，与示例严格一致。
✅ 示例 Schema 与路由验证
配合如下 Schema 测试：
const schema = {
body: {
type: 'object',
required: ['email', 'password'],
properties: {
email: { type: 'string', format: 'email' },
password: { type: 'string', minLength: 6 }
}
}
};
app.post('/account/register', { schema }, async (request, reply) => {
return { success: true };
});
当请求体缺失 email 且 password 过短时，将精准返回：
{
"message": "Bad request",
"path": "/account/register",
"status": 400,
"timestamp": 1718234567,
"errors": [
{ "key": "email", "value": "must have required property 'email'" },
{ "key": "password", "value": "should NOT be shorter than 6 characters" }
]
}
⚠️ 注意事项
- 安全性权衡：allErrors: true 可能暴露 Schema 结构细节，建议在开发/测试环境启用，生产环境可结合 error.message 白名单过滤敏感词；
- 路径清洗：dataPath 默认含 /body/xxx 前缀，实际使用中应根据需求清洗（如正则替换 /body/ 或 /）；
- 国际化支持：如需多语言错误提示，可在 error.validation.map() 中接入 i18n 工具，将 err.keyword 映射为本地化文案；
- 性能影响：allErrors 模式会略微增加验证耗时，高并发场景建议压测评估。
通过以上配置，你将完全掌控 Fastify 的验证错误输出形态，实现 API 错误响应的标准化、可维护性与前端友好性。
