本文介绍如何利用 Zod 的 .transform() 方法，在不修改原始 API 数据结构的前提下，为解析后的对象动态添加基于已有字段计算得出的新属性（如 statusLabel），实现类型安全的前端数据增强。
本文介绍如何利用 zod 的 `.transform()` 方法，在不修改原始 api 数据结构的前提下，为解析后的对象动态添加基于已有字段计算得出的新属性（如 statuslabel），实现类型安全的前端数据增强。
在使用 Zod 进行 TypeScript 数据验证时，常遇到这样的需求：后端返回精简的原始数据（如 status: 1），而前端 UI 需要更语义化的派生字段（如 statusLabel: 'OK'）。此时不应在业务层手动二次处理，而应将该逻辑声明式地集成到 Schema 中，确保类型推导准确、数据转换可靠且可复用。
正确做法是：先定义基础对象 Schema，再在其整体上链式调用 .transform()，而非为单个字段（如 statusLabel）单独定义并 transform——后者会导致类型错误（因为原始输入不含 statusLabel 字段，Zod 会拒绝解析）。
以下是完整、类型安全的实现示例：
import { z } from 'zod';
export enum ReportMessageStatus {
UNKNOWN = 0,
OK = 1,
UNREAD = 2,
DELETED = 3,
}
// ✅ 正确：对整个对象 transform，注入新字段
const transformStatus = (status: ReportMessageStatus): string => {
switch (status) {
case ReportMessageStatus.OK: return 'OK';
case ReportMessageStatus.UNREAD: return 'Unread';
case ReportMessageStatus.DELETED: return 'Deleted';
default: return 'Unknown';
}
};
export const ReportMessageSchema = z
.object({
id: z.string(),
name: z.string(),
status: z.nativeEnum(ReportMessageStatus),
})
.transform((val) => ({
...val,
statusLabel: transformStatus(val.status), // 派生字段
}));
// 类型推导结果：ReportMessageSchema.infer === {
// id: string;
// name: string;
// status: ReportMessageStatus;
// statusLabel: string;
// }? 关键要点说明：
- .transform() 作用于整个解析后的对象，因此可自由访问任意已验证字段（如 val.status），并返回扩展后的新对象；
- 使用 ...val 保留原始字段，避免遗漏或重复定义；
- 枚举值应显式赋值（如 UNREAD = 2），避免因自动递增导致逻辑错位（你原代码中 case 1 返回 "DELETED" 显然是笔误）；
- 该 Schema 可直接用于 parse() 或 safeParse()，返回值自动包含 statusLabel，IDE 能精准提示，组件消费零成本。
⚠️ 注意：transform() 是运行时操作，不参与静态类型检查阶段；但配合 .infer，Zod 仍能生成完整、准确的 TypeScript 类型，保障开发体验与类型安全兼得。
