Zod项目中实现互斥键值的类型校验方案

在Zod项目中，开发者经常需要处理一种特殊的数据结构校验需求：要求配置对象中的某些键值必须互斥存在（即只能出现其中一个）。这种需求在API参数校验、配置文件解析等场景中十分常见。本文将深入探讨在Zod中实现这一需求的几种技术方案。

互斥键值的业务场景

典型的业务场景包括：

1. 单值或多值选择：如用户ID可以是单个字符串(userId)或多个ID的对象(userIds)
2. 查询参数过滤：如查询条件中project和task参数不能同时出现
3. 多版本API兼容：新旧字段不能混用

基础实现方案

Zod提供了两种基础实现方式：

1. 统一键名方案

最简单的解决方案是使用相同的键名，通过类型区分单值和多值：

const schema = z.object({
  userId: z.union([z.string(), z.record(z.string())])
});

这种方案的优点是：

• 类型系统友好
• 实现简单直接
• 不需要额外校验逻辑

2. 联合类型方案

对于简单场景，可以使用z.union组合不同结构：

const schema = z.union([
  z.object({ userId: z.string() }),
  z.object({ userIds: z.record(z.string()) })
]);

但当互斥字段增多时，联合类型的组合会呈指数级增长，难以维护。

高级校验方案

对于复杂场景，Zod提供了更灵活的校验机制：

1. 使用refine进行互斥校验

const schema = z.object({
  userId: z.string().optional(),
  userIds: z.record(z.string()).optional()
}).refine(
  (val) => !!(val.userId) !== !!(val.userIds),
  { message: "必须指定userId或userIds之一" }
);

这种方案的特点：

• 保持类型定义清晰
• 运行时进行互斥校验
• 可自定义错误消息

2. 动态互斥键校验

对于需要动态确定互斥字段的场景，可以这样实现：

const mutuallyExclusiveKeys = ['project', 'task'];

const schema = z.object({
  project: z.string().optional(),
  task: z.string().optional()
}).refine(
  (data) => {
    const presentKeys = mutuallyExclusiveKeys.filter(k => data[k] !== undefined);
    return presentKeys.length <= 1;
  },
  {
    message: `参数${mutuallyExclusiveKeys.join('、')}不能同时使用`
  }
);

技术选型建议

1. 简单场景：优先考虑统一键名方案，保持类型系统完整性
2. 中等复杂度：使用refine校验，平衡类型安全和实现复杂度
3. 高度动态场景：采用动态互斥键校验，提高代码可维护性
4. 避免过度设计：不要为少量互斥字段使用复杂的联合类型

注意事项

1. TypeScript类型系统无法直接表示XOR类型，运行时校验是必要的
2. 互斥校验会增加一定的运行时开销
3. 错误消息应该清晰指导用户正确的使用方式
4. 考虑在文档中明确说明字段的互斥关系

通过合理运用Zod的这些特性，开发者可以构建出既类型安全又符合业务需求的复杂校验逻辑。