springboot项目中统一返回数据格式

统一API响应格式设计

最新推荐文章于 2025-01-24 18:27:52 发布

原创最新推荐文章于 2025-01-24 18:27:52 发布 · 1k 阅读

5 ·

CC 4.0 BY-SA版权

文章标签：

#spring boot #java

spring boot常见问题专栏收录该内容

7 篇文章

订阅专栏

本文介绍了一种统一API响应格式的设计方案，包括响应的状态码、消息及数据等关键元素，并通过示例展示了如何在实际项目中实现这一设计。

项目中我们会将响应封装成json返回，一般我们会将所有接口的数据格式统一，使前端(iOS Android, Web)对数据的操作更一致、轻松。
一般情况下，统一返回数据格式没有固定的格式，只要能描述清楚返回的数据状态以及要返回的具体数据就可以。但是一般会包含状态码、返回消息、数据这几部分内容
例如，我们的系统要求返回的基本数据格式如下：
列表

{
  "success": true,
  "code": 20000,
  "message": "成功",
  "data": {
    "items": [
      {
        "id": "1",
        "name": "刘德华",
        "intro": "毕业于师范大学数学系，热爱教育事业，执教数学思维6年有余"
      }
    ]
  }
}

分页：

{
  "success": true,
  "code": 20000,
  "message": "成功",
  "data": {
    "total": 17,
    "rows": [
      {
        "id": "1",
        "name": "刘德华",
        "intro": "毕业于师范大学数学系，热爱教育事业，执教数学思维6年有余"
      }
    ]
  }
}

没有返回数据：

{
  "success": true,
  "code": 20000,
  "message": "成功",
  "data": {}
}

失败：

{
  "success": false,
  "code": 20001,
  "message": "失败",
  "data": {}
}

因此，我们定义统一结果：

{
  "success": 布尔, //响应是否成功
  "code": 数字, //响应码
  "message": 字符串, //返回消息
  "data": HashMap //返回数据，放在键值对中
}

一、创建接口定义返回码

public interface ResultCode {

    public static Integer SUCCESS = 20000;

    public static Integer ERROR = 20001;
}

这里的成功状态码和失败状态码可以自己进行修改

二、在公共模块common中编写一个R类

//统一返回值结果
@Data
public class R {

    @ApiModelProperty(value = "是否成功")
    private Boolean success;

    @ApiModelProperty(value = "返回码")
    private Integer code;

    @ApiModelProperty(value = "返回消息")
    private String message;

    @ApiModelProperty(value = "返回数据")
    private Map<String,Object> data=new HashMap<>();

    //构造器私有化：其他类在使用该类时不能够new
    private R(){}

    //返回静态成功方法
    public static R ok(){
        R r=new R();
        r.setSuccess(true);
        r.setCode(ResultCode.SUCCESS);
        r.setMessage("成功");
        return r;
    }

    //返回静态失败方法
    public static R error(){
        R r=new R();
        r.setSuccess(false);
        r.setCode(ResultCode.ERROR);
        r.setMessage("失败");
        return r;
    }

    //为了使用链式编程，以下方法返回值用this
    //R.ok().data()...

    public R success(Boolean success){
        this.setSuccess(success);
        return this;
    }

    public R message(String message){
        this.setMessage(message);
        return this;
    }

    public R code(Integer code){
        this.setCode(code);
        return this;
    }

    public R data(String key, Object value){
        this.data.put(key, value);
        return this;
    }

    public R data(Map<String, Object> map){
        this.setData(map);
        return this;
    }

}

其中的返回值可以由我们自己来定义

三、统一返回结果使用

在其它模块添加统一返回结果类所在的依赖:
例如：

<dependency>
    <groupId>com.atguigu</groupId>
    <artifactId>common_utils</artifactId>
    <version>0.0.1-SNAPSHOT</version>
</dependency>

接着修改controller中返回值的结果：
列表

@ApiOperation(value = "所有讲师列表")
@GetMapping
public R list(){
    List<Teacher> list = teacherService.list(null);
    return R.ok().data("items", list);
}

删除

@ApiOperation(value = "根据ID删除讲师")
@DeleteMapping("{id}")
public R removeById(
    @ApiParam(name = "id", value = "讲师ID", required = true)
    @PathVariable String id){
    teacherService.removeById(id);
    return R.ok();
}