debug-issuelisted

# 调试问题 > 系统性调试：收集 → 复现 → 定位 → 修复 → 验证。**禁止凭直觉猜测**。 ## 执行步骤 ### 第 1 步：收集信息（MUST 完整） 收集以下信息： - **错误信息**：完整的错误消息、堆栈 - **复现步骤**：如何重现问题 - **环境信息**：哪个环境（本地 / 测试 / 生产）、什么版本 - **最近变更**：最近改了什么代码 / 配置 / 依赖 - **影响范围**：影响哪些用户 / 功能 ```bash # 收集日志 tail -100 logs/application.log # 收集最近的 git 变更 git log --oneline -10 git diff HEAD~1 ``` ### 第 2 步：复现问题 在本地 / 测试环境尝试复现： - 能复现 → 继续第 3 步 - 不能复现 → 回到第 1 步收集更多信息（可能是环境差异） ### 第 3 步���定位根因 按层次排查： ``` 1. 输入层：请求参数是否正确？ 2. 业务层：业务逻辑是否有 bug？ 3. 数据层：SQL 是否正确？数据是否异常？ 4. 外部依赖：下游服务是否正常？ 5. 配置层：配置是否正确？ 6. 环境层：JDK / 框架版本是否兼容？ ``` **工具**： - 日志：`grep` 关键错误 - 调试：打断点（如本地） - 测试：写单元测试复现 - 监控：看指标异常 ### 第 4 步：分析根因 **禁止**： - 只看表面错误就修 - 没复现就修 - 凭印象修 **必须**： - 找到真正的根因（不是表象） - 理解为什么会出现这个问题 - 评估影响范围 ### 第 5 步：制定修复方案 **MUST 与用户确认**： - 修复方式是否合适 - 是否需要数据修复 - 是否需要变更提案（大改动） 小改动（typo / 配置）→ 直接修复 大改动（逻辑变更）→ 走 `requirement-analysis` 创建变更提案 ### 第 6 步：修复 + 测试 1. 写单元测试复现问题 2. 修复代码 3. 验证测试通过 4. 验证原问题场景已修复 ### 第 7 步：验证 - 本地验证 - 测试环境验证 - （生产问题）生产环境验证 + 监控 ### 第 8 步：总结 - 根因是什么 - 为什么没在测试阶段发现 - 如何避免类似问题（如需要，写入 `retrospective.md`） ## 常见问题模式 ### NPE / 空指针 - 检查参数校验（`@NotNull` / `@Valid`） - 检查 Optional 使用 - 检查数据库返回 null 字段 ### SQL 问题 - 打印实际执行的 SQL（`show-sql: true`） - 检查索引是否生效（`EXPLAIN`） - 检查 N+1 查询 ### 并发问题 - 检查共享可变状态 - 检查事务边界 - 检查锁使用 ### 性能问题 - 看监控（QPS / 延迟 / 内存） - 看慢查询日志 - 看 GC 日志 ## 产出物 - 问题根因分析 - 修复代码 + 测试 - 验证报告 - （可选）变更提案 + 复盘文档 ## 关联 - Wiki：`wiki/_common/error-handling.md` `wiki/_common/logging.md` - 后续：大改动 → `requirement-analysis`；小修复 → `coding` → `ci-gat