Spring Boot中返回含数据、空结果、错误的ResponseEntity最佳实践

• 类命名不规范：全局异常处理类命名为FileUploadException不符合类职责语义，和异常类命名规则冲突，后续如果定义文件上传相关的自定义异常很容易出现命名冲突，建议统一命名为GlobalExceptionHandler这类语义明确的名称。
• 代码冗余：ResponseEntity没有指定泛型，靠@SuppressWarnings("rawtypes")压制警告完全没必要，指定返回体泛型即可。
• 覆盖场景不全：当前只处理了文件上传大小超限这一种异常，没有覆盖其他系统异常、业务异常，也没有处理Optional.empty()空返回的场景。
• 你之前查到的核心实现思路在目前主流的Spring Boot 2.x、3.x版本依然适用，不需要废弃，只要结合@RestControllerAdvice和ResponseBodyAdvice做增强，就能覆盖所有需要的场景，不需要额外引入第三方依赖。

第一步：定义统一返回结构 #

所有场景的返回值都用这个结构封装，保证前后端交互格式一致：

public class Result<T> {
    // 状态码：200=请求成功，4xx=客户端/业务错误，5xx=服务端错误
    private Integer code;
    // 返回提示信息
    private String message;
    // 实际业务载荷
    private T data;

    // 成功返回（携带业务数据）
    public static <T> Result<T> success(T data) {
        Result<T> res = new Result<>();
        res.setCode(200);
        res.setMessage("success");
        res.setData(data);
        return res;
    }

    // 空结果返回
    public static <T> Result<T> empty() {
        Result<T> res = new Result<>();
        res.setCode(200);
        res.setMessage("未查询到对应资源");
        res.setData(null);
        return res;
    }

    // 异常/错误返回
    public static <T> Result<T> fail(Integer code, String msg) {
        Result<T> res = new Result<>();
        res.setCode(code);
        res.setMessage(msg);
        res.setData(null);
        return res;
    }

    // 省略所有字段的getter、setter方法
}

第二步：全局异常处理（覆盖所有异常返回场景） #

用@RestControllerAdvice替代普通的@ControllerAdvice，自带@ResponseBody注解，不需要每个方法额外加响应体注解，更适配RESTful接口：

@RestControllerAdvice
public class GlobalExceptionHandler extends ResponseEntityExceptionHandler {

    // 原有文件上传大小超限异常处理
    @ExceptionHandler(MaxUploadSizeExceededException.class)
    public ResponseEntity<Result<Void>> handleMaxSizeException(MaxUploadSizeExceededException e) {
        return ResponseEntity.status(HttpStatus.EXPECTATION_FAILED)
                .body(Result.fail(417, "上传文件大小超出系统限制"));
    }

    // 自定义业务异常处理：业务逻辑里需要中断返回的场景直接抛自定义BusinessException即可
    @ExceptionHandler(BusinessException.class)
    public ResponseEntity<Result<Void>> handleBusinessException(BusinessException e) {
        return ResponseEntity.status(HttpStatus.BAD_REQUEST)
                .body(Result.fail(e.getCode(), e.getMessage()));
    }

    // 兜底：处理所有未被单独捕获的系统异常
    @ExceptionHandler(Exception.class)
    public ResponseEntity<Result<Void>> handleDefaultException(Exception e) {
        // 这里记得打印错误日志方便排查问题，生产环境不要直接把异常栈信息返回给前端
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                .body(Result.fail(500, "系统内部异常，请稍后重试"));
    }

    // 重写父类方法，处理参数校验失败的场景
    @Override
    protected ResponseEntity<Object> handleMethodArgumentNotValid(MethodArgumentNotValidException ex,
                                                                  HttpHeaders headers,
                                                                  HttpStatusCode status,
                                                                  WebRequest request) {
        String errMsg = ex.getBindingResult().getFieldErrors().stream()
                .map(FieldError::getDefaultMessage)
                .findFirst()
                .orElse("请求参数不合法");
        return ResponseEntity.status(HttpStatus.BAD_REQUEST)
                .body(Result.fail(400, errMsg));
    }
}

自定义BusinessException只需要继承RuntimeException，增加错误码字段即可，业务代码里遇到校验不通过、权限不足这类需要提前返回的场景，直接抛出对应异常，会被全局处理器自动捕获。

第三步：全局响应包装（覆盖正常业务返回、Optional.empty()空返回场景） #

实现ResponseBodyAdvice接口，拦截所有Controller方法的返回值，在响应写出前自动做统一包装，不需要在每个Controller里手动写Result包装逻辑，也不需要手动判断Optional是否为空：

@RestControllerAdvice
public class GlobalResponseHandler implements ResponseBodyAdvice<Object> {

    @Override
    public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {
        // 已经是Result类型的返回值不需要重复包装（比如全局异常处理器返回的结果）
        return !returnType.getParameterType().equals(Result.class);
    }

    @Override
    public Object beforeBodyWrite(Object body,
                                  MethodParameter returnType,
                                  MediaType selectedContentType,
                                  Class<? extends HttpMessageConverter<?>> selectedConverterType,
                                  ServerHttpRequest request,
                                  ServerHttpResponse response) {
        // 识别Optional类型返回值，空值直接返回空结果结构，有值自动取数据包装
        if (body instanceof Optional<?> optionalVal) {
            return optionalVal.map(Result::success).orElseGet(Result::empty);
        }
        // 普通业务数据直接包装成统一成功结构
        return Result.success(body);
    }
}

• 这套方案在Spring Boot 2.7+、3.x全版本可直接运行，不需要额外配置。
• Service层可以直接返回业务对象或者Optional包装的对象，Controller层直接把Service返回结果透传即可，全局组件会自动完成包装、空值判断逻辑，减少大量重复代码。
• 实际使用时注意一个小坑：如果Controller方法返回值类型是String，需要单独做JSON序列化处理——因为String类型的消息转换器优先级高于JSON转换器，直接返回Result对象会报类型转换错误，只需要在beforeBodyWrite方法里判断返回值是String时，提前用ObjectMapper把Result对象序列化成JSON字符串再返回即可。

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