Zod项目中处理nullable字段的注意事项

在使用Zod进行TypeScript类型校验时，处理nullable字段是一个常见的需求。本文将通过一个实际案例，分析如何正确处理可空字段，以及在使用pick方法时需要注意的事项。

问题背景

在开发过程中，我们经常会遇到需要从基础schema中提取部分字段创建新schema的情况。Zod提供了方便的pick()方法来实现这一功能。然而，当基础schema中包含nullable字段时，直接使用pick可能会导致类型校验失败。

原始代码分析

原始代码中定义了一个基础schema：

const dataSchema = z.object({
    document_type: z.string(),
    invoice_number: z.string().nullable(),
    receipt_number: z.string().nullable(),
});

然后尝试从这个基础schema中提取部分字段创建新的schema：

const invoiceSchema = dataSchema.pick({
  document_type: true,
  invoice_number: true,
}).partial();

当使用这个schema进行校验时，如果字段值为undefined，校验会失败，提示"Required"错误。

问题根源

这个问题的根本原因在于Zod的nullable()和nullish()方法的行为差异：

1. nullable()：允许字段值为null，但不允许undefined
2. nullish()：允许字段值为null或undefined

当使用pick方法时，原始的nullable约束会被保留，但partial()方法会将所有字段变为可选（即允许undefined）。这就导致了类型系统的冲突。

解决方案

作者最终通过将nullable改为nullish解决了这个问题：

const dataSchema = z.object({
    document_type: z.string(),
    invoice_number: z.string().nullish(),
    receipt_number: z.string().nullish(),
});

这种修改是合理的，因为：

1. 在实际业务中，undefined和null通常表示相同的语义 - 字段缺失
2. 使用nullish可以更好地配合partial()的行为
3. 保持了类型系统的自洽性

最佳实践建议

1. 明确字段语义：在设计schema时，明确区分字段是必须的、可选的、可为null的，还是三者组合
2. 谨慎使用pick：当基础schema包含nullable字段时，pick后的新schema可能需要调整类型约束
3. 考虑使用merge：对于复杂场景，可以考虑使用merge组合多个schema而不是pick
4. 统一处理空值：尽量统一使用nullish而不是nullable，除非业务上确实需要区分null和undefined

总结

Zod的类型系统非常强大，但在处理nullable字段时需要特别注意。通过理解nullable和nullish的区别，以及pick方法的行为，可以避免这类类型校验问题。在实际开发中，建议根据业务需求选择合适的类型约束，并在团队内保持一致的编码风格。