游戏客户端架构 / 系统课时
事件名怎么写才不容易歧义
事件名怎么写才不容易歧义
当战斗模块发出 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 运行。
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 });预期输出:
Damage applied to p1: 25
Health of p1: 75这个例子中,requested 可以被拒绝,而 applied 只在实际扣血后发出。changed 表示生命值已经更新,可以用于刷新界面。Node.js 的 EventEmitter 默认同步执行监听器,因此示例中的输出顺序是确定的;实际游戏项目若使用队列分发,还需要单独定义消息顺序规则。
检查事件是否存在语义漂移
命名规范不能只在第一次定义时有效。项目迭代后,事件触发时机、参数或业务含义可能发生变化,导致旧名称逐渐失真。
审查事件契约时,可以依次检查:
- 只看到事件名,能否判断它是请求还是事实?
- 事件是否只在名称描述的条件真正满足后发送?
- 不同发送方是否遵守完全相同的语义?
- 新增订阅者后,是否需要修改事件名称才能继续使用?
- 修改业务规则后,原有订阅者是否仍能正确理解事件?
例如 player.died 应表示玩家已经进入死亡状态。如果真正需要等待死亡动画播放结束,应另设 player.death_animation.finished,而不是改变原事件的触发时间。
好的事件名称既要让当前代码容易理解,也要在更换 UI、战斗算法和事件总线实现后保持稳定。先定义清楚业务事实,再确定事件名称,通常比从函数名反推事件名更可靠。