架构与系统设计 / 系统课时

统一响应与异常处理

统一响应与异常处理

本课将把控制器返回值、业务错误、参数错误和未知异常收敛到同一套响应协议,并补上 traceId 贯穿请求链路。完成后,前端可以稳定解析结果,后端也能按错误码和追踪号快速定位问题。

学习目标

  • 设计包含业务码、消息、数据和追踪号的统一响应结构
  • 区分业务异常、请求异常与系统异常的处理边界
  • 使用全局异常处理器返回正确的 HTTP 状态和错误码

统一响应契约

统一响应的核心不是“所有请求都返回 HTTP 200”,而是让响应体结构稳定,同时保留 HTTP 状态的语义。成功请求返回 2xx,参数错误返回 400,业务规则不满足可返回 422,未知系统异常返回 500。

建议固定四个字段:code 表示机器可判断的业务码,message 面向调用方说明结果,data 承载成功数据,traceId 用于关联网关、应用和日志。业务码必须稳定,不能直接使用可能随文案调整而变化的异常消息。

异常处理链路

请求进入应用后,控制器只负责参数接收与业务调用。可预期的业务失败抛出 BusinessException,框架级请求错误由专门处理器接管,未识别异常统一转换为系统错误,并记录完整堆栈。

统一响应与异常处理链路

下面给出一个可直接放入 Spring Boot 3 工程的完整示例。工程需已引入 spring-boot-starter-web。

java
package com.example.multitenant;

import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.math.BigDecimal;
import java.util.Map;
import java.util.UUID;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.slf4j.MDC;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Component;
import org.springframework.web.bind.MissingServletRequestParameterException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.filter.OncePerRequestFilter;

@SpringBootApplication
public class UnifiedResponseApplication {

    public static void main(String[] args) {
        SpringApplication.run(UnifiedResponseApplication.class, args);
    }
}

record ApiResult<T>(String code, String message, T data, String traceId) {

    static <T> ApiResult<T> success(T data) {
        return new ApiResult<>("OK", "success", data, MDC.get("traceId"));
    }

    static ApiResult<Void> failure(ErrorCode errorCode) {
        return new ApiResult<>(
                errorCode.code(),
                errorCode.message(),
                null,
                MDC.get("traceId")
        );
    }
}

enum ErrorCode {
    INVALID_AMOUNT("ORDER-001", "金额必须大于 0", HttpStatus.UNPROCESSABLE_ENTITY),
    MISSING_PARAMETER("REQ-001", "缺少必填参数", HttpStatus.BAD_REQUEST),
    INTERNAL_ERROR("SYS-500", "系统暂时不可用", HttpStatus.INTERNAL_SERVER_ERROR);

    private final String code;
    private final String message;
    private final HttpStatus httpStatus;

    ErrorCode(String code, String message, HttpStatus httpStatus) {
        this.code = code;
        this.message = message;
        this.httpStatus = httpStatus;
    }

    String code() {
        return code;
    }

    String message() {
        return message;
    }

    HttpStatus httpStatus() {
        return httpStatus;
    }
}

final class BusinessException extends RuntimeException {
    private final ErrorCode errorCode;

    BusinessException(ErrorCode errorCode) {
        super(errorCode.message());
        this.errorCode = errorCode;
    }

    ErrorCode errorCode() {
        return errorCode;
    }
}

@Component
class TraceIdFilter extends OncePerRequestFilter {
    private 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();
        }

        MDC.put("traceId", traceId);
        response.setHeader(HEADER, traceId);
        try {
            filterChain.doFilter(request, response);
        } finally {
            MDC.remove("traceId");
        }
    }
}

@RestController
class DemoController {

    @GetMapping("/demo/order")
    ApiResult<Map<String, Object>> createOrder(@RequestParam BigDecimal amount) {
        if (amount.signum() <= 0) {
            throw new BusinessException(ErrorCode.INVALID_AMOUNT);
        }
        return ApiResult.success(Map.of("accepted", true));
    }
}

@RestControllerAdvice
class GlobalExceptionHandler {
    private static final Logger log =
            LoggerFactory.getLogger(GlobalExceptionHandler.class);

    @ExceptionHandler(BusinessException.class)
    ResponseEntity<ApiResult<Void>> handleBusiness(BusinessException exception) {
        ErrorCode errorCode = exception.errorCode();
        return ResponseEntity.status(errorCode.httpStatus())
                .body(ApiResult.failure(errorCode));
    }

    @ExceptionHandler(MissingServletRequestParameterException.class)
    ResponseEntity<ApiResult<Void>> handleMissingParameter(
            MissingServletRequestParameterException exception
    ) {
        return ResponseEntity.badRequest()
                .body(ApiResult.failure(ErrorCode.MISSING_PARAMETER));
    }

    @ExceptionHandler(Exception.class)
    ResponseEntity<ApiResult<Void>> handleUnknown(Exception exception) {
        log.error("Unhandled exception, traceId={}", MDC.get("traceId"), exception);
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                .body(ApiResult.failure(ErrorCode.INTERNAL_ERROR));
    }
}

TraceIdFilter 在请求开始时生成或沿用 X-Trace-Id,并放入 MDC。全局异常处理器只对外返回安全信息,未知异常的真实堆栈仅写入服务端日志,避免把数据库、路径或密钥细节泄露给调用方。

运行与验证

应用启动后,分别请求正常金额和非法金额。示例中的 <PORT>、<ID> 需要替换或以实际响应为准。

bash
curl -i "http://localhost:<PORT>/demo/order?amount=88.50"
curl -i "http://localhost:<PORT>/demo/order?amount=0"

预期结果

text
HTTP/1.1 200
X-Trace-Id: <ID>

{"code":"OK","message":"success","data":{"accepted":true},"traceId":"<ID>"}

HTTP/1.1 422
X-Trace-Id: <ID>

{"code":"ORDER-001","message":"金额必须大于 0","data":null,"traceId":"<ID>"}

缺少 amount 时应返回 HTTP 400 和 REQ-001。如果代码抛出未处理异常,应返回 HTTP 500 和 SYS-500,同时日志中保留同一个 traceId 及完整堆栈。

关键边界与常见错误

错误码一旦对外发布就应保持兼容,文案可以优化,但业务码不能随意改名。多租户系统还应避免在错误消息中暴露租户名称、数据库标识或内部资源路径。

不要在控制器中到处编写 try-catch 并手动拼装响应,这会让异常规则分散。也不要把所有异常都转换成成功状态,否则网关监控、重试策略和客户端缓存都会失去可靠依据。

本课总结

  • 统一响应负责稳定数据结构,HTTP 状态负责表达请求处理结果
  • 可预期业务失败、请求错误和未知异常应由不同分支处理
  • traceId 必须同时出现在响应头、响应体和服务端日志中

下一课预告

下一课将继续搭建工程基础设施,学习如何组织公共配置、环境配置、租户配置与敏感配置,并明确它们的覆盖顺序和隔离边界。

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

目录与阅读设置

阅读设置

17

记录一个想法

统一响应与异常处理

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

登录哪都通