Zod中利用transform为对象添加派生属性

先来看一个常见的开发场景：后端返回的数据里，`status` 字段是数字类型（如 `1`），但在前端展示时，你需要将其转换为“OK”、“Unread”这类可读文案。如果直接在 Zod schema 中为每个字段添加 `.transform()` 来派生新属性，很容易踩坑——Zod 会误认为输入数据中本来就存在这个字段，导致解析时报错，类型推导也会混乱。

其实解决思路非常直观：先定义好基础的对象结构，然后对整个解析结果执行一次整体转换。这样派生字段仅出现在输出侧，不参与输入校验，既简洁又安全。具体实现如下：

import { z } from 'zod';

export enum ReportMessageStatus {
  UNKNOWN = 0,
  OK = 1,
  UNREAD = 2,
  DELETED = 3,
}

function transformStatus(status: ReportMessageStatus): string {
  switch (status) {
    case ReportMessageStatus.OK:      return 'OK';
    case ReportMessageStatus.UNREAD:  return 'Unread';
    case ReportMessageStatus.DELETED: return 'Deleted';
    default:                          return 'Unknown';
  }
}

// ✅ 正确姿势：基础对象 + 整体 .transform()
export const ReportMessageSchema = z
  .object({
    id: z.string(),
    name: z.string(),
    status: z.nativeEnum(ReportMessageStatus),
  })
  .transform((val) => ({
    ...val,
    statusLabel: transformStatus(val.status), // 派生属性，不会出现在输入中
  }));

// 使用示例
const rawData = { id: '203923', name: 'best name', status: 1 };
const parsed = ReportMessageSchema.parse(rawData);
// 类型推导为：{ id: string; name: string; status: ReportMessageStatus; statusLabel: string; }
console.log(parsed.statusLabel); // "OK"

这里有几个关键要点值得记住：

• .transform() 必须挂载在完整的 z.object() 实例之后，而不是某个字段上——否则会因为输入中不存在该字段而直接报错，导致 Zod 类型校验失败。
• 派生字段（如 statusLabel）仅出现在解析后的输出类型中，输入校验阶段完全不可见，运行时和类型推导始终保持一致，确保类型安全。
• 如果需要反向操作（例如提交表单时排除 statusLabel），可以组合使用 .omit({ statusLabel: true }) 生成一个专门用于提交的 schema，实现输入与输出的分离。
• 对于复杂的转换逻辑，建议单独抽离为函数并添加 JSDoc 注释，这样后续维护会更加清晰高效。

这种方案的优势在于：Zod 的强类型约束完全保留，同时又可以灵活地为前端 UI 层添加各种语义化字段。整体思路简单、可控，且符合直觉，适合在需要派生属性的 TypeScript 项目中推广使用。