一线大厂的最佳实践 - API 错误处理

-

1

-

API 中的错误如何定义，请求过程中出错或请求处理中出错。API 无法解析传递的数据，API 本身有很多问题，甚至格式正确的请求也会进行失败。在这两种情况下，都需要进行分析查找原因。

无论是代码形式的错误还是简单的错误响应，错误代码可能是 API 领域中最有用的诊断元素，错误代码非常有用。API 响应阶段中的错误代码是开发人员可以将故障传达给用户的基本方式。

curl https://graph.facebook.com/v2.9/me?fields=id%2Cname%2Cpicture%2C%20picture&access_token=xxxxxxxxxxx

curl https://api.twitter.com/1.1/statuses/mentions_timeline.json

请求处理中出错

{

"domain": "order",

"code": 111501002,

"message": "支付通道网络异常"

}

{

"domain": "user",

"code": 100501001,

"message": "对应的用户不存在！"

}

错误代码详细说明：

• domain 定义了领域，方便定位错误的根源。

• code 定义了内部错误的编码

• message 描述了错误的原因

• error 对部分具体性错误进行了详细的说明

code 补充说明：异常码说明是由 8位 数字组成，前三位系统标识（从100开始），中间两位是模块标识（业务划分），后三位是异常标识（特定异常）

error 补充说明：当 message 不能准确描述错误产生的原因，需要细化每项错误说明时，可考虑使用 error 字段，来补充说明错误项。

domain 补充说明：底层框架里面封装了部分异常处理，比如参数校验错误这种 code 应该是全系统共用的，而不会有系统标识。导致就不能根据 code 识别出来是哪个系统发生错误了，链路一长就很难排查到底是哪的问题了，所以错误处理中动态去拿当前应用的业务域标识。

异常拦截器处理

Spring Boot 的项目已经对有一定的异常处理了，但是比较泛化不够精细化，因此需要基础框架对这些异常进行统一的捕获并处理。Spring Boot 中有一个 @RestControllerAdvice  的注解，使用该注解表示开启了全局异常的捕获，我们只需在自定义一个方法使用 ExceptionHandler 注解然后定义捕获异常的类型即可对这些捕获的异常进行统一的处理。

定义异常基础类

import lombok.AllArgsConstructor;

import lombok.Getter;

import lombok.NoArgsConstructor;

/**

* 扩展异常

*

* @author Weichao Li ([email protected])

* @since 2019-08-11

*/

@Getter

@NoArgsConstructor

@AllArgsConstructor

public class ExtensionException extends RuntimeException {

/**

* 业务异常码 ( 详情参加文档说明 )

*/

private Long code;

/**

* 业务异常信息

*/

private String message;

/**

* 额外数据，可支持扩展

*/

private Object data;

/**

* cause

*/

private Throwable cause;

public ExtensionException(Long code, String message) {

this.code = code;

this.message = message;

}

}

全局异常处理器 - 信息枚举

import lombok.Getter;

/**

* WebMvc 模块异常码定义

* <p>

* 系统标识：100

* 模块标识：02

*

* @author Weichao Li (liweichao0102@gmail.com)

* @since 2019-08-11

*/

@Getter

public enum EnumExceptionMessageWebMvc {

// 非预期异常

UNEXPECTED_ERROR(10002000L, "服务发生非预期异常，请联系管理员！"),

PARAM_VALIDATED_UN_PASS(10002001L, "参数校验(JSR303)不通过，请检查参数或联系管理员！"),

NO_HANDLER_FOUND_ERROR(10002002L, "未找到对应的处理器，请检查 API 或联系管理员！"),

HTTP_REQUEST_METHOD_NOT_SUPPORTED_ERROR(10002003L, "不支持的请求方法，请检查 API 或联系管理员！"),

HTTP_MEDIA_TYPE_NOT_SUPPORTED_ERROR(10002004L, "不支持的互联网媒体类型，请检查 API 或联系管理员"),

;

private final Long code;

private final String message;

EnumExceptionMessageWebMvc(Long code, String message) {

this.code = code;

this.message = message;

}

}

全局异常处理器

import com.github.hicolors.best.practices.exception.ExtensionException;

import com.github.hicolors.best.practices.pojo.Result;

import lombok.extern.slf4j.Slf4j;

import org.springframework.beans.factory.annotation.Value;

import org.springframework.validation.BindException;

import org.springframework.validation.FieldError;

import org.springframework.web.HttpMediaTypeNotSupportedException;

import org.springframework.web.HttpRequestMethodNotSupportedException;

import org.springframework.web.bind.MethodArgumentNotValidException;

import org.springframework.web.bind.annotation.ExceptionHandler;

import org.springframework.web.bind.annotation.RestControllerAdvice;

import org.springframework.web.servlet.NoHandlerFoundException;

import javax.servlet.http.HttpServletRequest;

import javax.servlet.http.HttpServletResponse;

import javax.validation.ConstraintViolation;

import javax.validation.ConstraintViolationException;

import java.text.MessageFormat;

import java.util.Objects;

/**

* ExceptionHandlerAdvice

*

* @author Weichao Li (liweichao0102@gmail.com)

* @since 2019/11/25

*/

@RestControllerAdvice

@Slf4j

