Java 后端 / 系统课时
设计错误码与错误响应
设计错误码与错误响应
本课设计一套可长期维护的错误契约:HTTP 状态表达请求结果类别,业务错误码定位具体规则,traceId 串联客户端、网关与服务日志。完成后,客户端可以稳定分支处理,服务端也能快速追踪一次失败请求。
学习目标
- 划分 HTTP 状态、业务错误码和错误文案的职责
- 设计稳定、可扩展且不泄露内部细节的错误响应
- 为每次请求生成并回传
traceId
错误响应需要解决什么
一个可用的错误响应至少回答四个问题:发生了哪类错误、客户端能否修正、应该展示什么文案、服务端如何定位日志。只返回 "error":"失败" 无法支持自动处理,只返回异常堆栈又会泄露实现细节。
推荐把错误协议拆成稳定字段:code 供程序判断,message 供用户或调用方理解,traceId 用于排查,path 与 timestamp 用于确认请求上下文。HTTP 状态仍然保留,用来表达协议层面的成功、参数错误、冲突或服务故障。

设计稳定的业务错误码
错误码应表达业务语义,而不是 Java 类名或数据库错误。可以用“领域 + 原因”的形式,例如 USER_NOT_FOUND、USER_EMAIL_EXISTS、ORDER_STATUS_INVALID。代码一旦公开给客户端,就应尽量保持兼容。
以下为片段示例,用枚举集中管理默认 HTTP 状态和默认文案:
package com.example.demo.error;
import org.springframework.http.HttpStatus;
public enum ErrorCode {
VALIDATION_FAILED(
HttpStatus.BAD_REQUEST,
"请求参数不合法"
),
USER_NOT_FOUND(
HttpStatus.NOT_FOUND,
"用户不存在"
),
USER_EMAIL_EXISTS(
HttpStatus.CONFLICT,
"邮箱已被占用"
),
INTERNAL_ERROR(
HttpStatus.INTERNAL_SERVER_ERROR,
"服务暂时不可用,请稍后重试"
);
private final HttpStatus status;
private final String message;
ErrorCode(HttpStatus status, String message) {
this.status = status;
this.message = message;
}
public HttpStatus status() {
return status;
}
public String message() {
return message;
}
}业务错误码不必与 HTTP 状态一一对应。多个具体业务错误可以共享 409,客户端再通过 code 决定是提示用户、更换输入还是刷新数据。
定义统一响应结构
响应字段应少而稳定。不要直接序列化 Throwable,也不要把堆栈、SQL、服务器路径或第三方密钥放入 message。
package com.example.demo.error;
import java.time.Instant;
public record ApiError(
String code,
String message,
String traceId,
String path,
Instant timestamp
) {
}message 可以因国际化或产品文案调整而变化,因此客户端不应依赖文案做逻辑判断。需要字段级校验信息时,可以在契约经过评审后增加结构化 details,不要临时拼接不可解析的长字符串。
生成并传递追踪标识
下面的过滤器优先复用客户端传入的 X-Trace-Id,没有时生成新的标识,并写入响应头与 MDC。后续日志会自动带上同一个追踪值,异常处理器也可以从 MDC 读取。
package com.example.demo.web;
import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.slf4j.MDC;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;
import java.io.IOException;
import java.util.UUID;
@Component
public class TraceIdFilter extends OncePerRequestFilter {
public static final String TRACE_ID = "traceId";
public static final String HEADER = "X-Trace-Id";
@Override
protected void doFilterInternal(
HttpServletRequest request,
HttpServletResponse response,
FilterChain filterChain)
throws ServletException, IOException {
String traceId = request.getHeader(HEADER);
if (traceId == null || traceId.isBlank()) {
traceId = UUID.randomUUID()
.toString()
.replace("-", "");
}
MDC.put(TRACE_ID, traceId);
response.setHeader(HEADER, traceId);
try {
filterChain.doFilter(request, response);
} finally {
// 线程复用前必须清理,避免请求之间串值
MDC.remove(TRACE_ID);
}
}
}异常处理器创建 ApiError 时,可通过 MDC.get(TraceIdFilter.TRACE_ID) 读取当前追踪标识。生产环境通常还会由网关统一透传该请求头。
组装错误响应
下面的方法把错误码定义转换为统一响应。它适合放在 @RestControllerAdvice 中,由具体异常处理方法调用。
package com.example.demo.error;
import jakarta.servlet.http.HttpServletRequest;
import org.slf4j.MDC;
import org.springframework.http.ResponseEntity;
import java.time.Instant;
import static com.example.demo.web.TraceIdFilter.TRACE_ID;
public final class ErrorResponses {
private ErrorResponses() {
}
public static ResponseEntity<ApiError> of(
ErrorCode errorCode,
HttpServletRequest request) {
ApiError body = new ApiError(
errorCode.name(),
errorCode.message(),
MDC.get(TRACE_ID),
request.getRequestURI(),
Instant.now()
);
return ResponseEntity
.status(errorCode.status())
.body(body);
}
}这是片段示例,依赖前面的 ErrorCode、ApiError 与 TraceIdFilter。验证时应同时检查响应头和响应体中的追踪标识是否一致。
验证客户端可用性
发送一个不存在的用户查询,并主动传入追踪标识:
curl -i http://localhost:<PORT>/users/<ID> -H "X-Trace-Id: demo-trace-001"预期结果:
HTTP/1.1 404
X-Trace-Id: demo-trace-001
Content-Type: application/json
{"code":"USER_NOT_FOUND","message":"用户不存在","traceId":"demo-trace-001","path":"/users/<ID>","timestamp":"<TIME>"}客户端应按 code 处理业务分支,向用户展示 message,报障时提交 traceId。实际端口、用户 ID 和时间会不同。
契约演进原则
错误码应新增而不是随意改名;删除旧错误码前,要确认所有客户端都已迁移。HTTP 状态与业务码的映射应在接口文档中明确,并用集成测试锁定。
同一错误码不要在不同接口里表达不同含义。对外文案保持可理解,对内诊断通过日志字段完成;需要展示更多上下文时,也只返回经过筛选的安全信息。