zod schema 必须显式声明 mongodb 所有 required 字段，否则导致数据不一致；应使用 .min()、.nonempty()、.refine() 等强化语义，并用 .omit()/.pick() 衍生安全 schema，避免手动删字段。
z.object 定义 Schema 时必须覆盖所有 required 字段
MongoDB 插入前若漏掉 required: true 字段，而 Zod Schema 没强制约束，就会导致数据不一致。Zod 不会自动读取 Mongoose Schema 或 MongoDB 集合验证规则，它只认自己定义的 z.object。
常见错误是写成这样：
const UserSchema = z.object({
username: z.string(),
email: z.string().email()
});
// ❌ age 字段没声明，但 MongoDB 集合规则里设了 required: true
// 入库时 age 缺失不会被 Zod 拦住
正确做法是显式声明必填项，并用 .min()、.nonempty() 等补强语义：
-
username: z.string().min(2).max(20)—— 避免空格或超长入库 -
email: z.string().email().toLowerCase()—— 统一格式，防重复 -
status: z.enum(['active', 'inactive']).default('active')—— 明确默认值，不依赖 MongoDB 的 default
safeParse + 自定义错误映射适配 MongoDB 错误响应
直接用 parse() 在路由层抛错会导致 500，而 MongoDB 原生报错（比如 duplicate key）又和 Zod 校验失败混在一起，前端难区分。推荐统一走 safeParse()，再把 Zod 错误转成 MongoDB 兼容字段名。
例如后端接收 JSON body，需校验并返回结构化错误：
const result = UserSchema.safeParse(req.body);
if (!result.success) {
// 把 z.ZodError.path 转成 MongoDB 常见字段路径（如 "profile.name" → "profile.name"）
const errors = result.error.issues.map(issue => ({
field: issue.path.join('.'),
message: issue.message,
code: 'VALIDATION_ERROR'
}));
return res.status(400).json({ errors });
}
注意：MongoDB 驱动插入失败（如唯一索引冲突）会抛 MongoServerError，和 Zod 错误是两套体系，不能混为一谈 —— Zod 只管“数据合不合规则”，MongoDB 才管“数据能不能存进去”。
嵌套对象和数组校验容易忽略 .refine() 边界条件
MongoDB 支持嵌套文档和数组，但 Zod 默认对 z.array() 或 z.object() 内部不做深度校验，除非你主动加约束。
使用 JSON Schema 验证 JSON 数据，从示例 JSON 生成 schema，并将其转换为 TypeScript 接口、Python 数据类或 Markdown 文档。
典型坑点：
-
tags: z.array(z.string())—— 允许空数组[]，但业务可能要求至少一个 tag -
address: z.object({ city: z.string(), zip: z.string().optional() })—— 若zip是字符串但传了null，Zod 默认放过（因.optional()匹配undefined | null）
修复方式：
tags: z.array(z.string().min(1)).min(1, '至少需要一个标签'),
address: z.object({
city: z.string().min(1),
zip: z.string().nullish().refine(v => v == null || /^\d{6}$/.test(v), {
message: '邮编必须是6位数字'
})
})
.nullish() 显式接受 null 或 undefined，再用 .refine() 控制逻辑分支，比靠 .optional() 模糊处理更稳。
避免在 insertOne 前手动删掉 unknown 字段
有人会用 omit 或 pick 清洗数据，比如：
const { password, ...cleanData } = req.body;
collection.insertOne(cleanData);
这其实绕过了 Zod 的类型保障。正确姿势是用 Zod 的 .pick() 或 .omit() 方法从 Schema 衍生新 Schema：
const InsertUserSchema = UserSchema.omit({ _id: true, createdAt: true });
// 这样 cleanData 仍是类型安全的，且 IDE 能推导出字段
const cleanData = InsertUserSchema.parse(req.body);
await collection.insertOne(cleanData);
关键点：.omit() 返回的是新 Schema，不是运行时对象；它能保留类型、校验、默认值等全部能力。手动删字段等于放弃 Zod 最核心的价值 —— 类型即校验，校验即类型。
真正难的不是写几个 z.string().email()，而是让 Zod Schema 和 MongoDB 的实际写入契约完全对齐：字段存在性、空值容忍度、嵌套深度、数组长度、甚至时区/精度等隐含约定。这些细节一旦错位，debug 时就会发现错误出现在「本不该发生的路径」上。
