TypeScript React如何实现类型安全的泛型通用请求封装

核心思路是通过集中式实体配置+泛型约束实现需求，既满足泛型调用的写法，又能在编译阶段拦截非法实体类型传入，后续新增实体不需要改动核心请求逻辑。

1. 替换原有枚举为强类型实体配置映射 #

普通枚举只能存储路径字符串，无法关联每个实体对应的类型信息，所以改用常量配置+类型推导的方式，把实体的路径值、对应附件类型全部收敛到一个配置里维护：

// 所有支持的实体配置统一在这里维护，后续新增实体只需要加一行配置
export const EntityConfig = {
  Personnel: { path: 'personnel', attachmentRef: null as unknown as AttachmentDetails },
  Workorder: { path: 'workorder', attachmentRef: null as unknown as AttachmentDetails },
  Asset: { path: 'asset', attachmentRef: null as unknown as AttachmentDetails },
  AssetBooking: { path: 'assetbooking', attachmentRef: null as unknown as AttachmentDetails },
} as const;

// 推导合法的实体类型集合，替代原有枚举
export type ValidEntityType = keyof typeof EntityConfig;

这里用null as unknown as 目标类型只是为了让TS能推导类型，不会产生实际运行时的开销。

2. 重构带泛型约束的请求方法 #

给泛型加类型约束，只允许传入提前定义的合法实体类型，路径拼接逻辑自动从配置里取值，从根源避免硬编码传错路径的问题：

async getAttachments<T extends ValidEntityType>(
  id: string | number,
  entityType: T
) {
  const currentEntity = EntityConfig[entityType];
  return this.get<(typeof currentEntity)['attachmentRef'][]>(
    `attachment/${currentEntity.path}/${id}/attachment`
  );
}

3. 效果说明 #

• 正常调用时会有完整的类型提示，不需要手动指定泛型参数，TS会自动推导返回值类型：

  // 返回值自动推导为AttachmentDetails[]
  const personnelAttachments = await this.getAttachments(1001, 'Personnel');
  

• 传入未定义的非法实体类型时，TS会直接在编译阶段抛错，阻断非法调用：

  // ❌ 编译报错：类型“"UnknownEntity"”的参数不能赋给类型“ValidEntityType”的参数
  const invalidCall = await this.getAttachments(1002, 'UnknownEntity');
  

可选扩展 #

如果后续不同实体的附件返回结构有差异，只需要修改对应实体配置里的attachmentRef类型即可，核心请求逻辑完全不需要调整：

export const EntityConfig = {
  // 其他实体配置不变
  // 给工单附件增加独有的工单标签字段类型
  Workorder: { 
    path: 'workorder', 
    attachmentRef: null as unknown as AttachmentDetails & { orderTag: string } 
  },
} as const;

// 调用时TS会自动识别工单附件的独有字段，自动补全类型提示
const workorderAttachments = await this.getAttachments(2001, 'Workorder');
console.log(workorderAttachments[0].orderTag); // 有完整类型提示，不会报类型错误

这种写法把所有易变的硬编码值全部收敛到了统一配置里，核心请求逻辑只需要写一次，后续维护成本极低，同时完全满足类型安全的要求。

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