如何在TypeScript中为FormData定义必填字段实现编译时校验

问题根源 #

你之前的写法不生效，是因为FormData的字段存储在内部实例中，并不会作为实例的公开属性存在，所以直接给继承FormData的接口加字段定义，TypeScript无法将append操作和这些字段关联，自然无法做校验。

具体实现 #

我们可以通过泛型+类型标记的方式，给FormData增加编译期的字段约束：

1. 定义通用泛型类型与构造工具 #

// 仅类型层面存在的唯一标记，避免普通FormData和带约束的FormData混淆
declare const __typedFormDataBrand: unique symbol;

// 带字段约束的FormData泛型类型
export type TypedFormData<T extends Record<string, FormDataEntryValue>> = FormData & {
  [__typedFormDataBrand]: T;
};

// 构造带约束的FormData的工具函数，会强制校验传入的字段是否完整
export function createTypedFormData<T extends Record<string, FormDataEntryValue>>(fields: T): TypedFormData<T> {
  const formData = new FormData();
  Object.entries(fields).forEach(([key, value]) => {
    formData.append(key, value);
  });
  return formData as TypedFormData<T>;
}

2. 业务场景使用 #

对应你的需求可以直接按如下方式写：

export interface AddRequest {
  image: Blob;
  username: string;
}

// 定义接口对应的带约束FormData类型
export type AddRequestApi = TypedFormData<{
  image: Blob;
  username: string;
}>;

export const mapRequest = (request: AddRequest): AddRequestApi => {
  // 漏传任意字段、字段类型不匹配都会触发TS编译报错
  return createTypedFormData({
    image: request.image,
    username: request.username
  });
};

可选优化：扩展get方法类型提示 #

如果需要后续调用FormData.get时也能获得正确的类型返回，可以扩展全局FormData接口：

declare global {
  interface FormData {
    get<K extends keyof T, T extends Record<string, FormDataEntryValue>>(this: TypedFormData<T>, key: K): T[K] | null;
  }
}

// 使用示例
const form = mapRequest({ image: new Blob(), username: 'test' });
const image = form.get('image'); // 类型自动推导为Blob | null
const wrongKey = form.get('notExist'); // TS直接报错，提示键不存在

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