public class ExceptionHandlerAdvice {

//业务领域标识，首先去配置中的业务领域标识，没有之后取应用名称，最后取默认值

@Value("${spring.application.domain:${spring.application.name:unknown-spring-boot}}")

private String domain;

/**

* 针对业务异常的处理

*

* @param exception 业务异常

* @param request http request

* @param response http response

* @return 异常处理结果

*/

@ExceptionHandler(value = ExtensionException.class)

public Result extensionException(ExtensionException exception, HttpServletRequest request,

HttpServletResponse response) {

log.warn("请求发生了预期异常，出错的 url [{}]，出错的描述为 [{}]", request.getRequestURL().toString(), exception.getMessage());

Result result = new Result();

result.setDomain(domain);

result.setCode(exception.getCode());

result.setMsg(exception.getMessage());

Object data = exception.getData();

if (Objects.nonNull(data)) {

// todo 策略调整

}

return result;

}

/**

* 针对参数校验失败异常的处理

*

* @param exception 参数校验异常

* @param request http request

* @param response http response

* @return 异常处理结果

*/

@ExceptionHandler(value = {BindException.class, MethodArgumentNotValidException.class, ConstraintViolationException.class})

public Result databindException(Exception exception, HttpServletRequest request, HttpServletResponse response) {

log.error(MessageFormat.format("请求发生了非预期异常，出错的 url [{0}]，出错的描述为 [{1}]",

request.getRequestURL().toString(), exception.getMessage()), exception);

Result result = new Result();

result.setDomain(domain);

result.setCode(EnumExceptionMessageWebMvc.PARAM_VALIDATED_UN_PASS.getCode());

result.setMsg(EnumExceptionMessageWebMvc.PARAM_VALIDATED_UN_PASS.getMessage());

if (exception instanceof BindException) {

for (FieldError fieldError : ((BindException) exception).getBindingResult().getFieldErrors()) {

result.addError(fieldError.getField(), fieldError.getDefaultMessage());

}

} else if (exception instanceof MethodArgumentNotValidException) {

for (FieldError fieldError : ((MethodArgumentNotValidException) exception).getBindingResult().getFieldErrors()) {

result.addError(fieldError.getField(), fieldError.getDefaultMessage());

}

} else if (exception instanceof ConstraintViolationException) {

for (ConstraintViolation cv : ((ConstraintViolationException) exception).getConstraintViolations()) {

result.addError(cv.getPropertyPath().toString(), cv.getMessage());

}

}

return result;

}

/**

* 针对spring web 中的异常的处理

*

* @param exception Spring Web 异常

* @param request http request

* @param response http response

* @return 异常处理结果

*/

@ExceptionHandler(value = {

NoHandlerFoundException.class,

HttpRequestMethodNotSupportedException.class,

HttpMediaTypeNotSupportedException.class

})

public Result springWebExceptionHandler(Exception exception, HttpServletRequest request, HttpServletResponse response) {

log.error(MessageFormat.format("请求发生了非预期异常，出错的 url [{0}]，出错的描述为 [{1}]",

request.getRequestURL().toString(), exception.getMessage()), exception);

Result result = new Result();

result.setDomain(domain);

if (exception instanceof NoHandlerFoundException) {

result.setCode(EnumExceptionMessageWebMvc.NO_HANDLER_FOUND_ERROR.getCode());

result.setMsg(EnumExceptionMessageWebMvc.NO_HANDLER_FOUND_ERROR.getMessage());

} else if (exception instanceof HttpRequestMethodNotSupportedException) {

result.setCode(EnumExceptionMessageWebMvc.HTTP_REQUEST_METHOD_NOT_SUPPORTED_ERROR.getCode());

result.setMsg(EnumExceptionMessageWebMvc.HTTP_REQUEST_METHOD_NOT_SUPPORTED_ERROR.getMessage());

} else if (exception instanceof HttpMediaTypeNotSupportedException) {

result.setCode(EnumExceptionMessageWebMvc.HTTP_MEDIA_TYPE_NOT_SUPPORTED_ERROR.getCode());

result.setMsg(EnumExceptionMessageWebMvc.HTTP_MEDIA_TYPE_NOT_SUPPORTED_ERROR.getMessage());

} else {

result.setCode(EnumExceptionMessageWebMvc.UNEXPECTED_ERROR.getCode());

result.setMsg(EnumExceptionMessageWebMvc.UNEXPECTED_ERROR.getMessage());

}

return result;

}

/**

* 针对全局异常的处理

*

* @param exception 全局异常

* @param request http request

* @param response http response

* @return 异常处理结果

*/

@ExceptionHandler(value = Throwable.class)

public Result throwableHandler(Exception exception, HttpServletRequest request, HttpServletResponse response) {

log.error(MessageFormat.format("请求发生了非预期异常，出错的 url [{0}]，出错的描述为 [{1}]",

request.getRequestURL().toString(), exception.getMessage()), exception);

Result result = new Result();

result.setDomain(domain);

result.setCode(EnumExceptionMessageWebMvc.UNEXPECTED_ERROR.getCode());

result.setMsg(EnumExceptionMessageWebMvc.UNEXPECTED_ERROR.getMessage());

return result;

}

}

使用

业务开发异常使用

// 此处只是简单演示，逻辑处理应该抽象在 mvc 分层中，业务开发过程中只需要抛异常即可。

@GetMapping

public String get() {

throw new ExtensionException(105001001L, "simple 资源不存在");

}

基础框架异常使用

model

@Data

public class ValidatedModel {

@NotNull(message = "id 不能为空")

@Min(value = 10, message = "id 不能小于 10")

private Long id;

@NotBlank(message = "name 不能为空")

@Length(max = 5, message = "name 长度不能超过 5")

private String name;

}

controller

// 此处只是简单演示

@PostMapping("/test/validated")

public String getx(@Validated @RequestBody ValidatedModel model) {

return model.getName();

}

代码链接

https://github.com/hiColors/best-practices-api-error-handling

招聘

潮流电商平台行业独角兽（毒APP）基础架构团队诚招 Java / Golang / Kubernetes 研发工程师/架构师，Base 上海杨浦互联宝地，欢迎有兴趣的同学投递简历到 [email protected] 。