架构与系统设计 / 系统课时
统一响应与异常处理
统一响应与异常处理
本课将把控制器返回值、业务错误、参数错误和未知异常收敛到同一套响应协议,并补上 traceId 贯穿请求链路。完成后,前端可以稳定解析结果,后端也能按错误码和追踪号快速定位问题。
学习目标
- 设计包含业务码、消息、数据和追踪号的统一响应结构
- 区分业务异常、请求异常与系统异常的处理边界
- 使用全局异常处理器返回正确的 HTTP 状态和错误码
统一响应契约
统一响应的核心不是“所有请求都返回 HTTP 200”,而是让响应体结构稳定,同时保留 HTTP 状态的语义。成功请求返回 2xx,参数错误返回 400,业务规则不满足可返回 422,未知系统异常返回 500。
建议固定四个字段:code 表示机器可判断的业务码,message 面向调用方说明结果,data 承载成功数据,traceId 用于关联网关、应用和日志。业务码必须稳定,不能直接使用可能随文案调整而变化的异常消息。
异常处理链路
请求进入应用后,控制器只负责参数接收与业务调用。可预期的业务失败抛出 BusinessException,框架级请求错误由专门处理器接管,未识别异常统一转换为系统错误,并记录完整堆栈。

下面给出一个可直接放入 Spring Boot 3 工程的完整示例。工程需已引入 spring-boot-starter-web。
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> 需要替换或以实际响应为准。
curl -i "http://localhost:<PORT>/demo/order?amount=88.50"
curl -i "http://localhost:<PORT>/demo/order?amount=0"预期结果
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必须同时出现在响应头、响应体和服务端日志中
下一课预告
下一课将继续搭建工程基础设施,学习如何组织公共配置、环境配置、租户配置与敏感配置,并明确它们的覆盖顺序和隔离边界。