ZenStack 中 Zod 模式从 `.nullish()` 到 `.optional()` 的演进

在 ZenStack 2.1.0 版本中，团队对 Zod 模式定义做出了一个重要调整：将可选字段的表示方式从 .nullish() 改为 .optional()。这一变更虽然看似微小，却对类型系统的严谨性和开发者体验产生了显著影响。

变更背景

在 TypeScript 生态中，可选字段通常有三种可能的表示形式：

1. 字段完全不存在
2. 字段值为 undefined
3. 字段值为 null

.nullish() 方法会接受 null 和 undefined 两种值，而 .optional() 仅接受 undefined 或字段缺失的情况。ZenStack 之前的实现使用 .nullish()，导致生成的 Zod 模式与 Prisma 模型类型不完全匹配。

技术影响分析

这一变更主要解决了类型系统的一致性问题。在 Prisma 模型中，可选字段被表示为 T | null 类型，而使用 .nullish() 生成的 Zod 模式会产生 T | null | undefined 类型。这种不匹配会导致在以下场景中出现类型错误：

1. 表单验证后的数据传递到业务逻辑层时
2. API 接口的输入输出类型转换时
3. 前后端数据交互时的类型校验

开发者适配建议

对于已经使用 ZenStack 的项目，升级到 2.1.0 版本后需要注意：

1. 检查所有使用 Zod 模式进行数据验证的地方
2. 确保业务逻辑不依赖于接收 undefined 值的场景
3. 对于确实需要区分 null 和 undefined 的特殊场景，需要显式处理

最佳实践

在新的版本下，推荐以下模式处理可选字段：

// 模型定义
model User {
  name String?
}

// 使用方式
const UserSchema = z.object({
  name: z.string().optional() // 而不是 .nullish()
});

// 业务逻辑处理
function createUser(data: z.infer<typeof UserSchema>) {
  // 明确处理可能的null值
  const prismaData = {
    name: data.name ?? null
  };
  // ...调用Prisma客户端
}

这一变更使 ZenStack 的类型系统更加严谨，减少了运行时意外的可能性，同时也更符合 Prisma 的类型设计哲学。开发者现在可以更自信地在应用的不同层级间传递数据，而不用担心隐式的类型转换问题。