TypeScript为何未匹配最具体的函数重载？如何按入参给出对应类型提示

问题原因 #

你对TypeScript重载优先匹配最具体实现的认知没有本质错误，出现不符合预期的匹配结果，核心有两个原因：

1. 给出的示例代码存在笔误：类中定义的方法名为doSomethingWith，调用时写的是doSomething，请先确认实际代码中是否存在该问题。
2. TypeScript的重载匹配规则是严格按照声明顺序从上到下校验，只要参数满足当前签名的类型要求就会直接匹配，不会继续向后查找更具体的签名。你当前代码中第二个签名的inputType: allPossibileTypes已经包含了'my-first-type'的取值范围，如果实际运行时匹配到了第二个签名，大概率是你实际代码中的重载声明顺序和给出的示例不一致，把通用签名放到了具体签名的前面。

实现方案 #

方案1：调整重载顺序（适合类型少的场景） #

把所有具体取值对应的重载放到通用重载的前面即可，示例如下：

type allPossibileTypes = 'my-first-type' | 'my-second-type' | 'my-third-type';
type genericFunction = (innerVariable: any) => void;

class A {
   // 具体取值的重载放在最前面
   doSomethingWith(inputType: 'my-first-type', callback: (innerVariable: string) => void): void;
   doSomethingWith(inputType: 'my-second-type', callback: (innerVariable: number) => void): void;
   doSomethingWith(inputType: 'my-third-type', callback: (innerVariable: boolean) => void): void;
   // 通用重载放在最后
   doSomethingWith(inputType: allPossibileTypes, callback: genericFunction): void;
   // 方法实现
   doSomethingWith(inputType: string, callback: any) {
      // 业务逻辑
   }
}

此时调用AInstance.doSomethingWith('my-first-type', ...)时，会优先匹配到第一个重载，给出对应的(innerVariable: string) => void类型提示。

方案2：泛型+映射类型（适合类型多、易扩展的场景） #

如果可传入的字符串类型较多，写大量重载维护成本很高，可以通过映射类型绑定输入字符串和后续参数的类型关系，不需要写多个重载：

// 定义输入字符串和回调参数的映射关系
type CallbackTypeMap = {
  'my-first-type': string,
  'my-second-type': number,
  'my-third-type': boolean
}
// 直接从映射中提取所有允许传入的字符串类型
type allPossibileTypes = keyof CallbackTypeMap;

class A {
  // 用泛型动态关联输入参数和回调的类型
  doSomethingWith<T extends allPossibileTypes>(
    inputType: T, 
    callback: (innerVariable: CallbackTypeMap[T]) => void
  ) {
    // 业务逻辑
  }
}

该方案效果和多重载完全一致，后续新增类型只需要在CallbackTypeMap中添加对应条目即可，不需要额外修改方法签名，维护效率更高。

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