Spring Boot如何实现Controller层响应结果的全局统一封装

解决方案 #

Spring 完全支持全局自动封装 Controller 响应，无需修改现有业务方法代码，通过 ResponseBodyAdvice + @ControllerAdvice 即可实现，具体步骤如下：

步骤1：定义统一响应包装类 #

首先创建通用的返回包装对象，对应你需要的响应结构：

public class CommonResponse<T> {
    private String status;
    private T response;
    private Object extra;

    // 构造方法
    public CommonResponse(String status, T response, Object extra) {
        this.status = status;
        this.response = response;
        this.extra = extra;
    }

    // 按需补充Getter、Setter方法
    public String getStatus() { return status; }
    public void setStatus(String status) { this.status = status; }
    public T getResponse() { return response; }
    public void setResponse(T response) { this.response = response; }
    public Object getExtra() { return extra; }
    public void setExtra(Object extra) { this.extra = extra; }
}

步骤2：实现全局响应处理类 #

通过 @ControllerAdvice 扫描所有 Controller 响应，自动执行包装逻辑：

import org.springframework.core.MethodParameter;
import org.springframework.http.MediaType;
import org.springframework.http.converter.HttpMessageConverter;
import org.springframework.http.server.ServerHttpRequest;
import org.springframework.http.server.ServerHttpResponse;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.servlet.mvc.method.annotation.ResponseBodyAdvice;

@ControllerAdvice
public class GlobalResponseWrapper implements ResponseBodyAdvice<Object> {

    // 判定哪些返回值需要包装，返回true才会执行后续包装逻辑
    @Override
    public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {
        // 排除本身已经是包装类的返回值，避免重复包装
        return !returnType.getParameterType().equals(CommonResponse.class);
    }

    // 执行实际的包装逻辑
    @Override
    public Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType selectedContentType, Class<? extends HttpMessageConverter<?>> selectedConverterType, ServerHttpRequest request, ServerHttpResponse response) {
        // status的值可根据业务自定义，比如成功传"SUCCESS"、异常传对应错误码
        return new CommonResponse<>("SOMETHING", body, null);
    }
}

注意事项 #

• 如果项目存在返回值为 String 类型的接口，可能出现类型转换异常，这是因为Spring的StringHttpMessageConverter优先级高于JSON消息转换器，你可以在beforeBodyWrite中单独处理String类型，将包装后的对象转成JSON字符串返回即可。
• 如果需要排除部分接口不参与包装，可以在supports方法中添加过滤逻辑，比如判断方法上是否有自定义的忽略包装注解、或者只对指定包路径下的Controller生效。
• 异常场景的响应可以和这个格式对齐，配合@RestControllerAdvice + @ExceptionHandler做全局异常处理，异常时直接返回CommonResponse对象即可。

内容的提问来源于stack exchange，提问作者ima.technophyle