TypeScript中如何确保API调用传入模型全部可选字段？

问题场景 #

我正在开发一个调用OData API的TypeScript应用，该API支持通过$select指定要获取的字段（例如api/some/getbyid(42)?$select=x,y,z），同时会自动返回id、author这类技术字段。我定义了对应API输出的模型类型：

type APIItem = {
  id: number; 
  author: string; 
}

type CustomerModel = APIItem & {
  firstName: string;
  lastName: string;
  age: number
}

我封装了数据获取函数loadFromDB，接收ID和要获取的字段，调用API后将结果转为指定模型类型：

const fakeApi = (id: number, fields: string[]): Promise<APIItem> => {
  // 构建URL、请求逻辑...
  const result = JSON.parse(`{
    "id": ${id}, "firstName": "Mark", "lastName": "Hamill", "age": 20, "author": "d@some.com"
  }`) ;
  return Promise.resolve(result);
}

const loadFromDB = async <TModel extends APIItem>(
  id: number, 
  fields: (keyof Omit<TModel, 'id'> & string)[] 
): Promise<TModel> => {
  const fromDb = await fakeApi(id, fields);
  const result = fromDb as TModel;
  return Promise.resolve(result);
}

const customerPromise = loadFromDB<CustomerModel>(42, ['firstName']); // 编码错误：漏传字段

目前逻辑正常，但存在问题：调用方可能漏传字段，导致返回的对象不完整。由于TypeScript类型不会编译到JS中，无法直接遍历类型键，需要找到解决方案确保返回的模型始终完整。

解决方案 #

方案1：编译时强制传入所有非技术字段 #

修改loadFromDB的字段参数类型，要求必须包含模型中所有非技术字段（即排除APIItem自带的id、author），通过TypeScript的类型约束在编译阶段拦截漏传：

const loadFromDB = async <TModel extends APIItem>(
  id: number, 
  fields: Array<Exclude<keyof TModel, keyof APIItem>> extends infer U
    ? U extends string[] ? never : (U extends string ? U[] : never)
    : never
): Promise<TModel> => {
  const fromDb = await fakeApi(id, fields);
  return fromDb as TModel;
}

// 漏传字段会触发TypeScript错误
const badPromise = loadFromDB<CustomerModel>(42, ['firstName']); // 错误：缺少'lastName'和'age'
// 传入所有字段才能正常通过
const validPromise = loadFromDB<CustomerModel>(42, ['firstName', 'lastName', 'age']);

这种方式无需额外代码，完全依赖TypeScript的类型检查，能在开发阶段及时发现漏传问题。

方案2：辅助函数生成字段数组 #

编写一个辅助函数，结合类型推导和const断言，确保生成的字段数组包含所有必填项：

function requiredFields<T extends string>(...fields: T[]): T[] {
  return fields;
}

// 用类型约束确保传入所有非技术字段
const customerFields = requiredFields<Exclude<keyof CustomerModel, keyof APIItem>>(
  'firstName', 'lastName', 'age'
);
const customerPromise = loadFromDB<CustomerModel>(42, customerFields);

// 漏传字段会触发TypeScript错误
const badFields = requiredFields<Exclude<keyof CustomerModel, keyof APIItem>>('firstName'); // 类型不匹配

这种方式更灵活，字段数组可以复用在其他场景（比如表单验证、字段映射）。

方案3：手动维护字段数组+类型关联 #

通过手动维护字段数组，同时让TypeScript类型与数组关联，既保证编译时检查，又能在运行时复用数组：

// 手动维护非技术字段数组
const customerRequiredFields = ['firstName', 'lastName', 'age'] as const;
// 从数组推导字段类型
type CustomerRequiredFields = typeof customerRequiredFields[number];
// 确保模型类型与数组一致
type CustomerModel = APIItem & Record<CustomerRequiredFields, string | number>;

// 调用时直接传入数组，无需手动拼写字段
const customerPromise = loadFromDB<CustomerModel>(42, [...customerRequiredFields]);

这种方式的优势是修改字段时只需更新数组，类型会自动同步，减少手动维护的不一致性。

总结 #

由于TypeScript类型无法在运行时直接访问，核心思路是通过编译阶段的类型约束拦截漏传问题，或通过手动维护字段数组+类型关联的方式兼顾编译检查和运行时复用。根据项目场景选择合适的方案即可。

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