Node.js 输入校验与数据契约：Zod、类型安全与工程实践

// 编译期：type 只存在编译期，运行时早已擦除
type User = { id: number; name: string };
const u: User = JSON.parse(rawBody); // TS 信了，运行时 rawBody 可能是任意值

import { z } from 'zod';

const UserSchema = z.object({
  id: z.number().int().positive(),
  name: z.string().min(1).max(50),
  email: z.string().email(),
  age: z.number().int().min(0).max(150).optional(),
  role: z.enum(['admin', 'user']).default('user'),
});

// 校验
const result = UserSchema.safeParse(raw);
if (result.success) {
  result.data; // 类型已经推导：{ id: number; name: string; ... }
} else {
  result.error.issues; // 结构化错误列表
}

const BaseUser = z.object({ id: z.number(), name: z.string() });

const CreateUser = BaseUser.omit({ id });          // 创建时无 id
const UpdateUser = BaseUser.partial();              // 更新时全部可选
const UserView = BaseUser.extend({                  // 扩展字段
  createdAt: z.coerce.date(),
});

// 联合/可空
const Response = z.discriminatedUnion('type', [   // 可辨识联合，比 z.union 更优
  z.object({ type: z.literal('ok'), data: UserView }),
  z.object({ type: z.literal('error'), message: z.string() }),
]);

// 单一事实来源：schema 即类型
const OrderSchema = z.object({
  id: z.string().uuid(),
  amount: z.number().positive(),
  items: z.array(z.object({ sku: z.string(), qty: z.number().int() })),
});
type Order = z.infer<typeof OrderSchema>;
// Order = { id: string; amount: number; items: { sku: string; qty: number }[] }

// ✗ 双写：interface 与 zod schema 各写一份，必然漂移
interface Order { ... }
const OrderSchema = z.object({ ... });

// ✓ 单源：只写 schema，类型自动 infer，永不失同步

// transform：校验通过后再加工（脱敏、格式化）
const MoneySchema = z.number().transform((v) => Math.round(v * 100));

const validate = (schema) => (req, res, next) => {
  const result = schema.safeParse(req.body);
  if (!result.success) {
    return res.status(400).json({
      code: 'VALIDATION_ERROR',
      issues: result.error.issues.map((i) => ({
        path: i.path.join('.'),
        message: i.message,
      })),
    });
  }
  req.validated = result.data; // 后续路由用干净的已校验数据
  next();
};

app.post('/users', validate(CreateUser), (req, res) => {
  // req.validated 类型完整，可直接落库
});

{
  "code": "VALIDATION_ERROR",
  "issues": [
    { "path": "email", "message": "Invalid email" },
    { "path": "age", "message": "Number must be greater than 0" }
  ]
}

共享契约层（共享包 / 模块）：
  schemas/
    order.ts        —— Order 的创建/查询/响应 schema
    user.ts         —— User 的公开/内部 schema
    common.ts       —— 分页、错误结构、traceId

// 内部：完整字段（含 DB 私有字段）
const OrderInternal = z.object({ id, amount, createdBy, createdAt });

// 对外：白名单视图（不含敏感字段）
const OrderPublic = OrderInternal.omit({ createdBy }).extend({
  createdAt: z.coerce.date(),
});

const schema = z.object({
  email: z.string().email('请输入有效的邮箱地址'),
  age: z.number().min(18, '年龄必须大于等于 18 岁'),
});

// 前端/后端共享错误字典，避免散落字符串
const messages = {
  'invalid_type': '字段类型不正确',
  'too_small': '字段长度/数值过小',
  'invalid_email': '邮箱格式不正确',
};
// 按 issue.code 翻译