126-java-exception-handling

Java 异常处理指南

识别并应用稳健的 Java 异常处理实践，以提升错误信息的清晰度、安全性、可调试性和系统可靠性。

本技能涵盖哪些内容？

• 使用具体异常类型，而非通用的 Exception/RuntimeException
• 使用 try-with-resources 自动清理资源
• 编写安全的异常消息，避免信息泄露
• 使用异常链保留完整的错误上下文
• 使用 IllegalArgumentException/NullPointerException 提前验证输入
• 处理 InterruptedException 时恢复中断状态
• 使用 @throws 编写 JavaDoc 文档，并遵循快速失败原则
• 使用关联 ID 进行结构化日志记录，避免重复记录并抛出异常
• 通过集中式异常映射器在 API 边界转换异常
• 仅对幂等操作进行带退避的有限重试
• 使用截止时间传播强制执行超时
• 使用 Throwable#addSuppressed 处理次要清理失败
• 切勿捕获 Throwable/Error
• 通过错误指标实现可观测性
• 在异步 CompletionStage 代码中传播失败

范围： 本参考按示例（良好/不良代码模式）介绍各个核心领域。请根据适用示例应用建议。

约束

在应用任何异常处理变更之前，确保项目可以编译。如果编译失败，请立即停止——解决问题之前不得继续。完成改进后，运行完整验证。

• MANDATORY：应用任何变更之前，运行 ./mvnw compile 或 mvn compile
• SAFETY：如果编译失败，请立即停止——在项目恢复到有效状态之前不得继续
• VERIFY：应用改进后，运行 ./mvnw clean verify 或 mvn clean verify
• BEFORE APPLYING：请阅读参考文档，了解每种异常处理模式的详细正反示例、约束和安全措施

何时使用此技能

• 处理异常
• 在 Java 代码中使用 try-with-resources
• 在 Java 代码中创建异常链
• 在 Java 代码中应用快速失败验证
• 审查 Java 异常分类和传播方式

工作流

1. 在修改异常处理之前编译项目

运行 ./mvnw compile 或 mvn compile，如果编译失败，请立即停止。

2. 阅读异常处理参考文档

阅读 references/126-java-exception-handling.md，并确定适用的失败处理和可观测性改进措施。

3. 应用异常处理改进

重构代码，使用具体异常、安全的资源处理、错误转换和一致的日志记录模式。

4. 通过完整构建进行验证

应用改进后，运行 ./mvnw clean verify 或 mvn clean verify。

参考

详细指南、示例和约束请参阅 references/126-java-exception-handling.md。