BusinessException 配合错误码枚举封装，实现结构化、可读、可扩展的异常处理：定义含编码、消息占位符、HTTP状态码的字符串型枚举；异常继承RuntimeException，构造时传入枚举及参数；统一@ControllerAdvice拦截并返回标准响应体；错误码需契约化管理与协作。
业务异常 BusinessException 配合错误码枚举（Enum）封装，核心是让异常携带结构化、可读、可扩展的错误信息，同时避免硬编码字符串或数字，提升维护性和国际化支持能力。
定义统一错误码枚举
错误码枚举应包含唯一编码（如字符串或整数）、提示消息（可预留多语言占位）、HTTP 状态码（可选）等字段。推荐用字符串编码（如 "USER_NOT_FOUND"），语义清晰且不易冲突。
- 每个枚举项代表一个明确的业务失败场景，例如用户不存在、余额不足、参数校验失败等
- 消息字段建议使用占位符（如
"用户 {0} 不存在"），便于后续配合 MessageSource 实现国际化 - 避免在枚举中直接拼接动态值，保持枚举纯粹性
设计 BusinessException 继承 RuntimeException
BusinessException 应为运行时异常，无需强制 try-catch，符合业务流程中“非预期但可预知”的失败场景定位。构造函数接收错误码枚举 + 可变参数（用于填充消息占位符）。
- 内部持有
ErrorCode枚举引用，提供getCode()、getMessage()（经参数填充后）等访问方法 - 重写
toString()或提供getDetail()方法，方便日志记录完整上下文 - 可额外携带 traceId、requestId 等诊断字段（通过 ThreadLocal 或调用链透传）
统一异常处理器捕获并响应
通过 @ControllerAdvice + @ExceptionHandler(BusinessException.class) 拦截，将枚举中的错误码、填充后的消息、HTTP 状态码组装成标准响应体（如 { "code": "USER_NOT_FOUND", "message": "用户 abc123 不存在" }）。
立即学习“Java免费学习笔记（深入）”；
- 避免在 controller 层手动 new 异常并 throw，推荐封装工具类（如
Exceptions.illegalArgument(ErrorCode.USER_NOT_FOUND, userId)） - 响应体结构建议固定字段：code（枚举 name() 或 code 值）、message（本地化后）、timestamp、traceId（如有）
- 对同一错误码，前端可基于
code做精准提示或跳转，无需解析 message 文本
扩展性与协作建议
错误码枚举和异常类是前后端/多团队协作的关键契约，需配套管理。
- 错误码枚举建议单独模块发布（如
common-error-code），被各服务依赖，保证一致性 - 新增错误码需走小范围评审，避免随意添加或语义模糊（如不使用
"ERROR_001"这类无意义编码） - 日志中记录异常时，优先打印
e.getCode()和关键业务参数，而非堆栈全量（除非 DEBUG 级别）
