SpringBoot RESTful API返回统一数据格式还不懂？

最新推荐文章于 2025-06-29 16:12:06 发布

原创

最新推荐文章于 2025-06-29 16:12:06 发布 · 5.1k 阅读

19 ·

CC 4.0 BY-SA版权

文章标签：

#Spring # RESTful # 统一数据格式

本文探讨了SpringBoot中如何实现RESTful API的统一数据返回格式，通过创建通用返回值类并配置相关注解，简化了API的响应结构。文中详细解释了其实现过程，并提供了测试案例，帮助读者理解这一处理方式背后的原理。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

关于 Spring 的全局处理，我有两方面要说:

统一数据返回格式
统一异常处理
为了将两个问题说明清楚，将分两个章节分别说明，本章主要说第一点

有童鞋说，我们项目都做了这种处理，就是在每个 API 都单独工具类将返回值进行封装，但这种不够优雅；我想写最少的代码完成这件事，也许有童鞋说，加几个注解就解决问题了，说的没错，但这篇文章主要是为了说明为什么加了几个注解就解决问题了，目的是希望大家知其所以然。

为了更好的说明问题，本文先说明如何实现，然后再详细剖析实现原理(这很关键)

为什么要做统一数据返回格式

前后端分离是当今服务形式的主流，如何设计一个好的 RESTful API ，以及如何让前端小伙伴可以处理标准的 response JSON 数据结构都至关重要，为了让前端有更好的逻辑展示与页面交互处理，每一次 RESTful 请求都应该包含以下几个信息:

名称	描述
status	状态码，标识请求成功与否，如 [1:成功；-1:失败]
errorCode	错误码，给出明确错误码，更好的应对业务异常；请求成功该值可为空
errorMsg	错误消息，与错误码相对应，更具体的描述异常信息
resultBody	返回结果，通常是 Bean 对象对应的 JSON 数据, 通常为了应对不同返回值类型，将其声明为泛型类型

实现

通用返回值类定义

根据上面的描述，用 Java Bean 来体现这个结构就是这样:

@Data
public final class CommonResult<T> {

    private int status = 1;

    private String errorCode = "";

    private String errorMsg = "";

    private T resultBody;

    public CommonResult() {
    }

    public CommonResult(T resultBody) {
        this.resultBody = resultBody;
    }
}

配置

没错，我们需要借助几个关键注解来完成一下相关配置:

@EnableWebMvc
@Configuration
public class UnifiedReturnConfig {

    @RestControllerAdvice("com.example.unifiedreturn.api")
    static class CommonResultResponseAdvice implements ResponseBodyAdvice<Object>{
        @Override
        public boolean supports(MethodParameter methodParameter, Class<? extends HttpMessageConverter<?>> aClass) {
            return true;
        }

        @Override
        public Object beforeBodyWrite(Object body, MethodParameter methodParameter, MediaType mediaType, Class<? extends HttpMessageConverter<?>> aClass, ServerHttpRequest serverHttpRequest, ServerHttpResponse serverHttpResponse) {
            if (body instanceof CommonResult){
                return body;
            }

            return new CommonResult<Object>(body);
        }
    }
}

到这里就结束了，我们就可以纵情的写任何 RESTful API 了，所有的返回值都会有统一的 JSON 结构

测试

新建 UserController，添加相应的 RESTful API，测试用例写的比较简单，只为了说明返回值的处理

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


    @GetMapping("")
    public List<UserVo> getUserList(){
        List<UserVo> userVoList = Lists.newArrayListWithCapacity(2);
        userVoList.add(UserVo.builder().id(1L).name("日拱一兵").age(18).build());
        userVoList.add(UserVo.bui