错误码设计

# 1 响应格式

为确保前后端交互的规范性和可维护性，所有 RESTful API 接口必须遵循统一的响应格式标准。

响应成功：

{
    "code": 0,
    "data": [
        {
            "id": 0,
            "name": "master",
            "url": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
            "username": "root"
        }
    ],
    "msg": ""
}

1
2
3
4
5
6
7
8
9
10
11
12

成功的响应码是 0 ，而非 200 ，这个是开发者喜好，因人而异。

响应失败：

{
     "code":1002000000,
     "data":null,
     "msg":"登录失败，账号密码不正确"
}

1
2
3
4
5

# 2 CommonResult

响应格式通过 CommonResult 类封装，类中包含三个核心元素： code （响应码）、data （响应体）、msg （消息内容）。

同时， CommonResult 类提供了多种封装成功和失败结果的简易方法。

比如正常响应时，直接使用：

# 3 手工抛出异常

当业务异常时，项目采用的是通过手工抛出异常 ServiceException ，系统会捕获该异常，将响应码和错误信息返回到前端。

在 ServiceExceptionUtil 类的 exception 方法会封装一个 ServiceException 对象：

那么最后一个疑问：系统如何捕获 ServiceException 异常？

在 Spring MVC 中，可以通过 @ControllerAdvice 配合 @ExceptionHandler 注解实现全局异常处理，将系统抛出的特定异常统一转换为标准化的 CommonResult 响应格式。

核心处理逻辑通常定义在 GlobalExceptionHandler 类中，其主要职责包括：

捕获控制器层抛出的各类异常
根据异常类型匹配对应的错误码
构造符合前端规范的错误响应体

如上图，当业务系统抛出 ServiceException 时， GlobalExceptionHandler 统一处理，转换成对应的 CommonResult 对象，进而提示给前端即可。

# 4 错误码分类

错误码分成两类：全局的系统错误码、模块的业务错误码。

# 01 系统错误码

全局的系统错误码，使用 0-999 错误码段，和 HTTP 响应状态码对应。

系统错误码定义在 GlobalErrorCodeConstants 类，代码如下：

# 02 业务错误码

模块的业务错误码，按照模块分配错误码的区间，避免模块之间的错误码冲突。

业务错误码一共 10 位，分成 4 段，规则见下图：

每个业务模块，定义自己的 ErrorCodeConstants 错误码枚举类

← Redis 缓存分布式锁 →