异常处理（错误码）
1. 统一响应
后端提供 RESTful API 给前端时，需要响应前端 API 调用是否成功：
- 如果成功，成功的数据是什么。后续，前端会将数据渲染到页面上
- 如果失败，失败的原因是什么。一般，前端会将原因弹出提示给用户
因此，需要有统一响应，而不能是每个接口定义自己的风格。一般来说，统一响应返回信息如下：
- 成功时，返回成功的状态码 + 数据
- 失败时，返回失败的状态码 + 错误提示
在标准的 RESTful API 的定义，是推荐使用 HTTP 响应状态码作为状态码。一般来说，我们实践很少这么去做，主要原因如下：
- 业务返回的错误状态码很多，HTTP 响应状态码无法很好的映射。例如说，活动还未开始、订单已取消等等
- 学习成本高，开发者对 HTTP 响应状态码不是很了解。例如说，可能只知道 200、403、404、500 几种常见的
1.1 CommonResult
项目在实践时，将状态码放在 Response Body 响应内容中返回。一共有 3 个字段，通过 framework/common/pojo/CommonResult.java定义如下：
```json
// 成功响应
{
code: 0,
data: {
id: 1,
username: “yudaoyuanma”
}
}
// 失败响应
{
code: 233666,
message: “太丑了”
}
**可以增加 success 字段吗？**<br />有些团队在实践时，会增加了 success 字段，通过 true 和 false 表示成功还是失败。<br />这个看每个团队的习惯吧。还是偏好基于约定，返回 0 时表示成功。<br />失败时的 code 字段，使用全局的错误码，稍后在 「4. 错误码」 小节来讲解。<br />① 在 RESTful API 成功时，定义 Controller 对应方法的返回类型为 CommonResult，并调用framework/common/pojo/CommonResult.java #success(T data)方法来返回。代码如下图：<br /><br />CommonResult 的 data 字段是**泛型**，建议定义对应的 VO 类，而不是使用 Map 类。<br />② 在 RESTful API 失败时，通过抛出 Exception 异常，具体在 「2. 异常处理」 小节。<a name="ThDvI"></a>### 1.2 使用 @ControllerAdvice ？在 Spring MVC 中，可以使用 @ControllerAdvice 注解，通过 Spring AOP 拦截修改 Controller 方法的返回结果，从而实现全局的统一返回。为什么项目不采用这种方式呢？主要原因是，这样的方式“破坏”了方法的定义，导致一些隐性的问题。例如说，Swagger 接口定义错误，展示的响应结果不是 CommonResult。<br />还有个原因，部分 RESTful API 不需要自动包装 CommonResult 结果。例如说，第三方支付回调只需要返回 "success" 字符串。<a name="GJGat"></a>## 2. 异常处理RESTful API 发生异常时，需要拦截 Exception 异常，转换成**统一响应**的格式，否则前端无法处理。<a name="Fs2uy"></a>### 2.1 Spring MVC 的异常在 Spring MVC 中，通过 @ControllerAdvice + @ExceptionHandler 注解，声明将指定类型的异常，转换成对应的 CommonResult 响应。实现的代码，可见 framework/web/core/handler/GlobalExceptionHandler.java类，代码如下：<br /><a name="gPkA1"></a>### 2.2 Filter 的异常在请求被 Spring MVC 处理之前，是先经过 Filter 处理的，此时发生异常时，是无法通过 @ExceptionHandler 注解来处理的。只能通过 try catch 的方式来实现，代码如下：<br /><a name="E6pM6"></a>## 3. 业务异常在 Service 发生业务异常时，如果进行返回呢？例如说，用户名已经存在，商品库存不足等。常用的方案选择，主要有两种：- 方案一，使用 CommonResult 统一响应结果，里面有错误码和错误提示，然后进行 return 返回- 方案二，使用 ServiceException 统一业务异常，里面有错误码和错误提示，然后进行 throw 抛出选择方案一 CommonResult 会存在两个问题：- 因为 Spring @Transactional 声明式事务，是基于异常进行回滚的，如果使用 CommonResult 返回，则事务回滚会非常麻烦- 当调用别的方法时，如果别人返回的是 CommonResult 对象，还需要不断的进行判断，写起来挺麻烦的因此，项目采用方案二 ServiceException 异常。<a name="LFAEp"></a>### 3.1 ServiceException定义 framework/common/exception/ServiceException.java异常类，继承 RuntimeException 异常类（非受检），用于定义业务异常。代码如下：<br /><br />**为什么继承 RuntimeException 异常？**<br />大多数业务场景下，我们无需处理 ServiceException 业务异常，而是通过 GlobalExceptionHandler 统一处理，转换成对应的 CommonResult 对象，进而提示给前端即可。<br />如果真的需要处理 ServiceException 时，通过 try catch 的方式进行主动捕获。<a name="SDkxZ"></a>### 3.2 ServiceExceptionUtil在 Service 需抛出业务异常时，通过调用 framework/common/exception/util/ServiceExceptionUtil.java的 #exception(ErrorCode errorCode, Object... params) 方法来构建 ServiceException 异常，然后使用 throw 进行抛出。代码如下：```java// ServiceExceptionUtil.javapublic static ServiceException exception(ErrorCode errorCode) { /** 省略参数 */ }public static ServiceException exception(ErrorCode errorCode, Object... params) { /** 省略参数 */ }
为什么使用 ServiceExceptionUtil 来构建 ServiceException 异常？
错误提示的内容，支持使用管理后台进行动态配置，所以通过 ServiceExceptionUtil 获取内容的配置与格式化。
4. 错误码
错误码，对应 framework/common/exception/ErrorCode.java类，枚举项目中的错误，全局唯一，方便定位是谁的错、错在哪。
4.1 错误码分类
4.1.1 系统错误码
全局的系统错误码，使用 0-999 错误码段，和 HTTP 响应状态码对应。虽然说，HTTP 响应状态码作为业务使用表达能力偏弱，但是使用在系统层面还是非常不错的。
系统错误码定义在 framework/common/exception/enums/GlobalErrorCodeConstants.java类，代码如下：
4.1.2 业务错误码
模块的业务错误码，按照模块分配错误码的区间，避免模块之间的错误码冲突。
① 业务错误码一共 10 位，分成 4 段，在 framework/common/exception/enums/ServiceErrorCodeRange.java分配，规则与代码如下图：
② 每个业务模块，定义自己的 ErrorCodeConstants 错误码枚举类。以 ykkj-module-system 模块举例子，代码如下：
4.2 错误码管理
在管理后台的 [系统管理 -> 错误码管理] 菜单，可以进行错误码的管理。
启动中的项目会每 60 秒，加载最新的错误码配置。所以，我们在修改完错误码的提示后，无需重启项目。
4.2.1 手动添加
4.2.2 自动添加
通过 ykkj.error-code.constants-class-list 配置项，设置需要自动添加的 ErrorCodeConstants 错误码枚举类。如下图所示：
项目启动时，会自动扫描对应的 ErrorCodeConstants 中的错误码，自动添加或修改错误码的配置。
注意，自动添加的错误码的类型为【自动生成】，一旦在管理后台手动 [编辑] 后，该错误码就不再支持自动修改。
自动添加是如何实现的？
参见 system/framework/errorcode包的代码。
新加系统错误码
infra 系统，使用 1-001-000-000 段
system 系统，使用 1-002-000-000 段
member 系统，使用 1-004-000-000 段
工作流系统，使用 1-009-000-000 段
新开发系统从1-010开始
若有收获，就点个赞吧
0 人点赞
