123-java-exception-handling

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Java Exception Handling Guidelines

Java异常处理指南

Identify and apply robust Java exception handling practices to improve error clarity, security, debuggability, and system reliability.

What is covered in this Skill?

Specific exception types instead of generic
```
Exception
```
/
```
RuntimeException
```
try-with-resources for automatic resource cleanup
Secure exception messages that avoid information leakage
Exception chaining to preserve full error context

Early input validation with

IllegalArgumentException

NullPointerException

```
InterruptedException
```
handling with interrupted-status restoration
```
@throws
```
JavaDoc documentation, fail-fast principle
Structured logging with correlation IDs, avoiding log-and-throw duplication
API boundary translation via centralized exception mappers
Bounded retry with backoff for idempotent operations only
Timeout enforcement with deadline propagation
```
Throwable#addSuppressed
```
for secondary cleanup failures
Never catching
```
Throwable
```
/
```
Error
```
Observability via error metrics
Failure propagation in async
```
CompletionStage
```
code

Scope: The reference is organized by examples (good/bad code patterns) for each core area. Apply recommendations based on applicable examples.

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

本技能涵盖哪些内容？

使用特定异常类型而非通用的
```
Exception
```
/
```
RuntimeException
```
使用try-with-resources实现资源自动清理
避免信息泄露的安全异常消息
通过异常链保留完整错误上下文

使用

IllegalArgumentException

NullPointerException

进行提前输入验证

处理
```
InterruptedException
```
并恢复中断状态
使用
```
@throws
```
JavaDoc文档、快速失败原则
带关联ID的结构化日志，避免记录后再抛出的重复操作
通过集中式异常映射器实现API边界转换
仅对幂等操作执行带退避策略的有限重试
强制执行超时并传播截止时间
使用
```
Throwable#addSuppressed
```
处理次要清理失败
绝不捕获
```
Throwable
```
/
```
Error
```
通过错误指标实现可观测性
在异步
```
CompletionStage
```
代码中传播故障

适用范围： 本参考资料按每个核心领域的示例（良好/不良代码模式）组织。根据适用示例应用建议。

Constraints

约束条件

Before applying any exception handling changes, ensure the project compiles. If compilation fails, stop immediately — do not proceed until resolved. After applying improvements, run full verification.

MANDATORY: Run
```
./mvnw compile
```
or
```
mvn compile
```
before applying any changes
SAFETY: If compilation fails, stop immediately — do not proceed until the project is in a valid state
VERIFY: Run
```
./mvnw clean verify
```
or
```
mvn clean verify
```
after applying improvements
BEFORE APPLYING: Read the reference for detailed good/bad examples, constraints, and safeguards for each exception handling pattern

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

强制要求：在应用任何变更前运行
```
./mvnw compile
```
或
```
mvn compile
```
安全注意：如果编译失败，请立即停止——直到项目恢复有效状态后再继续
验证步骤：应用改进后运行
```
./mvnw clean verify
```
或
```
mvn clean verify
```
应用前准备：阅读参考资料，了解每种异常处理模式的详细优劣示例、约束条件和防护措施

When to use this skill

何时使用本技能

Exception handling
Use try-with-resources in Java code
Create exception chaining in Java code
Apply fail-fast validation in Java code

异常处理
在Java代码中使用try-with-resources
在Java代码中创建异常链
在Java代码中应用快速失败验证

Workflow

工作流程

Compile project before exception-handling changes

Run

./mvnw compile

mvn compile

and stop immediately if compilation fails.

Read exception-handling reference

Read

references/123-java-exception-handling.md

and identify applicable failure-handling and observability improvements.

Apply exception-handling improvements

Refactor to specific exceptions, safe resource handling, error translation, and consistent logging patterns.

Verify with full build

Run

./mvnw clean verify

mvn clean verify

after applying improvements.

异常处理变更前编译项目

运行

./mvnw compile

或

mvn compile

，如果编译失败请立即停止。

阅读异常处理参考资料

阅读

references/123-java-exception-handling.md

，确定适用的故障处理和可观测性改进方案。

应用异常处理改进

重构为使用特定异常、安全资源处理、错误转换和一致的日志模式。

通过完整构建验证

应用改进后运行

./mvnw clean verify

或

mvn clean verify

。

Reference

参考资料

For detailed guidance, examples, and constraints, see references/123-java-exception-handling.md.

如需详细指导、示例和约束条件，请查看references/123-java-exception-handling.md。