如何设计 API 接口，实现统一格式返回

文章目录

1.接口相互作用

前端和前端进行交互，前端按约定的请求URL路径，并合并相关参数，进入服务器接收请求，进行业务处理，返回数据给前端。

2.返回格式

{
  #返回状态码
  code:integer,
  #返回信息描述
  message:string,
  #返回值
  data:object
}

：下面是常见的HTTP状态码：
200 - 请求成功
301 - 资源（网页等）被永久转移到其它URL
404 - 请求的资源（网页等）不存在
500 - 内部服务器错误

我们可以参考这样的设计，这样的好处就把错误类型归类到某个区间内，如果区间不够，可以设计成4个数字。

#1000～1999 区间表示参数错误
#2000～2999 区间表示用户错误
#3000～3999 区间表示接口异常

这样前端开发人员在得到返回值后，根据状态码就可以知道，大概什么错误，再根据消息相关的信息描述，可以快速定位。

状态码和信息就会一一对应，比较好维护。

3.数据

返回数据体，JSON格式，根据不同的业务又不同的JSON体。

我们要设计一个返回体类结果

4.控制层控制器

我们会在控制器层处理业务请求，并返回给前端，以orderorder为例

5.美观美化

问题:

• 每个方法的返回都是Result封装对象，没有业务含义
• 在业务代码中，成功的时候我们调用Result.success，异常错误调用Result.failure。是不是很多余
• 上面的代码，判断id是否为null，实际上我们可以使用hibernate validate做校验，没有必要在方法体中做判断。

6.优雅优化

• 定义一个注解@ResponseResult，表示此接口返回的值需要包装一下
• 拦截请求，判断此请求是否需要被@ResponseResult注解
• 核心步骤就是实现接口ResponseBodyAdvice和@ControllerAdvice，判断是否需要包装返回值，如果需要，就把控制器接口的返回值进行转换。

拦截器

拦截请求，是否此请求返回的值需要包装，实际上就是运行的时候，解析@ResponseResult注解

改造控制器

在控制器类上或者方法体上加上@ResponseResult注解

7.其他优化方案

次请求都要反射一下，获取请求的方法是否需要包装，其实可以做个缓存，不需要每次都需要解析。