用 TypeScript 实现类型安全的 EventEmitter：泛型与重载的完美结合

做前端时间长了，基本都会遇到一个场景：某个全局事件总线或者组件内部的一个订阅发布机制，在项目变大之后，开始变成失控的暗号集。事件名靠记忆，参数靠默契，重构的时候改了 emit 的地方，忘了改 on 的地方，运行时才炸出来。

TypeScript 可以帮我们把这层关系变得明确：事件名必须存在，回调参数必须匹配，甚至每个事件的参数个数都能在编译期绑定好。而这本质上靠的是泛型和函数重载这两个特性的组合。这篇文章就围绕一个类型安全的 EventEmitter 展开，看看实现一个够用、不过度设计、可以放进生产项目的版本，需要注意哪些细节。

先想清楚一个问题：EventEmitter 里到底该约束什么？

对于一个事件系统，最容易出问题的不是任务调度，而是事件名与事件负载之间的映射关系。在 JavaScript 版本里，API 通常是这个样子：

bus.on('order:create', (order, meta) => {
  // 业务逻辑
})
bus.emit('order:create', orderObj)   // 少了 meta，回调还是能跑，但数据是 undefined

TypeScript 要解决的，就是让这种不匹配在编译期暴露出来。但具体约束什么，不同方案理解不一样。有人喜欢把事件值定义成 payload 类型，有人觉得应该定义成处理函数本身。后一种在演化中更舒服，因为它顺带解决了参数个数和顺序的问题。

用接口定义事件表，让每个事件自带签名

先定义事件表。比较推荐的做法，是给每个事件名配置一个处理函数签名，而不是单个 payload 类型：

interface OrderEvents {
  'order:create': (order: Order, meta?: RequestMeta) => void
  'order:paid': (orderId: string, paidAt: Date) => void
  'stock:empty': (skuId: string, remain: number) => void
}

注意这里每个事件对应的是一个函数类型。如果写成参数元组，比如 { 'order:create': [Order, Meta?] }，虽然也能用索引解析，但可读性要差不少，而且当某个参数存在与否依赖另一个参数时，元组表达会非常别扭。函数签名语义更贴近“事件发生后，谁该被调用来处理”，所以也更好读。

核心实现：泛型约束加工具函数，参数类型自动推理

把类定义成泛型，约束为“键是字符串、值是函数”的映射结构：

type EventMap = Record<string, (...args: any[]) => void>

class TypedEmitter<Events extends EventMap> {
  private listeners: { [K in keyof Events]?: Events[K][] } = {}

  on<K extends keyof Events>(event: K, listener: Events[K]) {
    if (!this.listeners[event]) this.listeners[event] = []
    this.listeners[event]!.push(listener)
    return this
  }

  off<K extends keyof Events>(event: K, listener: Events[K]) {
    const list = this.listeners[event]
    if (!list) return this
    this.listeners[event] = list.filter((l) => l !== listener)
    return this
  }

  emit<K extends keyof Events>(event: K, ...args: Parameters<Events[K]>) {
    this.listeners[event]?.forEach((listener) => listener(...args))
    return this
  }
}

这里 Parameters<Events[K]> 是 TypeScript 内置的工具类型，它把函数参数抽成元组。比如对于 'order:create' 事件，emit 的签名就是 (event: 'order:create', order: Order, meta?: RequestMeta)。

泛型 K extends keyof Events 保证了传给 on 和 emit 的事件名必须是事件表里定义过的字面量，同时能推导出对应回调的参数列表。on 和 emit 两端被牢牢绑在一起，改一头，另一头编译报错。

站在调用者角度看，这个泛型方法等价于为事件表里的每个事件生成了一份重载签名，事件表字段越多，收益越明显。这也是标题里说的“泛型与重载的结合”：由泛型来生成重载，而不是手写重复的签名。

还有一个容易被忽略的细节：on、off、emit 都返回 this。示例中的实现保留了链式调用的能力，同时因为泛型类返回的是当前实例类型，链式调用不会丢掉具体事件表类型。

一个真实场景：事件表成了团队协作的“契约”

