Restful API统一返回值格式以及Spring Boot应用中统一异常处理

统一返回值

在前后端分离流行的今天，统一的返回值格式不仅可以让我们的界面更美观，也让前端能够统一处理很多事情，避免很多问题。

返回值比较常见的格式如下：

public class Result<T> {
    // 接口调用成功或者失败
    private Integer code = 0;
    // 失败的具体code
    private String errorCode = "";
    // 需要传递的信息，例如错误信息
    private String msg;
    // 需要传递的数据
    private T data;
    ...
}

最原始的接口如下：

    @GetMapping("/test")
    public User test() {
        return new User();
    }

当我们需要统一返回值时，可以使用这个方法：

    @GetMapping("/test")
    public Result test() {
        return Result.success(new User());
    }

这个方法实现接口的返回值统一的目的，但是又出现了一些新的问题：

• 接口的返回值不明显，接口的返回值乍一看不可见。
• 每个接口都需要额外的代码。

幸运的是，Spring Boot为我们提供了更好的解决方案。我们只需要在项目中添加如下代码即可在无需任何知识的情况下为我们统一全局返回值。

/**
 * 全局返回值统一封装
 */
@EnableWebMvc
@Configuration
public class GlobalReturnConfig {

    @RestControllerAdvice
    static class ResultResponseAdvice implements ResponseBodyAdvice<Object> {
        @Override
        public boolean supports(MethodParameter methodParameter, Class<? extends HttpMessageConverter<?>> aClass) {
            return true;
        }

        @Override
        public Object beforeBodyWrite(Object body, MethodParameter methodParameter, MediaType mediaType, Class<? extends HttpMessageConverter<?>> aClass, ServerHttpRequest serverHttpRequest, ServerHttpResponse serverHttpResponse) {
            if (body instanceof Result) {
                return body;
            }
            return new Result(body);
        }
    }
}

我们的界面必须只以其最原始的形式编写。

    @GetMapping("/test")
    public User test() {
        return new User();
    }

异常的统一处理

通过对返回值的统一封装，我们没有考虑到接口抛出异常时的情况。当接口抛出异常时，用户直接看到服务器端的异常肯定不够友好，我们也不可能对每个接口都进行try/catch来处理。此时，我们只需要使用注解 @ExceptionHandler 就可以在无感知的情况下全局统一处理异常。

@RestControllerAdvice
public class GlobalExceptionHandler {

    private static final Logger LOG = LoggerFactory.getLogger(GlobalExceptionHandler.class);

    /**
     * 全局异常处理
     */
    @ExceptionHandler
    public JsonData handleException(HttpServletRequest request, HttpServletResponse response, final Exception e) {
        LOG.error(e.getMessage(), e);
        if (e instanceof AlertException) {//可以在前端Alert的异常
            if (((AlertException) e).getRetCode() != null) {//预定义异常
                return new Result(((AlertException) e).getRetCode());
            } else {
                return new Result(1, e.getMessage() != null ? e.getMessage() : "");
            }
        } else {//其它异常
            if (Util.isProduct()) {//如果是正式环境，统一提示
                return new Result(RetCode.ERROR);
            } else {//测试环境，alert异常信息
                return new Result(1, StringUtils.isNotBlank(e.getMessage()) ? e.getMessage() : e.toString());
            }
        }
    }

}

其中AlertException是我们自定义的异常，所以当企业需要引发错误时，可以手动引发AlertException。

上面是统一处理返回值和统一处理异常的两个步骤。