Spring 接口返回 errorMessage=null：如何排查二次异常覆盖原始业务错误

接口返回 errorMessage=null，可能是第二个异常遮蔽了真正原因

在数据建模、导入和校验接口中，最难受的一类错误不是"没有错误"，而是真正的业务错误已经产生，却被后续异常覆盖 。服务层明明知道输入不合法，前端最后却只看到 errorMessage=null，排障方向很容易被带到错误的地方。

本文复盘一条通用调用链：业务校验先返回失败原因并保存失败结果，Controller 随后读取一个可能不存在的辅助消息，空指针异常覆盖了原始错误。修复重点不是增加更多兜底文案，而是保护错误传播边界。

1. 先按时间线还原两条异常

现场事实可以还原为：

1. 业务校验发现非法数据，生成了明确的失败原因。
2. 服务层在事务内写入失败结果。
3. 完成接口调用 findAndDeleteMessage() 获取可选的辅助消息。
4. 没有对应消息时返回 null，旧代码继续执行 taskMessage.getFlag()。
5. 新的 NullPointerException 进入统一异常处理，响应中的 errorMessage 变成 null。

#mermaid-svg-Rtm9bWohIFBDKHc9{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-Rtm9bWohIFBDKHc9 .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-Rtm9bWohIFBDKHc9 .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-Rtm9bWohIFBDKHc9 .error-icon{fill:#552222;}#mermaid-svg-Rtm9bWohIFBDKHc9 .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-Rtm9bWohIFBDKHc9 .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-Rtm9bWohIFBDKHc9 .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-Rtm9bWohIFBDKHc9 .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-Rtm9bWohIFBDKHc9 .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-Rtm9bWohIFBDKHc9 .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-Rtm9bWohIFBDKHc9 .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-Rtm9bWohIFBDKHc9 .marker{fill:#333333;stroke:#333333;}#mermaid-svg-Rtm9bWohIFBDKHc9 .marker.cross{stroke:#333333;}#mermaid-svg-Rtm9bWohIFBDKHc9 svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-Rtm9bWohIFBDKHc9 p{margin:0;}#mermaid-svg-Rtm9bWohIFBDKHc9 .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-Rtm9bWohIFBDKHc9 .cluster-label text{fill:#333;}#mermaid-svg-Rtm9bWohIFBDKHc9 .cluster-label span{color:#333;}#mermaid-svg-Rtm9bWohIFBDKHc9 .cluster-label span p{background-color:transparent;}#mermaid-svg-Rtm9bWohIFBDKHc9 .label text,#mermaid-svg-Rtm9bWohIFBDKHc9 span{fill:#333;color:#333;}#mermaid-svg-Rtm9bWohIFBDKHc9 .node rect,#mermaid-svg-Rtm9bWohIFBDKHc9 .node circle,#mermaid-svg-Rtm9bWohIFBDKHc9 .node ellipse,#mermaid-svg-Rtm9bWohIFBDKHc9 .node polygon,#mermaid-svg-Rtm9bWohIFBDKHc9 .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-Rtm9bWohIFBDKHc9 .rough-node .label text,#mermaid-svg-Rtm9bWohIFBDKHc9 .node .label text,#mermaid-svg-Rtm9bWohIFBDKHc9 .image-shape .label,#mermaid-svg-Rtm9bWohIFBDKHc9 .icon-shape .label{text-anchor:middle;}#mermaid-svg-Rtm9bWohIFBDKHc9 .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-Rtm9bWohIFBDKHc9 .rough-node .label,#mermaid-svg-Rtm9bWohIFBDKHc9 .node .label,#mermaid-svg-Rtm9bWohIFBDKHc9 .image-shape .label,#mermaid-svg-Rtm9bWohIFBDKHc9 .icon-shape .label{text-align:center;}#mermaid-svg-Rtm9bWohIFBDKHc9 .node.clickable{cursor:pointer;}#mermaid-svg-Rtm9bWohIFBDKHc9 .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-Rtm9bWohIFBDKHc9 .arrowheadPath{fill:#333333;}#mermaid-svg-Rtm9bWohIFBDKHc9 .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-Rtm9bWohIFBDKHc9 .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-Rtm9bWohIFBDKHc9 .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-Rtm9bWohIFBDKHc9 .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-Rtm9bWohIFBDKHc9 .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-Rtm9bWohIFBDKHc9 .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-Rtm9bWohIFBDKHc9 .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-Rtm9bWohIFBDKHc9 .cluster text{fill:#333;}#mermaid-svg-Rtm9bWohIFBDKHc9 .cluster span{color:#333;}#mermaid-svg-Rtm9bWohIFBDKHc9 div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-Rtm9bWohIFBDKHc9 .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-Rtm9bWohIFBDKHc9 rect.text{fill:none;stroke-width:0;}#mermaid-svg-Rtm9bWohIFBDKHc9 .icon-shape,#mermaid-svg-Rtm9bWohIFBDKHc9 .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-Rtm9bWohIFBDKHc9 .icon-shape p,#mermaid-svg-Rtm9bWohIFBDKHc9 .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-Rtm9bWohIFBDKHc9 .icon-shape .label rect,#mermaid-svg-Rtm9bWohIFBDKHc9 .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-Rtm9bWohIFBDKHc9 .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-Rtm9bWohIFBDKHc9 .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-Rtm9bWohIFBDKHc9 :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 消息存在
消息缺失
业务校验
生成原始业务错误
事务内保存失败结果
完成接口读取可选辅助消息
拼装 HTTP 错误响应
旧代码解引用 null
二次异常覆盖原始错误
前端看到 errorMessage=null

