统一异常处理与错误码规范

异常分类与基类

• 定义业务异常基类 BusinessException 承载可预期业务错误
• 系统异常使用运行时异常表示，不直接暴露到底层详情
• 按模块划分业务异常子类或者使用错误码枚举区分

全局异常处理

• 使用 @RestControllerAdvice 统一处理异常
• 使用 @ExceptionHandler 分别处理业务异常与系统异常
• 在处理逻辑中统一转换为统一返回体结构

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(BusinessException.class)
    public Result<?> handleBusinessException(BusinessException ex) {
        return Result.fail(ex.getCode(), ex.getMessage());
    }

    @ExceptionHandler(Exception.class)
    public Result<?> handleException(Exception ex) {
        return Result.fail("INTERNAL_ERROR", "系统异常");
    }
}

错误码设计

• 错误码使用字符串或整型，按业务域分段管理
• 推荐结构为 模块前缀 + 数字编码，如 USER_1001
• 为每个错误码编写清晰描述与解决建议

抛出异常的约定

• 在领域层与应用层中抛出业务异常，避免在 Controller 层充斥大量判断
• 捕获底层异常时保留原始异常作为 cause
• 在日志中记录异常详情，但对外返回统一错误信息

调试与追踪

• 在错误响应中携带可追踪的请求标识，例如 traceId
• 对高频或关键接口的异常情况进行统计与报警