SpringMVC 以注解的方式配置 Controller 统一返回包装对象

在以前的web开发中，使用SpringMVC框架通常是创建一个统一包装类 RespBean，Controller 中的每个方法的返回值都是这个类的对象。这样可以实现接口返回数据格式统一。

本文将介绍一种以注解配置的方式来实现这样的效果，即在Controller 上加一个注解就可以做到返回结果格式统一。

实现步骤如下：

1. 统一包装类 RespBean.java

package com.hejjon.bean;

import com.alibaba.fastjson.annotation.JSONField;
import com.hejjon.constant.RespInfo;

import java.io.Serializable;

/**
 *  Controller 统一返回对象
 * @author: Shi Cao
 * @date: 2022-11-21 13:33:38
 * @since: 1.0
 */
public class RespBean<T> implements Serializable {

    private static final long serialVersionUID = 7048691672612601L;


    /**
     * 状态码
     */
    @JSONField(ordinal = 0)
    private int code;

    /**
     * 信息对象
     */
    @JSONField(ordinal = 1)
    private String msg;

    /**
     * 结果对象
     */
    @JSONField(ordinal = 2)
    private T data;

    public RespBean() {
        this(RespInfo.HTTP_OK_CODE, RespInfo.HTTP_OK_MESSAGE, null);
    }


    public RespBean(int code, String msg) {
        this(code, msg, null);
    }

    public RespBean(int code, String msg, T data) {
        this.code = code;
        this.msg = msg;
        this.data = data;
    }

    public int getCode() {
        return code;
    }

    public void setCode(int code) {
        this.code = code;
    }

    public String getMsg() {
        return msg;
    }

    public void setMsg(String msg) {
        this.msg = msg;
    }

    public T getData() {
        return data;
    }

    public void setData(T data) {
        this.data = data;
    }


    public RespBean<T> data(T data) {
        this.data = data;
        return this;
    }


    public static <T> RespBean<T> ok() {
        return new RespBean<>(RespInfo.HTTP_OK_CODE, RespInfo.HTTP_OK_MESSAGE);
    }

    public static <T> RespBean<T> ok(T data) {
        return new RespBean<>(RespInfo.HTTP_OK_CODE, RespInfo.HTTP_OK_MESSAGE, data);
    }


}

类中用到的常量

package com.hejjon.constant;

/**
 *  返回结果信息常量类
 * @author:
 * @date: 2022-11-21 13:40:56
 * @since: 1.0
 */
public class RespInfo {

    public static final Integer HTTP_OK_CODE = 200;
    public static final String HTTP_OK_MESSAGE = "success";
    public static final Integer HTTP_ERROR_CODE = 500;
    public static final String HTTP_ERROR_MESSAGE = "error";

}

2. 定义注解 @RestWrapper

package com.hejjon.annotation;

import java.lang.annotation.*;

/**
 *  统一返回包装注解
 * @author: cshi
 * @date: 2022/11/21 12:44
 * @since 1.0
 */
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface RestWrapper {


}

3. 统一返回包装配置

package com.hejjon.config;

import com.alibaba.fastjson.JSON;
import com.hejjon.annotation.IgnoreWrapper;
import com.hejjon.annotation.RestWrapper;
import com.hejjon.bean.RespBean;
import com.hejjon.constant.StandardContentType;
import com.hejjon.util.Servlets;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.MethodParameter;
import org.springframework.web.context.request.NativeWebRequest;
import org.springframework.web.method.support.HandlerMethodReturnValueHandler;
import org.springframework.web.method.support.ModelAndViewContainer;
import org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter;

import javax.annotation.PostConstruct;
import javax.annotation.Resource;
import javax.servlet.http.HttpServletResponse;
import java.util.ArrayList;
import java.util.List;

/**
 *  统一返回包装配置
 * @author: Shi Cao
 * @date: 2022-11-21 13:50:06
 * @since: 1.0
 */
@Configuration
public class WrapperResultConfig implements HandlerMethodReturnValueHandler {


    @Resource
    private RequestMappingHandlerAdapter requestMappingHandlerAdapter;

    /**
     *  程序加载完毕后将配置的实例添加到 RequestMappingHandlerAdapter
     */
    @PostConstruct
    public void compare() {
        List<HandlerMethodReturnValueHandler> handlers = requestMappingHandlerAdapter.getReturnValueHandlers();
        List<HandlerMethodReturnValueHandler> list = new ArrayList<>();
        list.add(this);
        // ！！！注意这里，需要将requestMappingHandlerAdapter 原有的返回值处理器添加进去
        if (handlers != null) {
            list.addAll(handlers);
        }
        requestMappingHandlerAdapter.setReturnValueHandlers(list);
    }

