异常处理全生命周期规范指南 ​

前置检查清单 ​

开始异常处理前，请确认以下步骤：

• [ ] 已确定业务模块名称（如 Order、User）
• [ ] 已梳理该模块需要定义的业务异常场景
• [ ] 已检查 src/main/resources/i18n/messages.properties 和 src/main/resources/i18n/messages_en.properties 都同时存在（如不存在则创建）
• [ ] 已确认每次新增/修改错误码枚举值时，同步更新上述两个 properties 文件

Step 1：异常类型选择决策 ​

异常类型速查 ​

框架全局异常处理器（HttpHandlerExceptionResolverConfiguration）会自动捕获这些异常并转换为统一的 BaseResponse 响应。

决策流程 ​

按以下顺序逐步判断，匹配到任一条件即停止：

判断点 1：是否需要给用户提示且不需要记录错误日志？

• 如果是 → 选择 BusinessHintException
• 如果否 → 继续判断点 2

判断点 2：是否涉及认证或鉴权失败？

• 如果是 → 选择 AuthException
• 如果否 → 继续判断点 3

判断点 3：是否为系统内部错误或第三方服务调用失败？

• 如果是 → 选择 SystemException
• 如果否 → 继续判断点 4

判断点 4：其余所有业务逻辑异常场景

• 选择 BusinessException（参数校验、业务规则、数据不存在等）

场景对照表 ​

Step 2：错误码枚举与 i18n 配置 ​

创建错误码枚举 ​

枚举类需实现 IBusinessExceptionCodeConfiguration 接口。

命名规则：XxxOfBusinessExceptionCodeEnum 或 XxxExceptionCodeEnum
包路径建议：xxx.constants 或 xxx.enums

完整枚举模板代码与 i18n 资源文件定义详见 error-code-definition.md。

接口方法说明 ​

创建 i18n 资源文件 ​

每个异常枚举需配套创建以下两个文件：

• 中文默认资源文件：src/main/resources/i18n/messages.properties
• 英文资源文件：src/main/resources/i18n/messages_en.properties

键名为枚举 code() 返回值，值为对应语言的错误描述。同时提供中英文可确保英文环境不 fallback 到中文。

完整 properties 示例详见 error-code-definition.md。

占位符使用规范 ​

支持 java.text.MessageFormat 格式（{0}、{1} 等）。

定义与使用必须成对出现：在枚举中定义占位符后，抛出时务必通过 args 传入对应数量的实际值，否则占位符无法被替换。

// Step 2：枚举定义占位符
ERR_SIZE_LIMIT("字段 {0} 长度必须在 {1} 到 {2} 之间")

// Step 3：抛出时传入对应数量的 args
throw BusinessException.error(
    XxxOfBusinessExceptionCodeEnum.ERR_SIZE_LIMIT,
    "description", 10, 200
);
// 中文结果: "字段 description 长度必须在 10 到 200 之间"
// 英文结果: "Field description length must be between 10 and 200"

Step 3：异常抛出规范 ​

抛出方式选择 ​

标准抛出模板 ​

模板 A：使用枚举默认消息（配合 i18n）

throw BusinessException.error(XxxOfBusinessExceptionCodeEnum.ERR_DATA_NOT_FOUND);

模板 B：带参数 args（i18n 占位符替换）

throw BusinessException.error(
    XxxOfBusinessExceptionCodeEnum.ERR_REQUIRED_FIELD_MISSING,
    "userName"
);

模板 C：多参数占位符替换

throw BusinessException.error(
    XxxOfBusinessExceptionCodeEnum.ERR_SIZE_LIMIT,
    "description", 10, 200
);

模板 D：包装底层异常（需要传递 cause 时）

使用构造函数直接实例化并传递原始异常：

try {
    thirdPartyApi.call();
} catch (Exception e) {
    throw new BusinessException(
        XxxOfBusinessExceptionCodeEnum.ERR_RPC,
        e.getMessage(),
        e
    );
}

注：当需要传递 cause 时，必须使用 new 构造函数而非静态工厂方法 error()，以确保原始堆栈信息不丢失。

常见场景速查 ​

上述场景的完整代码示例详见对应参考文档。

远程调用注意事项 ​

在 Dubbo/Feign 等跨服务调用场景中：

• Provider 端：按 Step 1 决策结果直接抛出对应异常类型即可（业务校验失败用 BusinessException，远程调用失败用 SystemException），无需额外处理
• Consumer 端：通常不需要 try-catch，让全局处理器统一接管
• 如需降级，捕获后按 Step 1 重新决策目标异常类型，并带上原始 cause

Step 4：异常捕获与处理 ​

捕获原则 ​

• [ ] 捕获异常前，确认是否有明确的降级逻辑或转换需求
• [ ] 如果没有明确处理逻辑，直接抛出让全局处理器接管
• [ ] BusinessHintException 的处理方法中不记录 error 日志
• [ ] 捕获后如需重新抛出，带上原始 cause
• [ ] 捕获后如需转换异常类型，回退到 Step 1 决策流程重新判断目标类型

常见场景速查 ​

上述场景的完整代码示例详见 exception-catching.md。

全局处理机制说明 ​

业务层不需要手动编写 @ControllerAdvice 或 try-catch 来转换响应格式。框架自动完成以下工作：

1. 捕获异常并解析枚举 code() 作为响应码
2. 通过 @AppI18n 切面自动翻译消息
3. 根据异常类型决定是否记录 error 日志（BusinessHintException 不记录）
4. 包装为统一的 BaseResponse 返回给前端

常见反模式速查 ​

Do's and Don'ts ​

参考文档 ​