使用Zod处理复杂TypeScript接口的验证与转换

在TypeScript项目中，我们经常需要处理复杂的数据结构验证问题。Zod作为一个强大的TypeScript-first的运行时验证库，能够很好地解决这类需求。本文将深入探讨如何利用Zod处理包含联合类型、条件字段和嵌套对象的复杂接口验证场景。

复杂接口的验证挑战

在实际开发中，我们经常会遇到需要验证的复杂数据结构。以金融交易场景为例，我们可能需要处理提现操作的不同模式：

1. 单一资产提现模式：用户指定特定资产进行提现
2. 平衡提现模式：系统自动平衡多种资产进行提现

每种模式都有自己独特的字段要求，且某些字段之间存在互斥关系。这种复杂的验证需求正是Zod大显身手的地方。

基础类型定义

首先，我们需要定义一些基础类型和验证规则：

// 提现模式枚举
const SingleWithdrawModeSchema = z.literal('Single');
const BalancedWithdrawModeSchema = z.literal('Balanced');

// 大整数处理（兼容多种输入格式）
const BigIntSchema = z.union([
  z.bigint(),
  z.number().transform(v => BigInt(v.toString())),
  z.string().transform(v => BigInt(v))
]);

// 基础提现参数
const BaseWithdrawSchema = z.object({
  pool: AddressSchema,
  burnLpAmount: BigIntSchema,
  queryId: BigIntSchema.optional(),
  recipient: AddressSchema.optional(),
  slippageTolerance: SlippageSchema.optional(),
  extraPayload: z.null().optional()
});

处理联合类型和条件字段

核心挑战在于处理联合类型和条件字段。我们需要确保：

1. 在单一提现模式下，withdrawAsset和nextWithdraw字段互斥
2. 在平衡提现模式下，只允许特定的字段组合

单一提现模式的处理

// 基础单一提现模式
const SingleWithdrawBaseSchema = BaseWithdrawSchema.extend({
  mode: SingleWithdrawModeSchema
});

// 变体1：包含withdrawAsset但不含nextWithdraw
const SingleWithdrawNoNextSchema = SingleWithdrawBaseSchema.merge(
  z.object({
    withdrawAsset: z.union([
      z.instanceof(Asset), 
      AssetSchema.transform(v => new Asset(v))
    ]),
    nextWithdraw: z.undefined()
  })
);

// 变体2：包含nextWithdraw但不含withdrawAsset
const SingleWithdrawWithNextSchema = SingleWithdrawBaseSchema.merge(
  z.object({
    nextWithdraw: NextWithdrawSchema,
    withdrawAsset: z.undefined()
  })
).omit({ withdrawAsset: true });

// 合并单一提现模式变体
const SingleWithdrawParamsSchema = z.union([
  SingleWithdrawNoNextSchema, 
  SingleWithdrawWithNextSchema
]);

平衡提现模式的处理

const BalancedWithdrawParamsSchema = BaseWithdrawSchema.extend({
  mode: BalancedWithdrawModeSchema,
  nextWithdraw: NextWithdrawSchema.optional()
});

最终组合与序列化处理

将所有模式组合起来，并添加序列化逻辑：

export const WithdrawParamsSchema = z
  .union([SingleWithdrawParamsSchema, BalancedWithdrawParamsSchema])
  .transform(data => {
    return {
      ...data,
      toJSON(): Record<string, unknown> {
        const serializeNextWithdraw = (nextWithdraw?: NextWithdraw) => {
          if (!nextWithdraw) return undefined;
          return {
            pool: nextWithdraw.pool.toString(),
            mode: nextWithdraw.mode,
            withdrawAsset: 
              nextWithdraw.mode === 'Single' && nextWithdraw.withdrawAsset
                ? nextWithdraw.withdrawAsset.toJSON()
                : undefined
          };
        };
        
        return {
          pool: data.pool.toString(),
          burnLpAmount: data.burnLpAmount.toString(),
          queryId: data.queryId?.toString(),
          recipient: data.recipient?.toString(),
          slippageTolerance: data.slippageTolerance?.toString(),
          extraPayload: data.extraPayload,
          nextWithdraw: serializeNextWithdraw(data.nextWithdraw)
        };
      }
    };
  });

类型推导与使用

Zod的强大之处在于它能够自动推导TypeScript类型：

// 输入类型（验证前）
export type WithdrawParams = z.input<typeof WithdrawParamsSchema>;

// 输出类型（验证后）
export type ParsedWithdrawParams = z.infer<typeof WithdrawParamsSchema>;

最佳实践总结

1. 分层验证：先定义基础类型，再构建复杂结构
2. 互斥字段处理：使用.merge()和.omit()组合确保字段互斥
3. 类型转换：利用.transform()处理输入数据标准化
4. 序列化逻辑：在验证阶段内置序列化方法
5. 类型安全：充分利用Zod的类型推导能力

通过这种方式，我们不仅实现了运行时验证，还保持了完整的TypeScript类型安全，大大减少了潜在的错误，提高了代码的可维护性。