springboot 统一返回值
为什么SpringBoot要返回统一的标准数据格式?
统一的标准数据格式好处
SpringBoot返回统一的标准数据格式主要有以下几点好处:
增强接口的可读性和可维护性,使得前端开发人员能够更加清晰地理解接口返回的数据结构,从而提高开发效率。
降低前后端耦合度,当后端需要修改返回数据结构时,只需要调整统一的数据格式,而不用修改大量的前端代码。
有利于统一异常处理,对于出错时的返回数据格式也是一致的,便于前端统一处理错误信息。
当接口版本的升级和兼容时,可以通过统一的数据格式进行向下兼容或者向上兼容,减少接口变更带来的影响。
格式不同的痛楚
一般情况下,SpringBoot
服务的返回格式有如下几种:
第一种:返回String
@GetMapping("/hello")
public String getStr() {
return "hello";
}
此时调用接口获取到的返回值是这样:
hello
第二种:返回自定义对象
@GetMapping("/aniaml")
public Aniaml getAniaml(){
Aniaml aniaml = new Aniaml(1,"pig");
return aniaml;
}
此时调用接口获取到的返回值是这样:
{
"id": 1,
"name": "pig"
}
第三种:接口异常
@GetMapping("/error")
public int error(){
int i = 10/0;
return i;
}
此时调用接口获取到的返回值是这样:
{
"timestamp": "2021-07-08T08:05:15.423+00:00",
"status": 500,
"error": "Internal Server Error",
"path": "/error"
}
看了上边的几种情况,不难发现,一个接口在不同情况下,返回的数据格式竟然截然不同?那作为API的使用方就要骂娘了,到底要兼容你多少种数据格式!此时,返回统一的标准数据格式就显得很有必要。
定义返回标准格式
一个标准的返回格式应包含以下三部分:
Status(状态):由后端统一定义各种返回结果的状态码。
Message(描述):描述本次接口调用的结果信息。
Data(数据):包含本次返回的具体数据内容。
{
"status":"100",
"message":"操作成功",
"data":"hello"
}
当然了这并不是绝对的,在有了主要的字段后,可以按需加入其他扩展值,比如我们就在返回对象中添加了接口调用时间timestamp
等。
定义返回对象
@Data
public class ResultData<T> {
private int status;
private String message;
private T data;
private long timestamp ;
public ResultData (){
this.timestamp = System.currentTimeMillis();
}
public static <T> ResultData<T> success(T data) {
ResultData<T> resultData = new ResultData<>();
resultData.setStatus(ReturnCode.RC100.getCode());
resultData.setMessage(ReturnCode.RC100.getMessage());
resultData.setData(data);
return resultData;
}
public static <T> ResultData<T> fail(int code, String message) {
ResultData<T> resultData = new ResultData<>();
resultData.setStatus(code);
resultData.setMessage(message);
return resultData;
}
}
定义状态码
public enum ReturnCode {
/**操作成功**/
RC100(100,"操作成功"),
/**操作失败**/
RC999(999,"操作失败"),
/**服务限流**/
RC200(200,"服务开启限流保护,请稍后再试!"),
/**服务降级**/
RC201(201,"服务开启降级保护,请稍后再试!"),
/**热点参数限流**/
RC202(202,"热点参数限流,请稍后再试!"),
/**系统规则不满足**/
RC203(203,"系统规则不满足要求,请稍后再试!"),
/**授权规则不通过**/
RC204(204,"授权规则不通过,请稍后再试!"),
/**access_denied**/
RC403(403,"无访问权限,请联系管理员授予权限"),
/**access_denied**/
RC401(401,"匿名用户访问无权限资源时的异常"),
/**服务异常**/
RC500(500,"系统异常,请稍后重试"),
CLIENT_AUTHENTICATION_FAILED(1001,"客户端认证失败"),
USERNAME_OR_PASSWORD_ERROR(1002,"用户名或密码错误"),
UNSUPPORTED_GRANT_TYPE(1003, "不支持的认证模式");
/**自定义状态码**/
private final int code;
/**自定义描述**/
private final String message;
ReturnCode(int code, String message){
this.code = code;
this.message = message;
}
public int getCode() {
return code;
}
public String getMessage() {
return message;
}
}
统一返回格式
经过上边我们定义的数据格式,再次调用API,在Controller
层通过ResultData.success()
对返回结果进行包装后返回给前端。
@GetMapping("/hello")
public String getStr() {
return ResultData.success("hello");
}
此时调用接口获取到的返回值已经是标准的格式,符合我们预期的效果
{
"status": 100,
"message": "hello",
"data": null,
"timestamp": 1625736481648
}
最大的弊端就是我们后面每写一个接口都需要调用ResultData.success()
这行代码对结果进行包装,重复劳动,浪费体力;
而且还很容易被其他老鸟给嘲笑。
所以呢我们需要对代码进行优化,目标就是不要每个接口都手工制定ResultData
返回值。
高级实现方式
要优化这段代码很简单,我们只需要借助SpringBoot提供的ResponseBodyAdvice
即可。
“
ResponseBodyAdvice的作用:拦截Controller方法的返回值,统一处理返回值/响应体,一般用来统一返回格式,加解密,签名等等。
”
先来看下ResponseBodyAdvice
的源码:
public interface ResponseBodyAdvice<T> {
/**
* 是否支持advice功能
* true 支持,false 不支持
*/
boolean supports(MethodParameter var1, Class<? extends HttpMessageConverter<?>> var2);
/**
* 对返回的数据进行处理
*/
@Nullable
T beforeBodyWrite(@Nullable T var1, MethodParameter var2, MediaType var3, Class<? extends HttpMessageConverter<?>> var4, ServerHttpRequest var5, ServerHttpResponse var6);
}
我们只需要编写一个具体实现类即可
/**
* @author jam
* @date 2021/7/8 10:10 上午
*/
@RestControllerAdvice
public class ResponseAdvice implements ResponseBodyAdvice<Object> {
@Autowired
private ObjectMapper objectMapper;
@Override
public boolean supports(MethodParameter methodParameter, Class<? extends HttpMessageConverter<?>> aClass) {
return true;
}
@SneakyThrows
@Override
public Object beforeBodyWrite(Object o, MethodParameter methodParameter, MediaType mediaType, Class<? extends HttpMessageConverter<?>> aClass, ServerHttpRequest serverHttpRequest, ServerHttpResponse serverHttpResponse) {
if(o instanceof String){
return objectMapper.writeValueAsString(ResultData.success(o));
}
return ResultData.success(o);
}
}
需要注意两个地方:
@RestControllerAdvice
注解@RestControllerAdvice
是@RestController
注解的增强,可以实现三个方面的功能:
全局异常处理
全局数据绑定
全局数据预处理
- String类型判断
if(o instanceof String){
return objectMapper.writeValueAsString(ResultData.success(o));
}
这段代码一定要加,如果Controller直接返回String的话,SpringBoot是直接返回,故我们需要手动转换成json。
经过上面的处理我们就再也不需要通过ResultData.success()
来进行转换了,直接返回原始数据格式,SpringBoot自动帮我们实现包装类的封装。
@GetMapping("/hello")
public String getStr(){
return "hello";
}
此时我们调用接口返回的数据结果为:
@GetMapping("/hello")
public String getStr(){
return "hello";
}
是不是感觉很完美,别急,还有个问题在等着你呢。
接口异常问题
此时有个问题,由于我们没对Controller的异常进行处理,当我们调用的方法一旦出现异常,就会出现问题,比如下面这个接口
@GetMapping("/wrong")
public int error(){
int i = 9/0;
return i;
}