Spring Boot 统一数据返回格式

在 Spring Boot 项目中，统一的数据格式返回是一种良好的实践，它提高了代码的可维护性和一致性，并改善了客户端与服务端之间的通信。本文将介绍如何在 Spring Boot 中实现统一的数据格式返回。

---

1 为什么需要统一数据返回格式

1. ⽅便前端程序员更好的接收和解析后端数据接⼝返回的数据。
2. 降低前端程序员和后端程序员的沟通成本，按照某个格式实现就⾏了，因为所有接⼝都是这样返回的。
3. 有利于项⽬统⼀数据的维护和修改。
4. 有利于后端技术部⻔的统⼀规范的标准制定，不会出现稀奇古怪的返回内容。

2 统一数据返回格式的实现

统⼀的数据返回格式可以使⽤ @ControllerAdvice + ResponseBodyAdvice 的⽅式实现。

• @ControllerAdvice是Spring框架提供的一个用于全局处理控制器的增强器注解。通过@ControllerAdvice注解的类，可以将对应的增强逻辑应用到所有的@Controller注解的控制器中。
• @ResponseBodyAdvice是一个用于处理响应体的接口。通过实现这个接口，可以在Controller方法返回之前和之后对响应体进行处理。

具体实现如下：

2.1 创建统一响应类

首先，我们需要创建一个统一的响应类，用于封装 API 返回的数据：

public class ApiResponse<T> {private int status;private String message;private T data;public ApiResponse(int status, String message, T data) {this.status = status;this.message = message;this.data = data;}// Getters and Setters
}

2.2 创建统一响应处理类

这里使用@controller注解和ResponseBodyAdvice来实现

@ControllerAdvice
public class GlobalResponseBodyAdvice implements ResponseBodyAdvice<Object> {@Overridepublic boolean supports(MethodParameter returnType, Class converterType) {// 判断是否需要处理响应体return true;}@Overridepublic Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType selectedContentType,Class selectedConverterType, ServerHttpRequest request, ServerHttpResponse response) {// 包装响应体if (body instanceof ApiResponse) {return body;}return new ApiResponse<>(HttpStatus.OK.value(), "Success", body);}
}

为了保证异常也能返回统一的数据格式，我们需要创建一个全局异常处理类，博客 讲解了Spring Boot中如何进行统一异常处理。

@ControllerAdvice //添加完此注解后，此类随着springboot项目的启动而启动，并且会监控controller的异常.监听项目中所有的异常
@ResponseBody
public class MyExceptionAdvice {//这里的一场都是意外异常，并不是业务异常，业务异常后端controller会处理返回给前端.业务异常会和前端沟通好已规定的状态码返回。@ExceptionHandler(NullPointerException.class)public ApiResponse<String> doNullPointerException(NullPointerException e){ApiResponse<String> apiResponse = new ApiResponse<>(HttpStatus.INTERNAL_SERVER_ERROR.value(), e.getMessage(), null);return apiResponse;}// 默认的异常处理，当有有异常出现的时候，会先匹配子类的异常，当所有的异常都没有匹配的时候就会走这一条默认的一场路线业务。@ExceptionHandler(Exception.class)public ApiResponse<String> doException(Exception e){ApiResponse<String> apiResponse = new ApiResponse<>(HttpStatus.INTERNAL_SERVER_ERROR.value(), e.getMessage(), null);return apiResponse;}
}

2.3 controller模拟数据并返回

观察异常出现情况下和正常访问情况下，是否都实现了统一格式返回。

@RestController
@RequestMapping("/user")
public class UserController {@RequestMapping("login")public String login(){Object obj = null;System.out.println(obj.hashCode());return  "这里是login";}@GetMapping("/data")public User getUserData() {// 这个方法会返回一个User对象User user = new User();user.setId(1);user.setName("张三");user.setEmail("[e-mail]");return user;}@GetMapping("/success")public Integer getSuccessMessage() {// 这个方法会返回一个简单的字符串return 123456;}
}

访问：127.0.0.1:8080/user/login 可以看到异常信息被统一处理并统一格式后返回。

访问127.0.0.1:8080/user/data ，可以看到接收到的数据也被统一处理。

访问127.0.0.1:8080/user/success ，可以看到接收到的数据也被统一处理。

---

 总结

通过上述步骤，我们实现了使用@ControllerAdvice和ResponseBodyAdvice统一API数据返回格式的功能。这种方式不仅简化了代码，还使得API响应格式一致，更加规范和易于维护。