用途:在系统的所有入口点(API 路由、Webhook、队列消费者、定时任务输入等)加入集中式输入校验层,且校验在任何业务逻辑或数据库操作之前执行。
主要能力与原则:在边界校验;使用白名单而非黑名单;不信任 headers、query、URL params、body、cookies、Webhook 载荷;失败关闭(未知/多余字段被剥离或拒绝);单一 Schema 作为真相来源,同时用于校验、TypeScript 类型与文档。示例使用 Zod:定义 CreateInvoiceSchema 并用 z.infer 推导类型;默认 .strip() 剥离未知字段,.strict() 完全拒绝未知键。
使用方式:用中间件模式集中校验。示例 export function validate(schema, target = 'body') 使用 schema.safeParse(req[target]),失败返回 400 及问题列表,成功则用解析结果替换 req[target]。在路由中组合 requireAuth、validate(CreateInvoiceSchema,'body')、validate(params 校验,'params') 等。查询参数用 z.coerce 做字符串到数字的转换并设置默认值。Webhook 先验签再解析载荷,例如 validateStripeSignature 调用 stripe.webhooks.constructEvent(req.rawBody, req.headers['stripe-signature'], WEBHOOK_SECRET),失败返回 400。队列消费者用 schema.parse(rawPayload) 校验后再执行。启动时用 EnvSchema.parse(process.env) 校验环境变量,尽早失败。
需校验的非显性输入:URL 中的数字 ID、枚举字段、日期、货币(整数分)、重定向 URL、文件上传(MIME、扩展名、大小三者)、自由文本(.max())、数组(.array().min(1).max(50))。
校验与净化:校验用于拒绝无效输入,始终在入口执行;净化仅用于必须保留格式时,如 .trim()、.toLowerCase()。安全敏感字段优先拒绝而非转换,不静默截断 ID、token 或枚举值。
错误响应:所有端点保持统一形状,如 {"error":"Validation failed","issues":[{"field":"recipient.email","message":"Invalid email"}]},不泄漏堆栈等内部细节。
限制与说明:资料未提供该技能的具体安装方式、运行平台、收费信息与适用范围细节,暂未提供相关说明。