Codex 用日志辅助 Debug 详解与操作指南

1. 文档目标

这份文档专门解决下面几个问题：

• 怎么把日志正确交给 Codex
• 什么样的日志最有价值
• Codex 能从日志里帮你做什么
• 怎样从日志一路追到代码、SQL、配置和根因
• 怎样让日志分析结果最终落到修复和回归验证

读完后，你应该能够：

• 用更高质量的方式把日志交给 Codex
• 让 Codex 更快判断问题是参数、逻辑、SQL 还是环境导致
• 让 Codex 帮你输出更靠谱的根因分析和修复路径
• 在 Java / Spring Boot、接口联调、分页查询、事务问题等场景中稳定使用这套方法

2. 为什么日志对 Codex Debug 特别重要

日志本质上是系统运行时留下的"现场证据"。

相比只给一段代码，日志更能告诉 Codex：

• 问题在哪一步发生
• 哪个类、方法、SQL、线程、请求出了问题
• 问题是偶发、稳定复现还是环境相关
• 系统已经执行到了哪个阶段

一句话理解：

日志不是附属信息，很多时候它本身就是 Debug 的主线索。

3. Codex 能从日志里帮你做什么

3.1 判断问题大类

例如判断更像是：

• 参数问题
• Java 逻辑问题
• SQL 条件问题
• 事务问题
• 配置或环境问题
• 权限或调用顺序问题

3.2 帮你定位关键代码范围

日志通常能暴露：

• 类名
• 方法名
• 行号
• 调用链
• SQL 片段

这些信息可以帮助 Codex 迅速缩小范围。

3.3 帮你梳理问题发生路径

如果你给了：

• 复现步骤
• 请求参数
• 返回结果
• 日志堆栈

Codex 很擅长把这些串成一条问题链路。

3.4 帮你给出修复优先级

它可以帮你判断：

• 先查参数还是先查 SQL
• 先看事务还是先看异常处理
• 先看 Controller 还是先看 Service / Mapper

3.5 帮你补验证和回归清单

日志分析不是终点，Codex 还可以继续帮你输出：

• 修复后怎么验证
• 哪些类似场景要回归
• 哪些日志点值得补充

4. 哪些日志最有价值

不是所有日志都一样有用。

下面这些信息最值得优先给 Codex。

4.1 完整异常堆栈

最好不要只截一两行报错，而是给尽量完整的堆栈。

4.2 请求参数和返回结果

尤其是接口问题、联调问题、分页筛选问题。

4.3 SQL 日志

对于查询错误、空数据、分页异常、动态条件问题特别重要。

4.4 关键业务日志

例如：

• 进入方法
• 关键分支判断
• 外部调用结果
• 异常捕获点

4.5 复现步骤

日志单独看不一定完整，和复现步骤结合才更有价值。

5. 日志不够时最常见的问题

如果日志信息不完整，Codex 很容易出现这些情况：

• 只能给泛化猜测
• 不能稳定判断根因
• 无法区分是参数问题还是代码问题
• 无法确认问题发生在哪一层

所以：

给日志时，不只是贴报错，而是尽量给出"报错 + 请求 + 场景 + 代码位置"。

6. 推荐的日志 Debug 输入结构

问题目标
复现步骤
请求参数 / 输入数据
返回结果 / 现象
完整日志 / 堆栈 / SQL
相关代码位置
约束与输出要求

7. 最推荐的日志 Debug 输入模板

请帮我定位一个问题。

目标：
[要解决什么问题]

复现步骤：
1. ...
2. ...
3. ...

请求参数 / 输入数据：
[关键参数]

当前现象：
[报错、空数据、行为异常]

返回结果：
[接口返回或页面表现]

日志 / 堆栈 / SQL：
[完整日志]

相关文件：
[Controller / Service / Mapper / XML / 配置]

约束：
[不能改什么 / 先不要直接修改 / 不做无关重构]

输出要求：
1. 先判断根因
2. 再给排查优先级
3. 最后给最小修复建议和验证步骤

8. 标准操作流程

