Spring或Spring Boot无侵入实现接口统一返回

作者: felixu | 来源:发表于2020-09-05 21:19 被阅读0次

问题描述

不知道你们有没有过这样的经历，项目已经经历了几个版本，但是始终没有做过统一返回，突然某一版要做统一返回格式，包括统一异常拦截处理也一起统一，比如统一成如下常用格式

{
    "code": 0;
    "message": "成功";
    "data": {}
}

如果要改代码这心态得崩啊，接口少的话倒是问题也不大，但是像我们接口比较多的情况下，改代码的话可能会想死，而且还有原先抛的自定义异常，我们处理后返回的结果如下：

{
    "code": aaa.bbb.ccc;
    "message": "某某操作不合法";
    "detail": {}                // 详细描述，不一定存在
}

这与我们想要统一的结构也不太一样，而且HTTP状态码也并非200，我们现在希望都返回200，code来标识结果是否为正确返回，这直接原来抛异常的处理也不能用了，而这个异常的拦截处理又是在我们通用的web stater中去处理的，如果直接改造，这无疑将带来巨大的工作量。

可能这么说无法体会到这之中的工作量，那就详细说一下

Controller 中现有的写法：

@PostMapping("/test13")
public TestClass test13(@RequestBody @Validated TestClass test) {
    return test;
}

@Data
public static class TestClass {
    @NotNull
    private String name;

    @NotBlank
    private String address;
}

这到前端之间就一个TestClass返回了

{
    "name": felixu;
    "address": 杭州
}

但是我们希望的结构是：

{
    "code": 0;
    "message": "成功";
    "data": {
        "name": felixu;
        "address": 杭州
    }
}

这就需要对然后结果做包装，不然全部接口都得改成

@PostMapping("/test13")
public RespDTO<TestClass> test13(@RequestBody @Validated TestClass test) {
    return RespDTO.onSuc(test);
}

另一个就是原有的自定义异常：

@GetMapping("/test1")
public String test1() {
    throw new BusinessException("param.error");
}

它会被我们web stater中的统一异常处理器所处理：

@Slf4j
@RestControllerAdvice
public class ExceptionResolver {
    /**
     * i18n 消息源
     */
    private final MessageSource messageSource;

    public ExceptionResolver(MessageSource messageSource, Environment environment) {
        this.messageSource = messageSource;
    }

