TypeScript函数重载报错原因及额外重载签名必要性咨询

我最近在TypeScript里处理函数重载时遇到了一个让人困惑的错误，折腾了一番终于搞清楚了原因和解决办法，分享给大家：

问题复现 #

先看这个最小复现代码，我定义了递归嵌套的类型X和Y，还有一个重载的transform函数，用来把X转换成Y：

interface XComplex { value: X }
type X = string | XComplex
interface YComplex { value: Y }
type Y = string | YComplex

function transform(v: string): string
function transform(v: XComplex): YComplex
function transform(x: X): Y {
  if (typeof x === "string") {
    return x
  }
  const xValue: X = x.value
  return { value: transform(xValue), // <---- 这里报错！
  }
}

报错信息是：

[ts] Argument of type 'X' is not assignable to parameter of type 'XComplex'. Type 'string' is not assignable to type 'XComplex'.

矛盾点：移除重载的影响 #

如果我把重载签名删掉，错误会消失，但这样在调用函数时就没法精确推断返回类型了：

// 有重载时的正确用法：可以精确指定返回类型
const yString1: string = transform('hello')
const yComplex1: YComplex = transform({ value: 'xValue'})

// 无重载时的用法：只能用联合类型Y，丢失了精确类型
const yString2: Y = transform('hello')
const yComplex2: Y = transform({ value: 'xValue'})

解决办法：添加额外的重载签名 #

后来我发现，只要在重载里多添加一个和实现签名完全一致的签名，错误就消失了：

function transform(v: string): string
function transform(v: XComplex): YComplex
function transform(v: X): Y // <--- 新增的通用重载签名
function transform(x: X): Y {
  // 实现代码不变...
}

错误原因分析 #

为什么会这样？其实TypeScript在处理重载函数的内部调用时，只会匹配你显式声明的重载签名，而不会直接使用函数的实现签名。

原来的重载只有两个：

• 接受string，返回string
• 接受XComplex，返回YComplex

当递归调用transform(xValue)时，xValue是X类型（也就是string | XComplex），TypeScript会尝试匹配已有的重载：

1. 第一个重载要求参数是string，但xValue可能是XComplex，不匹配；
2. 第二个重载要求参数是XComplex，但xValue可能是string，也不匹配。

而TypeScript的错误提示会默认指向最后一个尝试匹配的重载，所以才会显示“无法把X赋值给XComplex”这种容易让人困惑的信息——其实本质是没有任何一个已声明的重载能匹配X类型的参数。

添加那个通用的重载签名后，TypeScript就能匹配到这个接受X返回Y的签名，递归调用的类型检查就通过了。

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