核心内容摘要
什么是眼图？有什么作用
说明本文讲得比较细所以篇幅较长。
请认真读完希望读完后能对统一异常处理有一个清晰的认识。
01背景软件开发过程中不可避免的是需要处理各种异常就我自己来说至少有一半以上的时间都是在处理各种异常情况所以代码中就会出现大量的try {...} catch {...} finally {...} 代码块不仅有大量的冗余代码而且还影响代码的可读性。
比较下面两张图看看您现在编写的代码属于哪一种风格然后哪种编码风格您更喜欢丑陋的 try catch 代码块优雅的Controller上面的示例还只是在Controller层如果是在Service层可能会有更多的try catch代码块。
这将会严重影响代码的可读性、“美观性”。
所以如果是我的话我肯定偏向于第二种我可以把更多的精力放在业务代码的开发同时代码也会变得更加简洁。
既然业务代码不显式地对异常进行捕获、处理而异常肯定还是处理的不然系统岂不是动不动就崩溃了所以必须得有其他地方捕获并处理这些异常。
那么问题来了如何优雅的处理各种异常02什么是统一异常处理Spring在
2版本增加了一个注解ControllerAdvice可以与ExceptionHandler、InitBinder、ModelAttribute 等注解注解配套使用对于这几个注解的作用这里不做过多赘述若有不了解的可以参考Spring
2新注解ControllerAdvice先大概有个了解。
不过跟异常处理相关的只有注解ExceptionHandler从字面上看就是 异常处理器 的意思其实际作用也是若在某个Controller类定义一个异常处理方法并在方法上添加该注解那么当出现指定的异常时会执行该处理异常的方法其可以使用springmvc提供的数据绑定比如注入HttpServletRequest等还可以接受一个当前抛出的Throwable对象。
但是这样一来就必须在每一个Controller类都定义一套这样的异常处理方法因为异常可以是各种各样。
这样一来就会造成大量的冗余代码而且若需要新增一种异常的处理逻辑就必须修改所有Controller类了很不优雅。
当然你可能会说那就定义个类似BaseController的基类这样总行了吧。
这种做法虽然没错但仍不尽善尽美因为这样的代码有一定的侵入性和耦合性。
简简单单的Controller我为啥非得继承这样一个类呢万一已经继承其他基类了呢。
大家都知道Java只能继承一个类。
那有没有一种方案既不需要跟Controller耦合也可以将定义的 异常处理器 应用到所有控制器呢所以注解ControllerAdvice出现了简单的说该注解可以把异常处理器应用到所有控制器而不是单个控制器。
借助该注解我们可以实现在独立的某个地方比如单独一个类定义一套对各种异常的处理机制然后在类的签名加上注解ControllerAdvice统一对 不同阶段的、不同异常 进行处理。
这就是统一异常处理的原理。
注意到上面对异常按阶段进行分类大体可以分成进入Controller前的异常 和 Service 层异常具体可以参考下图不同阶段的异常03目标消灭95%以上的 try catch 代码块以优雅的 Assert(断言) 方式来校验业务的异常情况只关注业务逻辑而不用花费大量精力写冗余的 try catch 代码块。
public interface Assert { /** * 创建异常 * return */ BaseException newException(Object... args); /** * 创建异常 * return */ BaseException newException(Throwable t, Object... args); /** * p断言对象codeobj/code非空。
如果对象codeobj/code为空则抛出异常 * param obj 待判断对象 */ default void assertNotNull(Object obj) { if (obj null) { throw newException(obj); } } /** * p断言对象codeobj/code非空。
如果对象codeobj/code为空则抛出异常 * p异常信息codemessage/code支持传递参数方式避免在判断之前进行字符串拼接操作 * param obj 待判断对象 * param args message占位符对应的参数列表 */ default void assertNotNull(Object obj, Object... args) { if (obj null) { throw newException(args); } } }04统一异常处理实战在定义统一异常处理类之前先来介绍一下如何优雅的判定异常情况并抛异常。
用 Assert(断言) 替换 throw exception想必 Assert(断言) 大家都很熟悉比如 Spring 家族的 org.springframework.util.Assert在我们写测试用例的时候经常会用到使用断言能让我们编码的时候有一种非一般丝滑的感觉比如有没有感觉第一种判定非空的写法很优雅第二种写法则是相对丑陋的 if {...} 代码块。
那么神奇的 Assert.notNull() 背后到底做了什么呢下面是 Assert 的部分源码可以看到Assert 其实就是帮我们把 if {...} 封装了一下是不是很神奇。
虽然很简单但不可否认的是编码体验至少提升了一个档次。
那么我们能不能模仿org.springframework.util.Assert也写一个断言类不过断言失败后抛出的异常不是IllegalArgumentException 这些内置异常而是我们自己定义的异常。
下面让我们来尝试一下。
Assert上面的Assert断言方法是使用接口的默认方法定义的然后有没有发现当断言失败后抛出的异常不是具体的某个异常而是交由2个newException接口方法提供。
因为业务逻辑中出现的异常基本都是对应特定的场景比如根据用户id获取用户信息查询结果为null此时抛出的异常可能为UserNotFoundException并且有特定的异常码比如7001和异常信息“用户不存在”。
所以具体抛出什么异常有Assert的实现类决定。
看到这里您可能会有这样的疑问按照上面的说法那岂不是有多少异常情况就得有定义等量的断言类和异常类这显然是反人类的这也没想象中高明嘛。
别急且听我细细道来。
善解人意的Enum自定义异常BaseException有2个属性即code、message这样一对属性有没有想到什么类一般也会定义这2个属性没错就是枚举类。
且看我如何将 Enum 和 Assert 结合起来相信我一定会让你眼前一亮。
如下public interface IResponseEnum { int getCode(); String getMessage(); } /** * p业务异常/p * p业务处理时出现异常可以抛出该异常/p */ publicclass BusinessExceptionextends BaseException { privatestatic final long serialVersionUID 1L; public BusinessException(IResponseEnum responseEnum,Object[] args,String message) { super(responseEnum, args, message); } public BusinessException(IResponseEnum responseEnum,Object[] args,String message, Throwable cause) { super(responseEnum, args, message, cause); } } publicinterface BusinessExceptionAssertextends IResponseEnum, Assert { Override default BaseException newException(Object... args) { String msg MessageFormat.format(this.getMessage(), args); returnnew BusinessException(this, args, msg); } Override default BaseException newException(Throwable t,Object... args) { String msg MessageFormat.format(this.getMessage(), args); returnnew BusinessException(this, args, msg, t); } } Getter AllArgsConstructor publicenum ResponseEnumimplements BusinessExceptionAssert { /** * Bad licence type */ BAD_LICENCE_TYPE(7001,Bad licence type.), /** * Licence not found */ LICENCE_NOT_FOUND(7002,Licence not found.) ; /** * 返回码 */ private int code; /** * 返回消息 */ privateString message; }看到这里有没有眼前一亮的感觉代码示例中定义了两个枚举实例BADLICENCETYPE、LICENCENOTFOUND分别对应了BadLicenceTypeException、LicenceNotFoundException两种异常。
以后每增加一种异常情况只需增加一个枚举实例即可再也不用每一种异常都定义一个异常类了。
然后再来看下如何使用假设LicenceService有校验Licence是否存在的方法如下/** * 校验{link Licence}存在 * param licence */ private void checkNotNull(Licence licence) { ResponseEnum.LICENCE_NOT_FOUND.assertNotNull(licence); }若不使用断言代码可能如下private void checkNotNull(Licence licence) { if (licence null) { throw new LicenceNotFoundException(); // 或者这样 throw new BusinessException(7001, Bad licence type.); } }使用枚举类结合(继承)Assert只需根据特定的异常情况定义不同的枚举实例如上面的BADLICENCETYPE、LICENCENOTFOUND就能够针对不同情况抛出特定的异常这里指携带特定的异常码和异常消息这样既不用定义大量的异常类同时还具备了断言的良好可读性当然这种方案的好处远不止这些请继续阅读后文慢慢体会。
注上面举的例子是针对特定的业务而有部分异常情况是通用的比如服务器繁忙、网络异常、服务器异常、参数校验异常、404等所以有CommonResponseEnum、ArgumentResponseEnum、ServletResponseEnum其中 ServletResponseEnum 会在后文详细说明。
05定义统一异常处理器类Slf4j Component ControllerAdvice ConditionalOnWebApplication ConditionalOnMissingBean(UnifiedExceptionHandler.class) publicclass UnifiedExceptionHandler { /** * 生产环境 */ privatefinalstatic String ENV_PROD prod; Autowired private UnifiedMessageSource unifiedMessageSource; /** * 当前环境 */ Value(${spring.profiles.active}) private String profile; /** * 获取国际化消息 */ public String getMessage(BaseException e) { String code response. e.getResponseEnum().toString(); String message unifiedMessageSource.getMessage(code, e.getArgs()); if (message null || message.isEmpty()) { return e.getMessage(); } return message; } /** * 业务异常 */ ExceptionHandler(value BusinessException.class) ResponseBody public ErrorResponse handleBusinessException(BaseException e) { log.error(e.getMessage(), e); returnnew ErrorResponse(e.getResponseEnum().getCode(), getMessage(e)); } /** * 自定义异常 */ ExceptionHandler(value BaseException.class) ResponseBody public ErrorResponse handleBaseException(BaseException e) { log.error(e.getMessage(), e); returnnew ErrorResponse(e.getResponseEnum().getCode(), getMessage(e)); } /** * Controller上一层相关异常 */ ExceptionHandler({ NoHandlerFoundException.class, HttpRequestMethodNotSupportedException.class, HttpMediaTypeNotSupportedException.class, MissingPathVariableException.class, MissingServletRequestParameterException.class, TypeMismatchException.class, HttpMessageNotReadableException.class, HttpMessageNotWritableException.class, // BindException.class, // MethodArgumentNotValidException.class HttpMediaTypeNotAcceptableException.class, ServletRequestBindingException.class, ConversionNotSupportedException.class, MissingServletRequestPartException.class, AsyncRequestTimeoutException.class }) ResponseBody public ErrorResponse handleServletException(Exception e) { log.error(e.getMessage(), e); int code CommonResponseEnum.SERVER_ERROR.getCode(); try { ServletResponseEnum servletExceptionEnum ServletResponseEnum.valueOf(e.getClass().getSimpleName()); code servletExceptionEnum.getCode(); }catch (IllegalArgumentException e
{ log.error(class [{}] not defined in enum {}, e.getClass().getName(), ServletResponseEnum.class.getName()); } if (ENV_PROD.equals(profile)) { // 当为生产环境, 不适合把具体的异常信息展示给用户, 比如
code CommonResponseEnum.SERVER_ERROR.getCode(); BaseException baseException new BaseException(CommonResponseEnum.SERVER_ERROR); String message getMessage(baseException); returnnew ErrorResponse(code, message); } returnnew ErrorResponse(code, e.getMessage()); } /** * 参数绑定异常 */ ExceptionHandler(value BindException.class) ResponseBody public ErrorResponse handleBindException(BindException e) { log.error(参数绑定校验异常, e); return wrapperBindingResult(e.getBindingResult()); } /** * 参数校验异常将校验失败的所有异常组合成一条错误信息 */ ExceptionHandler(value MethodArgumentNotValidException.class) ResponseBody public ErrorResponse handleValidException(MethodArgumentNotValidException e) { log.error(参数绑定校验异常, e); return wrapperBindingResult(e.getBindingResult()); } /** * 包装绑定异常结果 */ private ErrorResponse wrapperBindingResult(BindingResult bindingResult) { StringBuilder msg new StringBuilder(); for (ObjectError error : bindingResult.getAllErrors()) { msg.append(, ); if (errorinstanceof FieldError) { msg.append(((FieldError) error).getField()).append(: ); } msg.append(error.getDefaultMessage() null ? : error.getDefaultMessage()); } returnnew ErrorResponse(ArgumentResponseEnum.VALID_ERROR.getCode(), msg.substring(
); } /** * 未定义异常 */ ExceptionHandler(value Exception.class) ResponseBody public ErrorResponse handleException(Exception e) { log.error(e.getMessage(), e); if (ENV_PROD.equals(profile)) { // 当为生产环境, 不适合把具体的异常信息展示给用户, 比如数据库异常信息. int code CommonResponseEnum.SERVER_ERROR.getCode(); BaseException baseException new BaseException(CommonResponseEnum.SERVER_ERROR); String message getMessage(baseException); returnnew ErrorResponse(code, message); } returnnew ErrorResponse(CommonResponseEnum.SERVER_ERROR.getCode(), e.getMessage()); } }可以看到上面将异常分成几类实际上只有两大类一类是ServletException、ServiceException还记得上文提到的 按阶段分类 吗即对应 进入Controller前的异常 和 Service 层异常然后 ServiceException 再分成自定义异常、未知异常。
对应关系如下进入Controller前的异常: handleServletException、handleBindException、handleValidException自定义异常: handleBusinessException、handleBaseException未知异常: handleException接下来分别对这几种异常处理器做详细说明。
异常处理器说明handleServletException一个http请求在到达Controller前会对该请求的请求信息与目标控制器信息做一系列校验。
这里简单说一下NoHandlerFoundException首先根据请求Url查找有没有对应的控制器若没有则会抛该异常也就是大家非常熟悉的404异常HttpRequestMethodNotSupportedException若匹配到了匹配结果是一个列表不同的是http方法不同如Get、Post等则尝试将请求的http方法与列表的控制器做匹配若没有对应http方法的控制器则抛该异常HttpMediaTypeNotSupportedException然后再对请求头与控制器支持的做比较比如content-type请求头若控制器的参数签名包含注解RequestBody但是请求的content-type请求头的值没有包含application/json那么会抛该异常当然不止这种情况会抛这个异常MissingPathVariableException未检测到路径参数。
比如url为/licence/{licenceId}参数签名包含PathVariable(licenceId)当请求的url为/licence在没有明确定义url为/licence的情况下会被判定为缺少路径参数MissingServletRequestParameterException缺少请求参数。
比如定义了参数RequestParam(licenceId) String licenceId但发起请求时未携带该参数则会抛该异常TypeMismatchException: 参数类型匹配失败。
比如接收参数为Long型但传入的值确是一个字符串那么将会出现类型转换失败的情况这时会抛该异常HttpMessageNotReadableException与上面的HttpMediaTypeNotSupportedException举的例子完全相反即请求头携带了content-type: application/json;charsetUTF-8但接收参数却没有添加注解RequestBody或者请求体携带的 json 串反序列化成 pojo 的过程中失败了也会抛该异常HttpMessageNotWritableException返回的 pojo 在序列化成 json 过程失败了那么抛该异常HttpMediaTypeNotAcceptableException未知ServletRequestBindingException未知ConversionNotSupportedException未知MissingServletRequestPartException未知AsyncRequestTimeoutException未知handleBindException参数校验异常后文详细说明。
handleValidExceptionhandleBusinessException、handleBaseException处理自定义的业务异常只是handleBaseException处理的是除了 BusinessException 意外的所有业务异常。
就目前来看这2个是可以合并成一个的。
handleException处理所有未知的异常比如操作数据库失败的异常。
注上面的handleServletException、handleException 这两个处理器返回的异常信息不同环境返回的可能不一样以为这些异常信息都是框架自带的异常信息一般都是英文的不太好直接展示给用户看所以统一返回SERVER_ERROR代表的异常信息。
异于常人的404上文提到当请求没有匹配到控制器的情况下会抛出NoHandlerFoundException异常但其实默认情况下不是这样默认情况下会出现类似如下页面Whitelabel Error Page这个页面是如何出现的呢实际上当出现404的时候默认是不抛异常的而是 forward跳转到/error控制器spring也提供了默认的error控制器如下BasicErrorController那么如何让404也抛出异常呢只需在properties文件中加入如下配置即可spring.mvc.throw-exception-if-no-handler-foundtrue spring.resources.add-mappingsfalse如此就可以异常处理器中捕获它了然后前端只要捕获到特定的状态码立即跳转到404页面即可06捕获404对应的异常统一返回结果在验证统一异常处理器之前顺便说一下统一返回结果。
说白了其实是统一一下返回结果的数据结构。
code、message 是所有返回结果中必有的字段而当需要返回数据时则需要另一个字段 data 来表示。
所以首先定义一个 BaseResponse 来作为所有返回结果的基类然后定义一个通用返回结果类 CommonResponse继承 BaseResponse而且多了字段 data为了区分成功和失败返回结果于是再定义一个 ErrorResponse最后还有一种常见的返回结果即返回的数据带有分页信息因为这种接口比较常见所以有必要单独定义一个返回结果类 QueryDataResponse该类继承自 CommonResponse只是把 data 字段的类型限制为 QueryDdataQueryDdata中定义了分页信息相应的字段即totalCount、pageNo、 pageSize、records。
其中比较常用的只有 CommonResponse 和 QueryDataResponse但是名字又贼鬼死长何不定义2个名字超简单的类来替代呢于是 R 和 QR 诞生了以后返回结果的时候只需这样写new R(data)、new QR(queryData)。
所有的返回结果类的定义这里就不贴出来了验证统一异常处理因为这一套统一异常处理可以说是通用的所有可以设计成一个 common包以后每一个新项目/模块只需引入该包即可。
所以为了验证需要新建一个项目并引入该 common包。
主要代码下面是用于验证的主要源码Service publicclass LicenceService extends ServiceImplLicenceMapper, Licence { Autowired private OrganizationClient organizationClient; /** * 查询{link Licence} 详情 */ public LicenceDTO queryDetail(Long licenceId) { Licence licence this.getById(licenceId); checkNotNull(licence); OrganizationDTO org ClientUtil.execute(() - organizationClient.getOrganization(licence.getOrganizationId())); return toLicenceDTO(licence, org); } /** * 分页获取 */ public QueryDataSimpleLicenceDTO getLicences(LicenceParam licenceParam) { String licenceType licenceParam.getLicenceType(); LicenceTypeEnum licenceTypeEnum LicenceTypeEnum.parseOfNullable(licenceType); // 断言, 非空 ResponseEnum.BAD_LICENCE_TYPE.assertNotNull(licenceTypeEnum); LambdaQueryWrapperLicence wrapper new LambdaQueryWrapper(); wrapper.eq(Licence::getLicenceType, licenceType); IPageLicence page this.page(new QueryPage(licenceParam), wrapper); returnnew QueryData(page,this::toSimpleLicenceDTO); } /** * 新增{link Licence} */ Transactional(rollbackFor Throwable.class) public LicenceAddRespData addLicence(LicenceAddRequest request) { Licence licence new Licence(); licence.setOrganizationId(request.getOrganizationId()); licence.setLicenceType(request.getLicenceType()); licence.setProductName(request.getProductName()); licence.setLicenceMax(request.getLicenceMax()); licence.setLicenceAllocated(request.getLicenceAllocated()); licence.setComment(request.getComment()); this.save(licence); returnnew LicenceAddRespData(licence.getLicenceId()); } /** * entity - simple dto */ private SimpleLicenceDTO toSimpleLicenceDTO(Licence licence) { // 省略 } /** * entity - dto */ private LicenceDTO toLicenceDTO(Licence licence, OrganizationDTO org) { // 省略 } /** * 校验{link Licence}存在 */ private void checkNotNull(Licence licence) { ResponseEnum.LICENCE_NOT_FOUND.assertNotNull(licence); } }ps: 这里使用的DAO框架是mybatis-plus。
启动时自动插入的数据为-- licence INSERTINTO licence (licence_id, organization_id, licence_type, product_name, licence_max, licence_allocated) VALUES (1,1,user,CustomerPro,100,
; INSERTINTO licence (licence_id, organization_id, licence_type, product_name, licence_max, licence_allocated) VALUES (2,1,user,suitability-plus,200,
; INSERTINTO licence (licence_id, organization_id, licence_type, product_name, licence_max, licence_allocated) VALUES (3,2,user,HR-PowerSuite,100,
; INSERTINTO licence (licence_id, organization_id, licence_type, product_name, licence_max, licence_allocated) VALUES (4,2,core-prod,WildCat Application Gateway,16,
; -- organizations INSERTINTOorganization (id,name, contact_name, contact_email, contact_phone) VALUES (1,customer-crm-co,Mark Balster,mark.balstercustcrmco.com,
-
; INSERTINTOorganization (id,name, contact_name, contact_email, contact_phone) VALUES (2,HR-PowerSuite,Doug Drewry,doug.drewryhr.com,
-
;开始验证捕获自定义异常获取不存在的 licence 详情http://localhost:10000/licence/5。
成功响应的请求licenceId1校验非空捕获 Licence not found 异常Licence not found根据不存在的 licence type 获取 licence 列表http://localhost:10000/licence/list?licenceTypeddd。
可选的 licence type 为user、core-prod 。
捕获 Bad licence type 异常Bad licence type捕获进入 Controller 前的异常访问不存在的接口http://localhost:10000/licence/list/ddd捕获404异常http 方法不支持http://localhost:10000/licencePostMapping捕获 Request method not supported 异常Request method not supported校验异常1http://localhost:10000/licence/list?licenceTypegetLicencesLicenceParam捕获参数绑定校验异常licence type cannot be empty校验异常2post 请求这里使用postman模拟。
addLicenceLicenceAddRequest请求url即结果注因为参数绑定校验异常的异常信息的获取方式与其它异常不一样所以才把这2种情况的异常从 进入 Controller 前的异常 单独拆出来下面是异常信息的收集逻辑异常信息的收集捕获未知异常假设我们现在随便对 Licence 新增一个字段 test但不修改数据库表结构然后访问http://localhost:10000/licence/1。
增加test字段捕获数据库异常Error querying database小结可以看到测试的异常都能够被捕获然后以 code、message 的形式返回。
每一个项目/模块在定义业务异常的时候只需定义一个枚举类然后实现接口 BusinessExceptionAssert最后为每一种业务异常定义对应的枚举实例即可而不用定义许多异常类。
使用的时候也很方便用法类似断言。
扩展在生产环境若捕获到 未知异常 或者 ServletException因为都是一长串的异常信息若直接展示给用户看显得不够专业于是我们可以这样做当检测到当前环境是生产环境那么直接返回 网络异常。
生产环境返回“网络异常”可以通过以下方式修改当前环境修改当前环境为生产环境07
总结使用 断言 和 枚举类 相结合的方式再配合统一异常处理基本大部分的异常都能够被捕获。
为什么说大部分异常因为当引入 spring cloud security 后还会有认证/授权异常网关的服务降级异常、跨模块调用异常、远程调用第三方服务异常等这些异常的捕获方式与本文介绍的不太一样不过限于篇幅这里不做详细说明。
另外当需要考虑国际化的时候捕获异常后的异常信息一般不能直接返回需要转换成对应的语言不过本文已考虑到了这个获取消息的时候已经做了国际化映射逻辑如下获取国际化消息最后
总结全局异常属于老生长谈的话题希望这次通过手机的项目对大家有点指导性的学习。
大家根据实际情况自行修改。
也可以采用以下的jsonResult对象的方式进行处理也贴出来代码.Slf4j RestControllerAdvice publicclass GlobalExceptionHandler { /** * 没有登录 */ ExceptionHandler(NoLoginException.class) public Object noLoginExceptionHandler(HttpServletRequest request,HttpServletResponse response,Exception e) { log.error([GlobalExceptionHandler][noLoginExceptionHandler] exception,e); JsonResult jsonResult new JsonResult(); jsonResult.setCode(JsonResultCode.NO_LOGIN); jsonResult.setMessage(用户登录失效或者登录超时,请先登录); return jsonResult; } /** * 业务异常 */ ExceptionHandler(ServiceException.class) public Object businessExceptionHandler(HttpServletRequest request,HttpServletResponse response,Exception e) { log.error([GlobalExceptionHandler][businessExceptionHandler] exception,e); JsonResult jsonResult new JsonResult(); jsonResult.setCode(JsonResultCode.FAILURE); jsonResult.setMessage(业务异常,请联系管理员); return jsonResult; } /** * 全局异常处理 */ ExceptionHandler(Exception.class) public Object exceptionHandler(HttpServletRequest request,HttpServletResponse response,Exception e) { log.error([GlobalExceptionHandler][exceptionHandler] exception,e); JsonResult jsonResult new JsonResult(); jsonResult.setCode(JsonResultCode.FAILURE); jsonResult.setMessage(系统错误,请联系管理员); return jsonResult; } }好了到这里关于如何优雅地异常处理全部介绍完毕如果觉得有用大家可以在自己的项目中使用下。