duck-debug 是一套以“橡皮鸭调试”为核心的方法论技能,通过苏格拉底式提问引导开发者自行定位缺陷根因,而不是直接提供答案。其基本规则是:在给出一个答案之前,先提出三个问题。
核心框架 围绕三个问题展开:应该发生什么(规格、意图、契约);实际发生什么(当前行为、日志、输出);差距在哪里(规格与现实之间的差值就是缺陷所在)。
执行路径追踪 沿着调用路径追踪:入口点(什么触发了它)、数据流(每个函数接收、修改、返回什么)、状态转换(状态在哪里意外改变)、副作用(作为结果运行了什么)、时序(竞态条件、异步顺序、事件循环)。
堆栈跟踪审阅 找到最后成功执行的行,再到抛错的行,观察两者之间发生了什么变化。关注上下文:哪个函数、什么输入、之前的状态是什么。不必阅读每一帧,而是按“错误帧→调用帧→该帧的调用者”的顺序重复,直到看到熟悉的代码。注意:堆栈中的行号常常具有误导性,缺陷往往发生在崩溃之前。
运行时假设挑战 聚焦运行时的值,而非架构。对每一个断言追问:你确定它永远不会返回 null/undefined 吗?如果输入为空呢?如果缓存已过期呢?堆栈中的那个行号真的是缺陷所在,还是只是崩溃的位置?旧代码处理方式不同吗?为什么?若涉及扩展性、兼容性、回滚等问题,则转向 duck-design。
复现提示 不做清单式检查,而是提问:触发这个问题的最小输入是什么?你能连续复现两次吗,还是时有时无?错误信息与你的预期一致,还是具有误导性?你“没有”在看什么?如果两轮之后仍没有复现步骤,则转向 duck-triage。
何时停止 当开发者已经自行追踪了执行路径、规格与现实之间的差距已经可见、并且能用一句话说出缺陷(例如“X 是 null,因为 Y 没有调用 Z”)时,即可停止。如果做不到,说明还没有找到正确的问题,应继续提问。
示例 开发者说认证中间件一直返回 401,并给出堆栈跟踪。代理先问该中间件的契约是什么,开发者回答读取 Bearer token、校验 JWT 密钥并把用户加到请求对象上。代理接着要求展示 401 时 req.headers 的样子,开发者发现 headers 为空。代理追问是客户端没发请求头,还是请求头在到达应用前被剥离。开发者意识到 Nginx 会剥离 Authorization 头,除非配置 proxy_set_header。代理确认差距在于规格说中间件读取请求头,但 Nginx 吃掉了请求头,并让开发者用一句话总结根因,开发者给出“Nginx 在请求到达 Express 之前丢弃了 Authorization 头,需要在 Nginx 配置中加上 proxy_set_header Authorization $http_authorization”。代理确认这就是根因。
边界 不要在开发者自己陈述问题之前给出修复方案;不要调试本不需要调试的内容,先检查是否是规格问题;不要建议更换框架或工具,那属于 duck-design 的范畴。