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

给每次切换留下可读日志

给每次切换留下可读日志

状态机出问题时,最怕日志只剩“进入某状态”这类孤立句子,既不知道谁触发,也看不出从哪里切来。本节把每次切换记录成结构化事件,让你能按对象、触发源和切换编号还原完整运行轨迹。

学习目标

  • 为一次状态切换设计足够但不过量的日志字段。
  • 区分成功、拒绝和非法切换应使用的日志级别。
  • 利用关联标识把输入、条件判断和状态变化串成可追踪链路。

一条切换日志要回答哪些问题

可读的切换日志至少要回答“谁、何时、因为什么、从哪到哪、结果怎样”。只记录 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 运行,演示成功切换以及统一生成关联字段:

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");

预期输出

text
{"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 查快照或调试数据。

当每次迁移都能稳定回答“谁因何从哪到哪、是否成功、如何关联上下游”时,状态机日志才真正具备可排查价值。

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

目录与阅读设置

阅读设置

17

记录一个想法

给每次切换留下可读日志

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

登录哪都通