游戏客户端架构 / 系统课时
一个事件触发多个系统怎么追踪
一个事件触发多个系统怎么追踪
角色受到攻击时,一次事件可能同时更新血条、播放音效和记录统计。如果其中某个系统没有响应,普通日志往往只能看到事件已经发布,却无法确定是谁处理了它。本篇为本地事件总线增加可开关的追踪入口,记录发布者、订阅者和实际调用顺序,快速定位隐藏依赖与异常回调。
学习目标
- 识别一次事件分发中需要记录的关键追踪信息。
- 实现能够展示发布者、订阅者及调用顺序的调试事件总线。
- 根据追踪结果定位遗漏订阅、重复调用和异常中断。
事件追踪需要记录什么
普通事件总线通常只负责将事件载荷交给订阅者。由于发布者不知道最终有哪些模块接收事件,问题发生时很容易出现信息断层。
例如 Combat 发布 player.damaged 后,HUD、Audio 和 Stats 各自独立响应。如果音效没有播放,需要先知道音效系统是否订阅成功、回调有没有开始,以及它之前的回调是否抛出了异常。
一条有诊断价值的追踪记录至少应包含以下信息:
| 字段 | 用途 |
|---|---|
dispatchId |
区分不同的事件发布批次 |
eventName |
标识发生的事件类型 |
publisher |
识别主动发布事件的模块 |
subscriberId |
唯一标识当前订阅记录 |
subscriberName |
提供可读的模块名称 |
order |
标识当前批次中的回调调用次序 |
status |
区分开始、完成与失败 |
其中 dispatchId 尤其重要。两次连续发布相同类型的事件时,仅凭事件名称无法判断某条回调日志属于哪一次分发。
发布者名称最好由调用 Publish 的业务模块显式传入,不要通过解析调用栈猜测。调用栈可能受到包装函数、优化和异步边界影响,不适合作为稳定的事件来源标识。
看清一次事件的完整分发链
对于同步本地事件总线,追踪应覆盖事件发布和每个订阅者执行前后的节点。这样既能看出一个事件影响了哪些系统,也能观察异常发生在什么位置。