最早的业务异常与最后的空指针不是同一个问题。前者解释"为什么任务失败"，后者解释"为什么用户看不到失败原因"。

2. 三个职责边界不要混在一起

边界	应负责什么	不应承担什么
服务层	执行业务校验并保存失败结果	假设辅助消息一定存在
数据库消息表	保存可选的提醒或附加信息	作为所有业务错误的唯一来源
Controller	把非空业务错误转换为 HTTP 响应	用第二个异常替换第一个错误

一个接口同时使用返回字符串和数据库消息并不一定错误，但两者必须被视为独立的可选载体。任何一个载体缺失，都不能改变原始业务失败的事实。

3. 为什么 null 会把真正错误冲掉

典型的旧代码类似这样：

package com.example.task;

public ResponseEntity<?> complete(String taskId) {
    // 服务层已经完成业务校验和失败结果落库
    String errorMessage = taskService.complete(taskId);
    TaskMessage taskMessage = messageService.findAndDeleteMessage(taskId);

    // 错误假设：每个失败任务都一定有 TaskMessage
    if (taskMessage.getFlag()) {
        errorMessage = taskMessage.getMessage();
    }
    return ResponseEntity.ok(new Result(errorMessage));
}

当 findAndDeleteMessage() 返回 null 时，Controller 的辅助逻辑抛出空指针。统一异常处理只能看到后发生的异常，于是原始 errorMessage 没有机会正常返回。

4. 最小修复应放在 Controller 边界

修复目标是两点：辅助消息按可选值处理；非空业务错误明确转换为 HTTP 失败响应。

package com.example.task;

public ResponseEntity<?> complete(String taskId) {
    // 服务层继续负责业务校验和失败结果落库
    String errorMessage = taskService.complete(taskId);
    TaskMessage taskMessage = messageService.findAndDeleteMessage(taskId);

    // 辅助消息缺失时保持原始业务错误，不制造第二个异常
    if (taskMessage != null && taskMessage.getFlag()) {
        errorMessage = taskMessage.getMessage();
    }
    if (errorMessage != null && !errorMessage.isBlank()) {
        return ResponseEntity.badRequest().body(new ErrorResult(errorMessage));
    }
    return ResponseEntity.ok(new SuccessResult());
}

这里没有新增异常层或消息工厂。修复只收敛在现有 Controller 的职责内：它负责传播结果，不重新解释业务规则。

