线上接口偶发 500，别急着改代码：使用华为云 CodeArts Agent 进行 Spring Boot 日志根因分析

一、前言

线上问题最棘手的地方，往往不是报错本身，而是问题出现得不稳定：同一个接口有时正常、有时返回
500；日志分散在
Controller、Service、数据库访问层和下游服务中；本地又很难复现。

排查时不应看到异常就立即修改代码，而应先把证据串起来，确认问题发生在哪个环节，再验证根因。华为云
CodeArts Agent
可以结合项目代码上下文辅助分析调用链、理解异常堆栈，并协助制定排查与修复方案。

需要说明：CodeArts Agent
不会自动获得生产环境日志。使用时应通过授权的日志平台、已配置的工具，或手动提供脱敏后的日志和相关代码来补充上下文。

二、为什么线上异常难定位？

假设订单详情接口偶发返回 500，日志中只有：

java.lang.NullPointerException
    at com.example.order.OrderService.calculateDiscount(OrderService.java:87)
    at com.example.order.OrderService.getDetail(OrderService.java:52)
    at com.example.order.OrderController.detail(OrderController.java:39)

堆栈指出异常发生的位置，却没有说明哪个请求触发了异常、当时订单数据是什么状态、为什么只有部分请求失败，以及最近一次发布是否修改了相关逻辑。

三、先建立可关联的日志

1. 为每次请求设置 traceId

Spring Boot 项目可以使用 MDC 将请求标识写入日志。以下是简化示例：

@Component
public class TraceIdFilter extends OncePerRequestFilter {
    @Override
    protected void doFilterInternal(
            HttpServletRequest request,
            HttpServletResponse response,
            FilterChain filterChain)
            throws ServletException, IOException {
        String traceId = UUID.randomUUID().toString().replace("-", "");
        MDC.put("traceId", traceId);
        response.setHeader("X-Trace-Id", traceId);
        try {
            filterChain.doFilter(request, response);
        } finally {
            // 线程池会复用线程，必须清理 MDC。
            MDC.remove("traceId");
        }
    }
}

示例采用服务端生成 ID，避免直接信任外部传入的任意标识。若系统已接入
OpenTelemetry 或分布式链路追踪，应优先沿用现有 trace
context；如果需要从网关传递请求 ID，应明确可信边界并校验格式。

以 Logback 为例，可以在日志格式中加入 %X{traceId}：

<pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level [traceId=%X{traceId}] %logger{36} - %msg%n</pattern>

同一请求的多条日志就可以通过 traceId
关联。跨服务调用还需要通过受控的链路上下文传播机制传递追踪信息。

2. 记录有用信息，而不是所有信息

建议记录请求标识、接口路径、耗时、结果状态、非敏感业务标识、依赖服务超时情况及必要的异常堆栈。不要将密码、访问令牌、完整身份证号、银行卡号或未经脱敏的个人信息写入日志，也不要无差别记录整个请求体。

四、让 CodeArts Agent 梳理异常证据

准备好日志后，可以在 CodeArts Agent
中补充异常堆栈、相关日志片段和涉及的代码文件。官方文档说明，智能体上下文可以引入指定文件、文件夹、Git
记录和终端输出；代码库索引也可以帮助检索项目中的调用与依赖关系。

可复用以下提示词：

你是一名严谨的 Java 线上故障分析工程师。

请分析我提供的 Spring Boot 异常日志和相关代码。
1. 列出日志中能够直接确认的事实。
2. 区分已确认事实、合理推断和待验证假设。
3. 根据堆栈梳理调用链，指出还需查看的类、方法和数据来源。
4. 给出最可能的根因及替代假设，并说明判断依据。
5. 提出低风险的验证步骤，优先使用日志、测试或只读查询。
6. 未经我确认，不要修改文件、执行数据库写操作或运行有副作用的命令。
7. 不要编造日志中没有出现的字段、执行结果或测试结论。
8. 如果上下文不足，请明确说明缺少哪些信息。

请按“现有证据、可能根因、验证方法、修复建议、回归测试”输出。

重点不是让 AI
立刻猜出答案，而是要求它把证据和假设分开，并给出可以验证的下一步操作。

五、从异常堆栈追到业务根因

例如，补充后的日志可能是：

2026-10-20 14:22:31.103 ERROR [traceId=8e4a7d12]
OrderService - calculate discount failed, orderId=ORD-1024

java.lang.NullPointerException
    at com.example.order.OrderService.calculateDiscount(OrderService.java:87)

假设第 87 行是：

BigDecimal discount = coupon.getDiscountAmount();

目前只能确认该执行路径中对 coupon
的状态存在假设；具体原因仍需结合完整代码确认。下一步应检查：

• coupon 来自数据库、Redis 还是远程服务？
• 查询无结果时，调用方是否正确处理空值？
• 优惠券是否过期、已使用或被并发更新？
• 最近的代码变更是否调整了查询条件或返回结构？
• 是否只有某些订单类型会进入这条分支？

可以继续向 Agent 提问：

请沿着 OrderController.detail ->
OrderService.getDetail ->
OrderService.calculateDiscount 的调用链分析。

重点检查 coupon 的赋值位置、返回值约束和空值处理。
先给出代码证据和验证方案，不要直接修改代码。
如果当前上下文不足，请指出还需要哪些文件。

如果 Agent 没有看到 coupon
的实际来源，就不应该让它凭空断定问题一定来自
Redis、数据库或远程接口。此时应补充相应
Mapper、Repository、缓存封装或客户端代码。

六、修复后如何验证？

假设最终确认某种订单类型没有关联优惠券，但代码错误地假设优惠券一定存在。修复方式应由业务规则决定，而不是简单地对所有空值返回默认优惠。

可以让 CodeArts Agent 辅助设计以下测试：

场景 需要验证的结果

正常订单且优惠券有效 按业务规则计算优惠金额
订单没有优惠券 按既定无优惠规则处理
优惠券查询失败 按业务要求返回可识别错误或执行降级
优惠券已失效 不应用失效优惠
下游服务超时 超时策略、日志和错误响应符合约定
相同请求重复执行 不产生非预期的重复业务操作

单元测试可以验证分支和异常处理；集成测试可以验证数据库、缓存和下游依赖的交互。若问题与并发或时间窗口有关，还应设计针对性的并发测试或在测试环境中复现。

不要只看覆盖率数字。每个测试都应验证明确的业务结果，而不是仅仅执行到某一行代码。

七、把排障流程沉淀为项目级 Agent

如果团队经常遇到相似的线上故障，可以创建项目级自定义智能体，将统一的排障规范写入提示词：

• 先收集证据，再提出根因；
• 明确区分事实、推断和假设；
• 优先给出只读验证步骤；
• 未经授权不得修改生产数据；
• 修复建议必须附带回归测试；
• 输出中标明尚未验证的结论。

CodeArts Agent
支持通过提示词、技能和工具集配置自定义智能体。将团队排障习惯沉淀为可复用规则，可以减少每次重复描述要求的成本。但智能体规范不能替代访问控制；生产日志、终端命令、数据库和外部工具仍应遵循团队的授权与审计要求。

八、总结

线上故障排查最重要的不是尽快猜中原因，而是建立一条能够复核的证据链。

通过请求标识关联日志、根据堆栈梳理调用链，再让 CodeArts Agent
辅助分析代码和设计验证方案，开发者可以更系统地定位问题，减少无效试错。

建议遵循这条路径：

收集日志 → 关联请求 → 定位调用链 → 提出假设 → 验证根因 → 小范围修复 →
回归测试。