架构与系统设计 / 系统课时
统一响应与异常
统一响应与异常
本课解决接口返回格式不一致、业务错误难追踪和异常直接暴露给客户端的问题。完成后,你将得到统一响应模型、可维护的错误码体系,以及把各类异常稳定转换为 HTTP 响应的全局处理机制。
学习目标
- 定义同时适用于成功与失败场景的统一响应模型
- 建立可扩展、可定位且不泄露内部细节的错误码体系
- 使用业务异常和全局异常处理器统一接口行为
统一响应需要解决什么
支付平台通常同时包含商户接口、运营接口和内部服务接口。若每个控制器自行拼装返回值,客户端就必须适配多种字段名称,日志也难以通过同一标识关联请求与错误。
统一响应应至少包含 code、message、data 和 traceId。其中 code 面向程序判断,message 面向调用方阅读,data 承载成功结果,traceId 用于把客户端报错与服务端日志连接起来。

统一响应不等于所有请求都返回 HTTP 200。参数错误可返回 400,未认证返回 401,无权限返回 403,资源不存在返回 404,未知服务端错误返回 500;业务码则进一步说明具体原因。
定义响应模型和错误码
下面是项目代码片段,需按注释中的文件名分别保存到 Spring Boot 工程。示例依赖 Spring Web、Validation 和 SLF4J,traceId 从 MDC 中读取。
// Result.java
package com.example.pay.common;
import org.slf4j.MDC;
import java.util.UUID;
public record Result<T>(String code, String message, T data, String traceId) {
public static <T> Result<T> success(T data) {
return new Result<>("0", "success", data, currentTraceId());
}
public static <T> Result<T> failure(ErrorCode errorCode) {
return new Result<>(
errorCode.code(),
errorCode.message(),
null,
currentTraceId()
);
}
private static String currentTraceId() {
String traceId = MDC.get("traceId");
// 尚未接入请求过滤器时仍返回可用于报障的标识。
return traceId != null
? traceId
: UUID.randomUUID().toString().replace("-", "");
}
}
// ErrorCode.java
package com.example.pay.common;
public interface ErrorCode {
String code();
String message();
}
// CommonErrorCode.java
package com.example.pay.common;
public enum CommonErrorCode implements ErrorCode {
INVALID_ARGUMENT("COMMON_400", "请求参数不合法"),
RESOURCE_NOT_FOUND("COMMON_404", "资源不存在"),
SYSTEM_ERROR("COMMON_500", "系统繁忙,请稍后重试");
private final String code;
private final String message;
CommonErrorCode(String code, String message) {
this.code = code;
this.message = message;
}
@Override
public String code() {
return code;
}
@Override
public String message() {
return message;
}
}
// BizException.java
package com.example.pay.common;
import org.springframework.http.HttpStatus;
public class BizException extends RuntimeException {
private final ErrorCode errorCode;
private final HttpStatus httpStatus;
public BizException(ErrorCode errorCode, HttpStatus httpStatus) {
super(errorCode.message());
this.errorCode = errorCode;
this.httpStatus = httpStatus;
}
public ErrorCode getErrorCode() {
return errorCode;
}
public HttpStatus getHttpStatus() {
return httpStatus;
}
}Result.success 只负责成功数据,失败响应统一从错误码生成。错误码枚举保存稳定的机器码和默认文案,业务异常额外携带 HTTP 状态,避免控制器重复编写状态映射逻辑。
实现全局异常处理
全局异常处理器按“已知业务异常、参数异常、未知异常”的顺序处理。未知异常必须记录完整堆栈,但响应中只能返回通用提示,不能把数据库语句、密钥或内部类名暴露给调用方。
package com.example.pay.web;
import com.example.pay.common.BizException;
import com.example.pay.common.CommonErrorCode;
import com.example.pay.common.Result;
import jakarta.validation.ConstraintViolationException;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
@RestControllerAdvice
public class GlobalExceptionHandler {
private static final Logger log =
LoggerFactory.getLogger(GlobalExceptionHandler.class);
@ExceptionHandler(BizException.class)
public ResponseEntity<Result<Void>> handleBizException(BizException ex) {
return ResponseEntity
.status(ex.getHttpStatus())
.body(Result.failure(ex.getErrorCode()));
}
@ExceptionHandler({
MethodArgumentNotValidException.class,
ConstraintViolationException.class
})
public ResponseEntity<Result<Void>> handleValidationException(Exception ex) {
log.warn("request validation failed: {}", ex.getMessage());
return ResponseEntity
.badRequest()
.body(Result.failure(CommonErrorCode.INVALID_ARGUMENT));
}
@ExceptionHandler(Exception.class)
public ResponseEntity<Result<Void>> handleUnknownException(Exception ex) {
// 服务端保留堆栈,客户端只接收稳定的通用错误。
log.error("unhandled server exception", ex);
return ResponseEntity
.status(HttpStatus.INTERNAL_SERVER_ERROR)
.body(Result.failure(CommonErrorCode.SYSTEM_ERROR));
}
}该处理器生效后,控制器只需返回成功结果或抛出业务异常,不再编写重复的 try-catch。对于需要展示具体校验字段的接口,可在参数异常分支提取首个字段错误,但仍应保持固定响应结构。
验证接口行为
下面的控制器用于验证成功和业务失败两条路径。它是项目代码片段,需要与前面的公共类一起放入 Spring Boot 工程。
package com.example.pay.web;
import com.example.pay.common.BizException;
import com.example.pay.common.CommonErrorCode;
import com.example.pay.common.Result;
import jakarta.validation.constraints.Positive;
import org.springframework.http.HttpStatus;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import java.util.Map;
@Validated
@RestController
public class DemoPaymentController {
@GetMapping("/demo/pay")
public Result<Map<String, Object>> pay(
@RequestParam @Positive long amount) {
if (amount > 1_000_000) {
throw new BizException(
CommonErrorCode.INVALID_ARGUMENT,
HttpStatus.BAD_REQUEST
);
}
return Result.success(Map.of("acceptedAmount", amount));
}
}启动应用后执行:
curl -i "http://localhost:<PORT>/demo/pay?amount=100"预期结果如下,<PORT> 和 <TRACE_ID> 以实际运行值为准:
HTTP/1.1 200
Content-Type: application/json
{"code":"0","message":"success","data":{"acceptedAmount":100},"traceId":"<TRACE_ID>"}再验证业务失败:
curl -i "http://localhost:<PORT>/demo/pay?amount=1000001"预期结果:
HTTP/1.1 400
Content-Type: application/json
{"code":"COMMON_400","message":"请求参数不合法","data":null,"traceId":"<TRACE_ID>"}错误码设计边界
错误码一旦提供给外部调用方,就应视为接口契约。建议采用“领域前缀加数字或语义编号”的形式,例如 PAYMENT_1001、MERCHANT_2001,并保证同一编码只表达一种含义。
不要把异常类名、数据库错误码或第三方通道原始文案直接当作平台错误码。外部响应保持稳定,内部日志再记录原始异常和通道返回值,这样既便于排查,也能避免上游系统变化破坏客户端判断逻辑。