1. 收集复现步骤与日志
2. 提供请求参数和返回结果
3. 提供相关代码位置
4. 让 Codex 判断根因方向
5. 如有需要补充日志或链路信息
6. 再让 Codex 给修复建议
7. 最后补验证与回归清单

9. 第一步：先说清楚"这是个什么问题"

不要一上来就只贴日志。

先说清楚：

• 问题发生在哪个功能
• 预期是什么
• 当前错成了什么样

示例

目标：修复订单分页接口手机号筛选失效问题。
预期：带手机号时能筛出正确数据。
现象：带手机号时返回空数据，不带手机号时正常。

10. 第二步：把复现步骤和日志绑在一起给

只给日志，不给触发路径，Codex 有时难以判断问题上下文。

推荐一起提供：

• 用户做了什么操作
• 第几步出现问题
• 请求发向哪个接口
• 接口返回了什么

示例提示词

复现步骤：
1. 打开订单列表
2. 输入手机号筛选条件
3. 点击查询
4. 返回空列表

请结合下面日志一起分析。

11. 第三步：尽量给完整堆栈和关键 SQL

很多定位失败，不是因为 Codex 不会，而是只给了半截日志。

推荐做法

• 异常堆栈尽量完整
• SQL 日志尽量带条件参数
• 不要只截最上面一行报错

原因

因为真正的线索可能藏在：

• 嵌套异常
• SQL 绑定参数
• 调用链深处

12. 第四步：让 Codex 先判断问题方向，不急着让它改

对于复杂问题，更稳的做法是先让它判断：

• 更可能是哪一层出问题
• 排查顺序是什么
• 还缺哪些信息

示例提示词

先不要改代码，先基于日志和现象判断问题方向。

请输出：
1. 更可能是参数、Java 逻辑、SQL 条件、事务还是环境问题
2. 最值得优先检查的 3 个位置
3. 如果仍然不够判断，还缺哪些日志或代码上下文

13. 第五步：如果信息不够，让 Codex 明确列出还缺什么

这是非常实用的一步。

可以直接问：

如果你还不能稳定判断根因，请明确列出你还需要哪些额外日志、参数或代码位置。

这样你补的就不是"更多信息"，而是"更有针对性的关键信息"。

14. 第六步：让日志分析结果继续落到修复和回归

日志分析不能停留在"猜测根因"，还要继续推进：

• 最小修复建议
• 验证步骤
• 回归清单

示例提示词

请基于你刚才的日志分析结果，继续输出：
1. 最小修复建议
2. 验证步骤
3. 回归测试建议

15. Java / Spring Boot 项目实战实例

场景

订单分页接口在带手机号筛选时返回空数据。

低质量输入示例

订单接口有问题，帮我看下日志。

问题在于：

• 没有目标
• 没有现象说明
• 没有复现步骤
• 没有相关代码位置

高质量输入示例

请帮我定位一个 bug。

目标：
修复订单分页接口手机号筛选失效问题。

复现步骤：
1. 打开订单列表页
2. 输入手机号
3. 点击查询
4. 返回空列表

请求参数：
phone=13800000000
pageNo=1
pageSize=10

当前现象：
带手机号时返回空数据，不带手机号时正常。

日志 / SQL：
[这里贴完整异常堆栈和 SQL 日志]

相关文件：
1. OrderController
2. OrderServiceImpl
3. OrderMapper
4. OrderMapper.xml

约束：
1. 不修改接口路径
2. 不改变入参结构
3. 不做无关重构

输出要求：
1. 先判断更可能是参数、Java 逻辑还是 SQL 条件问题
2. 再给最小修复建议
3. 最后给验证与回归步骤

为什么这个输入更有效

因为它把日志真正放进了问题上下文，而不是孤立地扔一段报错。

16. 事务问题实战实例

场景

订单提交时偶发"库存扣减成功，但订单保存失败"。

推荐日志分析思路

先给：

• 复现步骤
• 关键业务日志
• 异常堆栈
• 事务相关代码位置

示例提示词

请帮我基于日志分析一个事务问题。

现象：
订单提交后，库存被扣减，但订单主表没有成功落库。

