Java 后端 / 系统课时

设计错误码与错误响应

设计错误码与错误响应

本课设计一套可长期维护的错误契约:HTTP 状态表达请求结果类别,业务错误码定位具体规则,traceId 串联客户端、网关与服务日志。完成后,客户端可以稳定分支处理,服务端也能快速追踪一次失败请求。

学习目标

  • 划分 HTTP 状态、业务错误码和错误文案的职责
  • 设计稳定、可扩展且不泄露内部细节的错误响应
  • 为每次请求生成并回传 traceId

错误响应需要解决什么

一个可用的错误响应至少回答四个问题:发生了哪类错误、客户端能否修正、应该展示什么文案、服务端如何定位日志。只返回 "error":"失败" 无法支持自动处理,只返回异常堆栈又会泄露实现细节。

推荐把错误协议拆成稳定字段:code 供程序判断,message 供用户或调用方理解,traceId 用于排查,path 与 timestamp 用于确认请求上下文。HTTP 状态仍然保留,用来表达协议层面的成功、参数错误、冲突或服务故障。

统一错误响应结构关系

设计稳定的业务错误码

错误码应表达业务语义,而不是 Java 类名或数据库错误。可以用“领域 + 原因”的形式,例如 USER_NOT_FOUND、USER_EMAIL_EXISTS、ORDER_STATUS_INVALID。代码一旦公开给客户端,就应尽量保持兼容。

以下为片段示例,用枚举集中管理默认 HTTP 状态和默认文案:

java
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。

java
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 读取。

java
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 中,由具体异常处理方法调用。

java
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。验证时应同时检查响应头和响应体中的追踪标识是否一致。

验证客户端可用性

发送一个不存在的用户查询,并主动传入追踪标识:

bash
curl -i http://localhost:<PORT>/users/<ID> -H "X-Trace-Id: demo-trace-001"

预期结果:

text
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 状态与业务码的映射应在接口文档中明确,并用集成测试锁定。

同一错误码不要在不同接口里表达不同含义。对外文案保持可理解,对内诊断通过日志字段完成;需要展示更多上下文时,也只返回经过筛选的安全信息。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

设计错误码与错误响应

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通