系统化调试（Systematic Debugging）

概述

随机修复浪费时间并产生新的 bug。快速补丁只会掩盖深层问题。

核心原则： 在尝试修复之前，必须先找到根因（Root Cause）。只修复症状就是失败。

违反这一流程的字面要求，就是违反调试的精神。

铁律

没有完成根因调查，就不能进行任何修复

如果你没有完成第一阶段，就不能提出修复方案。

何时使用

适用于任何技术问题：

• 测试失败
• 生产环境 bug
• 意外行为
• 性能问题
• 构建失败
• 集成问题

尤其在以下情况下更应使用：

• 时间压力大（紧急情况使人倾向于猜测）
• "就改一个快速修复"看起来很明显
• 你已经尝试了多次修复
• 上一次修复没有起作用
• 你没有完全理解这个问题

以下情况不要跳过：

• 问题看起来很简单（简单 bug 也有根因）
• 你很赶时间（匆忙保证返工）
• 领导要求立刻修好（系统化方法比反复折腾更快）

四个阶段

你必须完成每个阶段后才能进入下一个阶段。

第一阶段：根因调查

在尝试任何修复之前：

1. 仔细阅读错误信息

   • 不要跳过错误或警告
   • 它们通常包含确切的解决方案
   • 完整阅读堆栈追踪（Stack Trace）
   • 记录行号、文件路径、错误码

2. 稳定复现

   • 你能可靠地触发它吗？
   • 确切的步骤是什么？
   • 每次都会发生吗？
   • 如果无法复现 → 收集更多数据，不要猜测

3. 检查近期变更

   • 哪些变更可能导致了这个问题？
   • Git diff、近期提交（commit）
   • 新依赖、配置变更
   • 环境差异

4. 在多组件系统中收集证据 对每个组件边界：

   • 记录进入组件的数据
   • 记录离开组件的数据
   • 验证环境/配置的传播
   • 检查每一层的状态

5. 追踪数据流

   • 错误值从哪里产生的？
   • 什么调用传入了错误值？
   • 持续向上追踪直到找到源头
   • 在源头修复，而不是在症状处修复

第二阶段：模式分析

1. 找到正常工作的示例 — 定位类似的正常运行代码
2. 与参考实现对比 — 完整阅读参考实现
3. 识别差异 — 列出每一个差异，无论多小
4. 理解依赖关系 — 需要哪些设置、配置、环境？

第三阶段：假设与测试

1. 形成单一假设 — "我认为 X 是根因，因为 Y"
2. 最小化测试 — 最小的可能变更，一次只改一个变量
3. 继续前先验证 — 没有起作用？形成新的假设
4. 当你不确定时 — 说"我不理解 X"，寻求帮助

第四阶段：实施

1. 创建失败测试用例 — 使用 TDD 技能
2. 实施单一修复 — 一次只做一个变更
3. 验证修复 — 测试通过了？其他测试没有被破坏？
4. 如果修复无效 — 如果尝试次数 < 3：返回第一阶段。如果 ≥ 3：停下来，质疑架构
5. 如果 3 次以上修复失败：质疑架构 — 这个模式（Pattern）从根本上是否合理？

危险信号 — 立即停下来，遵循流程

• "先快速修复，以后再调查"
• "试试改一下 X，看看行不行"
• "一次加多个改动，跑一下测试"
• "跳过测试，我手动验证"
• "大概是 X 的问题，让我修一下"
• "我没完全理解，但这个也许能行"
• 在追踪数据流之前就提出解决方案
• "再试一次修复"（已经尝试了 2 次以上）
• 每次修复都在不同的地方暴露新问题

以上所有情况都意味着：停下来。返回第一阶段。

常见的合理化借口

辅助技术

• 根因追踪（root-cause-tracing） — 通过调用栈向上追踪 bug
• 纵深防御（defense-in-depth） — 在多个层次添加验证
• 条件等待（condition-based-waiting） — 用条件轮询替代任意超时

实际效果

• 系统化方法：15-30 分钟修复
• 随机修复方法：2-3 小时的反复折腾
• 一次修复成功率：95% vs 40%
• 引入新 bug：几乎为零 vs 经常发生

附录A：根因追踪（Root Cause Tracing）

核心原则： 沿着调用链（Call Chain）向后追踪，直到找到最初的触发点，然后在源头修复。

适用场景：

• 错误发生在执行深处
• 堆栈追踪显示很长的调用链
• 不清楚无效数据的来源

追踪流程：

1. 观察症状
2. 找到直接原因
3. 追问：是什么调用了它？
4. 持续向上追踪
5. 找到最初的触发点

永远不要只在错误出现的位置修复。 向上追踪，找到最初的触发点。

附录B：纵深防御验证（Defense-in-Depth）

核心原则： 在数据经过的每一层都进行验证。让 bug 在结构上变得不可能发生。

四个层次：

1. 第一层：入口验证（Entry Point Validation） — 拒绝明显无效的输入
2. 第二层：业务逻辑验证（Business Logic Validation） — 确保数据对当前操作有意义
3. 第三层：环境守卫（Environment Guards） — 防止在特定上下文中执行危险操作
4. 第四层：调试埋点（Debug Instrumentation） — 捕获上下文信息用于事后分析

不要止步于一个验证点。 在每一层都添加检查。

附录C：条件等待（Condition-Based Waiting）

核心原则： 等待你真正关心的条件，而不是猜测它需要多长时间。

适用场景：

• 测试中有任意延迟（setTimeout、sleep）
• 测试不稳定（有时通过，负载下失败）
• 等待异步操作

核心模式：

// ❌ 之前：猜测时间
await new Promise(r => setTimeout(r, 50));

// ✅ 之后：等待条件
await waitFor(() => getResult() !== undefined);

快速参考模式：