企业级Java项目中应构建分层自定义异常体系：业务异常（如“余额不足”）、系统异常（如DB超时）、参数异常（如校验失败），每类需携带errorCode、errorMessage等结构化字段，并通过@ControllerAdvice统一处理，配套错误码文档与前端协作机制。
在企业级 Java 项目中，自定义异常不是为了“造轮子”，而是为了统一错误语义、分离业务逻辑与错误处理、支撑前端友好提示和日志可追溯性。关键不在于抛多少种异常，而在于每种异常是否承载明确的业务含义、是否能被系统性捕获和翻译。
定义分层的自定义异常体系
避免全项目只用一个 BusinessException。按错误性质和处理方式分层设计：
-
业务异常（Checked 或 RuntimeException）：表示可预期的业务规则失败，如“余额不足”“订单已取消”。建议继承
RuntimeException，避免强制 try-catch 干扰主流程，但需保证全局统一捕获并转为标准响应。 - 系统异常（RuntimeException）：封装底层技术错误（如 DB 连接超时、Redis 不可用），通常带原始异常 cause，用于告警和排查，不直接透出给前端。
- 参数异常（RuntimeException）：专用于校验失败（如 JSR-303 校验不通过），可自带字段名、错误码、默认提示模板，便于前端精准定位问题字段。
每个异常类必须携带结构化错误信息
不要只靠 getMessage() 返回字符串。推荐在自定义异常中内聚以下字段：
-
errorCode：全局唯一数字码（如
1001）或业务域前缀码（如ORDER_001），用于前端 i18n 映射和监控分类。 - errorMessage：用户可见的简明中文提示（如“库存不足，请稍后再试”），不含技术细节、不带堆栈。
- errorDetail（可选）：供运维/开发查看的上下文（如“商品ID=12345，当前库存=0，请求扣减量=2”），不返回给前端。
- HttpStatus（可选）：配合 Spring MVC，不同异常映射不同 HTTP 状态码（如参数错用 400，业务拒绝用 409，系统故障用 500）。
用全局异常处理器统一拦截与标准化输出
在 Spring Boot 中，通过 @ControllerAdvice + @ExceptionHandler 实现“一处定义，处处生效”：
Java 接口排错助手
下载
在调试 Java 后端 API 故障时使用此技能，尤其适用于以下任务：分析日志、跨 Controller、Service 和 Mapper 层追踪请求、定位异常根因、检查 SQL 执行或参数流转，以及生成简洁的诊断结论与修复方案。
立即学习“Java免费学习笔记（深入）”；
- 捕获自定义业务异常，组装成统一 JSON 响应体（如
{"code":1001,"msg":"库存不足","data":null}）； - 对
MethodArgumentNotValidException等框架异常做适配，提取校验注解信息，转为带字段名的错误码+提示； - 对未捕获的
Throwable记录完整堆栈到日志（ELK 可查），返回通用服务异常（如“系统繁忙，请稍后重试”），绝不暴露内部信息。
配套：错误码文档与前端协作机制
异常的价值最终体现在前端体验上。必须配套落地：
- 维护一份可检索的 错误码表 Excel 或 Markdown，包含 errorCode、含义、建议操作、是否需重试、所属模块；
- 前端根据
code字段做国际化映射（如 Vue 的$t(`error.${code}`)），而非硬编码中文； - 对需要特殊交互的错误（如登录过期跳转、支付重复提交拦截），约定特定 error code，前后端联合识别处理。
不复杂但容易忽略：异常类本身要加 serialVersionUID，确保分布式环境下反序列化稳定；所有构造方法都应支持 errorCode + errorMessage + cause 的组合，保持扩展性。
