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

统一返回响应

news 2025/6/27 19:38:17

前言

我们为什么要设置统一返回响应

提高代码的可维护性：通过统一返回请求的格式，可以使代码更加清晰和易于维护，减少重复的代码，提高代码质量。
便于调试和测试：统一的返回格式使得在调试和测试时更为简单，可以快速定位和解决问题。
增强系统的可靠性：统一的返回格式有助于保证系统的稳定性和一致性，减少因不同模块返回格式不统一而导致的错误。
提升用户体验：统一的返回格式使得前端处理更加便捷，提高了响应速度，提升了用户体验。
便于日志记录和监控：统一的返回格式便于记录和监控系统的运行状态，方便进行故障排查和性能优化。
简化前后端接口对接：前后端约定统一的返回格式后，接口对接工作会变得更加顺畅，减少沟通成本和开发时间。
提高扩展性：统一的返回格式有利于系统扩展，当需要新增功能或模块时，只需遵循既定的返回格式，无需大规模修改已有代码。
保证数据安全：通过统一的返回格式，可以更好地控制返回的数据内容，避免敏感信息的泄露，提高数据安全性。

确定响应实体

我们首先要定义一个公共的接口响应实体，以后所有的接口返回值，都是返回的这个公共响应实体。
这样做的好处是可以统一返回值的风格，编译接口的维护。
需要包含3个关键的成员变量：

状态码
返回信息
数据

/*** api请求响应实体** @author * @date */
@AllArgsConstructor
@Data
public class ApiResult<T> {/*** 请求成功状态码*/public static final int OK = HttpStatus.HTTP_OK;/*** 接口返回码*/private int code;/*** 接口返回信息*/private String message;/*** 数据*/private T data;
}

确定响应实体工具类

为了更加优雅的创建相应实体类，我们可以增加一个专门的工具类。
这个工具类的职责是创建上面的ApiResult类的实例。
当然有两种情况：

/*** api请求响应实体处理工具类**/
public class ApiResultUtil {private ApiResultUtil() {}/*** 请求成功** @param data 数据* @param <T>  数据类型* @return 接口相应实体*/public static <T> ApiResult<T> success(T data) {return new ApiResult<>(ApiResult.OK, null, data);}/*** 请求成功** @param <T> 数据类型* @return 接口相应实体*/public static <T> ApiResult<T> success() {return success(null);}/*** 请求成功** @param code    返回码* @param message 返回信息* @param <T>     数据类型* @return 接口相应实体*/public static <T> ApiResult<T> error(int code, String message) {return new ApiResult<>(code, message, null);}
}

ApiResultUtil工具类中包含了两个重载的success方法，主要是处理接口请求成功的情况。
而error方法，主要是为了处理接口请求出现异常的情况。
需要注意的是ApiResultUtil类有一个私有的无参构造方法，是为了防止调用者new这个类的实例对象的一种常规做法，很多JDK源码中都有类似的做法。

业务异常

有了上面公共的响应实体类，我们可以先处理异常了。
但异常有两种：

系统异常
业务异常
系统异常我们在统一处理时，错误码都返回500没问题。
但如果有些业务异常，错误码都返回500，这种设计不太合理。
因此，我们需要增加一个专门的业务异常类：BusinessException。

AllArgsConstructor
@Data
public class BusinessException extends RuntimeException {public static final long serialVersionUID = -6735897190745766939L;/*** 异常码*/private int code;/*** 具体异常信息*/private String message;public BusinessException() {super();}
}

这个异常类继承了RuntimeException类，是一种运行时异常，后面好处理。
包含了两个成员变量：

code：表示异常码
message：表示异常信息
比如用户添加接口中，出现用户名称相同时，异常信息可以提示：用户名称重复。

全局异常处理

接下来，我们可以统一处理全局异常了。
在Spring MVC中可以通过@RestControllerAdvice注解处理全局异常：

@Slf4j
@RestControllerAdvice
public class GlobalExceptionHandler {/*** 统一处理异常** @param e 异常* @return API请求响应实体*/@ExceptionHandler(Throwable.class)public ApiResult handleException(Throwable e) {if (e instanceof BusinessException) {BusinessException businessException = (BusinessException) e;log.info("请求出现业务异常：", e);return ApiResultUtil.error(businessException.getCode(), businessException.getMessage());}log.error("请求出现系统异常：", e);return ApiResultUtil.error(HttpStatus.INTERNAL_SERVER_ERROR.value(), "服务器内部错误");}
}

正常接口响应处理


@ControllerAdvice
public class GlobalApiResultHandler implements ResponseBodyAdvice<Object> {@Overridepublic boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {ServletRequestAttributes sra = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();HttpServletRequest request = sra.getRequest();String requestURI = request.getRequestURI();return matchUrl(requestURI);}private boolean matchUrl(String uri) {if (StringUtils.isBlank(uri)) {return false;}return uri.contains("/v1");}@Overridepublic Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType selectedContentType, Class<? extends HttpMessageConverter<?>> selectedConverterType, ServerHttpRequest request, ServerHttpResponse response) {if (body instanceof ApiResult) {return (ApiResult) body;}return ApiResultUtil.success(body);}
}