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

统一响应与异常

统一响应与异常

本课解决接口返回格式不一致、业务错误难追踪和异常直接暴露给客户端的问题。完成后,你将得到统一响应模型、可维护的错误码体系,以及把各类异常稳定转换为 HTTP 响应的全局处理机制。

学习目标

  • 定义同时适用于成功与失败场景的统一响应模型
  • 建立可扩展、可定位且不泄露内部细节的错误码体系
  • 使用业务异常和全局异常处理器统一接口行为

统一响应需要解决什么

支付平台通常同时包含商户接口、运营接口和内部服务接口。若每个控制器自行拼装返回值,客户端就必须适配多种字段名称,日志也难以通过同一标识关联请求与错误。

统一响应应至少包含 code、message、data 和 traceId。其中 code 面向程序判断,message 面向调用方阅读,data 承载成功结果,traceId 用于把客户端报错与服务端日志连接起来。

统一响应与异常处理链路

统一响应不等于所有请求都返回 HTTP 200。参数错误可返回 400,未认证返回 401,无权限返回 403,资源不存在返回 404,未知服务端错误返回 500;业务码则进一步说明具体原因。

定义响应模型和错误码

下面是项目代码片段,需按注释中的文件名分别保存到 Spring Boot 工程。示例依赖 Spring Web、Validation 和 SLF4J,traceId 从 MDC 中读取。

java
// 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 状态,避免控制器重复编写状态映射逻辑。

实现全局异常处理

全局异常处理器按“已知业务异常、参数异常、未知异常”的顺序处理。未知异常必须记录完整堆栈,但响应中只能返回通用提示,不能把数据库语句、密钥或内部类名暴露给调用方。

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

java
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));
    }
}

启动应用后执行:

bash
curl -i "http://localhost:<PORT>/demo/pay?amount=100"

预期结果如下,<PORT> 和 <TRACE_ID> 以实际运行值为准:

text
HTTP/1.1 200
Content-Type: application/json

{"code":"0","message":"success","data":{"acceptedAmount":100},"traceId":"<TRACE_ID>"}

再验证业务失败:

bash
curl -i "http://localhost:<PORT>/demo/pay?amount=1000001"

预期结果:

text
HTTP/1.1 400
Content-Type: application/json

{"code":"COMMON_400","message":"请求参数不合法","data":null,"traceId":"<TRACE_ID>"}

错误码设计边界

错误码一旦提供给外部调用方,就应视为接口契约。建议采用“领域前缀加数字或语义编号”的形式,例如 PAYMENT_1001、MERCHANT_2001,并保证同一编码只表达一种含义。

不要把异常类名、数据库错误码或第三方通道原始文案直接当作平台错误码。外部响应保持稳定,内部日志再记录原始异常和通道返回值,这样既便于排查,也能避免上游系统变化破坏客户端判断逻辑。

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

目录与阅读设置

阅读设置

17

记录一个想法

统一响应与异常

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

登录哪都通