Java API 调试

概述

使用本技能分析来自日志、代码片段、堆栈跟踪及失败请求描述中的 Java 接口错误。该技能针对遵循典型 controller -> service -> mapper 流程的后端项目进行了优化，可快速完成故障隔离，并提供明确的下一步修复方案。

快速开始

当本技能被触发时，请执行以下步骤：

1. 首先收集故障证据：错误日志、堆栈跟踪、请求路径、请求参数以及预期行为。
2. 在提出修复建议前，先定位故障所在层级：controller、service、mapper、SQL、依赖注入配置或环境/配置问题。
3. 输出诊断结论，结构为：现象 -> 可能原因 -> 验证步骤 -> 推荐修复。
4. 确保响应内容具备实操性，优先指定具体文件或类（如 OrderController），而非泛泛而谈的理论说明。

如需更详细的启发式排查逻辑，请参阅 references/troubleshooting.md。

工作流程

1. 标准化输入

提取并重述关键事实：

• 请求路径或接口名称
• HTTP 方法
• 异常类型
• 首个业务相关堆栈帧
• 受影响模块、类或包
• 该问题是否可稳定复现，还是偶发性问题

若用户仅提供模糊症状（例如“API 返回 500”），请主动索要或基于日志、Controller 映射定义及近期变更推断缺失的最小上下文。

2. 判定故障层级

按如下决策路径分类：

• 若问题表现为路由错误、参数绑定失败、校验异常、序列化问题、注解缺失或响应封装异常，则归类为 controller
• 若问题表现为业务逻辑分支错误、空值处理不当、事务边界不清、远程调用失败、DTO/VO 转换异常，则归类为 service
• 若问题表现为 SQL 执行失败、MyBatis 参数映射错误、结果集映射异常、表/字段不匹配、动态 SQL 生成异常，则归类为 mapper
• 若问题表现为数据源、Redis、Nacos、端口、Bean 扫描或 profile/环境加载等配置问题，则归类为 configuration

当多个层级均涉及问题时，应首先识别最初出错的层级，再单独说明其引发的下游影响。

3. 分层检查

Controller 检查项

需审查以下内容：

• @RequestMapping、@GetMapping、@PostMapping 等路径定义是否正确
• 请求对象注解，如 @RequestBody、@RequestParam、@PathVariable
• 校验注解（如 @Valid）及全局异常处理器
• 响应转换问题，如枚举、日期、JSON 序列化异常

常见信号：

• 405、404、HttpMessageNotReadableException
• 必填参数缺失
• 请求体解析失败
• 枚举类型转换失败

Service 检查项

需审查以下内容：

• 入参是否为空、服务返回值是否未经判空处理
• 业务分支条件与状态流转逻辑
• 事务边界设置与回滚预期
• 远程依赖调用、缓存读取或权限校验逻辑

常见信号：

• NullPointerException
• 业务断言失败（如 Assert.notNull() 抛出异常）
• 部分字段更新未生效
• 数据已写入但未提交

Mapper 检查项

需审查以下内容：

• Mapper XML 文件或注解形式的 SQL 语句
• 参数命名及 @Param 注解使用是否正确
• 结果映射（resultMap）与字段别名（alias）配置
• 动态 SQL 条件判断及空集合处理逻辑
• 数据库中表/字段是否存在，以及兼容性（如大小写敏感、关键字冲突）

常见信号：

• BindingException
• BadSqlGrammarException
• TooManyResultsException
• 返回行数与预期不符

4. 输出诊断结论

采用如下固定格式输出：

现象:
初步判断:
定位依据:
优先检查:
建议修复:
风险与回归点:

诊断结论须简洁、可操作。若存在不确定性，应列出最可能的 2–3 个原因并排序，避免强行断言唯一根因。

输出规范

• 优先指定具体类或文件目标，例如 OrderController、UserServiceImpl 或 OrderMapper.xml。
• 引用首个有意义的堆栈帧，而非完整堆栈跟踪。
• 区分根本原因与后续衍生现象。
• 提出修复建议时，至少包含一项可执行的验证步骤。
• 若问题很可能源于 SQL 或 MyBatis，请明确指出需检查的具体输入、映射配置或查询结构。

示例请求

• “请使用 $java-api-debug 分析我 Spring Boot 订单接口产生的这个 500 错误。”
• “请使用 $java-api-debug 定位该异常源自 controller、service 还是 mapper。”
• “请使用 $java-api-debug 解析此堆栈跟踪，给出最可能的根因及修复步骤。”

参考资料

• 如需针对常见 Java API 错误模式的深度排查清单，请查阅 references/troubleshooting.md。