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.
17 KiB
17 KiB
服务层封装
**本文引用的文件** - [IBaseService.java](file://crm-base/src/main/java/com/crm/base/service/IBaseService.java) - [BaseServiceImpl.java](file://crm-base/src/main/java/com/crm/base/service/impl/BaseServiceImpl.java) - [MybatisPlusConfig.java](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java) - [MetaObjectFillHandler.java](file://crm-base/src/main/java/com/crm/base/config/MetaObjectFillHandler.java) - [CrmSqlInjector.java](file://crm-base/src/main/java/com/crm/base/config/CrmSqlInjector.java) - [BaseEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/BaseEntity.java) - [OwnedEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/OwnedEntity.java) - [PageResult.java](file://crm-base/src/main/java/com/crm/base/domain/result/PageResult.java) - [Result.java](file://crm-base/src/main/java/com/crm/base/domain/result/Result.java) - [DataScopeHelper.java](file://crm-base/src/main/java/com/crm/base/security/DataScopeHelper.java) - [SecurityUtils.java](file://crm-base/src/main/java/com/crm/base/security/SecurityUtils.java) - [SysDeptServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/SysDeptServiceImpl.java) - [ISysDeptService.java](file://crm-auth/src/main/java/com/crm/auth/service/ISysDeptService.java)目录
简介
本文件面向CRM后端项目的服务层封装，聚焦于通用服务抽象与实现：IBaseService接口设计与BaseServiceImpl通用实现。内容涵盖CRUD、分页查询、批量操作、事务管理、数据权限与审计填充、以及扩展自定义服务的最佳实践与示例。目标是帮助开发者快速理解并复用基础服务能力，提升开发效率与代码一致性。
项目结构
服务层封装位于基础模块crm-base中，提供统一的接口与实现；业务模块crm-auth通过继承该基础能力，构建具体领域服务（如部门、菜单、角色等）。
graph TB
subgraph "基础模块 crm-base"
IBase["IBaseService 接口"]
BaseImpl["BaseServiceImpl 实现"]
MPConf["MybatisPlusConfig 配置"]
Fill["MetaObjectFillHandler 自动填充"]
SQLI["CrmSqlInjector 注入器"]
BE["BaseEntity 基础实体"]
OE["OwnedEntity 数据归属实体"]
PR["PageResult 分页结果"]
R["Result 统一响应"]
DSH["DataScopeHelper 数据权限助手"]
SU["SecurityUtils 安全工具"]
end
subgraph "业务模块 crm-auth"
ISysDept["ISysDeptService 接口"]
SysDeptImpl["SysDeptServiceImpl 实现"]
end
IBase --> BaseImpl
BaseImpl --> MPConf
BaseImpl --> Fill
BaseImpl --> SQLI
BaseImpl --> BE
BaseImpl --> OE
BaseImpl --> PR
BaseImpl --> R
BaseImpl --> DSH
BaseImpl --> SU
ISysDept --> SysDeptImpl
SysDeptImpl --> IBase
图表来源
- IBaseService.java
- BaseServiceImpl.java
- MybatisPlusConfig.java
- MetaObjectFillHandler.java
- CrmSqlInjector.java
- BaseEntity.java
- OwnedEntity.java
- PageResult.java
- Result.java
- DataScopeHelper.java
- SecurityUtils.java
- ISysDeptService.java
- SysDeptServiceImpl.java
章节来源
- IBaseService.java
- BaseServiceImpl.java
核心组件
- IBaseService：定义通用服务契约，包括新增、修改、删除、按ID获取、条件查询、分页查询、批量插入/更新/删除等。
- BaseServiceImpl：基于MyBatis-Plus的通用实现，封装事务、数据权限、审计字段自动填充、分页转换、批量操作优化等。
- 相关支撑：
- MybatisPlusConfig：注册分页插件、乐观锁、SQL注入器等。
- MetaObjectFillHandler：自动填充创建时间、更新时间、创建人、更新人等审计字段。
- CrmSqlInjector：注入公共SQL片段或方法（如数据权限过滤）。
- BaseEntity/OwenedEntity：实体基类，承载通用字段与数据归属信息。
- PageResult/Result：统一的分页与响应包装。
- DataScopeHelper/SecurityUtils：数据权限与安全上下文工具。
章节来源
- IBaseService.java
- BaseServiceImpl.java
- MybatisPlusConfig.java
- MetaObjectFillHandler.java
- CrmSqlInjector.java
- BaseEntity.java
- OwnedEntity.java
- PageResult.java
- Result.java
- DataScopeHelper.java
- SecurityUtils.java
架构总览
服务层采用“接口+基础实现”的抽象模式，业务服务仅需继承基础服务即可复用CRUD与分页能力，并通过自身接口暴露领域语义化方法。
classDiagram
class IBaseService {
+保存实体()
+批量保存()
+更新实体()
+批量更新()
+删除实体()
+批量删除()
+按ID查询()
+条件查询()
+分页查询()
}
class BaseServiceImpl {
-mapper : 泛型Mapper
-dataScopeHelper : DataScopeHelper
-securityUtils : SecurityUtils
+保存实体()
+批量保存()
+更新实体()
+批量更新()
+删除实体()
+批量删除()
+按ID查询()
+条件查询()
+分页查询()
}
class SysDeptServiceImpl {
+部门树查询()
+部门权限过滤()
}
class ISysDeptService {
+部门树查询()
+部门权限过滤()
}
IBaseService <|.. BaseServiceImpl
ISysDeptService <|.. SysDeptServiceImpl
BaseServiceImpl <|-- SysDeptServiceImpl
图表来源
- IBaseService.java
- BaseServiceImpl.java
- ISysDeptService.java
- SysDeptServiceImpl.java
详细组件分析
IBaseService 接口设计
- 目标：为所有领域服务提供一致的CRUD与分页能力，降低重复代码。
- 关键能力：
- 单条与批量保存/更新/删除
- 按ID查询与条件查询
- 分页查询（支持排序、过滤）
- 设计要点：
- 使用泛型约束实体类型，确保类型安全
- 返回统一结果包装，便于上层处理
- 与数据权限、审计填充解耦，由实现类统一处理
章节来源
- IBaseService.java
BaseServiceImpl 实现类
- 目标：基于MyBatis-Plus提供通用实现，屏蔽底层细节。
- 关键能力：
- CRUD：调用Mapper进行持久化
- 分页：结合分页插件与PageResult封装
- 批量：分批提交，减少事务压力
- 事务：默认开启事务，异常回滚
- 数据权限：在查询时注入数据范围过滤
- 审计填充：自动设置创建/更新时间与人员信息
- 性能优化：
- 批量操作使用分批写入
- 分页查询避免全表扫描，合理使用索引
- 条件查询优先使用精确匹配与范围查询
flowchart TD
Start(["进入服务方法"]) --> CheckTxn{"是否已存在事务?"}
CheckTxn --> |否| BeginTxn["开启新事务"]
CheckTxn --> |是| UseExisting["复用现有事务"]
BeginTxn --> Execute["执行数据库操作"]
UseExisting --> Execute
Execute --> Success{"操作成功?"}
Success --> |是| Commit["提交事务"]
Success --> |否| Rollback["回滚事务"]
Commit --> End(["结束"])
Rollback --> End
图表来源
- BaseServiceImpl.java
章节来源
- BaseServiceImpl.java
分页查询流程
- 入口：服务方法接收分页参数（页码、每页大小、排序字段）
- 处理：构造QueryWrapper或Lambda条件，应用数据权限过滤
- 执行：调用分页插件执行查询，转换为PageResult
- 输出：返回统一分页结果
sequenceDiagram
participant Client as "调用方"
participant Service as "BaseServiceImpl"
participant MP as "MyBatis-Plus 分页插件"
participant DB as "数据库"
Client->>Service : 分页查询(参数)
Service->>Service : 组装查询条件
Service->>Service : 应用数据权限过滤
Service->>MP : 执行分页查询
MP->>DB : 生成并执行SQL
DB-->>MP : 返回记录集
MP-->>Service : 返回分页对象
Service->>Service : 转换为PageResult
Service-->>Client : 返回分页结果
图表来源
- BaseServiceImpl.java
- MybatisPlusConfig.java
- PageResult.java
章节来源
- BaseServiceImpl.java
- MybatisPlusConfig.java
- PageResult.java
批量操作策略
- 批量插入/更新/删除：分批次提交，控制单次事务规模
- 适用场景：导入导出、初始化数据、定时任务
- 注意事项：
- 合理设置批次大小，避免内存溢出与长事务
- 对大表操作建议异步化或分片处理
章节来源
- BaseServiceImpl.java
事务管理与错误处理
- 默认事务：服务方法默认开启事务，异常自动回滚
- 嵌套事务：支持传播行为，外层失败整体回滚
- 错误处理：统一异常捕获，返回标准错误码与消息
章节来源
- BaseServiceImpl.java
数据权限与审计填充
- 数据权限：通过DataScopeHelper注入WHERE条件，限制可见数据范围
- 审计填充：MetaObjectFillHandler自动填充创建/更新时间与人员信息
- 安全上下文：SecurityUtils获取当前登录用户信息
章节来源
- DataScopeHelper.java
- MetaObjectFillHandler.java
- SecurityUtils.java
自定义服务扩展指南
- 步骤：
- 定义领域服务接口（如ISysDeptService），继承IBaseService
- 实现类（如SysDeptServiceImpl）继承BaseServiceImpl
- 在实现类中编写领域特定方法，复用基础CRUD与分页能力
- 如需自定义数据权限或审计逻辑，扩展MetaObjectFillHandler或DataScopeHelper
- 示例：部门服务扩展了树形结构与权限过滤
章节来源
- ISysDeptService.java
- SysDeptServiceImpl.java
实际使用示例
- 新增部门：调用保存方法，自动填充审计字段
- 分页查询部门：传入页码、每页大小、排序字段，返回PageResult
- 批量导入：分批插入，控制事务大小
- 删除部门：级联删除子节点，保证数据一致性
章节来源
- SysDeptServiceImpl.java
依赖关系分析
- 服务层依赖MyBatis-Plus进行数据访问
- 依赖安全与数据权限工具进行上下文与过滤
- 依赖统一结果与分页模型进行响应封装
graph LR
IBase["IBaseService"] --> BaseImpl["BaseServiceImpl"]
BaseImpl --> MP["MyBatis-Plus"]
BaseImpl --> DSH["DataScopeHelper"]
BaseImpl --> SU["SecurityUtils"]
BaseImpl --> PR["PageResult"]
BaseImpl --> R["Result"]
BaseImpl --> Fill["MetaObjectFillHandler"]
BaseImpl --> SQLI["CrmSqlInjector"]
图表来源
- IBaseService.java
- BaseServiceImpl.java
- MybatisPlusConfig.java
- MetaObjectFillHandler.java
- CrmSqlInjector.java
- PageResult.java
- Result.java
- DataScopeHelper.java
- SecurityUtils.java
章节来源
- BaseServiceImpl.java
性能考量
- 分页查询：避免N+1问题，使用JOIN或批量加载
- 批量操作：合理批次大小，避免长事务与内存峰值
- 索引优化：为常用查询字段建立索引，减少全表扫描
- 缓存策略：热点数据可引入Redis缓存，减轻数据库压力
- 连接池：调整连接池大小与超时，避免资源耗尽
[本节为通用指导，不直接分析具体文件]
故障排查指南
- 常见问题：
- 分页无效：检查分页插件是否正确注册
- 审计字段未填充：确认MetaObjectFillHandler生效
- 数据权限不生效：检查DataScopeHelper与上下文
- 批量操作失败：查看批次大小与事务边界
- 调试建议：
- 启用SQL日志，观察生成的SQL语句
- 使用统一异常处理器定位错误原因
- 通过TraceId追踪请求链路
章节来源
- MybatisPlusConfig.java
- MetaObjectFillHandler.java
- DataScopeHelper.java
结论
服务层封装通过IBaseService与BaseServiceImpl提供了稳定、高效、可扩展的通用能力。业务服务只需关注领域逻辑，显著提升开发效率与代码质量。结合数据权限、审计填充与事务管理，形成完整的服务层解决方案。
[本节为总结性内容，不直接分析具体文件]
附录
- 实体基类：BaseEntity、OwnedEntity
- 统一响应：Result、PageResult
- 配置项：MybatisPlusConfig、MetaObjectFillHandler、CrmSqlInjector
章节来源
- BaseEntity.java
- OwnedEntity.java
- Result.java
- PageResult.java
- MybatisPlusConfig.java
- MetaObjectFillHandler.java
- CrmSqlInjector.java