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.
15 KiB
15 KiB
工具类库
**本文引用的文件** - [PageConverter.java](file://crm-base/src/main/java/com/crm/base/utils/PageConverter.java) - [BeanCopyUtils.java](file://crm-base/src/main/java/com/crm/base/utils/BeanCopyUtils.java) - [EnumUtils.java](file://crm-base/src/main/java/com/crm/base/utils/EnumUtils.java) - [ExcelUtil.java](file://crm-base/src/main/java/com/crm/base/utils/ExcelUtil.java) - [TreeUtils.java](file://crm-base/src/main/java/com/crm/base/utils/TreeUtils.java) - [AssertUtils.java](file://crm-base/src/main/java/com/crm/base/utils/AssertUtils.java)目录
简介
本文件面向 crm-backend-matt 项目的通用工具类库，聚焦以下常用工具：
- PageConverter 分页转换器
- BeanCopyUtils 对象拷贝工具
- EnumUtils 枚举工具
- ExcelUtil Excel 处理工具
- TreeUtils 树结构处理工具
- AssertUtils 断言工具
文档从系统架构、组件职责、数据流与调用流程、API 说明、使用示例、性能考量与常见问题等方面展开，帮助读者快速理解并正确使用这些工具。
项目结构
工具类均位于基础模块的 utils 包中，彼此独立、低耦合，便于在业务模块中按需引入。
graph TB
subgraph "基础模块"
A["utils.PageConverter"]
B["utils.BeanCopyUtils"]
C["utils.EnumUtils"]
D["utils.ExcelUtil"]
E["utils.TreeUtils"]
F["utils.AssertUtils"]
end
G["业务模块<br/>controller/service/mapper"]
G --> A
G --> B
G --> C
G --> D
G --> E
G --> F
图表来源
- PageConverter.java
- BeanCopyUtils.java
- EnumUtils.java
- ExcelUtil.java
- TreeUtils.java
- AssertUtils.java
章节来源
- PageConverter.java
- BeanCopyUtils.java
- EnumUtils.java
- ExcelUtil.java
- TreeUtils.java
- AssertUtils.java
核心组件
- PageConverter：将数据库分页结果转换为统一的分页响应结构，支持字段映射与类型转换。
- BeanCopyUtils：提供高性能的对象属性拷贝能力，支持忽略空值、指定字段拷贝等场景。
- EnumUtils：封装枚举的常见操作，如按名称/值获取枚举、校验存在性、批量转换等。
- ExcelUtil：封装 Excel 读写能力（导入导出），支持表头映射、列过滤、异常聚合等。
- TreeUtils：对扁平列表进行树形结构组装，支持层级深度控制与排序策略。
- AssertUtils：统一的参数与业务前置断言工具，集中错误信息输出。
章节来源
- PageConverter.java
- BeanCopyUtils.java
- EnumUtils.java
- ExcelUtil.java
- TreeUtils.java
- AssertUtils.java
架构总览
工具类作为横切能力被各层复用，典型调用链如下：
sequenceDiagram
participant C as "控制器/服务"
participant PC as "PageConverter"
participant BC as "BeanCopyUtils"
participant EU as "EnumUtils"
participant EX as "ExcelUtil"
participant TU as "TreeUtils"
participant AU as "AssertUtils"
C->>AU : "参数校验/业务断言"
C->>EU : "枚举解析/转换"
C->>BC : "对象属性拷贝"
C->>PC : "分页结果转换"
C->>EX : "Excel 导入/导出"
C->>TU : "树结构组装"
图表来源
- PageConverter.java
- BeanCopyUtils.java
- EnumUtils.java
- ExcelUtil.java
- TreeUtils.java
- AssertUtils.java
详细组件分析
PageConverter 分页转换器
- 职责
- 将数据库分页对象转换为统一的分页响应结构。
- 支持字段映射、类型转换、空值处理。
- 关键 API
- 分页转换入口方法：接收源分页对象与目标类型，返回分页结果。
- 可选配置：是否包含总数、是否过滤空集合、自定义字段映射规则。
- 使用示例
- 在 Service 层查询后调用转换方法，直接返回给 Controller。
- 结合 BeanCopyUtils 完成复杂 DTO 映射。
- 性能考虑
- 避免在循环内重复创建映射器；优先复用静态实例或缓存映射规则。
- 大数据量分页时，注意只取必要字段，减少内存占用。
- 错误处理
- 当源分页为空或目标类型不匹配时，应返回空分页或抛出明确异常。
flowchart TD
Start(["进入转换"]) --> CheckInput["检查输入是否为空"]
CheckInput --> |为空| ReturnEmpty["返回空分页"]
CheckInput --> |非空| MapFields["执行字段映射/类型转换"]
MapFields --> BuildResult["构建分页结果对象"]
BuildResult --> ReturnResult["返回分页结果"]
图表来源
- PageConverter.java
章节来源
- PageConverter.java
BeanCopyUtils 对象拷贝工具
- 职责
- 高效拷贝对象属性，支持忽略空值、指定字段拷贝、嵌套对象拷贝等。
- 关键 API
- 单对象拷贝：源对象到目标对象。
- 批量拷贝：集合到集合。
- 选择性拷贝：白名单/黑名单字段控制。
- 使用示例
- Entity 转 DTO、DTO 转 VO、请求参数到领域模型。
- 性能考虑
- 反射开销较大，建议对热点路径做缓存或预编译映射。
- 大对象频繁拷贝时，优先考虑构造器或 Builder 模式。
- 错误处理
- 类型不匹配或缺失字段时，记录日志并跳过或抛出明确异常。
classDiagram
class BeanCopyUtils {
+copy(source, target)
+copyList(list, targetType)
+copySelective(source, target, includeFields)
-buildFieldMap()
-applyValue(src, dest, field)
}
图表来源
- BeanCopyUtils.java
章节来源
- BeanCopyUtils.java
EnumUtils 枚举工具
- 职责
- 提供枚举的查找、校验、转换等通用能力。
- 关键 API
- 按名称获取枚举。
- 按值获取枚举。
- 校验枚举是否存在。
- 批量字符串转枚举列表。
- 使用示例
- 接口入参为字符串时，先通过工具转为枚举再进行业务处理。
- 性能考虑
- 枚举查找应为 O(1)，内部通常基于 Map 缓存。
- 避免在热路径重复创建 Map。
- 错误处理
- 找不到对应枚举时，抛出明确的异常或返回 Optional。
flowchart TD
S(["传入名称/值"]) --> Lookup{"查找成功?"}
Lookup --> |是| ReturnEnum["返回枚举"]
Lookup --> |否| RaiseError["抛出未找到异常"]
图表来源
- EnumUtils.java
章节来源
- EnumUtils.java
ExcelUtil Excel 处理
- 职责
- 封装 Excel 导入导出，支持表头映射、列过滤、批量写入、异常聚合。
- 关键 API
- 导出：将集合数据导出为 Excel 文件流。
- 导入：读取 Excel 并映射为对象集合。
- 配置：列名映射、必填校验、默认值填充。
- 使用示例
- 管理后台导出报表、批量导入用户数据。
- 性能考虑
- 大数据导出建议使用流式写入，避免一次性加载到内存。
- 导入时限制行数与列数，防止恶意文件导致 OOM。
- 错误处理
- 行级错误聚合，返回失败明细以便前端提示。
sequenceDiagram
participant U as "调用方"
participant EX as "ExcelUtil"
participant FS as "文件系统/流"
U->>EX : "导出/导入请求"
EX->>FS : "生成/读取流"
FS-->>EX : "字节流"
EX-->>U : "文件流/对象集合"
图表来源
- ExcelUtil.java
章节来源
- ExcelUtil.java
TreeUtils 树结构处理
- 职责
- 将扁平列表组装为树形结构，支持层级深度、排序策略、根节点识别。
- 关键 API
- 列表转树：根据父 ID 关联构建。
- 树遍历：前序/后序遍历、过滤子树。
- 排序：按权重或时间排序。
- 使用示例
- 菜单树、部门树、分类树等。
- 性能考虑
- 使用 Map 缓存子节点，避免 N^2 复杂度。
- 大数据集建议分批组装或限制层级深度。
- 错误处理
- 检测到环引用或非法父 ID 时，抛出明确异常。
flowchart TD
L(["扁平列表"]) --> BuildMap["构建ID->节点映射"]
BuildMap --> LinkChildren["按父ID链接子节点"]
LinkChildren --> SortNodes["按策略排序"]
SortNodes --> RootFilter["筛选根节点"]
RootFilter --> ReturnTree["返回树结构"]
图表来源
- TreeUtils.java
章节来源
- TreeUtils.java
AssertUtils 断言工具
- 职责
- 统一的参数与业务前置断言，集中错误信息输出。
- 关键 API
- 非空断言、条件断言、范围断言、枚举存在断言。
- 使用示例
- 在 Service 入口处校验入参合法性。
- 性能考虑
- 断言仅在调试或开启校验时生效，生产环境可关闭以减少开销。
- 错误处理
- 抛出统一异常类型，便于全局异常处理器捕获。
flowchart TD
A(["断言条件"]) --> Check{"条件满足?"}
Check --> |是| Pass["通过"]
Check --> |否| Throw["抛出断言异常"]
图表来源
- AssertUtils.java
章节来源
- AssertUtils.java
依赖关系分析
工具类之间保持松耦合，主要依赖第三方库（如 Excel 处理）与基础类型。典型依赖如下：
graph LR
PC["PageConverter"] --> BC["BeanCopyUtils"]
EX["ExcelUtil"] --> IO["IO/流"]
TU["TreeUtils"] --> COL["集合/Map"]
AU["AssertUtils"] --> ERR["异常类型"]
EU["EnumUtils"] --> MAP["Map缓存"]
图表来源
- PageConverter.java
- BeanCopyUtils.java
- EnumUtils.java
- ExcelUtil.java
- TreeUtils.java
- AssertUtils.java
章节来源
- PageConverter.java
- BeanCopyUtils.java
- EnumUtils.java
- ExcelUtil.java
- TreeUtils.java
- AssertUtils.java
性能考虑
- 反射与映射
- BeanCopyUtils 的反射开销较高，建议在热点路径缓存字段映射或使用代码生成方案。
- 内存与流式处理
- ExcelUtil 导出大文件时使用流式写入，避免一次性加载全部数据。
- 数据结构优化
- TreeUtils 使用 Map 缓存子节点，确保线性时间复杂度。
- 枚举查找
- EnumUtils 内部使用 Map 缓存，保证 O(1) 查找。
- 分页转换
- PageConverter 应避免不必要的深拷贝，仅复制必要字段。
[本节为通用指导，不直接分析具体文件]
故障排查指南
- 分页转换结果为空
- 检查源分页对象是否为空，确认字段映射是否正确。
- 对象拷贝缺失字段
- 确认目标对象存在 setter 或字段可见性，必要时启用选择性拷贝。
- 枚举转换失败
- 检查枚举名称/值大小写与空格，确认枚举定义完整。
- Excel 导入失败
- 查看行级错误聚合信息，定位具体行列问题；限制文件大小与行数。
- 树结构出现环引用
- 检查父 ID 指向是否合法，增加环检测逻辑。
- 断言异常频繁触发
- 检查上游参数校验逻辑，确认断言条件是否符合预期。
章节来源
- PageConverter.java
- BeanCopyUtils.java
- EnumUtils.java
- ExcelUtil.java
- TreeUtils.java
- AssertUtils.java
结论
上述工具类覆盖了分页转换、对象拷贝、枚举处理、Excel 读写、树结构组装与参数断言等高频场景。通过统一的 API 与良好的错误处理，能够显著提升开发效率与代码质量。在生产环境中，建议关注性能优化与资源限制，确保稳定性与可扩展性。
[本节为总结性内容，不直接分析具体文件]
附录
- 最佳实践
- 在 Service 层统一使用 AssertUtils 进行参数校验。
- 对热点对象拷贝路径进行性能分析与缓存优化。
- Excel 导入导出需设置超时与大小限制，防止资源耗尽。
- 树结构构建前进行数据合法性校验，避免环引用。
- 分页转换时仅选择必要字段，降低内存压力。
[本节为补充性内容，不直接分析具体文件]