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.
19 KiB
19 KiB
框架使用
**本文引用的文件** - [CrmAppApplication.java](file://crm-app/src/main/java/com/crm/app/CrmAppApplication.java) - [application.yml](file://crm-app/src/main/resources/application.yml) - [AuthController.java](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.java) - [SystemController.java](file://crm-auth/src/main/java/com/crm/auth/controller/SystemController.java) - [AuthUser.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/AuthUser.java) - [SysDept.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysDept.java) - [AuthUserMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/AuthUserMapper.java) - [SysDeptMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/SysDeptMapper.java) - [IAuthUserService.java](file://crm-auth/src/main/java/com/crm/auth/service/IAuthUserService.java) - [AuthUserServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthUserServiceImpl.java) - [ISysDeptService.java](file://crm-auth/src/main/java/com/crm/auth/service/ISysDeptService.java) - [SysDeptServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/SysDeptServiceImpl.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) - [BaseDTO.java](file://crm-base/src/main/java/com/crm/base/domain/dto/BaseDTO.java) - [BaseParam.java](file://crm-base/src/main/java/com/crm/base/domain/param/BaseParam.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) - [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) - [CrmBaseMapper.java](file://crm-base/src/main/java/com/crm/base/mapper/CrmBaseMapper.java) - [BaseServiceImpl.java](file://crm-base/src/main/java/com/crm/base/service/impl/BaseServiceImpl.java) - [IBaseService.java](file://crm-base/src/main/java/com/crm/base/service/IBaseService.java) - [SnowflakeIdWorker.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeIdWorker.java) - [CustomIdGenerator.java](file://crm-base/src/main/java/com/crm/base/config/CustomIdGenerator.java) - [DataScope.java](file://crm-base/src/main/java/com/crm/base/annotation/DataScope.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) - [LoginUser.java](file://crm-base/src/main/java/com/crm/base/security/LoginUser.java) - [FileApiImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileApiImpl.java) - [FileInfoServiceImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileInfoServiceImpl.java) - [pom.xml](file://pom.xml)目录
简介
本指南面向基于该 CRM 后端框架进行业务模块快速开发的工程师，围绕“实体类创建、Mapper 接口定义、Service 层开发、Controller 接口编写”的完整 CRUD 流程展开，并结合 MyBatis Plus 的分页查询、条件构造器、批量操作等高级能力，系统讲解事务管理、数据验证、参数绑定、统一结果封装、全局异常处理、数据权限控制等常用功能。通过本项目中认证与部门管理等模块的真实实现，提供可复用的最佳实践与示例路径，帮助开发者快速上手并高效交付。
项目结构
项目采用多模块分层架构：
- crm-app：应用启动入口与全局配置
- crm-base：基础能力（通用实体、统一返回、分页、异常处理、MyBatis Plus 配置、雪花ID、数据权限等）
- crm-auth：认证与权限域（用户、角色、菜单、部门等）
- crm-file：文件服务（上传、下载、预览、清理任务）
graph TB
subgraph "应用层"
APP["crm-app<br/>启动与配置"]
end
subgraph "领域模块"
AUTH["crm-auth<br/>认证与权限"]
FILE["crm-file<br/>文件服务"]
end
subgraph "基础能力"
BASE["crm-base<br/>通用实体/配置/工具"]
end
APP --> AUTH
APP --> FILE
AUTH --> BASE
FILE --> BASE
图表来源
- CrmAppApplication.java
- application.yml
章节来源
- CrmAppApplication.java
- application.yml
核心组件
- 通用实体基类与数据所有权模型：用于统一字段（如创建时间、更新时间、逻辑删除等）与数据归属控制
- 统一返回与分页：标准响应体与分页结果封装
- MyBatis Plus 集成：自定义 BaseMapper、分页插件、自动填充、SQL 注入器、雪花 ID 生成
- 安全与数据权限：登录上下文、数据范围注解与拦截辅助
- 全局异常处理：统一错误码与异常转换
- 典型业务模块：认证用户、部门管理等，覆盖完整的 CRUD 链路
章节来源
- BaseEntity.java
- OwnedEntity.java
- Result.java
- PageResult.java
- MybatisPlusConfig.java
- MetaObjectFillHandler.java
- CrmSqlInjector.java
- CrmBaseMapper.java
- BaseServiceImpl.java
- IBaseService.java
- SnowflakeIdWorker.java
- CustomIdGenerator.java
- DataScope.java
- DataScopeHelper.java
- SecurityUtils.java
- LoginUser.java
架构总览
下图展示从 Controller 到 Service、Mapper、数据库的调用链路与关键横切能力（统一返回、异常处理、数据权限、自动填充）。
sequenceDiagram
participant Client as "客户端"
participant Ctrl as "Controller"
participant Svc as "Service(Impl)"
participant MP as "MyBatis Plus(BaseMapper)"
participant DB as "数据库"
Client->>Ctrl : "HTTP 请求"
Ctrl->>Svc : "调用业务方法"
Svc->>MP : "CRUD/分页/条件构造"
MP->>DB : "执行 SQL"
DB-->>MP : "结果集"
MP-->>Svc : "实体/分页对象"
Svc-->>Ctrl : "业务结果"
Ctrl-->>Client : "统一 Result 响应"
Note over Ctrl,Client : "全局异常处理/数据权限/自动填充贯穿"
图表来源
- AuthController.java
- AuthUserServiceImpl.java
- AuthUserMapper.java
- BaseServiceImpl.java
- CrmBaseMapper.java
详细组件分析
实体类设计（BaseEntity / OwnedEntity）
- BaseEntity：提供通用审计字段（如创建人、创建时间、更新人、更新时间、逻辑删除等），所有业务实体继承以复用
- OwnedEntity：在 BaseEntity 基础上增加数据所有权字段，配合数据权限注解实现行级数据隔离
最佳实践
- 所有业务表对应的实体均继承 BaseEntity；需要数据权限控制的实体再继承 OwnedEntity
- 字段命名遵循下划线转驼峰约定，便于 MyBatis Plus 自动映射
章节来源
- BaseEntity.java
- OwnedEntity.java
Mapper 层（CrmBaseMapper + 业务 Mapper）
- CrmBaseMapper：作为各业务 Mapper 的父接口，扩展常用方法与 SQL 片段
- 业务 Mapper（如 AuthUserMapper、SysDeptMapper）：继承 CrmBaseMapper，按需扩展自定义 SQL
最佳实践
- 优先使用 MyBatis Plus 提供的 CRUD 与条件构造器，减少手写 SQL
- 复杂查询或批量操作可在 Mapper 中追加 XML 或注解 SQL
章节来源
- CrmBaseMapper.java
- AuthUserMapper.java
- SysDeptMapper.java
Service 层（IBaseService + BaseServiceImpl + 业务 Service）
- IBaseService 与 BaseServiceImpl：封装通用 CRUD、分页、条件查询、批量操作等能力
- 业务 Service（如 IAuthUserService、AuthUserServiceImpl、ISysDeptService、SysDeptServiceImpl）：继承 BaseServiceImpl，实现具体业务逻辑
最佳实践
- 将跨表校验、事务边界、缓存读写、权限判断放在 Service 层
- 使用条件构造器组装查询条件，保持可读性与可维护性
章节来源
- IBaseService.java
- BaseServiceImpl.java
- IAuthUserService.java
- AuthUserServiceImpl.java
- ISysDeptService.java
- SysDeptServiceImpl.java
Controller 层（统一返回与参数绑定）
- 统一返回体 Result 与分页 PageResult：所有接口返回统一包装
- 参数绑定：支持 @RequestBody、@RequestParam、@PathVariable 等
- 示例控制器：认证相关接口（登录、用户信息等）、系统管理接口（部门、菜单、角色等）
最佳实践
- Controller 仅做参数校验与转发，不写业务逻辑
- 使用 DTO/Param 接收输入，避免直接暴露实体
章节来源
- Result.java
- PageResult.java
- AuthController.java
- SystemController.java
MyBatis Plus 集成与高级用法
- 分页查询：通过分页插件与 Page 对象实现
- 条件构造器：Wrapper 系列构建动态查询条件
- 批量操作：saveBatch/updateByIdBatch 等
- 自动填充：MetaObjectFillHandler 统一填充审计字段
- 雪花 ID：CustomIdGenerator + SnowflakeIdWorker 生成分布式主键
flowchart TD
Start(["进入 Service 方法"]) --> CheckParams["参数校验"]
CheckParams --> BuildQuery["构建查询条件(Wrapper)"]
BuildQuery --> ExecQuery["执行分页/条件查询"]
ExecQuery --> Transform["结果转换(DTO/VO)"]
Transform --> Return["返回统一结果(Result/PageResult)"]
图表来源
- MybatisPlusConfig.java
- MetaObjectFillHandler.java
- CrmSqlInjector.java
- SnowflakeIdWorker.java
- CustomIdGenerator.java
- BaseServiceImpl.java
章节来源
- MybatisPlusConfig.java
- MetaObjectFillHandler.java
- CrmSqlInjector.java
- SnowflakeIdWorker.java
- CustomIdGenerator.java
- BaseServiceImpl.java
事务管理
- 在 Service 层方法上声明事务边界，保证多步操作的原子性
- 结合业务校验与异常抛出，确保失败回滚
最佳实践
- 只读方法标注只读事务，提升并发性能
- 避免在事务内执行耗时 IO 操作
章节来源
- AuthUserServiceImpl.java
- SysDeptServiceImpl.java
数据验证与参数绑定
- 使用 DTO/Param 接收前端参数，结合 Bean Validation 注解完成入参校验
- 统一错误信息通过全局异常处理器转换为标准错误码与消息
章节来源
- BaseDTO.java
- BaseParam.java
- GlobalExceptionHandlerAdvice.java
数据权限与登录上下文
- DataScope 注解标记需要数据范围控制的接口或方法
- DataScopeHelper 与 SecurityUtils 提供当前登录用户信息与数据范围解析
- LoginUser 承载登录态与权限信息
classDiagram
class LoginUser {
+用户标识
+角色/权限集合
+数据范围
}
class DataScopeHelper {
+获取当前数据范围
+拼接数据权限SQL
}
class SecurityUtils {
+获取当前登录用户
+鉴权辅助方法
}
LoginUser <.. SecurityUtils : "读取"
DataScopeHelper <.. SecurityUtils : "依赖"
图表来源
- LoginUser.java
- DataScopeHelper.java
- SecurityUtils.java
- DataScope.java
章节来源
- DataScope.java
- DataScopeHelper.java
- SecurityUtils.java
- LoginUser.java
文件服务示例（上传/下载/预览）
- FileApiImpl：对外文件能力抽象实现
- FileInfoServiceImpl：文件元数据管理与持久化
章节来源
- FileApiImpl.java
- FileInfoServiceImpl.java
依赖关系分析
- 模块依赖：crm-app 依赖 crm-auth、crm-file；crm-auth、crm-file 依赖 crm-base
- 运行时依赖：Spring Boot、MyBatis Plus、Redis（可选）、MinIO（文件存储）等
graph LR
APP["crm-app"] --> AUTH["crm-auth"]
APP --> FILE["crm-file"]
AUTH --> BASE["crm-base"]
FILE --> BASE
图表来源
- pom.xml
章节来源
- pom.xml
性能与扩展性
- 分页查询：合理使用索引与分页大小，避免深分页
- 批量操作：使用 saveBatch/updateByIdBatch 降低往返次数
- 自动填充：减少重复代码，提高一致性
- 雪花 ID：分布式环境下主键唯一且有序，利于分库分表
- 只读事务：对查询方法开启只读事务，提升吞吐
[本节为通用建议，不直接分析具体文件]
故障排查指南
- 统一异常处理：全局异常处理器捕获业务异常与系统异常，返回标准错误码与消息
- 常见错误定位：检查参数校验、数据权限、事务回滚、SQL 执行日志
- 调试建议：开启 MyBatis SQL 日志，查看 Wrapper 生成的 SQL
章节来源
- GlobalExceptionHandlerAdvice.java
结论
通过统一的实体基类、标准化返回体、完善的 MyBatis Plus 集成与数据权限体系，本项目提供了开箱即用的 CRUD 开发模板。按照“实体→Mapper→Service→Controller”的标准路径，结合条件构造器、分页、批量、事务、自动填充等能力，可快速搭建高质量的业务模块。
[本节为总结性内容，不直接分析具体文件]
附录：快速上手清单
- 新建实体类：继承 BaseEntity 或 OwnedEntity，添加必要字段
- 新建 Mapper：继承 CrmBaseMapper，按需扩展方法
- 新建 Service：继承 BaseServiceImpl，实现业务逻辑与事务边界
- 新建 Controller：定义 RESTful 接口，使用 DTO/Param 接收参数，返回 Result/PageResult
- 分页查询：使用 Page 与条件构造器组装查询
- 批量操作：使用 saveBatch/updateByIdBatch
- 数据权限：在需要的方法上标注 DataScope，并确保登录上下文正确
- 自动填充：在 MetaObjectFillHandler 中补充默认值策略
- 主键策略：使用雪花 ID 生成器，避免冲突
[本节为操作清单，不直接分析具体文件]