Java异常命名规范与最佳实践

Java自定义异常命名绝非随意而为，而是关乎系统可维护性、工具链兼容性与团队协作效率的核心规范：必须严格以“Exception”结尾并采用大驼峰命名（如InsufficientBalanceException），这是JDK、IDE、Spring及各类静态分析工具识别和处理异常的底层契约；名字需精准表达业务失败场景，杜绝泛化命名；绝大多数业务异常应继承RuntimeException但不加Runtime前缀，通过语义而非名称区分类型；同时需配合领域化的包路径（如com.example.order.exception）和内嵌errorCode字段，让异常真正成为可观测、可定位、可响应的问题载体——好名字是起点，不是终点。

Java自定义异常必须以 Exception 结尾，且用大驼峰命名（PascalCase），否则就不是合格的异常类——这是JVM生态里最基础、最不容妥协的约定。

为什么必须以 Exception 结尾？

这不是风格偏好，而是类型识别契约。JDK标准库所有异常（NullPointerException、IOException、IllegalArgumentException）都严格遵循该后缀；IDE、日志框架、Spring异常处理器、甚至静态分析工具（如SpotBugs）都依赖这个命名特征做自动识别和分类。

• 不加 Exception：IDE不会高亮为异常类型，catch 块无法匹配，throws 声明报错
• 写成 InvalidUserError 或 UserException：前者被当成 Error 子类（严重不可恢复），后者语义模糊，团队协作时没人敢确定它是业务异常还是技术异常
• 小写或下划线（如 invalid_user_exception）：违反Java类名规范，编译器虽不拦，但会被SonarQube等工具标为“命名违规”

怎么起一个真正有用的异常名？

名字要像错误日志一样能直接回答“谁在什么场景下因何失败”。避免泛化词（如 BusinessException、SystemException），优先绑定具体业务动词+名词。

• ✅ 推荐：InsufficientBalanceException、OrderAlreadyPaidException、ProductOutOfStockException
• ❌ 避免：BalanceException（缺动词，不知是“不足”还是“超限”）、PayException（太宽泛，支付失败？支付超时？支付签名错？）
• ⚠️ 注意：若涉及分层（如DAO/Service），可在包路径中体现，类名本身不强行加 Dao、Service 前缀——com.example.order.exception.OrderNotFoundException 比 OrderServiceException 更清晰

继承 RuntimeException 还是 Exception？命名要不要体现这点？

绝大多数业务异常应继承 RuntimeException（即“非检查异常”），让调用方按需捕获，而非强制 try-catch 或 throws。命名上不建议加 Runtime 或 Checked 前缀（如 RuntimeValidationException）——这会增加认知负担，且无实际约束力。

• ✅ 正确做法：统一用 XXXException 命名，通过继承关系区分语义，例如：

  public class PaymentFailedException extends RuntimeException { ... }

• ❌ 不推荐：CheckedPaymentException —— 既没解决检查逻辑，又让名字变长，还可能误导人以为它必须被声明
• ? 关键判断点：如果这个异常代表“业务规则被违反”（如余额不足、库存不够），就用 RuntimeException 子类；如果代表“外部系统暂时不可用”（如数据库连不上、HTTP调用超时），才考虑继承 Exception 并强制上层处理

容易被忽略的细节：包结构与错误码耦合

光有好名字不够，异常类必须放在合理包路径下，并配合错误码设计，否则名字再准也白搭。

• 包路径应反映领域层级：com.example.payment.exception 而非 com.example.common.exception——后者会让所有模块异常混在一起，失去业务上下文
• 异常类内部最好封装 errorCode 字段（如 private final int errorCode = 4001;），前端或监控系统靠它做精准响应，而不是解析 getMessage() 字符串
• 别把“命名规范”当孤立任务：一个 OrderNotFoundException 如果抛出时没带订单ID、没记录traceId、没关联错误码，那名字再标准也没法快速定位问题

以上就是《Java异常命名规范与最佳实践》的详细内容，更多关于的资料请关注golang学习网公众号！