TypeScript泛型EventHandler类型不兼容问题排查与修复

先还原常见的错误代码场景：

// 定义联合事件类型
type UnionEvent = MouseEvent | KeyboardEvent | CustomEvent;

// 定义泛型事件处理器接口
interface EventHandler<T> {
  handle(event: T): void;
}

// 存储处理器的数组
const handlers: EventHandler<UnionEvent>[] = [];

// 尝试添加针对特定事件的处理器
function addEventHandler<T extends UnionEvent>(handler: EventHandler<T>) {
  handlers.push(handler); // ❌ 类型报错：EventHandler<T> 不能赋值给 EventHandler<UnionEvent>
}

违反的TypeScript类型规则 #

1. 函数参数的逆变特性
   EventHandler本质是包含函数类型的接口，handle(event: T): void的参数T遵循逆变规则：只有当目标类型的参数是源类型参数的超类型（更宽泛）时，函数类型才兼容。这里EventHandler<UnionEvent>的handle方法接受UnionEvent（更宽泛），而EventHandler<T>的handle只接受T（UnionEvent的子类型，更具体），不符合逆变要求，所以类型不兼容。

2. 泛型类型参数的不变性
   默认情况下，TypeScript的泛型类型参数是不变的：如果T extends U，EventHandler<T>既不兼容EventHandler<U>也不被EventHandler<U>兼容（除非显式指定协变/逆变）。基类继承思路无效，因为联合类型不是类继承关系，且泛型接口未设置逆变修饰符。

正确改写方法 #

方法1：将EventHandler的类型参数标记为逆变 #

在泛型参数前加in修饰符，明确指定参数逆变，这样子类型的处理器可以安全赋值给联合类型的处理器数组：

type UnionEvent = MouseEvent | KeyboardEvent | CustomEvent;

// 用in标记逆变的泛型参数
interface EventHandler<in T> {
  handle(event: T): void;
}

const handlers: EventHandler<UnionEvent>[] = [];

function addEventHandler<T extends UnionEvent>(handler: EventHandler<T>) {
  handlers.push(handler); // ✅ 类型兼容，因为逆变允许子类型处理器赋值给超类型处理器
}

方法2：使用类型断言（谨慎使用） #

如果不能修改EventHandler接口，可以用类型断言绕过检查，但要确保处理器确实能处理所有UnionEvent类型（否则运行时可能出错）：

function addEventHandler<T extends UnionEvent>(handler: EventHandler<T>) {
  handlers.push(handler as EventHandler<UnionEvent>); // ✅ 手动断言类型
}

方法3：重构为事件映射类型（更安全的场景化方案） #

如果不同事件有明确的区分标识（比如type字段），可以用映射类型绑定事件类型和处理器，避免联合类型的兼容性问题：

// 定义具体事件类型，带type区分
type MouseClickEvent = { type: 'click'; x: number; y: number };
type KeyPressEvent = { type: 'keypress'; key: string };
type CustomNotifyEvent = { type: 'notify'; message: string };

// 事件类型映射
type EventMap = {
  click: MouseClickEvent;
  keypress: KeyPressEvent;
  notify: CustomNotifyEvent;
};

// 针对特定事件的处理器类型
type EventHandler<K extends keyof EventMap> = {
  handle(event: EventMap[K]): void;
};

// 存储处理器的映射
const handlers: Partial<Record<keyof EventMap, EventHandler<any>[]>> = {};

function addEventHandler<K extends keyof EventMap>(eventType: K, handler: EventHandler<K>) {
  if (!handlers[eventType]) handlers[eventType] = [];
  handlers[eventType]!.push(handler); // ✅ 完全类型安全
}

这种方式更适合实际业务场景，既避免了联合类型的逆变兼容性问题，又保证了类型检查的严谨性。

内容的提问来源于stack exchange，提问作者aleksey-exe