luoweijian
/
crm-backend-matt
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
14 Commits
1 Branch
0 Tags
405 MiB
 
 
 
 
 
 
Tree: c877f0d6c4
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'c877f0d6c4'
${ noResults }
crm-backend-matt/.qoder/repowiki/zh/content/项目概览/模块说明/基础框架模块(crm-base)/公共常量与枚举.md

18 KiB
Raw Blame History

公共常量与枚举

**本文引用的文件** - [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) - [AuthConstants.java](file://crm-auth/src/main/java/com/crm/auth/constant/AuthConstants.java) - [FileConstants.java](file://crm-file/src/main/java/com/crm/file/constant/FileConstants.java) - [DataScopeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/DataScopeEnum.java) - [IdentityTypeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/IdentityTypeEnum.java) - [MenuTypeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/MenuTypeEnum.java)

目录

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

简介

本文件面向 CRM 后端项目的“公共常量与枚举”体系，聚焦 crm-base 模块中的系统级常量与通用枚举，并覆盖各业务模块（如认证、文件）的领域常量。目标包括：

  • 解释 CommonConstants 的系统常量定义与使用场景
  • 说明 HasValueEnum 与 StatusEnum 等枚举的设计原则与用法
  • 明确常量的命名规范与枚举设计原则
  • 提供扩展新常量与新枚举的最佳实践

项目结构

本项目采用多模块分层组织，公共常量与枚举集中在基础模块 crm-base 中，业务模块通过引用复用：

  • crm-base：基础能力与通用定义（常量、枚举、异常、结果封装、工具类等）
  • crm-auth：认证与权限相关领域常量与枚举
  • crm-file：文件服务相关常量
graph TB
subgraph "基础模块 crm-base"
BASE_CONST["常量<br/>CommonConstants"]
BASE_ENUMS["通用枚举<br/>HasValueEnum / StatusEnum"]
RESULT_ENUM["结果码枚举<br/>ResultCodeEnum"]
end
subgraph "认证模块 crm-auth"
AUTH_CONST["领域常量<br/>AuthConstants"]
AUTH_ENUMS["领域枚举<br/>DataScopeEnum / IdentityTypeEnum / MenuTypeEnum"]
end
subgraph "文件模块 crm-file"
FILE_CONST["领域常量<br/>FileConstants"]
end
AUTH_CONST --> BASE_ENUMS
FILE_CONST --> BASE_ENUMS
AUTH_ENUMS --> BASE_ENUMS

图表来源

  • CommonConstants.java
  • HasValueEnum.java
  • StatusEnum.java
  • ResultCodeEnum.java
  • AuthConstants.java
  • FileConstants.java
  • DataScopeEnum.java
  • IdentityTypeEnum.java
  • MenuTypeEnum.java

章节来源

  • CommonConstants.java
  • HasValueEnum.java
  • StatusEnum.java
  • ResultCodeEnum.java
  • AuthConstants.java
  • FileConstants.java
  • DataScopeEnum.java
  • IdentityTypeEnum.java
  • MenuTypeEnum.java

核心组件

  • 系统常量 CommonConstants

    • 作用：集中存放跨模块复用的系统级常量（如分页默认值、时间格式、缓存键前缀、消息头名等），避免魔法字符串散落各处。
    • 典型类别：分页参数默认值、日期时间格式、Redis Key 前缀、HTTP 请求头名称、通用开关或阈值等。
    • 使用建议：所有跨模块共享的“硬编码值”应优先从该处引用，禁止在业务代码中直接写死。

  • 通用枚举 HasValueEnum

    • 作用：为“有值/无值”或“启用/禁用”等二元状态提供统一抽象，便于在不同实体字段上复用一致的语义。
    • 设计要点：通常包含取值与显示文本映射，并提供按值查找、按显示文本查找等方法；保持枚举实例不可变且稳定。
    • 使用场景：布尔型字段的替代方案，利于前端展示与国际化扩展。

  • 通用枚举 StatusEnum

    • 作用：统一表示对象生命周期或运行状态（如正常、停用、删除等），确保全链路状态一致。
    • 设计要点：每个枚举项需具备稳定的 code/value 与可读描述；提供按值查询、排序顺序等辅助方法。
    • 使用场景：数据表中的状态列、接口返回的状态字段、流程控制的条件判断。

  • 结果码枚举 ResultCodeEnum

    • 作用：统一 API 响应码与消息，保证前后端对错误语义的一致性。
    • 设计要点：code 唯一且稳定，message 清晰可定位问题；必要时支持参数化消息模板。

章节来源

  • CommonConstants.java
  • HasValueEnum.java
  • StatusEnum.java
  • ResultCodeEnum.java

架构总览

下图展示了常量与枚举在各模块间的分布与复用关系。基础模块提供“最小可用”的通用定义，业务模块按需扩展领域常量与枚举，并通过引用实现解耦。

classDiagram
class CommonConstants {
+系统常量集合
}
class HasValueEnum {
+取值
+显示文本
+按值获取
}
class StatusEnum {
+状态码
+状态描述
+按值获取
}
class ResultCodeEnum {
+响应码
+响应消息
}
class AuthConstants {
+认证域常量
}
class FileConstants {
+文件域常量
}
class DataScopeEnum {
+数据范围
}
class IdentityTypeEnum {
+身份类型
}
class MenuTypeEnum {
+菜单类型
}
AuthConstants --> HasValueEnum : "可能复用"
AuthConstants --> StatusEnum : "可能复用"
FileConstants --> HasValueEnum : "可能复用"
FileConstants --> StatusEnum : "可能复用"
DataScopeEnum --> HasValueEnum : "可能复用"
IdentityTypeEnum --> HasValueEnum : "可能复用"
MenuTypeEnum --> HasValueEnum : "可能复用"

图表来源

  • CommonConstants.java
  • HasValueEnum.java
  • StatusEnum.java
  • ResultCodeEnum.java
  • AuthConstants.java
  • FileConstants.java
  • DataScopeEnum.java
  • IdentityTypeEnum.java
  • MenuTypeEnum.java

详细组件分析

CommonConstants（系统常量）

  • 职责边界
    • 集中管理跨模块共享的“不变量”，降低散落的魔法字符串与数字带来的维护成本。
    • 作为团队约定的一部分，约束输入输出、缓存键、日志标记、配置键等。
  • 常见分类
    • 分页与排序：默认页大小、最大页大小、默认排序字段等
    • 时间与格式：日期时间格式、时区、序列化策略等
    • 缓存与键空间：Redis Key 前缀、过期时间默认值等
    • HTTP 与网关：请求头名称、跨域策略、限流键前缀等
    • 业务阈值：文件大小限制、重试次数、超时时间等
  • 使用建议
    • 新增常量必须补充注释，说明用途与变更历史
    • 避免将易变的业务规则放入常量，必要时改为配置项
    • 对敏感信息（密钥、令牌）严禁以明文常量形式存在

章节来源

  • CommonConstants.java

HasValueEnum（有值/无值枚举）

  • 设计原则
    • 语义清晰：用枚举表达“有值/无值”或“启用/禁用”，避免裸布尔值歧义
    • 可扩展性：预留 displayText、sortOrder 等字段，便于前端展示与排序
    • 稳定性：code/value 一旦发布不得随意变更，如需调整需兼容迁移
  • 常用方法
    • 按值获取枚举实例
    • 校验值是否合法
    • 获取显示文本或国际化 key
  • 使用场景
    • 实体类中的布尔型字段替代
    • 表单校验与下拉选项生成
    • 与前端字典联动

章节来源

  • HasValueEnum.java

StatusEnum（状态枚举）

  • 设计原则
    • 状态机思维：明确初始态、流转规则与终态
    • 一致性：数据库、接口、日志、监控均使用同一套状态码
    • 可观测性：状态变化需可追踪，配合审计日志
  • 常用方法
    • 按值获取枚举实例
    • 判断是否为有效状态
    • 获取状态描述用于展示
  • 使用场景
    • 订单、审批、任务等业务流程状态
    • 资源的生命周期（启用/停用/删除）
    • 对外 API 的状态码映射

章节来源

  • StatusEnum.java

ResultCodeEnum（结果码枚举）

  • 设计原则
    • 全局唯一：code 不重复、不重用
    • 语义明确：message 能直接指导排错
    • 版本兼容：新增 code 不应破坏既有调用方
  • 使用场景
    • 统一 API 响应体
    • 错误码与监控告警关联
    • 前端错误提示文案来源

章节来源

  • ResultCodeEnum.java

领域常量与枚举（认证与文件）

  • AuthConstants
    • 职责：认证域内的固定键名、令牌前缀、会话标识等
    • 使用：登录、鉴权、第三方接入等流程
  • FileConstants
    • 职责：文件上传分片、存储路径、预览服务等固定配置
    • 使用：分片上传、断点续传、在线预览等流程
  • DataScopeEnum / IdentityTypeEnum / MenuTypeEnum
    • 职责：数据权限范围、身份类型、菜单类型等
    • 使用：权限模型、菜单树构建、数据隔离

章节来源

  • AuthConstants.java
  • FileConstants.java
  • DataScopeEnum.java
  • IdentityTypeEnum.java
  • MenuTypeEnum.java

依赖关系分析

  • 耦合度
    • 常量与枚举本身无运行时依赖，仅被其他模块引用
    • 业务逻辑通过引用常量/枚举减少硬编码，提升内聚性
  • 扩展性
    • 新增枚举项不影响既有调用方（只要不改变既有 code/value）
    • 常量变更需评估影响面，必要时提供兼容层或迁移脚本
graph LR
COMMON["CommonConstants"] --> AUTH["AuthConstants"]
COMMON --> FILE["FileConstants"]
HAS["HasValueEnum"] --> AUTH_ENUMS["认证枚举"]
STATUS["StatusEnum"] --> AUTH_ENUMS
HAS --> FILE_ENUMS["文件枚举(如有)"]
STATUS --> FILE_ENUMS

图表来源

  • CommonConstants.java
  • HasValueEnum.java
  • StatusEnum.java
  • AuthConstants.java
  • FileConstants.java

章节来源

  • CommonConstants.java
  • HasValueEnum.java
  • StatusEnum.java
  • AuthConstants.java
  • FileConstants.java

性能考虑

  • 枚举与常量均为编译期常量或轻量运行时对象，开销极低
  • 避免在热点路径频繁解析枚举显示文本，建议缓存或预取
  • 对大体积常量集合（如字典表）建议使用懒加载或外部配置中心

故障排查指南

  • 常见问题
    • 使用了未定义的枚举值导致空指针或分支遗漏
    • 常量拼写不一致导致缓存键冲突或请求头丢失
    • 修改了已有枚举 code/value 造成下游解析失败
  • 排查步骤
    • 检查枚举按值获取方法的健壮性与空值处理
    • 核对常量引用位置，确认是否存在多处不一致
    • 查看日志中的状态码与消息，定位具体环节
  • 修复建议
    • 增加单元测试覆盖枚举与常量的关键路径
    • 引入静态扫描或契约测试，防止破坏性变更

章节来源

  • HasValueEnum.java
  • StatusEnum.java
  • ResultCodeEnum.java
  • CommonConstants.java

结论

  • 统一的常量与枚举是系统可维护性的基石
  • 通过 CommonConstants、HasValueEnum、StatusEnum 等基础构件，结合各领域的常量与枚举，形成清晰的层次与复用机制
  • 遵循命名规范与设计原则，可有效降低沟通成本与回归风险

附录：扩展指南

新增系统常量（CommonConstants）

  • 适用场景
    • 跨模块共享的固定值（如分页默认值、时间格式、缓存前缀、请求头名等）
  • 步骤
    • 在 CommonConstants 中添加常量，给出清晰注释与用途说明
    • 在业务代码中替换原有硬编码引用
    • 更新相关文档与测试用例
  • 注意事项
    • 避免将易变规则放入常量，必要时改为配置项
    • 对敏感信息严禁以明文常量形式存在

章节来源

  • CommonConstants.java

新增通用枚举（HasValueEnum / StatusEnum）

  • 适用场景
    • 需要统一语义的二元或多值状态（如启用/停用、有值/无值）
  • 步骤
    • 在对应枚举中新增枚举项，确保 code/value 唯一且稳定
    • 完善按值获取、校验、显示文本等方法
    • 在实体与接口中使用新枚举替代裸值
  • 注意事项
    • 已发布枚举项不得随意变更 code/value
    • 新增枚举项需同步更新前端字典与测试用例

章节来源

  • HasValueEnum.java
  • StatusEnum.java

新增领域常量与枚举（认证/文件）

  • 适用场景
    • 特定业务域的固定键名、类型、范围等
  • 步骤
    • 在对应模块的 constant 或 enums 包下新增
    • 尽量复用基础枚举（HasValueEnum/StatusEnum）表达通用语义
    • 在控制器、服务层统一引用，避免散落
  • 注意事项
    • 保持命名一致性与可读性
    • 与接口文档保持一致，避免前后端不一致

章节来源

  • AuthConstants.java
  • FileConstants.java
  • DataScopeEnum.java
  • IdentityTypeEnum.java
  • MenuTypeEnum.java

命名规范与设计原则

  • 命名规范
    • 常量：全大写+下划线分隔，语义明确（如 PAGE_DEFAULT_SIZE、DATE_TIME_FORMAT）
    • 枚举：名词短语，首字母大写（如 StatusEnum、HasValueEnum）
    • 枚举项：全大写+下划线（如 ENABLED、DISABLED、DELETED）
  • 设计原则
    • 单一职责：一个枚举只表达一类语义
    • 稳定优先：code/value 一旦发布不得破坏性变更
    • 可观测性：枚举项需具备可读描述，便于日志与监控
    • 可扩展性：预留排序、显示文本、国际化 key 等扩展点

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