复现步骤：
1. 用户提交订单
2. 系统执行库存扣减
3. 订单保存失败

日志：
[贴事务相关异常日志]

相关代码：
1. OrderServiceImpl.submitOrder
2. 库存扣减方法
3. 订单保存方法

输出要求：
1. 判断更像是事务边界问题、异常吞掉问题还是调用顺序问题
2. 给排查优先级
3. 给修复建议和回归验证点

17. 联调问题实战实例

场景

前后端联调时，前端收到 500，但本地单测看起来正常。

推荐输入方式

一起给：

• 前端操作步骤
• 请求体
• 后端日志
• 返回体
• 接口定义

示例提示词

请帮我分析一个联调问题。

现象：
前端调用新增接口返回 500。

请求体：
[请求 JSON]

返回体：
[错误返回]

日志：
[后端异常日志]

相关接口：
[Controller / ReqVO / Service]

请输出：
1. 更可能是前端参数问题、后端校验问题还是业务逻辑问题
2. 最值得优先检查的字段或方法
3. 最小修复建议

18. Codex 还能帮你做哪些日志增强工作

除了分析已有日志，Codex 还可以帮你：

• 识别当前日志是否不足
• 建议在哪些关键位置补日志
• 帮你设计更可追踪的日志结构
• 提醒哪些日志不应打印敏感信息

示例提示词

请基于这个问题和当前日志，判断日志是否足够定位问题。
如果不够，请告诉我：
1. 哪些位置应该补日志
2. 每条日志要记录什么信息
3. 哪些信息不能打印

19. 常见误区

19.1 误区一：只给一行报错

问题：

• 线索不够，容易误判

19.2 误区二：只给日志，不给复现步骤

问题：

• Codex 不知道问题发生在哪个业务动作里

19.3 误区三：只给日志，不给代码位置

问题：

• 很难从现象快速落到实现

19.4 误区四：日志很多，但没有筛出关键段

问题：

• 信息噪声太大，影响判断

19.5 误区五：一上来就让它直接修

问题：

• 在复杂问题上容易跳过关键分析阶段

20. 注意事项

• 优先给完整堆栈，而不是半截报错
• 日志最好和复现步骤一起给
• SQL 问题优先补 SQL 日志和参数
• 高风险问题先让 Codex 判断方向，再考虑修改
• 信息不够时，主动让 Codex 列出缺失项
• 日志里注意脱敏，不要直接贴敏感数据

21. 高质量提示词模板

21.1 通用日志 Debug 模板

请帮我定位一个问题。

目标：

复现步骤：

请求参数 / 输入数据：

当前现象：

返回结果：

日志 / 堆栈 / SQL：

相关文件：

约束：

输出要求：
1. 先判断根因方向
2. 再给排查优先级
3. 最后给修复与验证建议

21.2 事务问题模板

请帮我基于日志分析一个事务问题。

现象：

复现步骤：

日志：

相关代码：

输出要求：
1. 判断更像哪类事务问题
2. 给排查顺序
3. 给修复和回归建议

21.3 联调问题模板

请帮我分析一个联调问题。

现象：

请求体：

返回体：

日志：

相关接口：

输出要求：
1. 判断问题更可能在哪一层
2. 给最值得优先检查的字段或方法
3. 给最小修复建议

22. 团队落地建议

如果你想把这套方法推广到团队里，建议这样做：

1. 统一一份"日志 Debug 输入模板"
2. 在团队规范里要求高风险问题优先提供完整日志
3. 沉淀几个高频问题的日志分析示例
4. 把"日志不够先补日志和上下文"写进 AI 协作规范
5. 让开发和测试都复用同一套日志分析输入结构

23. 一句话总结

Codex 用日志帮忙 Debug 的关键，不是把报错扔给它，而是把"复现步骤、请求参数、返回结果、完整日志、相关代码和约束"一起组织成一套可判断的上下文。

24. 快速上手清单

• 先说清问题目标
• 再给复现步骤
• 再给请求参数和返回结果
• 再给完整日志、堆栈和 SQL
• 再给相关代码位置
• 先让 Codex 判断方向，再让它给修复建议