Spring中如何将RestController返回结果封装到自定义包装对象？

你完全可以通过Spring MVC提供的ResponseBodyAdvice接口来实现这个需求——它就是专门用来在响应体被写入HTTP响应前，对返回值进行统一处理的组件，和@ControllerAdvice搭配使用非常合适，完全能满足你直接返回列表、自动包装成指定JSON格式的需求。

接下来我给你详细拆解实现步骤：

1. 定义统一响应实体类 #

首先创建一个符合你要求格式的通用响应类，用来包装所有接口的返回值：

import java.util.Collections;
import java.util.List;

public class ApiResponse<T> {
    private boolean success;
    private List<String> errors;
    private T responseObject;

    // 私有构造方法，让外部通过静态方法创建实例
    private ApiResponse() {}

    // 成功响应的静态工厂方法
    public static <T> ApiResponse<T> success(T data) {
        ApiResponse<T> response = new ApiResponse<>();
        response.setSuccess(true);
        response.setErrors(Collections.emptyList());
        response.setResponseObject(data);
        return response;
    }

    // 失败响应的静态工厂方法
    public static <T> ApiResponse<T> fail(List<String> errors) {
        ApiResponse<T> response = new ApiResponse<>();
        response.setSuccess(false);
        response.setErrors(errors);
        response.setResponseObject(null);
        return response;
    }

    // Getter和Setter方法（或者用Lombok简化）
    public boolean isSuccess() {
        return success;
    }

    public void setSuccess(boolean success) {
        this.success = success;
    }

    public List<String> getErrors() {
        return errors;
    }

    public void setErrors(List<String> errors) {
        this.errors = errors;
    }

    public T getResponseObject() {
        return responseObject;
    }

    public void setResponseObject(T responseObject) {
        this.responseObject = responseObject;
    }
}

2. 实现全局响应包装器 #

创建一个带有@ControllerAdvice注解的类，实现ResponseBodyAdvice接口，完成自动包装逻辑：

import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
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.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.servlet.mvc.method.annotation.ResponseBodyAdvice;

import java.util.Collections;

@ControllerAdvice
public class GlobalResponseHandler implements ResponseBodyAdvice<Object> {

    /**
     * 判断是否需要对当前返回值进行包装
     * 这里我们排除已经是ApiResponse类型的返回值，避免重复包装
     */
    @Override
    public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {
        return !returnType.getParameterType().isAssignableFrom(ApiResponse.class);
    }

    /**
     * 在响应体写入前，对返回值进行包装处理
     */
    @Override
    public Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType selectedContentType,
                                  Class<? extends HttpMessageConverter<?>> selectedConverterType,
                                  ServerHttpRequest request, ServerHttpResponse response) {
        // 处理返回值为null的情况
        if (body == null) {
            return ApiResponse.success(null);
        }

        // 特殊处理String类型：因为Spring的StringHttpMessageConverter优先级较高，直接返回对象会被转成字符串形式
        if (body instanceof String) {
            ObjectMapper objectMapper = new ObjectMapper();
            try {
                return objectMapper.writeValueAsString(ApiResponse.success(body));
            } catch (JsonProcessingException e) {
                throw new RuntimeException("Failed to wrap string response", e);
            }
        }

        // 其他类型直接包装成成功响应
        return ApiResponse.success(body);
    }

    /**
     * 全局异常处理：将异常信息包装成失败响应格式
     */
    @ExceptionHandler(Exception.class)
    @ResponseBody
    public ApiResponse<Void> handleGlobalException(Exception e) {
        // 这里可以根据实际需求定制错误信息，比如区分不同异常类型返回不同错误码
        return ApiResponse.fail(Collections.singletonList(e.getMessage()));
    }
}

3. 在Controller中直接返回业务数据 #

现在你可以在RestController里直接返回用户列表，不需要手动包装，框架会自动帮你处理：

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.Arrays;
import java.util.List;

@RestController
@RequestMapping("/users")
public class UserController {

    @GetMapping
    public List<User> getUsers() {
        // 模拟从数据库或服务层获取用户列表
        return Arrays.asList(
                new User("1", "Sonja"),
                new User("2", "Alice"),
                new User("3", "Bob")
        );
    }
}

// 模拟User实体类
class User {
    private String id;
    private String name;

    public User(String id, String name) {
        this.id = id;
        this.name = name;
    }

    // Getter方法
    public String getId() {
        return id;
    }

    public String getName() {
        return name;
    }
}

效果验证 #

当你访问/users接口时，会自动得到如下格式的响应：

{
  "success": true,
  "errors": [],
  "responseObject": [
    {"id": "1", "name": "Sonja"},
    {"id": "2", "name": "Alice"},
    {"id": "3", "name": "Bob"}
  ]
}

如果接口抛出异常，比如业务逻辑出错，会返回失败格式：

{
  "success": false,
  "errors": ["业务异常：用户不存在"],
  "responseObject": null
}

注意事项 #

• String类型处理：前面代码里已经针对String返回值做了特殊处理，因为Spring默认会用StringHttpMessageConverter处理字符串，直接返回ApiResponse对象会被转成toString()的结果，所以需要手动序列化成JSON字符串。
• 避免重复包装：supports方法里的判断确保了如果你的某个接口手动返回了ApiResponse对象（比如需要自定义错误信息时），不会被二次包装。
• 异常扩展：你可以根据业务需求添加更多的@ExceptionHandler方法，处理自定义异常、参数校验异常等，返回更精准的错误信息。

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