143-java-functional-exception-handling

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Java Functional Exception handling Best Practices

Java函数式异常处理最佳实践

Identify and apply functional exception handling best practices in Java to improve error clarity, maintainability, and performance by eliminating exception overuse in favour of monadic error types.

What is covered in this Skill?

Optional<T>

for nullable values over throwing

NullPointerException

NotFoundException

VAVR
```
Either<L,R>
```
for predictable business-logic failures
```
CompletableFuture<T>
```
for async error handling
Sealed classes and records for rich error type hierarchies with exhaustive pattern matching
Enum-based error types for simple failure cases
Functional composition:
```
flatMap
```
/
```
map
```
/
```
peek
```
/
```
peekLeft
```
for chaining operations that can fail
Structured logging: warn/info for business failures, error for system failures
Checked vs unchecked exception discipline
Exception chaining with full causal context when exceptions are unavoidable

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

识别并在Java中应用函数式异常处理最佳实践，通过用单子式错误类型替代过度使用的异常，提升错误清晰度、可维护性和性能。

本Skill涵盖哪些内容？

使用

Optional<T>

处理可空值，替代抛出

NullPointerException

或

NotFoundException

使用VAVR
```
Either<L,R>
```
处理可预测的业务逻辑失败
使用
```
CompletableFuture<T>
```
进行异步错误处理
使用Sealed classes和records构建支持穷尽模式匹配的丰富错误类型层级
使用基于Enum的错误类型处理简单故障场景
函数式组合：使用
```
flatMap
```
/
```
map
```
/
```
peek
```
/
```
peekLeft
```
链式调用可能失败的操作
结构化日志：业务失败使用warn/info级别，系统失败使用error级别
受检与非受检异常规范
当异常不可避免时，保留完整因果上下文的异常链式处理

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

Constraints

约束条件

Before applying any functional exception handling changes, ensure the project validates. When introducing Either types, confirm the VAVR dependency (io.vavr:vavr) and SLF4J are present.

MANDATORY: Run
```
./mvnw validate
```
or
```
mvn validate
```
before applying any changes
SAFETY: If validation fails, stop immediately — do not proceed until the project is in a valid state
DEPENDENCY: When introducing
```
Either
```
types, confirm VAVR (
```
io.vavr:vavr
```
) and SLF4J are present
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 functional exception handling pattern

在应用任何函数式异常处理变更之前，确保项目验证通过。当引入Either类型时，确认VAVR依赖（io.vavr:vavr）和SLF4J已存在。

强制要求：在应用任何变更前运行
```
./mvnw validate
```
或
```
mvn validate
```
安全提示：如果验证失败，立即停止——在项目恢复有效状态前不要继续
依赖要求：当引入
```
Either
```
类型时，确认VAVR（
```
io.vavr:vavr
```
）和SLF4J已存在
验证：应用改进后运行
```
./mvnw clean verify
```
或
```
mvn clean verify
```
应用前须知：阅读参考文档，了解每种函数式异常处理模式的详细良好/不良示例、约束条件和防护措施

When to use this skill

何时使用本Skill

Improve the code with Functional Exception Handling
Apply Functional Exception Handling
Refactor the code with Functional Exception Handling

使用函数式异常处理改进代码
应用函数式异常处理
使用函数式异常处理重构代码

Reference

参考文档

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

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