受检异常处理与SQLException封装技巧

本文深入剖析了Java中SQLException向业务异常（如BusinessException）进行受检异常包装的核心原则与实践陷阱，强调包装本质是语义明确、上下文完整的类型转换而非简单套壳：必须通过带Throwable参数的构造器保留原始堆栈和SQL状态码/错误码，按e.getSQLState()或e.getErrorCode()精准分类转换（如唯一键冲突转DuplicateKeyException），日志须在包装前用SLF4J等支持多级cause的方式完整记录，全局异常处理器应避免二次包装以保护异常链清晰度，且对外API严禁暴露原始SQL或堆栈以防信息泄露——这些细节直接决定系统可观测性、故障定位效率与生产环境稳定性。

受检异常包装的本质是类型转换，不是简单套壳

Java 中 SQLException 是受检异常（checked exception），而多数业务层希望抛出非受检的 BusinessException（继承自 RuntimeException）。所谓“包装”，不是用新异常把旧异常塞进去就完事——关键在于保留原始堆栈、语义清晰、不丢失上下文。

常见错误是直接 new 一个新异常但没传 cause：throw new BusinessException("数据库操作失败")。这会丢掉 SQLException 的 SQL 状态码、错误码、具体 SQL 片段等诊断信息，后续排查只能靠猜。

• 必须用带 Throwable 构造参数的重载： new BusinessException("订单查询失败", e)
• 业务异常类需显式声明接收 Throwable 的构造器，否则编译报错
• 不要在包装时吞掉原始异常（即避免 catch { log; throw new BusinessException(...) } 后不 re-throw 或不设 cause）

封装前先做分类判断，避免“一刀切”包装

不是所有 SQLException 都该转成同一个 BusinessException。比如连接超时、唯一键冲突、SQL 语法错误，业务含义和用户提示策略完全不同。

典型场景：插入用户时触发主键/唯一索引冲突，应转为 DuplicateKeyException（可继承自 BusinessException），前端可明确提示“手机号已被注册”；而连接池耗尽则属于系统级故障，更适合转为 SystemUnavailableException 并触发降级逻辑。

• 用 e.getSQLState() 或 e.getErrorCode() 做分支判断（如 PostgreSQL 的 23505 表示唯一约束违规）
• 避免仅靠 e.getMessage() 字符串匹配——不同驱动返回格式不一致，不可靠
• Spring JDBC 已内置部分分类（如 org.springframework.dao.DuplicateKeyException），可直接复用或参考其实现

日志记录必须在包装前完成，且带完整 cause

很多人习惯在 catch 块里先 log，再 throw 新异常。但如果 log 时只打 e.getMessage()，或用了不支持递归打印 cause 的日志框架（如老版本 Log4j 1.x 默认不展开嵌套异常），关键线索就没了。

正确做法是在包装前，用支持多级 cause 的方式记录原始异常，例如 SLF4J 的 logger.error("DB query failed", e) —— 这会自动展开整个异常链。

• 禁止写 logger.error("DB query failed: " + e.getMessage())，这是最常踩的坑
• 若用 Logback，确认 %ex 或 %xEx pattern 被启用；Log4j2 则检查 %throwable{full}
• 生产环境建议开启 JDBC 驱动的 trace 日志（如 HikariCP 的 leakDetectionThreshold 配合 jdbc:logging），辅助定位连接泄漏类问题

全局异常处理器里别二次包装，否则 cause 层级被破坏

Spring 的 @ControllerAdvice 或 WebFlux 的全局异常处理中，如果对已包装过的 BusinessException 再次 new 一个新异常（比如统一加个 errorId），会导致原始 SQLException 被埋得更深，堆栈里出现两层甚至三层 “Caused by”，调试时容易看花眼。

真正该做的，是在全局处理器里识别出业务异常子类，提取原始 cause（e.getCause()），然后有选择地透出底层错误码或 SQL 片段给监控系统，而不是再套一层。

• 用 instanceof 区分是否已是业务异常，避免重复封装
• 全局 handler 中调用 e.getRootCause()（Spring 提供的工具方法）比循环 getCause() 更安全
• 对外 API 返回体里，业务异常可暴露 errorCode 和 message，但绝不暴露原始 SQL 或堆栈（防信息泄露）

实际项目中最容易被忽略的，是 SQLException 的 cause 可能本身又是另一个 SQLException（比如连接池代理层抛出的异常），这种嵌套深度超过 2 层时，不靠工具方法或断点跟踪，几乎没法人工理清源头。

好了，本文到此结束，带大家了解了《受检异常处理与SQLException封装技巧》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多文章知识！