TypeScript中Zod泛型表单处理函数类型安全失效问题

在TypeScript项目中使用Zod做表单校验时，我编写了一个带泛型的schemaTest函数，目的是确保传入的表单数据与请求处理函数的参数类型严格匹配，避免混用不同表单的类型。但当前实现并未完全达到预期——仅在特定场景下才会触发类型错误，大部分情况下类型检查失效。

完整示例代码 #

import { z } from 'zod';

// 待测试的泛型函数
function schemaTest<T extends z.ZodSchema>(
  formData: z.infer<T>,
  requestFunc: (formData: z.infer<T>) => void
): void {}

// 示例表单Schema
const schemaA = z.object({
  email: z.string().email('Invalid email address'),
  password: z.string().min(6, 'Password must be at least 6 characters long')
});

const schemaB = z.object({
  email: z.string().email('Invalid email address') // 仅保留email字段
});

const schemaC = z.object({
  othername: z.string().email('Invalid email address') // 字段名与schemaA完全不同
});

// 示例1：无泛型指定，类型推断失效
// 函数被推断为 schemaTest<z.ZodType<any, z.ZodTypeDef, any>>(formData: any, requestFunc: (formData: any) => void): void
schemaTest(
  schemaA.parse({
    email: 'test@test.com',
    password: '123456'
  }),
  (formData: z.infer<typeof schemaB>) => {
    console.log(formData);
  }
);

// 示例2：指定泛型为schemaA，子集类型未触发错误
// 函数被推断为 schemaTest<typeof schemaA>(formData: { email: string; password: string; }, requestFunc: (formData: { email: string; password: string; }) => void): void
schemaTest<typeof schemaA>(
  schemaA.parse({
    email: 'test@test.com',
    password: '123456'
  }),
  (formData: z.infer<typeof schemaB>) => {
    console.log(formData);
  }
);

// 示例3：指定泛型为schemaA，完全不兼容类型触发错误（符合预期）
// 错误提示：Argument of type '(formData: z.infer<typeof schemaC>) => void' is not assignable to parameter of type '(formData: { email: string; password: string; }) => void'.
//  Types of parameters 'formData' and 'formData' are incompatible.
//  Property 'othername' is missing in type '{ email: string; password: string; }' but required in type '{ othername: string; }'.ts(2345)
schemaTest<typeof schemaA>(
  schemaA.parse({
    email: 'test@test.com',
    password: '123456'
  }),
  (formData: z.infer<typeof schemaC>) => {
    console.log(formData);
  }
);

// 示例4：无泛型指定，完全不兼容类型未触发错误
// 函数被推断为 schemaTest<z.ZodType<any, z.ZodTypeDef, any>>(formData: any, requestFunc: (formData: any) => void): void
schemaTest(
  schemaA.parse({
    email: 'test@test.com',
    password: '123456'
  }),
  (formData: z.infer<typeof schemaC>) => {
    console.log(formData);
  }
);

问题原因分析 #

1. 泛型推断模糊：当不手动指定泛型T时，TypeScript会将T推断为最宽泛的z.ZodType<any, ...>，导致formData和requestFunc的参数类型都退化为any，完全失去类型检查能力（如示例1、4）。
2. 结构类型兼容性：TypeScript采用结构类型系统，当requestFunc的参数类型是formData类型的子集时（如示例2中schemaB的类型是schemaA的子集），TypeScript会认为这种赋值是合法的——因为接受子集类型的函数可以安全处理超集类型的参数（多余属性会被忽略），所以不会触发错误。
3. 仅完全不兼容类型触发错误：只有当requestFunc的参数类型与formData类型完全没有结构兼容性时（如示例3），才会触发预期的类型错误。

解决方案 #

方案1：通过ZodSchema明确推导类型 #

将函数修改为接收ZodSchema作为第一个参数，让TypeScript从Schema中精确推导表单类型，避免泛型推断模糊：

import { z } from 'zod';

function schemaTest<T>(
  schema: z.ZodSchema<T>,
  formData: T,
  requestFunc: (formData: T) => void
): void {}

// 调用示例：
schemaTest(
  schemaA,
  schemaA.parse({ email: 'test@test.com', password: '123456' }),
  (formData) => { // formData自动推导为z.infer<typeof schemaA>
    console.log(formData.email, formData.password);
  }
);

// 错误示例：混用schemaB的requestFunc会触发类型错误
schemaTest(
  schemaA,
  schemaA.parse({ email: 'test@test.com', password: '123456' }),
  (formData: z.infer<typeof schemaB>) => { // 类型错误：参数类型不匹配
    console.log(formData);
  }
);

方案2：强制严格类型匹配（针对结构类型兼容性问题） #

如果需要强制requestFunc的参数类型与formData类型完全一致（不允许子集），可以通过Exact类型约束实现：

import { z } from 'zod';

// 定义Exact类型：仅当T和U完全相同时才返回T，否则返回never
type Exact<T, U> = T extends U ? (U extends T ? T : never) : never;

function schemaTest<T>(
  formData: T,
  requestFunc: (formData: Exact<T, z.infer<z.ZodSchema>>) => void
): void {}

// 调用示例：
schemaTest(
  schemaA.parse({ email: 'test@test.com', password: '123456' }),
  (formData) => { // 正常
    console.log(formData);
  }
);

// 错误示例：使用schemaB的类型会触发错误
schemaTest(
  schemaA.parse({ email: 'test@test.com', password: '123456' }),
  (formData: z.infer<typeof schemaB>) => { // 类型错误：Exact约束不满足
    console.log(formData);
  }
);

内容的提问来源于stack exchange，提问作者Quantum Martin