举个实际例子。一个中后台应用里，订单模块维护着 'order:paid' 事件，支付成功时会带着 orderId 和 paidAt 向外广播。库存模块和消息中心都订阅了这个事件。后来业务方想在事件里追加一个 couponId 字段。

如果没有类型约束，这个改动需要搜索所有出现 'order:paid' 的文件，逐个检查回调是否受影响。一旦漏改，某个回调里拿不到 couponId，线上就会出现 undefined 相关的问题。而有事件表之后，只需要修改接口定义，编译期会立刻标出所有调用了 emit 或 on 的地方，因为参数对不上。这个约束带来的收益，远不止少几次运行时报错，而是让事件名真正变成了可检索的 API。

常见误区：类型安全是怎么被破坏的

看上去实现不复杂，但实际项目里因为使用姿势不对，还是很容易把类型安全做成豆腐渣工程。几个典型问题：

• 事件表使用宽泛的字符串索引，比如 { [key: string]: (...args:any[])=>void }，这样 K extends keyof Events 退化成 string，任何事件都接收任意参数，等于没有类型安全。
• 为了省事，把事件值定义成元组类型，比如 { 'order:create': [Order, Meta?] }，然后 emit 里手动展开或索引取值，可读性差，也难以表达同一事件在不同生命周期里参数不同的情况。
• 在一些框架组件里，直接继承 emitter 却不把事件表泛型传下去，内部类型落到 any，后续所有调用安全链断裂。
• 把 emit 参数声明成 ...args: any[]，为了临时解决某一个类型报错，结果所有事件都失去了编译保护。

这些误区有一个共同点：都不是 TypeScript 不够强大，而是写代码时选择了更容易绕开的路径。维护类型安全最反直觉的一点，就是它需要你主动克制使用 any 的冲动。

几种实现方案的取舍

类型安全的 EventEmitter 在设计上有很多岔路口，具体选哪种，取决于项目体积和团队对类型的接受度。对比一下常见方案：

三种方案并不是互斥的。如果你的项目只是两三个事件，直接写重载反而简单；事件多了之后，泛型映射类优势才明显。

落地建议：从一个事件表开始

如果你现在准备在项目里引入类型安全的 EventEmitter，我的建议是从最小闭环开始，不要一上来就做全局总线。

• 第一步：给当前模块定义事件表接口，只需要包含真正在用的两三个事件。宁可少定义，也不要为了“通用性”把类型放宽。
• 第二步：把 emitter 实例和事件表类型一起导出。常见做法是单独写一个 events/types.ts 文件，后续需要跨模块复用时直接引用。
• 第三步：事件名加上模块前缀，比如 'order:paid'、'inventory:changed'，避免同名冲突。类型定义里也保持同样的前缀，搜索起来更直观。
• 第四步：如果你希望事件表在定义时也做类型校验，可以使用 TypeScript 4.9 之后的 satisfies。例如先声明 const orderEvents = { ... } satisfies EventMap，既能检查结构，又能保留具体回调的字面量类型。

实际业务中，事件驱动最常见的问题并不是事件数量多，而是“新来的人不知道有哪些事件”。类型定义天然就成为一份文档，编辑器的自动补全比任何 Wiki 都容易保鲜。

另外还有一个常见的使用场景是开发公共 SDK。当你的库导出一个带事件功能的实例时，事件的名称和参数就是公开 API 的一部分。类型安全的 EventEmitter 可以让使用者在编辑器中看到完整的事件列表，参数错误也会直接标红，这比维护一份容易过期的文档更有实际价值。

总结

类型安全的 EventEmitter 不是炫技，而是事件驱动代码里很实用的一道防线。它利用 TypeScript 的泛型把事件名和函数签名绑定在一起，让编译器替我们做一遍订阅与发布的契约检查。

真正值得记住的，并不是某个库的实现细节，而是设计思路：事件表就是系统内消息协议的类型定义，它应该被当成交互契约来维护，而不是随手写的字符串。从这个角度看，做一个类型安全的事件系统，投入产出比相当高。