    /**
     * 判断是否要进行包装返回值
     * 类上没有@RestWrapper 注解，返回false, 则该类的所以方法都不进行包装
     * 类上加了@RestWrapper 注解，但方法上加了 @IgnoreWrapper 返回false 不进行包装
     * @param methodParameter
     * @return
     */
    @Override
    public boolean supportsReturnType(MethodParameter methodParameter) {
        // 类上没有@RestWrapper 注解，直接返回false，不对返回值进行包装
        if (!methodParameter.getContainingClass().isAnnotationPresent(RestWrapper.class)) {
            return false;
        }
        // 方法上加了 @IgnoreWrapper 注解表示忽略包装该方法, 返回false
        return !methodParameter.hasMethodAnnotation(IgnoreWrapper.class);
    }

    /**
     * 处理返回值，进行包装！
     * @param o
     * @param methodParameter
     * @param modelAndViewContainer
     * @param nativeWebRequest
     * @throws Exception
     */
    @Override
    public void handleReturnValue(Object o, MethodParameter methodParameter, ModelAndViewContainer modelAndViewContainer, NativeWebRequest nativeWebRequest) throws Exception {

        HttpServletResponse response = nativeWebRequest.getNativeResponse(HttpServletResponse.class);
        if (null == response) {
            return;
        }
        RespBean<?> respBean;
        if (o instanceof RespBean) {
            // 如果返回值类型是 RespBean 就直接转成RespBean
            respBean = (RespBean<?>) o;
        } else {
            // 否则将该返回值设置为 RespBean类的data属性
            respBean = new RespBean<>().data(o);
        }
        modelAndViewContainer.setRequestHandled(true);
        // 设置响应格式
        response.setContentType(StandardContentType.APPLICATION_JSON);
        Servlets.transfer(response, JSON.toJSONString(respBean).getBytes());
    }

}

注意看这段代码，非常关键。作用是在程序启动时将返回值处理器设置到 RequestMappingHandlerAdapter 对象中。一定要把它原有的返回值处理器设置取出来再一并设置进去，否则将报错！！！

@PostConstruct
public void compare() {
    List<HandlerMethodReturnValueHandler> handlers = requestMappingHandlerAdapter.getReturnValueHandlers();
    List<HandlerMethodReturnValueHandler> list = new ArrayList<>();
    list.add(this);
    // ！！！注意这里，需要将requestMappingHandlerAdapter 原有的返回值处理器添加进去
    if (handlers != null) {
        list.addAll(handlers);
    }
    requestMappingHandlerAdapter.setReturnValueHandlers(list);
}

这个类中使用到的一些工具方法如下：

Servlets.java

public class Servlets {


    public static void transfer(HttpServletResponse response, byte[] bs) throws IOException {
        Streams.transfer(Streams.toInputStream(bs), response.getOutputStream());
    }
}

 Streams.java

public class Streams {

    public static int transfer(InputStream input, OutputStream output) throws IOException {
        long count = transferLarge(input, output);
        return count > 2147483647L ? -1 : (int) count;
    }

    public static long transferLarge(InputStream input, OutputStream output) throws IOException {
        byte[] buffer = new byte[8192];

        long count;
        int n;
        for (count = 0L; (n = input.read(buffer)) != -1; count += (long) n) {
            output.write(buffer, 0, n);
        }

        return count;
    }

    public static InputStream toInputStream(byte[] bs) {
        return new ByteArrayInputStream(bs);
    }


}

json 格式

/** * json 数据格式 */

public static final String APPLICATION_JSON = "application/json";

4. 在 Controller 中使用

StudentVO.java 返回对象

public class StudentVO {


    private String name;

    private Integer age;

    private Double score;

    private Integer sex;

...

控制器中使用，在类上加@RestWrapper 注解

@RestController
@RequestMapping("/demo")
@RestWrapper
public class DemoController {


    @GetMapping("/getById")
    public StudentVO getById() {

        StudentVO vo = new StudentVO("张三", 18, 90.0, 1);
        return vo;
    }
    
}

5. 效果展示

使用统一包装前的接口返回数据

 统一包装返回结果后