TypeScript中如何用泛型作为JSON键定义通用API响应接口？

问题背景 #

我们有Ebay Trading API的响应结构，其中Timestamp、Ack、Version、Build是所有请求响应的固定字段，而UserDeliveryPreferenceArray这类顶层字段会随请求接口不同而变化。

现有实现通过接口继承来定义具体响应类型，但希望用泛型实现更通用的抽象，避免重复定义基础字段。之前尝试的泛型写法存在语法错误，无法直接将泛型用作索引签名的键。

正确的泛型实现方案 #

方案1：针对单个可变顶层键的精确约束 #

如果每个请求仅对应一个唯一的可变顶层键，可通过泛型约束键名和对应值类型，结合交叉类型实现：

// 定义所有响应共有的固定字段类型
type EbayTradingBase = {
  Timestamp: string;
  Ack: string;
  Version: number;
  Build: string;
};

// 泛型响应类型：Key指定可变字段的键名，Data指定该字段的类型
type EbayTradingResponse<Key extends string, Data> = EbayTradingBase & {
  [K in Key]: Data;
};

// 定义具体可变字段的结构
interface UserDeliveryPreferenceArray {
  NotificationEnable: {
    EventType: string;
    EventEnable: string;
  }[];
}

// 生成具体的响应类型
type UserDeliveryPreferenceResponse = EbayTradingResponse<
  "UserDeliveryPreferenceArray",
  UserDeliveryPreferenceArray
>;

方案2：支持多个可变字段的灵活定义 #

如果响应可能包含多个可变顶层字段，可让泛型直接代表所有可变字段的集合，再与基础字段交叉合并：

type EbayTradingBase = {
  Timestamp: string;
  Ack: string;
  Version: number;
  Build: string;
};

// 泛型接收可变字段的完整类型，与基础字段合并
type EbayTradingResponse<T extends Record<string, unknown>> = EbayTradingBase & T;

// 定义一组可变字段的结构
interface UserDeliveryPreferenceData {
  UserDeliveryPreferenceArray: {
    NotificationEnable: {
      EventType: string;
      EventEnable: string;
    }[];
  };
  // 可添加其他可变字段
  // AnotherCustomField: SomeType;
}

// 生成具体响应类型
type UserDeliveryPreferenceResponse = EbayTradingResponse<UserDeliveryPreferenceData>;

方案3：键不确定的通用场景 #

如果可变字段的键完全无规律，仅能确定值的类型范围，可使用索引签名结合泛型约束值类型：

type EbayTradingBase = {
  Timestamp: string;
  Ack: string;
  Version: number;
  Build: string;
};

// 泛型约束可变字段的值类型，键为任意字符串
type EbayTradingResponse<T> = EbayTradingBase & {
  [key: string]: T;
};

// 使用示例：可变字段值为包含NotificationEnable的对象
type UserDeliveryPreferenceResponse = EbayTradingResponse<{
  NotificationEnable: {
    EventType: string;
    EventEnable: string;
  }[];
}>;

方案选择建议 #

• 方案1：适合单个可变顶层键的场景，类型检查最严格，能避免错误的键名；
• 方案2：适合多可变字段的场景，灵活性最高，可扩展任意数量的可变字段；
• 方案3：适合键不确定的通用场景，但类型宽松度较高，适合快速原型或动态字段场景。

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