chuxinneko/nekocodedesktop/debug-root-cause

定位根因

目标是找到为什么会错，而不是让报错消失。改到不报错但说不清原因的修复，往往只是把问题挪到了别处。

一、先稳定复现

没有稳定复现就没有排查，只有猜测。

1. 拿到确切的触发方式：命令、输入、环境、期望结果与实际结果。
2. 亲自跑一次，确认自己看到的现象和用户描述的一致。
3. 把复现步骤压到最小：去掉不影响现象的输入和步骤。最小复现本身常常就指出了原因。
4. 复现不了就先解决这个——问清楚版本、操作系统、数据、时序。不要在没见过现象的情况下开始改代码。

偶发问题：先找出它和什么相关（并发、顺序、时间、缓存、数据量），把偶发变成必现。

二、读完整的错误

• 堆栈从上往下读到第一个属于本项目的帧，那里通常是入口；但抛出点未必是原因所在。
• 看 caused by / cause 链的最内层。
• 错误信息里的具体值（路径、id、数字）要和你的预期对照——不一致的那个值就是线索。
• 没有报错只是结果不对时，找到"最后一个数据还正确"和"第一个数据已错误"之间的那一步。

三、缩小范围

按能砍掉最多可能性的顺序做，而不是按顺手的顺序：

• 二分：注释掉一半、回退一半改动、git bisect 定位引入问题的提交。每次把嫌疑范围砍半。
• 边界检查：在可疑区段的入口和出口打印/断点，确认数据进去时是对的、出来时是错的。
• 换一边验证：怀疑是自己的代码，就用最小的独立脚本调用同一个库；怀疑是库，就用手写实现替换掉它跑一次。

git log -S"<关键字符串>" 和 git log -p <文件> 能直接找到某行逻辑是什么时候、为什么加进来的。

四、验证假设，别信直觉

写下当前假设，然后设计一个能证伪它的观察：

假设：缓存返回了过期的值。

如果成立：关掉缓存后现象消失。

实际：关掉后仍然出错 → 假设不成立，排除缓存。

一次只改一个变量。同时改两处后现象消失，你不知道是哪一处起了作用。

排查过程中加的日志要留到确认之后再删。

五、确认根因

能把下面三句话都说清楚，才算找到根因：

1. 出错的数据/状态是在哪一步第一次变得不对的。
2. 那一步为什么会这样做——是逻辑写错、假设不成立，还是输入不符合预期。
3. 为什么之前没暴露——新输入？新并发？新版本？改了哪个默认值？

第 3 点最常被跳过，但它决定了修复范围。

六、修复

• 在根因处修，而不是在现象处加判断。为了让报错消失而加的 try/catch 或判空，要能说清为什么那里本来就该判。
• 先写一个能复现该缺陷的测试，确认它失败，再改代码让它通过。没有这一步，无法证明真的修好了。
• 检查同类问题：同一个错误模式在别处是否也存在（同一个函数的其它调用点、同一类边界）。
• 跑一遍相关测试，确认没有引入回归。

报告

说明：现象 → 根因（数据在哪一步变错、为什么）→ 改了什么 → 怎么验证的。 如果最后没能定位，就说明已排除了哪些可能、卡在哪里、需要什么信息，不要给一个"可能是……"的猜测当结论。