游戏客户端架构 / 系统课时

事件名怎么写才不容易歧义

事件名怎么写才不容易歧义

当战斗模块发出 Damage 事件时,订阅方可能不知道它表示请求扣血、已经完成扣血,还是播放受击反馈。本课建立一套可落地的事件命名规则,让发送方和接收方能够通过名称判断事件的含义、发生时机和处理责任。

学习目标

  • 区分动作请求、执行结果与状态事实三种事件语义。
  • 使用统一的领域、对象和阶段命名规则。
  • 识别并修复同名异义、时态混乱和语义漂移。

先区分事件到底表达什么

事件名首先要回答一个问题:消息描述的是希望发生的动作,还是已经发生的事实?如果这个问题不明确,即使模块之间没有直接调用,订阅者仍然需要猜测发送方的意图。

以角色受到伤害为例,可以区分三类消息:

类型 事件名 准确含义
动作请求 combat.damage.requested 请求执行伤害结算,尚未保证成功
结果通知 combat.damage.applied 一次伤害结算已经实际生效
状态事实 player.health.changed 玩家生命值已经发生变化

动作请求允许被业务规则拒绝。例如目标无敌、伤害值无效或目标已死亡,都可能使请求无法执行。接收者必须先校验,再决定是否产生结果事件。

结果通知强调一次操作的结局,状态事实强调某个属性发生了什么变化。两者可能同时出现,但用途不同:战斗统计关注实际伤害,血条界面关注生命值变化。

建立稳定的命名格式

推荐使用 领域.对象.阶段 的格式,例如 combat.damage.applied。领域说明事件归属,对象说明发生变化的业务概念,阶段说明事情处于什么状态。

命名时遵守以下约定:

  • 使用稳定的业务词汇,例如 combat、player、inventory,避免使用容易随代码重构变化的类名。
  • 请求使用 requested,成功生效的结果使用 applied、created 或 completed 等明确词汇。
  • 状态变化使用 changed,并确保发送事件时相应状态确实已经更新。
  • 失败结果根据含义选择 rejected 或 failed,不要把业务拒绝与执行异常混为一谈。
  • 同一项目统一采用小写点分隔命名,不同时混用驼峰、下划线和点分隔形式。

事件名称不应包含某个订阅者的实现细节。player.health.changed 比 ui.update.health.bar 更稳定,因为未来可能同时由音效、成就、统计和网络同步模块订阅。

运行一条语义明确的事件链

下面使用 Node.js 内置的 EventEmitter 模拟游戏客户端的事件总线。示例可以独立执行,不依赖任何游戏引擎。

将代码保存为 event-name.js,使用 node event-name.js 运行。

js
const { EventEmitter } = require('node:events');

const bus = new EventEmitter();
let hp = 100;

bus.on('combat.damage.requested', ({ targetId, amount }) => {
  // 请求阶段负责校验,不能提前宣称伤害已经生效。
  if (!Number.isFinite(amount) || amount <= 0 || hp === 0) {
    bus.emit('combat.damage.rejected', { targetId });
    return;
  }

  const actualDamage = Math.min(amount, hp);
  hp -= actualDamage;

  // 结算完成后,分别通知操作结果与状态变化。
  bus.emit('combat.damage.applied', { targetId, actualDamage });
  bus.emit('player.health.changed', { playerId: targetId, currentHp: hp });
});

bus.on('combat.damage.applied', ({ targetId, actualDamage }) => {
  console.log(`Damage applied to ${targetId}: ${actualDamage}`);
});

bus.on('player.health.changed', ({ playerId, currentHp }) => {
  console.log(`Health of ${playerId}: ${currentHp}`);
});

bus.emit('combat.damage.requested', { targetId: 'p1', amount: 25 });

预期输出:

text
Damage applied to p1: 25
Health of p1: 75

这个例子中,requested 可以被拒绝,而 applied 只在实际扣血后发出。changed 表示生命值已经更新,可以用于刷新界面。Node.js 的 EventEmitter 默认同步执行监听器,因此示例中的输出顺序是确定的;实际游戏项目若使用队列分发,还需要单独定义消息顺序规则。

检查事件是否存在语义漂移

命名规范不能只在第一次定义时有效。项目迭代后,事件触发时机、参数或业务含义可能发生变化,导致旧名称逐渐失真。

审查事件契约时,可以依次检查:

  1. 只看到事件名,能否判断它是请求还是事实?
  2. 事件是否只在名称描述的条件真正满足后发送?
  3. 不同发送方是否遵守完全相同的语义?
  4. 新增订阅者后,是否需要修改事件名称才能继续使用?
  5. 修改业务规则后,原有订阅者是否仍能正确理解事件?

例如 player.died 应表示玩家已经进入死亡状态。如果真正需要等待死亡动画播放结束,应另设 player.death_animation.finished,而不是改变原事件的触发时间。

好的事件名称既要让当前代码容易理解,也要在更换 UI、战斗算法和事件总线实现后保持稳定。先定义清楚业务事实,再确定事件名称,通常比从函数名反推事件名更可靠。

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

目录与阅读设置

阅读设置

17

记录一个想法

事件名怎么写才不容易歧义

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

登录哪都通