SpringBoot中优雅地实现统一响应对象

目录

• 前言
• 实现步骤
  • 定义统一响应对象类
  • 定义一个忽略响应封装的注解
  • 实现ResponseBodyAdvice接口
  • 定义Controller类
• 总结

前言

近日心血来潮想做一个开源项目，目标是做一款可以适配多端、功能完备的模板工程，包含后台管理系统和前台系统，开发者基于此项目进行裁剪和扩展来完成自己的功能开发。本项目为前后端分离开发，后端基于Java21和SpringBoot3开发，后端使用Spring Security、JWT、Spring Data JPA等技术栈，前端提供了vue、angular、react、uniapp、微信小程序等多种脚手架工程。

项目地址：https://gitee.com/breezefaith/fast-alden

在前后端分离的项目开发过程中，我们通常会对数据返回格式进行统一的处理，这样可以方便前端人员取数据。但如果定义好响应对象R后，Controller类中每一个方法的返回值类型都只能是这个响应对象类，会使代码显得很不优雅。

@RestController
@RequestMapping("/admin")
public class AdminController {
    @PostMapping(value = "/register")
    public R register(@Validated @RequestBody UmsAdminParam umsAdminParam) {
        return R.success(new UmsAdmin());
    }

    @PostMapping(value = "/logout")
    public R logout() {
        return R.success(null);
    }

    @PostMapping(value = "/login")
    public R login() {
        return R.success(new UmsAdmin());
    }
}

为了能够实现统一的响应对象，又能优雅的定义Controller类的方法，使其每个方法的返回值是其应有的类型，可以参考本文，主要是借助RestControllerAdvice注解和ResponseBodyAdvice接口来实现。

实现步骤

定义统一响应对象类

/**
 * 响应结果类
 *
 * @param  任意类型
 */
@Data
public class ResponseResult {
    /**
     * 响应状态码，200是正常，非200表示异常
     */
    private int status;
    /**
     * 异常编号
     */
    private String errorCode;
    /**
     * 异常信息
     */
    private String message;
    /**
     * 响应数据
     */
    private T data;

    public static  ResponseResult success() {
        return success(HttpServletResponse.SC_OK, null, null);
    }

    public static  ResponseResult success(T data) {
        return success(HttpServletResponse.SC_OK, null, data);
    }

    public static  ResponseResult fail(String message) {
        return fail(HttpServletResponse.SC_INTERNAL_SERVER_ERROR, null, message, null);
    }

    public static  ResponseResult fail(String errorCode, String message) {
        return fail(HttpServletResponse.SC_INTERNAL_SERVER_ERROR, errorCode, message, null);
    }

    public static  ResponseResult success(int status, String message, T data) {
        ResponseResult r = new ResponseResult<>();
        r.setStatus(status);
        r.setMessage(message);
        r.setData(data);

        return r;
    }

    public static  ResponseResult fail(int status, String errorCode, String message) {
        return fail(status, errorCode, message, null);
    }

    public static  ResponseResult fail(int status, String errorCode, String message, T data) {
        ResponseResult r = new ResponseResult<>();
        r.setStatus(status);
        r.setErrorCode(errorCode);
        r.setMessage(message);
        r.setData(data);
        return r;
    }

}

定义一个忽略响应封装的注解

有些场景下我们不希望Controller方法的返回值被包装为统一响应对象，可以先定义一个忽略响应封装的注解，配合后续代码实现。

/**
 * 忽略响应封装注解
 */
@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface IgnoreRestControllerResponseAdvice {
}

实现ResponseBodyAdvice接口

本步骤需要使用@RestControllerAdvice注解，它是一个组合注解，由@ControllerAdvice、@ResponseBody组成，而@ControllerAdvice继承了@Component，因此@RestControllerAdvice本质上是个Component，用于定义@ExceptionHandler，@InitBinder和@ModelAttribute方法，适用于所有使用@RequestMapping方法。

还要用到ResponseBodyAdvice，它是Spring框架提供的一个接口，用于对Controller方法返回的响应体进行全局处理。它可以在Controller方法执行完毕并且响应体已经生成之后，对响应体进行自定义的修改或者增强操作。它本质上就是使用Spring AOP定义的一个切面，作用于Controller方法执行完成后。

具体实现代码如下：

/**
 * 响应实体封装切面
 */
@RestControllerAdvice(basePackages = {"com.demo.controller"})
public class GlobalResponseAdvice implements ResponseBodyAdvice