应使用 getCause() 而非 toString() 获取底层异常，因 toString() 仅返回当前异常类名和消息，丢失原始堆栈与根本原因；需递归调用 getCause() 直至 null 才能定位根因。
为什么要用 getCause() 而不是 toString() 获取底层异常
直接调用 toString() 只能得到当前异常的类名和消息，丢失原始堆栈和根本原因。比如 SQLException 包装成 ServiceException 后，toString() 输出的是 ServiceException: DB error，完全看不到 JDBC 驱动抛出的 SQLTimeoutException 和它的 5 行堆栈。
正确做法是逐层调用 getCause()，直到返回 null。Java 7+ 还支持 Throwable#getStackTraceElement() 和 getSuppressed()，但绝大多数场景只需递归 getCause() 即可定位根因。
- 不要用
e.getMessage()替代e.getCause()—— 消息可能被重写或截断 - 日志中记录异常时，优先用
log.error("op failed", e)（SLF4J），它会自动展开整个异常链 - 若需手动拼接，用
org.apache.commons.lang3.exception.ExceptionUtils.getRootCause(e)更安全
包装异常时该不该保留原始堆栈
应该保留。调用 super(message, cause) 构造函数，而不是 super(message)，否则原始堆栈在构造时就被丢弃了。很多自定义异常类忘了提供带 cause 的构造器，导致上层捕获后只能看到“外壳”异常的堆栈。
常见错误写法：
public class ServiceException extends RuntimeException {
public ServiceException(String msg) {
super(msg); // ❌ 丢弃 cause
}
}正确写法必须显式委托：public ServiceException(String msg, Throwable cause) {
super(msg, cause); // ✅ 保留堆栈
}
- 所有自定义异常类至少提供两个构造器：一个带
cause，一个不带（内部调用前者并传null） - 避免在包装时调用
initCause()—— 它只在cause == null时生效，且无法覆盖已设置的 cause - Spring 的
RuntimeException子类（如DataAccessException）默认保留 cause，可直接用
什么时候不该包装异常：IO 和 NIO 场景的取舍
不是所有异常都适合包装。比如 IOException 在文件读写中本就是预期的一部分，业务层直接捕获并处理（重试、降级、提示用户）比包装成 BusinessException 更清晰。而 NIO 中的 AsynchronousCloseException 或 CancelledKeyException 属于框架生命周期控制信号，包装反而干扰状态判断。
分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
立即学习“Java免费学习笔记（深入）”；
- 底层是系统级错误（磁盘满、网络中断、权限拒绝）→ 建议原样抛出或转为更明确的 unchecked 异常（如
StorageUnavailableException） - 底层是协议/数据格式错误（JSON 解析失败、XML 格式错）→ 可包装为
InvalidInputException，并附带原始JsonProcessingException - 涉及响应体生成（如 Spring MVC
@ExceptionHandler）时，包装后需确保 HTTP 状态码与语义匹配，别把400 Bad Request错配成500 Internal Error
Logback / Log4j2 中如何让包装异常可检索
默认日志输出里，嵌套异常的类名和消息是连在一起的，比如 Caused by: java.sql.SQLTimeoutException: Timeout...，用 ELK 或 Loki 做日志分析时很难提取 SQLTimeoutException 这个关键词。
Logback 可通过 %ex{full, rootFirst} 或自定义 ThrowableRenderer 控制格式；Log4j2 推荐用 %xEx{full, rootFirst} 并启用 includeLocation="false" 减少冗余。关键是要让每层异常的类名独占一行，方便正则提取：
Caused by: java.sql.SQLTimeoutException Caused by: java.net.SocketTimeoutException Caused by: java.io.InterruptedIOException
- 避免使用
%throwable（Logback）或%throwable{short}（Log4j2）—— 它们会省略 cause 链 - 上线前用真实异常测试日志输出，确认 ELK 的 grok pattern 能匹配到最内层异常类名
- 如果用 OpenTelemetry 做 trace，记得调用
Span.recordException(e)，它会自动采集整个 cause 链
