TypeScript 中的类型安全事件发射器

你一定遇到过这种情况:事件名称中的一个拼写错误、载荷不匹配,然后监听器就悄无声息地失效了。追踪这个 bug 花了 30 分钟,而修复只需要改一个字符。TypeScript 中的类型化事件发射器通过将错误从运行时转移到编译时,彻底消除了这一类问题。

本文将向你展示 TypeScript 事件映射模式的工作原理、何时构建自己的抽象与使用现有方案的对比,以及一些值得了解的实用模式。

为什么类型安全的 EventEmitter 很重要

非类型化的方式看起来是这样的:

import { EventEmitter } from 'events'

const emitter = new EventEmitter()

emitter.on('userLoggedIn', (user) => {
  console.log(user.name) // user 是 `any` 类型
})

emitter.emit('userLoggedin', { name: 'Alice' }) // 拼写错误 — 没有报错

在这种非类型化的用法中,TypeScript 不会捕获 userLoggedIn 和 userLoggedin 之间的大小写差异。监听器永远不会触发,也没有任何提示告诉你原因。

TypeScript 事件映射模式

解决方案从一个简单的接口开始 — 事件映射 — 其中每个键是事件名称,每个值是其载荷类型:

interface UserEvents {
  userLoggedIn: { userId: string, timestamp: Date }
  userLoggedOut: { userId: string }
  profileUpdated: { userId: string, changes: Record<string, unknown> }
}

这个接口成为发射器所有功能的单一事实来源。

构建强类型的自定义发射器

这是一个最小但完整的类型化发射器类:

type EventCallback<T> = (payload: T) => void

class TypedEventEmitter<TEvents extends Record<string, unknown>> {
  private listeners: {
    [K in keyof TEvents]?: EventCallback<TEvents[K]>[]
  } = {}

  on<K extends keyof TEvents>(event: K, callback: EventCallback<TEvents[K]>): void {
    (this.listeners[event] ??= []).push(callback)
  }

  off<K extends keyof TEvents>(event: K, callback: EventCallback<TEvents[K]>): void {
    const cbs = this.listeners[event]
    if (cbs) this.listeners[event] = cbs.filter(cb => cb !== callback)
  }

  emit<K extends keyof TEvents>(event: K, payload: TEvents[K]): void {
    this.listeners[event]?.forEach(cb => cb(payload))
  }

  once<K extends keyof TEvents>(event: K, callback: EventCallback<TEvents[K]>): void {
    const wrapper: EventCallback<TEvents[K]> = (payload) => {
      this.off(event, wrapper)
      callback(payload)
    }
    this.on(event, wrapper)
  }
}

关键机制是 K extends keyof TEvents。当你调用 emit('userLoggedIn', ...) 时,TypeScript 将 K 精确收窄为 'userLoggedIn',并检查载荷是否匹配 { userId: string, timestamp: Date }。拼写错误或错误的结构会变成编译错误。

const emitter = new TypedEventEmitter<UserEvents>()

emitter.on('userLoggedIn', ({ userId, timestamp }) => {
  console.log(userId, timestamp) // 完全类型化
})

emitter.emit('userLoggedin', { userId: '1', timestamp: new Date() }) // ❌ 编译错误
emitter.emit('userLoggedIn', { userId: '1' }) // ❌ 缺少 timestamp

在 Node.js EventEmitter 中使用类型安全

现代 @types/node 将 EventEmitter 暴露为泛型类,因此你通常可以直接获得类型化事件,而无需编写包装器。

import { EventEmitter } from 'events'

interface AppEvents {
  'user:login': [userId: string, email: string]
  'data:sync': [recordCount: number]
}

const emitter = new EventEmitter<AppEvents>()

emitter.on('user:login', (userId, email) => {
  console.log(userId, email)
})

emitter.emit('data:sync', 42)

一个重要的注意事项:Node 的事件系统默认是同步的 — 监听器在 emit 返回之前按注册顺序运行。此外,'error' 事件具有特殊的运行时行为:如果在没有附加监听器的情况下发出,Node 会抛出未捕获的异常。像 events.once() 这样的辅助工具可能无法完全保留事件映射的类型,因此在这些情况下类型安全性可能会降低。

替代方案和库

在浏览器环境中,带有 CustomEvent 的 EventTarget 是原生选项,但在 TypeScript 中为自定义 EventTarget 子类添加类型很麻烦 — 泛型约束与 CustomEvent<T> 不能很好地对齐。

像 mitt 和 eventemitter3 这样的库开箱即提供类型化发射器,如果你想要一个经过实战检验的实现而不是自己编写,它们值得考虑。它们是可选的,不是必需的 — 这个模式本身足够简单,可以直接掌握。

实用的清理:避免内存泄漏

当监听器不再需要时,始终移除它们。被遗忘的监听器是事件驱动代码中最常见的内存泄漏来源之一:

const handler = ({ userId }: { userId: string }) => console.log(userId)

emitter.on('userLoggedOut', handler)

// 稍后,在清理时:
emitter.off('userLoggedOut', handler)

在 React 中,将其与 useEffect 清理配对使用。在任何长期运行的服务中,记录哪个组件负责监听器的拆卸。

结论

TypeScript 事件映射模式预先需要你定义一个接口。作为回报,你获得的是对整个代码库中事件名称和载荷结构的编译时强制执行 — 不再有静默的不匹配、不再有 any 类型的回调,并且每个监听器都有完整的 IntelliSense 支持。对于任何事件跨模块边界的系统,这种权衡值得立即采用。

常见问题

Complete picture for complete understanding

Capture every clue your frontend is leaving so you can instantly get to the root cause of any issue with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data.

Check our GitHub repo and join the thousands of developers in our community.