API统一返回数据格式

如今的项目，基本上都是前后端分离，而且前端的生态也已经很强大。后端基本上只要保证数据响应就可以了。

那么，接口交互就成了前后端对接最重要也是最耗时的工作。而提高交互效率的最好的方法就是统一数据格式，后端把数据丢到一个统一的格式中去，前端解析数据也从固定的格式中去取。这样，前端就省去复杂的无关数据解析，能直接拿到想要的数据。后端也只需要把数据丢到固定的格式中去，不用每次都要包装一下。

格式统一

达到目的的第一步，自然就是统一返回数据的格式。目前互联网公司通用的格式一般如下：

{
   
	# 状态码
	"code": integer,
	# 提示信息
	"message": string,
	# 响应数据
	"data": object
}

下面解释一下三个字段的意义和用法。

code

返回个前端的状态码，用来表示这个请求的结果。为了便于理解，后端设计的时候最好和http状态码意义一样。即：

状态值	意义
1xx	信息，服务器已经接收到请求，需要请求者继续执行操作
2xx	成功，服务器正确接收请求并已处理
3xx	重定向，需要客户端进一步的操作以完成请求
4xx	客户端错误，请求语法错误或者无法完成请求
5xx	服务器端错误，服务端在处理请求的时候发生了错误

设计的时候就可以参考http的状态码以便于客户端更好的理解。另外，考虑的业务场景远多于http状态，可以适当加多位数，下面以4位为例，设计一个简单的状态码，这只是一个demo，大家根据自己的业务场景自行设计。

状态值范围	意义
2000~2999	业务操作代码，表示后台处理成功，需要响应给前端此业务的处理情况，如申请xxx业务成功，开通xxx业务失败（此失败不是后台报错，而是业务失败，比如用户开通xxx业务需要某个必要条件而没有满足，所以对于服务器来说是处理成功了）
4000~4999	针对客户端的状态码，如传递的参数错误，权限不足等
5000~5999	针对接口异常

message

对接口返回的结果进行友好的提示。以便于客户端知道，到底发生了什么。这个message一般而言，是和code一一对应的。

比如：

code	message
4001	xx参数无效
4002	xx参数不能为空
4003	参数不完整，缺少xx参数

通过枚举，可以方便快捷的维护code和message的对应关系。

data

需要返回给前端的数据。这个data内的数据一定要是JSON格式，方便前端的解析。

进一步优化

要返回给前端的数据常见的有2个大类：

1. 业务操作结果

业务操作的过程，能否封装、优化要看实际情况，但是业务操作的最终结果，即最终得到的要返回给前端的数据，可以使用AOP统一封装的前面提到的统一格式中，而不用每次手动封装。

2. 参数校验结果

参数的校验如果不使用第三方库，会在代码中多出很多的冗余代码，所以，最好使用oval、hibernate validate或者Spring等参数校验方式，可以大幅度美观代码。

业务操作结果返回优化

1. 注解

import java.lang.annotation.*;

@Retention(value = RetentionPolicy.RUNTIME)
@Target(value = {
   ElementType.TYPE, ElementType.METHOD})
@Documented
public @interface Result