5. 不要在事务内重新抛出导致失败记录回滚

如果服务层已经写入失败结果，Controller 为了"统一异常"再次抛出，可能让事务回滚，造成两个问题同时出现：前端拿不到原始错误，数据库也没有失败记录。

package com.example.task;

public String completeInTransaction(String taskId) {
    // 失败结果需要在当前事务内保留，便于后续查询和重试
    String errorMessage = validator.validate(taskId);
    if (errorMessage != null) {
        taskRepository.markFailed(taskId, errorMessage);
        return errorMessage;
    }
    taskRepository.markFinished(taskId);
    return null;
}

事务边界的判断应回答：失败记录是否需要持久化？如果需要，就应返回可传播的业务结果或使用不会触发回滚的错误通道，而不是无条件抛出运行时异常。

6. 回归测试要覆盖"辅助消息缺失"

仅测试"消息存在"无法保护这条故障链。至少应覆盖以下场景：

package com.example.task;

@Test
void shouldKeepBusinessErrorWhenOptionalMessageIsMissing() {
    // 模拟服务层已经得到业务错误，但辅助消息表没有记录
    when(taskService.complete("task-1")).thenReturn("输入字段类型不合法");
    when(messageService.findAndDeleteMessage("task-1")).thenReturn(null);

    ResponseEntity<?> response = controller.complete("task-1");

    // Controller 不应抛出 NullPointerException，也不应丢失原始文案
    assertThat(response.getStatusCodeValue()).isEqualTo(400);
    assertThat(response.getBody()).hasFieldOrPropertyWithValue(
            "errorMessage", "输入字段类型不合法");
}

验证时要分别记录：目标测试结果、构建结果、部署状态和真实接口响应。当前证据只支持"回归测试通过、Maven reactor 构建成功"，不支持"已经部署到所有节点"。

7. 排障时沿最早错误和最晚响应双向核对

推荐按以下顺序收集证据：

1. 在服务层日志中找到最早的业务校验失败原因。
2. 核对失败结果是否已经提交到数据库。
3. 记录 Controller 调用的辅助消息查询是否允许返回空值。
4. 查看完整 Caused by 链，确认是否出现第二个异常。
5. 对比 HTTP 状态、响应体和前端读取字段，确认错误在哪一层丢失。
6. 部署后逐节点核对实际加载的 JAR 或类版本，再重跑同一场景。

这条路径能避免把"前端显示为空"误判成"后端没有生成错误"，也能避免把数据库消息表当成业务错误的唯一来源。

8. 常见错误修复方式为什么不够

只在前端给空文案兜底

这只能改善显示，不能恢复原始错误，也无法保证失败结果已经落库。

给 TaskMessage 强行补一条记录

如果消息表只服务提醒功能，伪造记录会污染数据语义。业务错误应沿服务层到 HTTP 的主链路传播。

把所有异常改成 HTTP 200

这会让调用方更难区分业务失败和接口成功，反而扩大误判范围。非空业务错误应使用项目既有的失败响应契约。

只看最后一个异常

最后一个异常经常只是错误处理路径的副作用。要先确认最早业务错误，再单独描述后续清理或响应阶段异常。

9. 验证清单

1. 业务校验失败原因是否在服务层产生并保留？
2. 失败结果是否在预期事务边界内提交？
3. 所有辅助消息查询是否按可选值处理？
4. 非空业务错误是否映射到明确的 HTTP 失败响应？
5. 缺少辅助消息时是否仍能返回原始错误？
6. 回归测试是否覆盖消息存在、消息缺失和无业务错误三种场景？
7. 是否分别记录源码修复、构建、部署和真实接口验收？

结语

接口错误处理的重点不是让响应"看起来有内容"，而是让最早的业务事实不被后续辅助逻辑覆盖。服务层负责产生并保存业务结果，Controller 负责稳定传播；可选消息缺失时，应该少做一件事，而不是多抛一个异常。

周末可提供 Java/Spring 远程问题诊断，欢迎通过平台私信交流。