Systematic Debugging

系统化调试

概述

核心原则： 在尝试修复之前，务必先找到根本原因。只修症状就是失败。

敷衍走流程等于违背调试的精神。

铁律

不做根因调查，不许提修复方案

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

何时使用

用于任何技术问题：

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

尤其在以下情况必须使用：

• 时间紧迫（紧急情况最容易让人猜测式修复）
• 觉得"一个小修改"就能搞定
• 已经尝试了多种修复
• 上一次修复没有生效
• 你没有完全理解问题

以下情况也不要跳过：

• 问题看起来很简单（简单的 bug 也有根本原因）
• 你很赶时间（越急越容易返工）
• 领导要求立刻修好（系统化调试比反复尝试更快）

四个阶段

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

第一阶段：根因调查

在尝试任何修复之前：

1. 仔细阅读错误信息

   • 不要跳过错误或警告
   • 它们往往直接包含解决方案
   • 完整阅读堆栈跟踪
   • 记下行号、文件路径、错误码

2. 稳定复现

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

3. 检查近期变更

   • 什么变更可能导致了这个问题？
   • git diff、最近的提交
   • 新依赖、配置变更
   • 环境差异

4. 在多组件系统中收集证据

   当系统有多个组件时（CI → 构建 → 签名，API → 服务 → 数据库）：

   在提出修复方案之前，先添加诊断埋点：

   对每个组件边界：
     - 记录进入组件的数据
     - 记录离开组件的数据
     - 验证环境/配置的传递
     - 检查每一层的状态
   
   执行一次以收集证据，确定断裂点在哪里
   然后分析证据，定位故障组件
   然后针对该组件深入调查
   

   示例（多层系统）：

   # 第 1 层：工作流
   echo "=== Secrets available in workflow: ==="
   echo "IDENTITY: $([ -n "${IDENTITY:-}" ] && echo SET || echo UNSET)"