Node.js / 系统课时

设计自定义事件

设计自定义事件

自定义事件的重点不在于“能触发就行”,而是让发布者与订阅者只依赖稳定的事件契约。本课用订单创建场景设计事件名、参数对象和模块边界,让日志与通知模块可以独立订阅,而订单模块不直接调用它们。

学习目标

  • 用稳定、可检索的命名规则定义自定义事件。
  • 把事件参数设计成单一对象,并保持字段语义稳定。
  • 用事件总线解耦发布者与多个订阅模块,同时识别同步执行边界。

定义事件契约

事件名应表达“已经发生的事实”,例如 order.created、user.deleted,而不是 createOrder 这种命令式名称。参数建议传一个对象,后续新增字段时不会改变监听函数的位置参数顺序。

下面的订单事件固定包含 orderId、userId、amountCents 三个字段,其中金额使用整数分,避免浮点金额带来的歧义。对外约定后,不要把 amountCents 随意改成 amount 或美元浮点数。

字段 示例值 约束
orderId ORD-1001 字符串,订单唯一标识
userId U-42 字符串,用户标识
amountCents 2599 非负整数,单位为分

用事件解耦模块

订单服务只负责创建订单并发布 order.created。审计与通知模块分别订阅同一个事件,彼此不需要相互引用;新增第三个订阅者时也不必修改订单服务的业务流程。

订单创建事件在发布者与多个订阅者之间的数据流

js
import { EventEmitter } from 'node:events';

const events = new EventEmitter();

events.on('order.created', ({ orderId, amountCents }) => {
  console.log(`audit:${orderId}:${amountCents}`);
});

events.on('order.created', ({ orderId, userId }) => {
  console.log(`notify:${userId}:${orderId}`);
});

function createOrder() {
  const order = {
    orderId: 'ORD-1001',
    userId: 'U-42',
    amountCents: 2599
  };

  events.emit('order.created', order);
  return order;
}

const order = createOrder();
console.log('created:', order.orderId);

预期输出:

text
audit:ORD-1001:2599
notify:U-42:ORD-1001
created: ORD-1001

因为监听器同步执行,所以 created: ORD-1001 一定出现在两个监听器输出之后。如果通知逻辑需要网络请求,不应让订单创建流程等待其耗时操作,可让监听器把任务投递到队列,或在监听器内部显式启动异步工作并自行处理失败。

让事件参数保持可演进

事件对象最好只携带订阅者真正需要的数据,不要直接把数据库连接、HTTP 请求对象或大型可变实体传出去。一个实用做法是把事件 payload 当成只读快照:发布前完成字段归一化,发布后监听器只读取,不修改共享对象。

如果未来需要新增 currency: 'USD',可以直接增加字段,旧监听器仍能正常解构已有字段。相反,把监听器定义成 (orderId, userId, amountCents) 后再插入第四个位置参数,调用点与所有监听器都更容易发生错位。

处理错误与监听器边界

不要用普通业务事件替代错误处理。error 仍然保留 Node.js 的特殊语义:没有对应监听器时触发会抛错。若某个订阅者失败,需要先决定这类失败是否应该阻断发布者。

对于审计这类必须成功的同步逻辑,可以直接让异常向上传播;对于邮件、Webhook 等可重试副作用,更适合把任务写入可靠队列,再由独立消费者执行。这样订单是否创建成功,不会取决于第三方通知接口是否在 500 ms 内返回。

自定义事件设计到位后,发布者只声明“发生了什么”,订阅者各自决定“收到后做什么”。检查事件名是否表示事实、payload 是否稳定、监听器失败是否会阻断主流程,通常就能判断这套事件边界是否足够清晰。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

设计自定义事件

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通