基于区分联合键收窄回调参数的TypeScript报错问题

问题代码 #

interface Foo {
    type: 'foo'
}

interface Bar {
    type: 'bar'
}

type MyEvent = Foo | Bar

function listen(_parameterType: 'foo', _callback: (event: Foo) => void): void;
function listen(_parameterType: 'bar', _callback: (event: Bar) => void): void;
function listen(_parameterType: MyEvent['type'], _callback: (event: MyEvent) => void): void {}

编译时出现报错：

This overload signature is not compatible with its implementation signature.

疑问：为何会出现这个报错？有没有无需强制类型转换或手动区分联合的实现方式？

报错原因 #

TypeScript对重载的兼容性有严格要求：所有重载签名必须能被实现签名兼容。

在你的代码中，重载签名的回调参数是特定的子类型（Foo或Bar），但实现签名的回调参数是更宽泛的联合类型MyEvent。从类型安全角度看，实现签名的回调需要能处理任意MyEvent类型的事件，但重载签名允许传入只处理单一子类型的回调——这就存在矛盾：如果实现逻辑中给回调传入了不符合其预期的事件类型（比如给Foo类型的回调传入Bar事件），就会引发类型错误。因此TypeScript会抛出重载不兼容的报错。

解决方案（无强制转换/手动区分） #

可以通过泛型+类型映射的方式，让TypeScript自动关联事件类型与回调类型，既满足类型安全，又无需手动处理联合类型：

方法1：使用事件映射类型 #

interface Foo {
    type: 'foo'
}

interface Bar {
    type: 'bar'
}

type MyEvent = Foo | Bar;
// 建立事件类型与type字段的映射关系
type EventMap = {
    foo: Foo;
    bar: Bar;
};

function listen<T extends keyof EventMap>(type: T, callback: (event: EventMap[T]) => void): void {
    // 这里写你的实现逻辑
}

// 使用示例
listen('foo', (event) => {
    // event自动推断为Foo类型
    console.log(event.type); // 类型为'foo'
});

listen('bar', (event) => {
    // event自动推断为Bar类型
    console.log(event.type); // 类型为'bar'
});

方法2：使用条件类型推导 #

如果不想额外定义EventMap，可以用Extract条件类型从联合类型中筛选对应事件：

interface Foo {
    type: 'foo'
}

interface Bar {
    type: 'bar'
}

type MyEvent = Foo | Bar;

function listen<T extends MyEvent['type']>(
    type: T,
    callback: (event: Extract<MyEvent, { type: T }>) => void
): void {
    // 这里写你的实现逻辑
}

// 使用示例同上

这两种方式都能让消费者调用时自动获得精准的类型推断，完全符合类型安全要求，无需任何强制转换或手动联合类型检查。

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