    @ExceptionHandler(value = BusinessException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public ErrorResponse<?> bizExceptionHandler(BusinessException ex,
                                                HttpServletRequest request) {
        String code = ex.getMessage();
        //优先从代码传递里获取异常描述，再从定义业务出错码的文件里获取
        String message = MoreObjects.firstNonNull(ex.getI18nDesc(), messageSource.getMessage(code, ex.getArgs(), code, LocaleContextHolder.getLocale()));
        return ErrorResponse.of(code, message);
    }

然后在国际化文件中配有：

param.error=您提交的数据不符合要求

这样到前端就是如下结果：

{
    "code": "param.error";
    "message": "您提交的数据不符合要求"
}

而这跟我们提到的结构明显不一致，首先统一异常处理得改，第二点要兼容代码中原有的如throw new BusinessException("param.error");的写法，因为经过几次迭代了，代码中存在大量的这种写法。

所以我就在想有么有没有什么“投机取巧”的方式。

问题分析

基于以上描述，我们发现要做以下事情：

对所有的Controller中接口返回结果做包装，将其处理为我们的统一返回结构；
需要重新定义统一异常拦截处理，并取代web stater中的异常处理；
兼容代码中原有的抛异常处理，并保留国际化处理。

至于为啥要改，前面版本为啥要这么做，国际化为啥在后端，我只想说emmmm，毕竟我只是个搬砖的，好了，既然要干，那就想想办法吧。

解决问题

首先是解决code的维护，我们定义一个ErrorCode来存储code，而且原有代码中抛的英文串肯定要在这个类中也映射上，所以可以看到比如之前的param.error会对应到一个PARAM_ERROR(100, "param.error")枚举项，并且定义parse方法，将原先的字符串映射到枚举项：

@Getter
@AllArgsConstructor
public enum ErrorCode {

    /*-------------------------------- 成功 ------------------------------*/
    OK(0, "成功"),

    /*------------------- 失败(大多为没有被处理到的特殊异常) ------------------*/
    FAIL(-1, "internal.server.error"),
    MISSING_CODE(-2, "missing.code"),
   
    /*-------------------------------- 通用异常 ------------------------------*/
    PARAM_ERROR(100, "param.error"),
    ;

    /**
     * 返回的 code，非 0 表示错误
     */
    private final int code;

    /**
     * 发生错误时的描述
     */
    private final String message;

    /**
     * 由于经过很长时间的迭代，才出现要统一返回，统一异常 code
     * 故而兼容原 BusinessException 和 SystemException 解析到 ErrorCode
     * 避免大规模改代码
     * 后续可能会逐步移除
     */
    public static ErrorCode parse(String message) {
        for (ErrorCode value : ErrorCode.values()) {
            if (value.message.equals(message))
                return value;
        }
        return MISSING_CODE;
    }
}

其次既然要做统一返回，首先我们需要定义一个统一返回的结构体：

@Data
@AllArgsConstructor
public class RespDTO<T> {

    /**
     * 返回的 code 码
     */
    private int code;

    /**
     * 发生错误时的错误信息
     */
    private String message;

    /**
     * 成功返回时的真正数据集
     */
    private T data;

    /**
     * 成功返回且无任何数据返回
     */
    public static <T> RespDTO<T> onSuc() {
        return onSuc(null);
    }

    /**
     * 成功返回且需要传入真正被返回的数据
     */
    public static <T> RespDTO<T> onSuc(T data) {
        return build(ErrorCode.OK.getCode(), ErrorCode.OK.getMessage(), data);
    }

    /**
     * 错误返回时，放入错误类型的枚举
     */
    public static <T> RespDTO<T> onFail(ErrorCode error) {
        return onFail(error.getCode(), error.getMessage());
    }

    /**
     * 错误返回时，放入错误的 code 码以及错误信息
     */
    public static <T> RespDTO<T> onFail(int code, String message) {
        return build(code, message, null);
    }
    
    private static <T> RespDTO<T> build(int code, String message, T data) {
        return new RespDTO<>(code, message, data);
    }
}

完成以上定义，接下来便是改造工作了，对于Controller的包装，这让我想起来ResponseBodyAdvice接口，他的Java doc上有如下注释：

/**
 * Allows customizing the response after the execution of an {@code @ResponseBody}
 * or a {@code ResponseEntity} controller method but before the body is written
 * with an {@code HttpMessageConverter}.
 *
 * <p>Implementations may be registered directly with
 * {@code RequestMappingHandlerAdapter} and {@code ExceptionHandlerExceptionResolver}
 * or more likely annotated with {@code @ControllerAdvice} in which case they
 * will be auto-detected by both.
 *
 * @author Rossen Stoyanchev
 * @since 4.1
 */

他说允许我们在执行完@ResponseBody或者ResponseEntity的控制器方法之后，但是在HttpMessageConverter执行之前做自定义的响应。下面一段则是告诉我们该怎么做以及怎么被处理的了，不想涉及太多原理，便暂且忽略。所以我们做如下实现：

@RestControllerAdvice
public class BaseResponseAdvice implements ResponseBodyAdvice<Object> {

    @Value("${api-full-prefix:}")
    private String prefix;

    // 该方法用于确定是否被处理，这里直接所有请求均处理
    @Override
    public boolean supports(MethodParameter returnType, 
                            Class<? extends HttpMessageConverter<?>> converterType) {
        return true;
    }

    // 该方法用于处理包装返回
    @Override
    public Object beforeBodyWrite(Object body, 
                                  MethodParameter returnType, 
                                  MediaType contentType,
                                  Class<? extends HttpMessageConverter<?>> converterType,
                                  ServerHttpRequest request, 
                                  ServerHttpResponse response) {
        ServletServerHttpResponse servletServerHttpResponse = (ServletServerHttpResponse) response;
        HttpServletResponse realResponse = servletServerHttpResponse.getServletResponse();
        // 均返回 Json 格式
        // 主要是为了处理 body 为 String 类型时，后面的 JsonMapper.toNonNullJson(resp) 后
        // 将会以 content-type 为 text/plain 返回 Json 字符串
        realResponse.setContentType(MediaType.APPLICATION_JSON_VALUE);
        // 没有返回，直接返回 RespDTO.onSuc() 这样能将 void 返回一起处理
        if (body == null)
            return RespDTO.onSuc();
        // 已经是 RespDTO(避免被包两层) 或者不是项目路径开头直接返回(避免其他框架如 Swagger 等的请求被包装)，不要杠我用 contains 毕竟某些有苦不能言
        if (body instanceof RespDTO || !request.getURI().getPath().contains(prefix))
            return body;
        // 其他类型直接包装
        RespDTO<Object> resp = RespDTO.onSuc(body);
        // 如果是 String 需要单独处理，不然 RespDTO 继续被 StringHttpMessageConverter 处理会报错
        return (body instanceof String) ? JsonMapper.toNonNullJson(resp) : resp;
    }
}

这便是我的实现了，其中有较详细的注释，便不再多解释，到此原有的返回便已经可以处理了，需要注意的就是String类型的返回需要单独处理，不然会报类型转换异常。

接下来便是处理原有的异常了，可是这个在web stater中已经定义过了，而这个类是无法被如exclude方法排除的，这里就需要定义一个统一异常拦截处理了，想必这个都不陌生吧，然后我们需要调整多个ControllerAdvice的执行顺序，当然，为了方便，不再直接在代码里面做类似throw new BusinessException("param.error");而改成throw new MyException(ErrorCode.PARAM_ERROR)这种形式，也对上层包中的BusinessException做了扩展，类似：

@Getter
public class MyException extends BusinessException {

    private final ErrorCode error;

    private final Object[] args;

    private final String i18nDesc;

    public MyException(ErrorCode error) {
        super(error.getMessage());
        this.error = error;
        this.args = null;
        this.i18nDesc = null;
    }

    public MyException(ErrorCode error, Object... args) {
        super(error.getMessage(), args);
        this.error = error;
        this.args = args;
        this.i18nDesc = null;
    }

    public MyException(ErrorCode error, String i18nDesc, Object... args) {
        super(error.getMessage(), i18nDesc, args);
        this.error = error;
        this.args = args;
        this.i18nDesc = i18nDesc;
    }
}

我们原有的异常：

@Getter
public class BusinessException extends RuntimeException {

    private final Object[] args;
    
    private final String i18nDesc;

    /**
     * @param code 异常错误code，非message
     */
    public BusinessException(String code) {
        this(code, (String) null);
    }

    /**
     * 需要带错误码及出错提示内容出来（动态内容，无法在拦截地方properties文件定义）
     *
     * @param code 异常code
     * @param i18nDesc  国际化翻译
     */
    public BusinessException(String code, String i18nDesc) {
        this(code, i18nDesc, (Object[]) null);
    }

    /**
     * @param code 错误码
     * @param i18nDesc  国际化翻译
     * @param args i18n 业务参数
     */
    public BusinessException(String code, String i18nDesc, Object... args) {
        super(code);
        this.args = args;
        this.i18nDesc = i18nDesc;
    }

    public BusinessException(String code, Object[] args) {
        this(code, null, args);
    }
}

接下来就统一异常拦截处理了：

@Slf4j
@RestControllerAdvice
// 调整该异常处理器的执行顺序，让其优先于 web stater 包中的执行，包中的便不再执行
@Order(1)
public class MyExceptionHandler {

    /**
     * i18n 消息源
     */
    private final MessageSource messageSource;

    public MyExceptionHandler(MessageSource messageSource, Environment environment) {
        this.messageSource = messageSource;
    }

    @ExceptionHandler(MyException.class)
    public ResponseEntity<RespDTO<?>> MyExceptionHandler(MyException ex, 
                                                           HttpServletRequest request) {
        log.debug("业务异常：{} {}", request.getMethod(), request.getRequestURI(), ex);
        ErrorCode error = ex.getError();
        String message = MoreObjects.firstNonNull(null, messageSource.getMessage(error.getMessage(), ex.getArgs(), error.getMessage(), LocaleContextHolder.getLocale()));
        return new ResponseEntity<>(RespDTO.onFail(error.getCode(), message), HttpStatus.OK);
    }

    @ExceptionHandler(BusinessException.class)
    public ResponseEntity<RespDTO<?>> bizExceptionHandler(BusinessException ex, 
                                                          HttpServletRequest request) {
        log.debug("业务异常：{} {}", request.getMethod(), request.getRequestURI(), ex);
        String code = ex.getMessage();
        ErrorCode error = ErrorCode.parse(code);
        Object[] args = ex.getArgs();
        if (error == ErrorCode.MISSING_CODE)
            args = new String[]{code};
        String message = MoreObjects.firstNonNull(ex.getI18nDesc(), messageSource.getMessage(error.getMessage(), args, code, LocaleContextHolder.getLocale()));
        return new ResponseEntity<>(RespDTO.onFail(error.getCode(), message), HttpStatus.OK);
    }
    .
    .
    .
    // 其他异常的处理省略
}

总结一下这里的操作：

通过@order(1)调整多个@RestControllerAdvice的顺序，让当前定义的执行，其他的不再执行
对于新拓展的异常，直接从枚举中拿到message，之后去国际化文件中获取真正的message信息，封装为统一结构体后返回
原有的异常，我们先将其解析为ErrorCode，再取ErrorCode中的message，完事之后再去取国际化后的message信息，封装为我们的统一返回体

结语

每个领导对于架构上的认知都不一样，这种变化是不可控的，但是作为搬砖的我，该偷懒的时候还是要偷懒的，一个短的迭代周期要去改一大堆代码这种事情我是不想去干的。
感觉迟早要写@RestControllerAdvice的原理？？？？

Spring或Spring Boot无侵入实现接口统一返回

问题描述

问题分析

解决问题

结语

相关文章

网友评论

延伸阅读

深度阅读

栏目导航

热点阅读