events 事件模块:订阅、触发与移除

用 EventEmitter 通知其他模块任务结果,并管理监听函数。

🎯 引言

学完这篇文章,你能用 EventEmitter 通知其他模块任务结果,并管理监听函数。


🧱 EventEmitter 用来发出与接收通知

EventEmitter 是 Node.js 的事件通知对象。一个功能完成工作后发出事件,其他部分提前订阅,就能执行自己的处理。例如文件处理完成后,日志功能收到通知并记录名称。

事件名由双方约定,比如 done。它不是 Node.js 自动识别的业务动作,只有程序明确调用触发方法时,监听函数才会运行。

创建 events.mjs,先准备事件对象,后续代码按顺序追加:

import { EventEmitter } from 'node:events'
const bus = new EventEmitter()

bus 是这组通知的发送与订阅入口。这里只创建对象,还没有输出。


👂 on:先登记谁要收到通知

const log = file => console.log(`已处理:${file}`)
bus.on('done', log)

on 的参数是事件名和监听函数。执行后仍然没有输出,因为注册不等于触发。函数被保存下来,等待以后收到 done。

on 返回这个事件对象本身,不是监听函数的执行结果;日常注册时通常无需使用这个返回值。


📣 emit:触发通知并传数据

bus.emit('done', 'note.txt')

运行当前文件,会输出 已处理:note.txt。事件名后面的值被传给监听函数,所以 log 的 file 参数收到了 note.txt。

emit 返回是否存在该事件的监听函数:有则为 true,没有则为 false。这个返回值不代表某项业务已经成功,只表示是否有监听者。

再次触发 done,on 注册的监听还会执行,因此它适合持续观察。


🧹 off:不再需要时取消监听

bus.off('done', log)
bus.emit('done', 'other.txt')

新增的这次触发没有日志,因为 log 已经移除。off 必须传入注册时的函数引用;需要移除的监听应保留引用,避免注册匿名函数后无法解除。

组件、任务或服务对象结束使用时,移除不再需要的监听,能避免重复处理以及长期保留无用数据。


1️⃣ once:只处理一次通知

不论后续发生多少次,只关心首次完成时用 once:

bus.once('ready', () => console.log('准备完成'))
bus.emit('ready')
bus.emit('ready')

只输出一次 准备完成。监听在首次调用时自动移除;它也不会补收注册之前已经发出的历史事件。


⏱️ emit 默认同步调用监听函数

在上述文件中追加一个新的事件例子:

bus.on('check', () => console.log('监听执行'))
bus.emit('check')
console.log('触发之后')

结果先是 监听执行,然后是 触发之后。emit 会在继续下一句之前调用监听;多个监听按注册顺序执行。因此耗时监听仍会阻塞后续 JavaScript。


📂 异步监听:在监听内部处理文件读取失败

事件适合发出通知;触发通知的代码不会等待异步监听完成。 例如通知日志功能读取一份文件,读取成功或失败都由日志功能自己报告。

单独新建 async-events.mjs,先准备事件对象和文件读取方法:

async-events.mjs
import { EventEmitter } from 'node:events'
import { readFile } from 'node:fs/promises'
const bus = new EventEmitter()

接着注册监听,把 try/catch 放在异步监听内部:

bus.on('show-file', async file => {
    try {
        const text = await readFile(file, 'utf8')
        console.log('文件内容:', text)
    } catch (error) {
        console.error('读取失败:', error.code)
        process.exitCode = 1
    }
})

最后触发通知:

bus.emit('show-file', 'note.txt')
console.log('通知已发出')

在同目录准备内容为 hello 的 note.txt,运行 node async-events.mjs:先输出 通知已发出,之后才输出 文件内容: hello。文件不存在时,先输出通知,再报告 读取失败: ENOENT,程序结束时返回退出码 1。

emit 调用了监听,但不会接收并等待它返回的 Promise。把 try/catch 放在 bus.emit(...) 外面,抓不到稍后发生的文件读取失败;写成 await bus.emit(...) 也无法等待读取完成,因为 emit 返回的是布尔值。


⏳ 下一步依赖读取结果时,直接等待函数

如果你必须先取得文件内容才能继续,就让函数返回读取结果,由调用处等待它。另存为 read-task.mjs:

read-task.mjs
import { readFile } from 'node:fs/promises'

async function loadText(file) {
    return readFile(file, 'utf8')
}

在同一文件中追加调用:

try {
    const text = await loadText('note.txt')
    console.log('文件内容:', text)
    console.log('读取完成,可以继续处理')
} catch (error) {
    console.error('读取失败:', error.code)
    process.exitCode = 1
}

运行 node read-task.mjs,文件存在时先输出内容,再输出 读取完成,可以继续处理;文件不存在时只报告读取失败,不执行成功分支。

两种方式的选择依据是:只通知其他功能自行处理,用事件;当前任务需要取得结果再继续,用函数返回值和 await。


⚠️ error 是需要处理的特殊事件

对可能报告错误的事件对象,先注册错误监听,再执行相关操作:

bus.on('error', error => console.error(error.message))
bus.emit('error', new Error('读取失败'))

输出 读取失败。如果没有 error 监听就触发该事件,Node.js 会抛出错误;它与普通事件没有监听时返回 false 的行为不同。

本篇默认创建的 EventEmitter 不会把 async 监听的 Promise 拒绝自动转成 error 事件。上面的异步读取仍要在监听内部捕获,不能只注册 error 监听就认为所有失败都处理好了。


❓ 知识问答

Q1:事件先触发再订阅能收到吗?

普通 EventEmitter 不保存历史事件,后订阅不会补收到此前通知。

Q2:为什么一次触发输出多次?

检查是否重复注册了监听,on 不会自动去重。

Q3:emit 能取得 async 监听的结果吗?

不能。emit 返回是否存在监听者,不返回监听函数的结果;需要文件内容时,使用上面的 loadText,并在调用处 await。


🧪 小练习

添加一个 once 监听,连续触发两次事件,比较它与 on 监听的输出次数。

// 请在这里编写代码

🎉 现在可以用自己的例子验证这些用法啦!