如何仅在实例化传参时为TypeScript类启用泛型类型约束

需求回顾 #

• 允许用户可选传入customData对象
• 若传入customData，必须保证每次调用measure()方法时，其属性集合完全一致
• 类型约束目标：
  • 指定泛型实例化时，measure()仅接受/返回匹配泛型结构的customData
  • 未指定泛型时，measure()禁止传入customData或任何额外对象

解决方案代码 #

class TelemetryLogger<T extends object = never> {
  private logBaseData() {
    return { timestamp: Date.now(), eventType: 'measurement' };
  }

  measure(
    customData: T extends never ? never : T
  ): {
    baseData: ReturnType<typeof this.logBaseData>;
    customData: T extends never ? never : T;
  } {
    const baseData = this.logBaseData();
    return {
      baseData,
      customData: customData as T
    };
  }
}

// 用法验证
// 1. 未指定泛型：无法传入任何customData
const basicLogger = new TelemetryLogger();
basicLogger.measure(); // ✅ 正常调用
// basicLogger.measure({ foo: 'bar' }); // ❌ 类型错误：参数不能赋值给never类型

// 2. 指定泛型：严格匹配结构
type AppCustomData = { userId: string; pagePath: string };
const typedLogger = new TelemetryLogger<AppCustomData>();
typedLogger.measure({ userId: 'u_123', pagePath: '/dashboard' }); // ✅ 符合结构
// typedLogger.measure({ userId: 'u_456' }); // ❌ 类型错误：缺少pagePath属性
// typedLogger.measure({ userId: 'u_789', pagePath: '/profile', extra: 'test' }); // ❌ 类型错误：存在未定义的额外属性

关键实现说明 #

1. 泛型默认值设为never：未指定泛型时，T的类型为never，直接限制measure()的参数不能传入有效值，从类型层面禁止额外数据输入
2. 条件类型分支处理：通过T extends never ? never : T区分两种使用场景，确保指定泛型时，参数和返回值的customData严格匹配泛型定义的结构
3. 返回值类型同步约束：返回对象的customData字段类型与参数保持一致，保证输入输出的类型统一性

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