crm-backend-matt/.qoder/repowiki/zh/content/基础框架/通用常量与枚举.md

# 通用常量与枚举

<cite>
**本文引用的文件**   
- [CommonConstants.java](file://crm-base/src/main/java/com/crm/base/constant/CommonConstants.java)
- [HasValueEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/HasValueEnum.java)
- [StatusEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/StatusEnum.java)
- [ResultCodeEnum.java](file://crm-base/src/main/java/com/crm/base/domain/result/ResultCodeEnum.java)
- [Result.java](file://crm-base/src/main/java/com/crm/base/domain/result/Result.java)
- [PageResult.java](file://crm-base/src/main/java/com/crm/base/domain/result/PageResult.java)
- [GlobalExceptionHandlerAdvice.java](file://crm-base/src/main/java/com/crm/base/advice/GlobalExceptionHandlerAdvice.java)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件面向“通用常量与枚举”的规范与使用，聚焦以下目标：
- 系统级常量定义（HTTP 状态码、请求头、数据库相关常量等）在 CommonConstants 中的组织方式与使用建议。
- HasValueEnum 与 StatusEnum 的设计意图、使用方法与扩展方式。
- ResultCodeEnum 的响应码规范与错误码体系，以及与统一返回体 Result、分页结果 PageResult 的配合。
- 提供最佳实践与自定义枚举创建指导，帮助团队保持一致性、可维护性与可扩展性。

## 项目结构
与通用常量与枚举相关的代码集中在 crm-base 模块中，便于各业务模块复用：
- 常量定义：crm-base/.../constant/CommonConstants.java
- 通用枚举：crm-base/.../domain/enums/HasValueEnum.java、StatusEnum.java
- 统一响应与错误码：crm-base/.../domain/result/ResultCodeEnum.java、Result.java、PageResult.java
- 全局异常处理：crm-base/.../advice/GlobalExceptionHandlerAdvice.java

```mermaid
graph TB
subgraph "基础能力(crm-base)"
CC["CommonConstants<br/>系统常量"]
HVE["HasValueEnum<br/>带值枚举基类"]
SE["StatusEnum<br/>状态枚举示例"]
RCE["ResultCodeEnum<br/>响应码与错误码"]
RES["Result<br/>统一返回体"]
PAGERES["PageResult<br/>分页返回体"]
GHA["GlobalExceptionHandlerAdvice<br/>全局异常处理"]
end
CC --> RES
HVE --> SE
RCE --> RES
RCE --> PAGERES
GHA --> RES
GHA --> RCE
```

图表来源
- [CommonConstants.java](file://crm-base/src/main/java/com/crm/base/constant/CommonConstants.java)
- [HasValueEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/HasValueEnum.java)
- [StatusEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/StatusEnum.java)
- [ResultCodeEnum.java](file://crm-base/src/main/java/com/crm/base/domain/result/ResultCodeEnum.java)
- [Result.java](file://crm-base/src/main/java/com/crm/base/domain/result/Result.java)
- [PageResult.java](file://crm-base/src/main/java/com/crm/base/domain/result/PageResult.java)
- [GlobalExceptionHandlerAdvice.java](file://crm-base/src/main/java/com/crm/base/advice/GlobalExceptionHandlerAdvice.java)

章节来源
- [CommonConstants.java](file://crm-base/src/main/java/com/crm/base/constant/CommonConstants.java)
- [HasValueEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/HasValueEnum.java)
- [StatusEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/StatusEnum.java)
- [ResultCodeEnum.java](file://crm-base/src/main/java/com/crm/base/domain/result/ResultCodeEnum.java)
- [Result.java](file://crm-base/src/main/java/com/crm/base/domain/result/Result.java)
- [PageResult.java](file://crm-base/src/main/java/com/crm/base/domain/result/PageResult.java)
- [GlobalExceptionHandlerAdvice.java](file://crm-base/src/main/java/com/crm/base/advice/GlobalExceptionHandlerAdvice.java)

## 核心组件
- CommonConstants：集中管理系统级常量，如 HTTP 状态码、常用请求头、数据库相关常量等，避免散落在各处导致不一致。
- HasValueEnum：为“带值枚举”提供统一抽象，便于枚举项携带业务值（如 code、message），并提供转换工具方法。
- StatusEnum：基于 HasValueEnum 的典型实现，用于表示常见状态（如启用/禁用、有效/无效等）。
- ResultCodeEnum：定义统一的响应码与错误码，配合 Result/PageResult 形成一致的 API 返回规范。
- GlobalExceptionHandlerAdvice：将业务异常转换为标准 Result 响应，确保错误码与消息的统一输出。

章节来源
- [CommonConstants.java](file://crm-base/src/main/java/com/crm/base/constant/CommonConstants.java)
- [HasValueEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/HasValueEnum.java)
- [StatusEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/StatusEnum.java)
- [ResultCodeEnum.java](file://crm-base/src/main/java/com/crm/base/domain/result/ResultCodeEnum.java)
- [GlobalExceptionHandlerAdvice.java](file://crm-base/src/main/java/com/crm/base/advice/GlobalExceptionHandlerAdvice.java)

## 架构总览
下图展示了常量与枚举在统一响应流程中的作用：业务层通过 ResultCodeEnum 获取错误码，结合业务信息封装为 Result；全局异常处理器将未捕获异常转为标准响应；分页场景使用 PageResult。

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Controller as "控制器"
participant Service as "服务层"
participant Enum as "ResultCodeEnum"
participant Resp as "Result/PageResult"
participant ExHandler as "GlobalExceptionHandlerAdvice"
Client->>Controller : "发起请求"
Controller->>Service : "执行业务逻辑"
Service-->>Controller : "返回数据或抛出异常"
alt "正常返回"
Controller->>Resp : "封装成功响应(含code/message/data)"
Resp-->>Client : "标准JSON响应"
else "发生异常"
Controller->>ExHandler : "抛出异常"
ExHandler->>Enum : "解析错误码/默认码"
ExHandler->>Resp : "封装错误响应"
Resp-->>Client : "标准JSON响应"
end
```

图表来源
- [ResultCodeEnum.java](file://crm-base/src/main/java/com/crm/base/domain/result/ResultCodeEnum.java)
- [Result.java](file://crm-base/src/main/java/com/crm/base/domain/result/Result.java)
- [PageResult.java](file://crm-base/src/main/java/com/crm/base/domain/result/PageResult.java)
- [GlobalExceptionHandlerAdvice.java](file://crm-base/src/main/java/com/crm/base/advice/GlobalExceptionHandlerAdvice.java)

## 详细组件分析

### CommonConstants：系统常量
- 职责：集中定义跨模块复用的系统常量，包括但不限于：
  - HTTP 状态码常量（如 2xx/4xx/5xx 分类）
  - 常用请求头键名（如认证、追踪、内容类型等）
  - 数据库相关常量（如表名前缀、字段命名约定、分页默认值等）
- 设计要点：
  - 使用静态 final 常量，保证不可变与线程安全
  - 按功能域分组（HTTP、Header、DB、Cache、Time 等），提升可读性
  - 避免硬编码字符串散落各处，统一由该常量类导出
- 使用建议：
  - 在过滤器、拦截器、Web 层统一读取请求头
  - 在持久化层使用表/字段前缀常量，保持命名一致
  - 在配置类中使用默认分页大小、超时时间等常量

章节来源
- [CommonConstants.java](file://crm-base/src/main/java/com/crm/base/constant/CommonConstants.java)

### HasValueEnum：带值枚举基类
- 设计意图：为所有“带业务值”的枚举提供统一抽象，典型包含：
  - 业务值字段（如 code、value）
  - 描述字段（如 message、label）
  - 根据值查找枚举项的方法
  - 校验与转换工具方法
- 复杂度与性能：
  - 查找通常为 O(n) 线性扫描，若枚举项较多可引入缓存映射以提升性能
  - 建议在枚举初始化时构建 value->enum 的映射，使查找降为 O(1)
- 扩展方式：
  - 新建枚举实现 HasValueEnum，定义自身业务值与描述
  - 提供 fromValue(value) 或类似方法，支持按值反查枚举
  - 对非法值进行明确异常提示，便于问题定位

```mermaid
classDiagram
class HasValueEnum {
+getValue() T
+getMessage() String
+fromValue(value) HasValueEnum
}
class StatusEnum {
+ACTIVE
+INACTIVE
+getValue() int
+getMessage() String
}
HasValueEnum <|-- StatusEnum : "实现"
```

图表来源
- [HasValueEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/HasValueEnum.java)
- [StatusEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/StatusEnum.java)

章节来源
- [HasValueEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/HasValueEnum.java)
- [StatusEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/StatusEnum.java)

### StatusEnum：状态枚举示例
- 用途：表达常见的状态语义（如启用/禁用、有效/无效等），并绑定对应的业务值与描述
- 使用模式：
  - 在 DTO/VO 中使用枚举类型替代裸数值，增强可读性
  - 在查询条件中通过枚举值构造 SQL 参数
  - 在前端展示时通过枚举描述渲染友好文本
- 扩展建议：
  - 新增状态时，遵循 HasValueEnum 的契约，补充 fromValue 映射
  - 避免修改已有枚举项的值，确保向后兼容

章节来源
- [StatusEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/StatusEnum.java)
- [HasValueEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/HasValueEnum.java)

### ResultCodeEnum：响应码与错误码体系
- 职责：统一定义 API 响应码与错误码，包括：
  - 成功码（如 200/0）
  - 客户端错误码（如参数错误、权限不足、资源不存在）
  - 服务端错误码（如系统异常、第三方调用失败）
- 与统一返回体的协作：
  - Result：封装 code、message、data，作为接口统一返回结构
  - PageResult：封装分页数据（列表、总数、页码等），同样遵循 code/message 规范
- 使用建议：
  - 业务异常应映射到具体的错误码，而非直接透传异常堆栈
  - 对外暴露的错误码需具备清晰语义，避免泄露内部实现细节
  - 新增错误码时，需在文档中同步更新说明

```mermaid
flowchart TD
Start(["进入业务方法"]) --> CheckParam["参数校验"]
CheckParam --> ParamOK{"参数合法?"}
ParamOK --> |否| BuildErr["构建错误响应(Result)<br/>使用ResultCodeEnum错误码"]
ParamOK --> |是| DoBiz["执行业务逻辑"]
DoBiz --> BizOK{"执行成功?"}
BizOK --> |否| HandleErr["捕获异常并映射为错误码"]
BizOK --> |是| BuildOk["构建成功响应(Result)<br/>code=成功码,data=业务数据"]
HandleErr --> BuildErr
BuildErr --> End(["返回统一响应"])
BuildOk --> End
```

图表来源
- [ResultCodeEnum.java](file://crm-base/src/main/java/com/crm/base/domain/result/ResultCodeEnum.java)
- [Result.java](file://crm-base/src/main/java/com/crm/base/domain/result/Result.java)

章节来源
- [ResultCodeEnum.java](file://crm-base/src/main/java/com/crm/base/domain/result/ResultCodeEnum.java)
- [Result.java](file://crm-base/src/main/java/com/crm/base/domain/result/Result.java)
- [PageResult.java](file://crm-base/src/main/java/com/crm/base/domain/result/PageResult.java)

### 全局异常处理与统一响应
- GlobalExceptionHandlerAdvice：集中处理未捕获异常，将其转换为标准 Result 响应，确保：
  - 错误码统一来自 ResultCodeEnum
  - 错误消息对用户友好且不泄露敏感信息
  - 日志记录关键上下文以便排障
- 与 Result 的配合：
  - 成功路径：controller/service 返回业务数据，统一封装为 Result
  - 失败路径：异常处理器捕获异常，映射为错误码并封装为 Result

```mermaid
sequenceDiagram
participant C as "客户端"
participant Ctrl as "控制器"
participant Svc as "服务层"
participant EH as "GlobalExceptionHandlerAdvice"
participant RC as "ResultCodeEnum"
participant R as "Result"
C->>Ctrl : "请求"
Ctrl->>Svc : "调用服务"
Svc-->>Ctrl : "返回数据或抛异常"
alt "无异常"
Ctrl->>R : "封装成功响应"
R-->>C : "返回"
else "有异常"
Ctrl->>EH : "抛出异常"
EH->>RC : "解析错误码"
EH->>R : "封装错误响应"
R-->>C : "返回"
end
```

图表来源
- [GlobalExceptionHandlerAdvice.java](file://crm-base/src/main/java/com/crm/base/advice/GlobalExceptionHandlerAdvice.java)
- [ResultCodeEnum.java](file://crm-base/src/main/java/com/crm/base/domain/result/ResultCodeEnum.java)
- [Result.java](file://crm-base/src/main/java/com/crm/base/domain/result/Result.java)

章节来源
- [GlobalExceptionHandlerAdvice.java](file://crm-base/src/main/java/com/crm/base/advice/GlobalExceptionHandlerAdvice.java)
- [ResultCodeEnum.java](file://crm-base/src/main/java/com/crm/base/domain/result/ResultCodeEnum.java)
- [Result.java](file://crm-base/src/main/java/com/crm/base/domain/result/Result.java)

## 依赖关系分析
- CommonConstants 被多处引用（HTTP、Header、DB 等），属于低耦合高内聚的基础常量集
- HasValueEnum 被具体枚举（如 StatusEnum）实现，体现“基类+实现”的枚举扩展模式
- ResultCodeEnum 与 Result/PageResult 紧密协作，构成统一的响应规范
- GlobalExceptionHandlerAdvice 依赖 ResultCodeEnum，确保异常到响应的映射一致性

```mermaid
graph LR
CC["CommonConstants"] --> |被引用| Any["任意模块"]
HVE["HasValueEnum"] --> |被实现| SE["StatusEnum"]
RCE["ResultCodeEnum"] --> |被使用| RES["Result"]
RCE --> |被使用| PAGERES["PageResult"]
GHA["GlobalExceptionHandlerAdvice"] --> |使用| RCE
GHA --> |返回| RES
```

图表来源
- [CommonConstants.java](file://crm-base/src/main/java/com/crm/base/constant/CommonConstants.java)
- [HasValueEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/HasValueEnum.java)
- [StatusEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/StatusEnum.java)
- [ResultCodeEnum.java](file://crm-base/src/main/java/com/crm/base/domain/result/ResultCodeEnum.java)
- [Result.java](file://crm-base/src/main/java/com/crm/base/domain/result/Result.java)
- [PageResult.java](file://crm-base/src/main/java/com/crm/base/domain/result/PageResult.java)
- [GlobalExceptionHandlerAdvice.java](file://crm-base/src/main/java/com/crm/base/advice/GlobalExceptionHandlerAdvice.java)

章节来源
- [CommonConstants.java](file://crm-base/src/main/java/com/crm/base/constant/CommonConstants.java)
- [HasValueEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/HasValueEnum.java)
- [StatusEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/StatusEnum.java)
- [ResultCodeEnum.java](file://crm-base/src/main/java/com/crm/base/domain/result/ResultCodeEnum.java)
- [Result.java](file://crm-base/src/main/java/com/crm/base/domain/result/Result.java)
- [PageResult.java](file://crm-base/src/main/java/com/crm/base/domain/result/PageResult.java)
- [GlobalExceptionHandlerAdvice.java](file://crm-base/src/main/java/com/crm/base/advice/GlobalExceptionHandlerAdvice.java)

## 性能考虑
- 枚举查找优化：对于频繁按值查找的枚举，可在初始化阶段构建 value->枚举的映射，将查找从 O(n) 降至 O(1)
- 常量访问：静态常量访问开销极低，但应避免在热点路径中进行不必要的字符串拼接
- 统一响应封装：Result/PageResult 的序列化成本可控，注意避免在循环中重复创建对象
- 异常处理：尽量减少异常抛出的频率，优先采用条件判断与返回值控制流程

[本节为通用性能建议，不直接分析具体文件]

## 故障排查指南
- 常见问题
  - 错误码缺失或未定义：检查 ResultCodeEnum 是否已定义对应错误码，并在异常映射中补齐
  - 枚举值不匹配：确认前端传递的枚举值与后端枚举定义一致，必要时增加 fromValue 的容错与提示
  - 请求头不一致：核对 CommonConstants 中的 Header 常量是否与网关/前端保持一致
- 定位步骤
  - 查看全局异常处理器日志，确认异常类型与错误码映射
  - 检查 Result 返回的 code/message，对照 ResultCodeEnum 说明
  - 验证枚举 fromValue 的实现是否正确覆盖所有业务值
- 修复建议
  - 为新增枚举项补充映射与测试用例
  - 在接口文档中更新错误码说明与示例
  - 对关键路径增加断言与边界检查

章节来源
- [GlobalExceptionHandlerAdvice.java](file://crm-base/src/main/java/com/crm/base/advice/GlobalExceptionHandlerAdvice.java)
- [ResultCodeEnum.java](file://crm-base/src/main/java/com/crm/base/domain/result/ResultCodeEnum.java)
- [HasValueEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/HasValueEnum.java)

## 结论
- CommonConstants 提供了系统级常量的统一入口，有助于减少硬编码与不一致
- HasValueEnum 与 StatusEnum 构成了可扩展的枚举体系，便于业务建模与前后端协同
- ResultCodeEnum 与 Result/PageResult 形成了清晰的响应与错误码规范，配合全局异常处理提升稳定性与可观测性
- 建议团队在新增常量与枚举时遵循本文的最佳实践，确保一致性与可维护性

[本节为总结性内容，不直接分析具体文件]

## 附录

### 常量使用最佳实践
- 分类清晰：按功能域分组（HTTP、Header、DB、Cache、Time 等）
- 命名规范：常量名全大写、下划线分隔，语义明确
- 避免魔法值：禁止在业务代码中直接使用字符串/数字字面量
- 版本兼容：新增常量不影响既有行为，旧常量保留兼容性

### 自定义枚举创建指导
- 继承 HasValueEnum，定义业务值与描述字段
- 实现 fromValue(value) 方法，确保所有业务值均可反查
- 对非法值抛出明确的异常或返回空，便于上层处理
- 在单元测试中覆盖正常与异常路径

### 统一响应与错误码规范
- 成功响应：code=成功码，message=成功描述，data=业务数据
- 失败响应：code=错误码，message=用户可见的错误描述，data=null
- 分页响应：PageResult 包含列表、总数、页码等字段，仍遵循 code/message 规范
- 错误码分层：客户端错误（4xx）、服务端错误（5xx）、业务错误（自定义区间）

[本节为概念性指导，不直接分析具体文件]