如何实现带字面量参数的TypeScript函数自动补全与重载兼容

我需要定义一个仅接受特定参数组合的函数，同时让每个参数都能获得精准的自动补全。尝试过两种方案，但都存在缺陷：

方案1：函数重载接口 #

interface MyFunction {
  (key: "one"): void;
  (key: "two", param: Record<"paramForTwo", string>): void;
  (key: "three", param: Record<"paramForThree", string>): void;
}

const fn: MyFunction = () => { /* 实现逻辑 */ };

该方案能正确限制参数组合，但在WebStorm和VSCode中，输入fn("three", {时会同时出现paramForTwo和paramForThree的补全提示，且错误信息会枚举所有重载，不够精准。

方案2：泛型映射方式 #

interface MyParams {
  "one": never,
  "two": "paramForTwo",
  "three": "paramForThree",
}

function fn<T extends keyof MyParams>(key: T, param: Record<MyParams[T], string>) {}

此方案能提供精准的自动补全和清晰的错误提示，但调用fn("one");时会报错，因为强制要求传入第二个参数。

可行解决方案 #

可以通过参数元组映射的方式，同时满足调用变体支持和精准补全的需求：

// 定义每个key对应的参数列表元组
interface ParamMap {
  "one": []; // 无额外参数
  "two": [param: Record<"paramForTwo", string>]; // 必须传入指定结构的参数
  "three": [param: Record<"paramForThree", string>]; // 必须传入指定结构的参数
}

function fn<T extends keyof ParamMap>(key: T, ...args: ParamMap[T]): void {
  // 函数实现逻辑示例
  switch(key) {
    case "one":
      // 处理无参数逻辑
      break;
    case "two":
      const paramTwo = args[0];
      // 处理paramForTwo相关逻辑
      break;
    case "three":
      const paramThree = args[0];
      // 处理paramForThree相关逻辑
      break;
  }
}

方案优势 #

• 支持所有调用变体：fn("one")、fn("two", {paramForTwo: "test"})、fn("three", {paramForThree: "test"})均能正常调用，无参数错误。
• 精准自动补全：输入fn("two", {时，编辑器只会提示paramForTwo；输入fn("three", {时仅提示paramForThree，不会出现无关补全。
• 清晰错误提示：当参数不符合要求时，TypeScript会直接指出当前key对应的参数错误，不会枚举所有重载，提示信息更精准。

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