beyondsoft-exception-spring3-starter 功能概览

1. 模块定位

beyondsoft-exception-spring3-starter 提供基于 Spring Boot 3 的 统一异常处理能力，负责将各类异常（业务异常、框架异常、安全异常等）转换为标准的错误响应结构，并输出统一的异常日志，是所有 Web/API 项目的统一异常入口。

2. 主要能力

• 全局异常处理器

  • 提供全局 @RestControllerAdvice 异常处理器 GlobalExceptionHandler，自动接管 Controller 层未处理的异常。
  • 将异常统一封装为 common-base 中的 ErrorResult，并设置合理的 HTTP 状态码。

• 业务异常处理

  • 支持处理 common-base 中定义的业务异常：BusinessException, ParameterInvalidException, DataConflictException, InternalServerException, RemoteAccessException, ExcelException 等。
  • 规范化业务异常到错误码、错误信息和 HTTP 状态码的映射。

• 框架与安全相关异常处理

  • 处理常见 Spring MVC 异常（如 NoResourceFoundException, HttpMessageNotReadableException, MethodArgumentNotValidException 等）。
  • 处理 Sa-Token 认证授权异常（如 NotLoginException）。
  • 处理安全 Starter 抛出的加解密/SQL 注入相关异常（如 RequestEncryptException, RequestSqlInjectException）。

• 统一异常日志记录

  • 在异常处理过程中记录详细的错误日志，包括：请求 URI、异常类型、错误信息、堆栈信息等，便于排查和追踪。

3. 使用约定

• 业务错误统一使用业务异常抛出

  • 在业务代码中出现业务校验失败或流程中断时，统一使用 common-base 中的业务异常（如 BusinessException, ParameterInvalidException），不要随意抛出 RuntimeException 或自定义的非框架异常类型。

• Controller 不再手写异常返回结构

  • Controller 层不再手动 try-catch 组装错误 JSON，交由全局异常处理器统一完成，保持 Controller 逻辑简洁、专注于业务流程。

• 与 Web Starter 协同使用

  • 建议与 beyondsoft-web-spring3-starter 搭配使用：
    • 正常返回由 Web Starter 的统一响应处理封装；
    • 异常由本模块统一转为 ErrorResult。

• 扩展异常处理时的注意事项

  • 如需扩展额外的异常处理逻辑，应基于现有异常体系追加，而非替换原有全局异常处理器，避免破坏框架统一行为。