在这个链路中,事件总线承担两项职责:正常执行订阅者回调,并向追踪入口报告实际执行状态。追踪功能不应该要求 HUD、Audio 或 Stats 自己编写统一格式的日志,否则每个模块都必须了解调试协议。
调试顺序也不等于业务依赖顺序。如果音效系统必须等待统计系统更新后才能执行,就不应依赖偶然的注册先后关系;这种约束需要由明确的业务流程协调。
为事件总线加入追踪入口
下面使用 C# 实现一个可运行的追踪事件总线。示例要求 .NET 8 或更高版本,将代码放入控制台项目的 Program.cs 后运行 dotnet run。
实现选择 List 保存带编号的订阅记录,保证该示例内同步回调按注册顺序调用。追踪入口使用可选的 Action<string>,调试时传入 Console.WriteLine,不需要日志时传入 null。
using System;
using System.Collections.Generic;
using System.Linq;
var hudHp = 100;
var audioCount = 0;
var totalDamage = 0;
var bus = new TraceBus<DamageEvent>(
"player.damaged", Console.WriteLine);
bus.Subscribe("HUD", e => hudHp -= e.Amount);
bus.Subscribe("Audio", _ => audioCount++);
bus.Subscribe("Stats", e => totalDamage += e.Amount);
bus.Publish("Combat", new DamageEvent(25));
Console.WriteLine(
$"验证: HP={hudHp}, 音效={audioCount}, 累计伤害={totalDamage}");
readonly record struct DamageEvent(int Amount);
sealed class TraceBus<T>
{
private readonly string _eventName;
private readonly Action<string>? _trace;
private readonly List<Subscription> _listeners = new();
private int _nextSubscriberId;
private int _nextDispatchId;
private sealed record Subscription(
int Id, string Name, Action<T> Handler);
public TraceBus(string eventName, Action<string>? trace)
{
ArgumentException.ThrowIfNullOrWhiteSpace(eventName);
_eventName = eventName;
_trace = trace;
}
public int Subscribe(string name, Action<T> handler)
{
ArgumentException.ThrowIfNullOrWhiteSpace(name);
ArgumentNullException.ThrowIfNull(handler);
int id = ++_nextSubscriberId;
_listeners.Add(new Subscription(id, name, handler));
return id;
}
public void Publish(string publisher, T payload)
{
ArgumentException.ThrowIfNullOrWhiteSpace(publisher);
int dispatchId = ++_nextDispatchId;
_trace?.Invoke(
$"#{dispatchId} 发布 {_eventName} <- {publisher}");
int order = 0;
// 快照固定本次分发的订阅者集合。
foreach (var subscriber in _listeners.ToArray())
{
order++;
string prefix =
$"#{dispatchId} [{order}] {subscriber.Name}";
_trace?.Invoke(
$"{prefix} (订阅#{subscriber.Id}) 开始");
try
{
subscriber.Handler(payload);
_trace?.Invoke($"{prefix} 完成");
}
catch (Exception ex)
{
// 保留出错订阅者,再向调用方传播异常。
_trace?.Invoke(
$"{prefix} 失败: {ex.GetType().Name}");
throw;
}
}
}
}预期输出:
#1 发布 player.damaged <- Combat
#1 [1] HUD (订阅#1) 开始
#1 [1] HUD 完成
#1 [2] Audio (订阅#2) 开始
#1 [2] Audio 完成
#1 [3] Stats (订阅#3) 开始
#1 [3] Stats 完成
验证: HP=75, 音效=1, 累计伤害=25这份日志完整标识了发布源 Combat、事件名称和分发批次。三个订阅者均有开始与完成记录,最后的业务状态也与本次伤害值一致。
示例选择同步、失败即停止的异常策略。如果 Audio 的回调抛出异常,总线会记录 Audio 失败并重新抛出异常,之后的 Stats 不会执行。这种策略便于立即暴露问题,但不适合所有事件类型。
根据追踪记录定位问题
有了统一追踪格式,可以按固定顺序分析异常,而不必在各个游戏模块之间猜测调用路径。
| 观察到的现象 | 优先排查方向 |
|---|---|
| 有发布记录,没有目标订阅者记录 | 订阅遗漏、注册时机或已注销 |
| 同一模块出现多个订阅编号 | 重复创建了订阅记录 |
| 有开始记录,没有完成记录 | 回调异常、阻塞或执行未结束 |
| 某个订阅者失败,后续订阅者未执行 | 同步分发被异常中断 |
| 回调都完成,画面仍未变化 | 模块内部状态更新或渲染问题 |
还需要区分两个编号:subscriberId 标识某次注册产生的订阅记录,order 则表示本次发布中的实际调用位置。它们不是一回事。如果订阅被删除后重新注册,新记录应具有新编号,调用位置也可能改变。
本示例把订阅列表直接暴露在事件总线内部,尚未实现取消订阅接口。实际集成时应增加以订阅编号为依据的注销能力,并与对象生命周期绑定。否则追踪工具本身虽然可以发现重复记录,却不能防止这些记录长期存在。
控制追踪开销与行为边界
事件追踪不应该改变正常的事件分发语义。上线前应明确以下规则:
- 开发环境开启详细追踪:记录每个订阅者的开始、完成和异常,便于复现问题。
- 高频事件减少日志:例如每帧的位置更新或输入事件,优先采用采样、过滤和计数,避免海量输出。
- 生产环境保留必要指标:按事件类型统计发布次数、失败次数或处理耗时,不必打印每次调用的完整载荷。
- 避免敏感数据泄漏:不要把认证令牌、玩家隐私字段或完整业务对象直接写入追踪日志。
- 隔离追踪设施异常:生产实现应防止日志写入失败中断业务分发,并为追踪缓冲设置容量上限。
[!info] 示例使用的 List 和递增编号针对单线程同步分发设计。异步回调、跨线程发布以及递归发布事件时,需要进一步处理并发安全、关联标识和实际执行顺序;不能简单地将注册顺序理解为异步操作的完成顺序。
当一个事件同时影响多个系统时,最重要的不是增加更多零散日志,而是建立贯穿发布和回调执行的统一标识。只要能从一次发布准确找到参与的订阅者、调用次序及失败位置,原本隐藏在事件总线后的模块关系就能被直接观察和验证。