游戏客户端架构 / 系统课时
给每次切换留下可读日志
给每次切换留下可读日志
状态机出问题时,最怕日志只剩“进入某状态”这类孤立句子,既不知道谁触发,也看不出从哪里切来。本节把每次切换记录成结构化事件,让你能按对象、触发源和切换编号还原完整运行轨迹。
学习目标
- 为一次状态切换设计足够但不过量的日志字段。
- 区分成功、拒绝和非法切换应使用的日志级别。
- 利用关联标识把输入、条件判断和状态变化串成可追踪链路。
一条切换日志要回答哪些问题
可读的切换日志至少要回答“谁、何时、因为什么、从哪到哪、结果怎样”。只记录 Enter Running,一旦同屏有几十个角色或多个状态机实例,就无法判断这条日志属于谁,也不知道前一个状态是什么。
| 字段 | 作用 | 示例 |
|---|---|---|
machine |
区分状态机类型 | PlayerMovement |
entityId |
定位具体实例 | player-42 |
event |
记录触发源 | MOVE_START |
fromState / toState |
还原迁移关系 | Idle → Running |
result |
区分成功、拒绝或异常 | success |
reason |
说明守卫条件或失败原因 | speed>0 |
traceId |
关联同一次输入或业务链路 | trace-input-7 |
transitionId |
唯一标识一次切换 | tr-0001 |
elapsedMs |
观察切换处理耗时 | 2 |
时间戳也应保留,但不要依赖它作为唯一关联键;并发环境里,多条日志可能落在同一毫秒。
把日志集中在统一切换入口
最稳妥的做法是让所有状态迁移都经过一个入口:先查规则,再执行切换,最后统一写日志。这样新增状态时,不需要提醒每个开发者“记得补日志”。
下面示例可直接用 Node.js 运行,演示成功切换以及统一生成关联字段:
const transitions = {
Idle: { MOVE_START: "Running" },
Running: { MOVE_STOP: "Idle" }
};
let seq = 0;
function transition(ctx, event, reason, now) {
const fromState = ctx.state;
const toState = transitions[fromState]?.[event];
if (!toState) {
console.warn(JSON.stringify({
time: now,
machine: ctx.machine,
entityId: ctx.entityId,
event,
fromState,
toState: null,
result: "rejected",
reason: "no-transition-rule",
traceId: ctx.traceId
}));
return;
}
// transitionId 只标识这一次迁移;traceId 用来串起同一条输入链路。
const transitionId = `tr-${String(++seq).padStart(4, "0")}`;
ctx.state = toState;
console.log(JSON.stringify({
time: now,
machine: ctx.machine,
entityId: ctx.entityId,
event,
fromState,
toState,
result: "success",
reason,
traceId: ctx.traceId,
transitionId,
elapsedMs: 1
}));
}
const player = {
machine: "PlayerMovement",
entityId: "player-42",
state: "Idle",
traceId: "trace-input-7"
};
transition(player, "MOVE_START", "speed>0", "2026-09-24T00:00:00.000Z");
transition(player, "MOVE_STOP", "speed=0", "2026-09-24T00:00:00.010Z");预期输出
{"time":"2026-09-24T00:00:00.000Z","machine":"PlayerMovement","entityId":"player-42","event":"MOVE_START","fromState":"Idle","toState":"Running","result":"success","reason":"speed>0","traceId":"trace-input-7","transitionId":"tr-0001","elapsedMs":1}
{"time":"2026-09-24T00:00:00.010Z","machine":"PlayerMovement","entityId":"player-42","event":"MOVE_STOP","fromState":"Running","toState":"Idle","result":"success","reason":"speed=0","traceId":"trace-input-7","transitionId":"tr-0002","elapsedMs":1}这里的时间为了便于验证使用固定值;真实运行时通常来自系统时钟,实际值会不同。
日志级别要表达异常程度
正常切换适合使用 info,因为它构成主要运行轨迹。被守卫条件挡住、收到当前状态不支持的事件,可使用 debug 或 warn,具体取决于它在业务上是否异常。进入未注册状态、状态数据损坏、切换回调抛出异常,则应使用 error。
用关联信息还原完整轨迹
entityId 解决“是哪一个对象”,traceId 解决“属于哪一次输入或请求”,transitionId 解决“是哪一次迁移”。三者职责不同,合在一起才能在并发场景下可靠过滤。
排查时先按 entityId 聚合,再按时间排序;如果问题由一次玩家输入、网络消息或任务触发,就继续按 traceId 收窄。看到某条异常切换后,再用 transitionId 查同一次迁移前后的守卫判断、退出回调和进入回调日志。
什么信息不该塞进切换日志
不要把完整角色对象、背包、黑板或大段序列化上下文直接写入每条日志。它会放大 I/O 成本,还可能泄露敏感数据。切换日志应保留“用于定位的索引字段”和“解释决策的最小上下文”,需要深挖时再通过对象 ID 查快照或调试数据。
当每次迁移都能稳定回答“谁因何从哪到哪、是否成功、如何关联上下游”时,状态机日志才真正具备可排查价值。