游戏客户端架构 / 系统课时
事件载荷放哪些字段才够用
事件载荷放哪些字段才够用
角色生命值变化后,HUD、音效和统计模块可能同时收到消息。如果事件包含整个角色对象、血条百分比和音效资源,发送方就不得不了解所有订阅者。本课通过一个可运行的生命值事件,确定必要字段、上下文信息和派生数据的边界。
学习目标
- 根据业务事实与订阅需求确定事件的最小载荷。
- 区分事实字段、可选上下文与接收方派生数据。
- 使用独立订阅者验证事件载荷不依赖具体模块实现。
从业务事实确定最小字段
事件载荷应描述事件发生时已经确定的事实,而不是发送方替每个订阅者准备好的显示结果。
假设玩家 p1 的生命值从 100 降到 75,事件名称为 player.health.changed。可以首先确定以下字段:
| 字段 | 示例值 | 用途 |
|---|---|---|
playerId |
p1 |
标识生命值发生变化的玩家 |
previousHp |
100 |
描述变化前的生命值 |
currentHp |
75 |
描述变化后的生命值 |
这三个字段足以支持当前场景:HUD 使用玩家标识和最新生命值,音效模块比较前后数值判断是否受伤,统计模块计算本次生命值减少量。
这里的最小载荷并不等于字段越少越好。如果事件需要支持伤害来源归因,sourceId 就可能成为必要字段;如果需要区分毒伤、直接攻击和剧情扣血,则可能需要明确的 cause 字段。
判断标准是:接收方完成约定的业务行为时,是否必须知道这项事件发生时的事实,并且不能从自身已有的可靠数据中获得。
把派生数据留给订阅者
常见的过度设计,是将生命值百分比、血条文案、角色对象引用甚至播放哪个音效都放入同一事件载荷。
这些数据通常属于不同的职责边界:
healthPercent可以由 HUD 根据当前生命值和最大生命值计算。hudText属于 UI 展示规则,还可能受到本地化设置影响。audioClip由音效系统根据受击类型和配置选择。playerObject是具体引擎对象引用,容易把订阅者绑定到发送方的内存布局和生命周期。
因此,更合理的通信关系是生命值系统发布事实,接收方自行完成显示、播放或记录,而不是由生命值系统提前决定所有表现。

这张关系图的关键不是减少几个字节,而是让事件生产者不需要知道未来有多少种订阅者。新增成就或日志模块时,只要现有事实字段足够,就无需修改生命值系统。
用可运行代码验证载荷边界
下面使用 Node.js 的 EventEmitter 演示三个订阅者。事件发送方只发布生命值变化的事实,HUD 和音效模块分别计算自己需要的结果。
将代码保存为 event-payload.js,运行 node event-payload.js。
const { EventEmitter } = require('node:events');
const bus = new EventEmitter();
const hp = new Map([['p1', 100]]);
const maxHp = new Map([['p1', 100]]);
bus.on('player.health.changed', ({ playerId, currentHp }) => {
// 最大生命值来自展示方可访问的规则数据,不由事件发送方计算百分比。
const percentage = Math.round(currentHp / maxHp.get(playerId) * 100);
console.log(`HUD ${playerId}: ${percentage}%`);
});
bus.on('player.health.changed', ({ previousHp, currentHp }) => {
if (currentHp < previousHp) console.log('AUDIO hurt');
});
bus.on('player.health.changed', ({ playerId, previousHp, currentHp }) => {
console.log(`METRIC ${playerId}: ${previousHp - currentHp}`);
});
function applyDamage(playerId, amount) {
if (!Number.isFinite(amount) || amount < 0) {
throw new Error('invalid damage');
}
const previousHp = hp.get(playerId);
if (previousHp === undefined) throw new Error('unknown player');
const currentHp = Math.max(0, previousHp - amount);
hp.set(playerId, currentHp);
// 只有生命值真正改变时,才发出包含前后状态的事实事件。
if (currentHp !== previousHp) {
bus.emit('player.health.changed', { playerId, previousHp, currentHp });
}
}
applyDamage('p1', 25);预期输出:
HUD p1: 75%
AUDIO hurt
METRIC p1: 25这里没有将 percentage、音效名称或统计结果写入事件。三个监听器仍然可以独立完成任务。未来调整血条显示规则或更换音效资源时,事件载荷无需变化。
这个示例假设最大生命值数据与事件接收方保持一致。如果最大生命值也会同时变化,而且系统要求历史回放准确,就需要在契约中补充相关状态快照或版本信息,不能依赖可能已经更新的当前配置。
什么时候需要增加上下文信息
最小载荷只针对明确的业务与交付需求成立。事件传输方式改变后,还可能需要上下文字段。
| 字段 | 适合增加的条件 |
|---|---|
eventId |
消息可能重复投递,需要幂等去重 |
tick |
需要按游戏逻辑帧排序或重放事件 |
sourceId |
需要记录攻击者、治疗者等来源 |
cause |
相同数值变化可能来自不同业务原因 |
schemaVersion |
存在跨版本持久化或独立升级的消费者 |
这些字段不是每个事件都必须具备。在单进程同步分发且不存在持久化需求时,盲目增加消息编号、时间戳和版本号,只会提高创建与维护成本。
用契约检查控制后续扩展
事件发布前,可以使用三个问题检查载荷设计:
- 删除某个字段后,现有订阅者是否仍能正确完成约定任务?如果可以,它可能不是必要字段。
- 增加一个订阅者时,是否需要发送方了解它的 UI、资源或内部对象?如果需要,应优先调整职责边界。
- 事件被延迟处理或重复处理时,是否仍能解释其含义?如果不能,再按实际要求增加顺序、标识或快照信息。
当需要修改字段含义时,应先评估现有消费者。新增可选字段通常可以保持兼容;删除字段、改变单位或调整原有含义则可能造成破坏性变更,需要明确迁移策略。
事件载荷的目标不是绝对最小,而是用足够的事实支撑稳定的业务契约,同时避免把发送方与订阅者的实现细节绑定在一起。