Spring Boot中@RestControllerAdvice如何统一异常与正常响应格式？

我在Spring Boot应用中实现了全局异常处理器，返回类型为ResponseEntity<ErrorResponse>，ErrorResponse类定义如下：

ErrorResponse:

public class ErrorResponse {
    private final int status;
    private final String message;
    private String stackTrace;
    private List<String> errors;
}

同时，我实现了ApiResponse类来统一控制器的响应格式：

ApiResponse:

public class ApiResponse<T> {

    private Long timestamp;
    private final String message;
    private final T data;

    public ApiResponse(Long timestamp, String message) {
        this.timestamp = timestamp;
        this.message = message;
        this.data = data;
    }
}

控制器方法示例：

Controller:

@GetMapping("/units/{id}")
public ResponseEntity<ApiResponse<UnitResponse>> findById(@PathVariable long id) {
    final UnitResponse response = unitService.findById(id);
    return ResponseEntity.ok(
        new ApiResponse<>(Instant.now(clock).toEpochMilli(), "Success", response));
}

现在遇到的问题是：控制器正常响应和异常处理器的响应类型不一致。我觉得应该合并ApiResponse和ErrorResponse，这个思路对吗？另外，我尝试在全局异常处理器中用合并后的响应类替代Object，但重写方法时因为返回类型不匹配报错。请问该怎么解决，实现错误和正常场景下的响应类型统一？

1. 合并响应类的思路是正确的 #

统一响应格式是REST API的最佳实践之一，合并ApiResponse和ErrorResponse能让前端处理逻辑更统一，避免分别适配两种不同的返回结构，这个思路完全没问题。

2. 设计通用响应类 #

你可以定义一个兼容成功、错误场景的通用响应类，包含两类场景需要的所有字段：

public class UnifiedApiResponse<T> {
    private final Long timestamp;
    private final int code;
    private final String message;
    private final T data;
    private List<String> errors;
    private String stackTrace;

    // 成功场景构造器
    public UnifiedApiResponse(int code, String message, T data) {
        this.timestamp = Instant.now().toEpochMilli();
        this.code = code;
        this.message = message;
        this.data = data;
    }

    // 错误场景构造器
    public UnifiedApiResponse(int code, String message, List<String> errors) {
        this.timestamp = Instant.now().toEpochMilli();
        this.code = code;
        this.message = message;
        this.data = null;
        this.errors = errors;
    }

    // 带栈信息的错误构造器（仅开发环境启用）
    public UnifiedApiResponse(int code, String message, List<String> errors, String stackTrace) {
        this(code, message, errors);
        this.stackTrace = stackTrace;
    }

    // 省略getter方法
}

3. 调整控制器与全局异常处理器 #

控制器修改

将控制器返回类型改为ResponseEntity<UnifiedApiResponse<T>>，示例：

@GetMapping("/units/{id}")
public ResponseEntity<UnifiedApiResponse<UnitResponse>> findById(@PathVariable long id) {
    final UnitResponse response = unitService.findById(id);
    return ResponseEntity.ok(
        new UnifiedApiResponse<>(HttpStatus.OK.value(), "Success", response));
}

全局异常处理器修改

不需要重写任何父类方法，直接用@RestControllerAdvice标注类，@ExceptionHandler标注异常处理方法，返回ResponseEntity<UnifiedApiResponse<?>>即可：

@RestControllerAdvice
public class GlobalExceptionHandler {

    // 处理自定义业务异常
    @ExceptionHandler(BusinessException.class)
    public ResponseEntity<UnifiedApiResponse<?>> handleBusinessException(BusinessException ex) {
        UnifiedApiResponse<?> response = new UnifiedApiResponse<>(
            HttpStatus.BAD_REQUEST.value(),
            ex.getMessage(),
            Collections.singletonList(ex.getDetail())
        );
        return new ResponseEntity<>(response, HttpStatus.BAD_REQUEST);
    }

    // 处理通用异常
    @ExceptionHandler(Exception.class)
    public ResponseEntity<UnifiedApiResponse<?>> handleGenericException(Exception ex) {
        List<String> errors = Collections.singletonList("服务器内部错误");
        UnifiedApiResponse<?> response;
        // 开发环境返回栈信息，生产环境隐藏
        if ("dev".equals(System.getenv("SPRING_PROFILES_ACTIVE"))) {
            String stackTrace = Arrays.toString(ex.getStackTrace());
            response = new UnifiedApiResponse<>(
                HttpStatus.INTERNAL_SERVER_ERROR.value(),
                ex.getMessage(),
                errors,
                stackTrace
            );
        } else {
            response = new UnifiedApiResponse<>(
                HttpStatus.INTERNAL_SERVER_ERROR.value(),
                "服务器内部错误",
                errors
            );
        }
        return new ResponseEntity<>(response, HttpStatus.INTERNAL_SERVER_ERROR);
    }
}

4. 关于重写方法报错的说明 #

之前的报错是因为你试图重写父类方法，但返回类型不兼容。实际上Spring全局异常处理器不需要重写任何方法，只要用@ExceptionHandler标注的方法能处理对应异常、返回合法的ResponseEntity即可，完全不需要依赖父类方法的返回类型。

内容的提问来源于stack exchange，提问作者Jack