crm-backend-matt/.qoder/repowiki/zh/content/开发指南/框架使用.md

# 框架使用

<cite>
**本文引用的文件**   
- [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)
</cite>

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

## 简介
本指南面向基于该 CRM 后端框架进行业务模块快速开发的工程师，围绕“实体类创建、Mapper 接口定义、Service 层开发、Controller 接口编写”的完整 CRUD 流程展开，并结合 MyBatis Plus 的分页查询、条件构造器、批量操作等高级能力，系统讲解事务管理、数据验证、参数绑定、统一结果封装、全局异常处理、数据权限控制等常用功能。通过本项目中认证与部门管理等模块的真实实现，提供可复用的最佳实践与示例路径，帮助开发者快速上手并高效交付。

## 项目结构
项目采用多模块分层架构：
- crm-app：应用启动入口与全局配置
- crm-base：基础能力（通用实体、统一返回、分页、异常处理、MyBatis Plus 配置、雪花ID、数据权限等）
- crm-auth：认证与权限域（用户、角色、菜单、部门等）
- crm-file：文件服务（上传、下载、预览、清理任务）

```mermaid
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](file://crm-app/src/main/java/com/crm/app/CrmAppApplication.java)
- [application.yml](file://crm-app/src/main/resources/application.yml)

章节来源
- [CrmAppApplication.java](file://crm-app/src/main/java/com/crm/app/CrmAppApplication.java)
- [application.yml](file://crm-app/src/main/resources/application.yml)

## 核心组件
- 通用实体基类与数据所有权模型：用于统一字段（如创建时间、更新时间、逻辑删除等）与数据归属控制
- 统一返回与分页：标准响应体与分页结果封装
- MyBatis Plus 集成：自定义 BaseMapper、分页插件、自动填充、SQL 注入器、雪花 ID 生成
- 安全与数据权限：登录上下文、数据范围注解与拦截辅助
- 全局异常处理：统一错误码与异常转换
- 典型业务模块：认证用户、部门管理等，覆盖完整的 CRUD 链路

章节来源
- [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)
- [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)
- [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)

## 架构总览
下图展示从 Controller 到 Service、Mapper、数据库的调用链路与关键横切能力（统一返回、异常处理、数据权限、自动填充）。

```mermaid
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](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.java)
- [AuthUserServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthUserServiceImpl.java)
- [AuthUserMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/AuthUserMapper.java)
- [BaseServiceImpl.java](file://crm-base/src/main/java/com/crm/base/service/impl/BaseServiceImpl.java)
- [CrmBaseMapper.java](file://crm-base/src/main/java/com/crm/base/mapper/CrmBaseMapper.java)

## 详细组件分析

### 实体类设计（BaseEntity / OwnedEntity）
- BaseEntity：提供通用审计字段（如创建人、创建时间、更新人、更新时间、逻辑删除等），所有业务实体继承以复用
- OwnedEntity：在 BaseEntity 基础上增加数据所有权字段，配合数据权限注解实现行级数据隔离

最佳实践
- 所有业务表对应的实体均继承 BaseEntity；需要数据权限控制的实体再继承 OwnedEntity
- 字段命名遵循下划线转驼峰约定，便于 MyBatis Plus 自动映射

章节来源
- [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)

### Mapper 层（CrmBaseMapper + 业务 Mapper）
- CrmBaseMapper：作为各业务 Mapper 的父接口，扩展常用方法与 SQL 片段
- 业务 Mapper（如 AuthUserMapper、SysDeptMapper）：继承 CrmBaseMapper，按需扩展自定义 SQL

最佳实践
- 优先使用 MyBatis Plus 提供的 CRUD 与条件构造器，减少手写 SQL
- 复杂查询或批量操作可在 Mapper 中追加 XML 或注解 SQL

章节来源
- [CrmBaseMapper.java](file://crm-base/src/main/java/com/crm/base/mapper/CrmBaseMapper.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)

### Service 层（IBaseService + BaseServiceImpl + 业务 Service）
- IBaseService 与 BaseServiceImpl：封装通用 CRUD、分页、条件查询、批量操作等能力
- 业务 Service（如 IAuthUserService、AuthUserServiceImpl、ISysDeptService、SysDeptServiceImpl）：继承 BaseServiceImpl，实现具体业务逻辑

最佳实践
- 将跨表校验、事务边界、缓存读写、权限判断放在 Service 层
- 使用条件构造器组装查询条件，保持可读性与可维护性

章节来源
- [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)
- [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)

### Controller 层（统一返回与参数绑定）
- 统一返回体 Result 与分页 PageResult：所有接口返回统一包装
- 参数绑定：支持 @RequestBody、@RequestParam、@PathVariable 等
- 示例控制器：认证相关接口（登录、用户信息等）、系统管理接口（部门、菜单、角色等）

最佳实践
- Controller 仅做参数校验与转发，不写业务逻辑
- 使用 DTO/Param 接收输入，避免直接暴露实体

章节来源
- [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)
- [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)

### MyBatis Plus 集成与高级用法
- 分页查询：通过分页插件与 Page 对象实现
- 条件构造器：Wrapper 系列构建动态查询条件
- 批量操作：saveBatch/updateByIdBatch 等
- 自动填充：MetaObjectFillHandler 统一填充审计字段
- 雪花 ID：CustomIdGenerator + SnowflakeIdWorker 生成分布式主键

```mermaid
flowchart TD
Start(["进入 Service 方法"]) --> CheckParams["参数校验"]
CheckParams --> BuildQuery["构建查询条件(Wrapper)"]
BuildQuery --> ExecQuery["执行分页/条件查询"]
ExecQuery --> Transform["结果转换(DTO/VO)"]
Transform --> Return["返回统一结果(Result/PageResult)"]
```

图表来源
- [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)
- [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)
- [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)
- [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)
- [BaseServiceImpl.java](file://crm-base/src/main/java/com/crm/base/service/impl/BaseServiceImpl.java)

### 事务管理
- 在 Service 层方法上声明事务边界，保证多步操作的原子性
- 结合业务校验与异常抛出，确保失败回滚

最佳实践
- 只读方法标注只读事务，提升并发性能
- 避免在事务内执行耗时 IO 操作

章节来源
- [AuthUserServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthUserServiceImpl.java)
- [SysDeptServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/SysDeptServiceImpl.java)

### 数据验证与参数绑定
- 使用 DTO/Param 接收前端参数，结合 Bean Validation 注解完成入参校验
- 统一错误信息通过全局异常处理器转换为标准错误码与消息

章节来源
- [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)
- [GlobalExceptionHandlerAdvice.java](file://crm-base/src/main/java/com/crm/base/advice/GlobalExceptionHandlerAdvice.java)

### 数据权限与登录上下文
- DataScope 注解标记需要数据范围控制的接口或方法
- DataScopeHelper 与 SecurityUtils 提供当前登录用户信息与数据范围解析
- LoginUser 承载登录态与权限信息

```mermaid
classDiagram
class LoginUser {
+用户标识
+角色/权限集合
+数据范围
}
class DataScopeHelper {
+获取当前数据范围
+拼接数据权限SQL
}
class SecurityUtils {
+获取当前登录用户
+鉴权辅助方法
}
LoginUser <.. SecurityUtils : "读取"
DataScopeHelper <.. SecurityUtils : "依赖"
```

图表来源
- [LoginUser.java](file://crm-base/src/main/java/com/crm/base/security/LoginUser.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)
- [DataScope.java](file://crm-base/src/main/java/com/crm/base/annotation/DataScope.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：对外文件能力抽象实现
- FileInfoServiceImpl：文件元数据管理与持久化

章节来源
- [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)

## 依赖关系分析
- 模块依赖：crm-app 依赖 crm-auth、crm-file；crm-auth、crm-file 依赖 crm-base
- 运行时依赖：Spring Boot、MyBatis Plus、Redis（可选）、MinIO（文件存储）等

```mermaid
graph LR
APP["crm-app"] --> AUTH["crm-auth"]
APP --> FILE["crm-file"]
AUTH --> BASE["crm-base"]
FILE --> BASE
```

图表来源
- [pom.xml](file://pom.xml)

章节来源
- [pom.xml](file://pom.xml)

## 性能与扩展性
- 分页查询：合理使用索引与分页大小，避免深分页
- 批量操作：使用 saveBatch/updateByIdBatch 降低往返次数
- 自动填充：减少重复代码，提高一致性
- 雪花 ID：分布式环境下主键唯一且有序，利于分库分表
- 只读事务：对查询方法开启只读事务，提升吞吐

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

## 故障排查指南
- 统一异常处理：全局异常处理器捕获业务异常与系统异常，返回标准错误码与消息
- 常见错误定位：检查参数校验、数据权限、事务回滚、SQL 执行日志
- 调试建议：开启 MyBatis SQL 日志，查看 Wrapper 生成的 SQL

章节来源
- [GlobalExceptionHandlerAdvice.java](file://crm-base/src/main/java/com/crm/base/advice/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 生成器，避免冲突

[本节为操作清单，不直接分析具体文件]