当前位置：首页 > news >正文

Spring Boot接口返回统一格式

news 来源：原创 2025/7/15 5:37:03

统一的标准数据格式好处

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);/*** 对返回的数据进行处理*/@NullableT 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> {@Autowiredprivate ObjectMapper objectMapper;@Overridepublic boolean supports(MethodParameter methodParameter, Class<? extends HttpMessageConverter<?>> aClass) {return true;}@SneakyThrows@Overridepublic 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;
}

统一的标准数据格式好处

格式不同的痛楚

标准格式

定义返回对象

定义状态码

统一返回格式

高级实现方式

相关文章：