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.
20 KiB
20 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) - [AuthService.java](file://crm-auth/src/main/java/com/crm/auth/service/IAuthService.java) - [AuthServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthServiceImpl.java) - [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) - [SecurityConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java) - [JwtAuthenticationFilter.java](file://crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java) - [TokenService.java](file://crm-auth/src/main/java/com/crm/auth/security/TokenService.java) - [DataScopeInterceptor.java](file://crm-auth/src/main/java/com/crm/auth/security/DataScopeInterceptor.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) - [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) - [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java) - [SnowflakeIdWorker.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeIdWorker.java) - [MetaObjectFillHandler.java](file://crm-base/src/main/java/com/crm/base/config/MetaObjectFillHandler.java) - [DataScope.java](file://crm-base/src/main/java/com/crm/base/annotation/DataScope.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) - [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) - [FileController.java](file://crm-file/src/main/java/com/crm/file/controller/FileController.java) - [OrphanChunkCleanupTask.java](file://crm-file/src/main/java/com/crm/file/task/OrphanChunkCleanupTask.java)目录
简介
本指南面向新加入的开发者，提供从环境搭建到业务模块快速落地的完整路径。内容涵盖：
- 项目开发规范、代码风格与命名约定
- Git 工作流与协作流程
- 基于基础框架（Base 层）快速实现实体、Service、Controller、数据访问层
- 高级特性：自定义注解、AOP 切面、消息队列集成、定时任务
- 代码审查清单、性能优化建议与安全编码规范
目标是确保代码质量与团队协作效率，帮助开发者在统一规范下高效交付。
项目结构
本项目采用多模块 Maven 工程，按领域与职责划分：
- crm-app：应用启动入口与全局配置
- crm-base：通用能力（基础实体、结果封装、异常处理、安全上下文、MyBatis Plus、Redis、雪花ID等）
- crm-auth：认证授权与系统管理（用户、角色、菜单、部门、权限、数据范围）
- crm-file：文件服务（上传、分片、预览、清理任务）
graph TB
subgraph "应用层"
APP["crm-app<br/>启动入口"]
end
subgraph "基础能力"
BASE["crm-base<br/>通用组件"]
end
subgraph "业务域"
AUTH["crm-auth<br/>认证与系统管理"]
FILE["crm-file<br/>文件服务"]
end
APP --> AUTH
APP --> FILE
AUTH --> BASE
FILE --> BASE
图表来源
- CrmAppApplication.java
- application.yml
章节来源
- CrmAppApplication.java
- application.yml
核心组件
- 基础实体与分页结果
- BaseEntity：公共字段（如创建时间、更新时间等）
- OwnedEntity：数据所有权扩展（用于数据范围控制）
- Result/PageResult：统一响应体与分页封装
- 异常与全局处理
- GlobalExceptionHandlerAdvice：统一异常捕获与错误码返回
- MyBatis Plus 与数据库
- MybatisPlusConfig：分页插件、元对象填充处理器等
- MetaObjectFillHandler：自动填充审计字段
- SnowflakeIdWorker：分布式主键生成
- Redis 缓存
- RedisConfig：序列化策略与连接配置
- 安全上下文与数据范围
- DataScope 注解与拦截器：实现数据可见性控制
- SecurityUtils：获取当前登录用户信息
章节来源
- BaseEntity.java
- OwnedEntity.java
- Result.java
- PageResult.java
- GlobalExceptionHandlerAdvice.java
- MybatisPlusConfig.java
- MetaObjectFillHandler.java
- SnowflakeIdWorker.java
- RedisConfig.java
- DataScope.java
架构总览
整体分层清晰：Controller -> Service -> Mapper -> DB，辅以安全、缓存、分页、审计等横切能力。
sequenceDiagram
participant Client as "客户端"
participant Controller as "控制器(Controller)"
participant Service as "服务层(Service)"
participant Mapper as "数据访问(Mapper)"
participant DB as "数据库"
participant Cache as "缓存(Redis)"
Client->>Controller : "HTTP 请求"
Controller->>Service : "调用业务方法"
Service->>Cache : "可选：读取/写入缓存"
Service->>Mapper : "CRUD/查询"
Mapper->>DB : "SQL 执行"
DB-->>Mapper : "结果集"
Mapper-->>Service : "实体/DTO"
Service-->>Controller : "业务结果"
Controller-->>Client : "统一响应(Result)"
图表来源
- AuthController.java
- AuthService.java
- AuthServiceImpl.java
- BaseServiceImpl.java
详细组件分析
认证与鉴权（Auth）
- 控制器
- AuthController：登录、登出、用户信息等接口
- SystemController：系统级接口（如字典、配置等）
- 安全配置
- SecurityConfig：Spring Security 配置、放行路径、过滤器链
- JwtAuthenticationFilter：JWT 解析与认证上下文设置
- TokenService：令牌签发、校验、刷新
- DataScopeInterceptor：数据范围拦截，结合 @DataScope 注解
- 服务层
- IAuthService / AuthServiceImpl：登录逻辑、第三方登录、权限加载
- IAuthUserService / AuthUserServiceImpl：用户信息查询、密码校验
- ISysDeptService / SysDeptServiceImpl：部门树构建与缓存
classDiagram
class AuthController {
+登录()
+登出()
+获取用户信息()
}
class AuthService {
+登录(参数)
+第三方登录(类型, 参数)
+加载权限(用户)
}
class AuthUserServiceImpl {
+校验密码()
+查询用户()
}
class SecurityConfig {
+配置过滤器链()
+配置授权规则()
}
class JwtAuthenticationFilter {
+解析JWT()
+设置认证上下文()
}
class TokenService {
+签发()
+校验()
+刷新()
}
class DataScopeInterceptor {
+拦截请求()
+注入数据范围条件()
}
AuthController --> AuthService : "调用"
AuthService --> AuthUserServiceImpl : "使用"
SecurityConfig --> JwtAuthenticationFilter : "注册"
SecurityConfig --> DataScopeInterceptor : "注册"
图表来源
- AuthController.java
- AuthService.java
- AuthServiceImpl.java
- AuthUserServiceImpl.java
- SecurityConfig.java
- JwtAuthenticationFilter.java
- TokenService.java
- DataScopeInterceptor.java
章节来源
- AuthController.java
- SystemController.java
- SecurityConfig.java
- JwtAuthenticationFilter.java
- TokenService.java
- DataScopeInterceptor.java
- AuthService.java
- AuthServiceImpl.java
- AuthUserServiceImpl.java
- SysDeptServiceImpl.java
文件服务（File）
- 控制器
- FileController：上传、下载、分片初始化、断点续传、预览
- 服务层
- FileApiImpl：对外文件 API 实现（对接 MinIO/本地存储）
- FileInfoServiceImpl：文件元信息管理、状态流转
- 定时任务
- OrphanChunkCleanupTask：清理孤儿分片，避免磁盘膨胀
flowchart TD
Start(["开始"]) --> Init["初始化分片会话"]
Init --> Upload["上传分片"]
Upload --> Merge{"是否全部上传完成?"}
Merge --> |否| Upload
Merge --> |是| SaveMeta["保存文件元信息"]
SaveMeta --> Preview["生成预览链接"]
Preview --> Done(["结束"])
图表来源
- FileController.java
- FileApiImpl.java
- FileInfoServiceImpl.java
- OrphanChunkCleanupTask.java
章节来源
- FileController.java
- FileApiImpl.java
- FileInfoServiceImpl.java
- OrphanChunkCleanupTask.java
基础服务与通用能力（Base）
- BaseServiceImpl：通用 CRUD、分页、批量操作封装
- IBaseService：通用接口定义
- 元对象填充：MetaObjectFillHandler 自动填充创建人、创建时间等
- 雪花ID：SnowflakeIdWorker 分布式主键
- Redis：RedisConfig 统一序列化与过期策略
- 数据范围：@DataScope 注解配合拦截器实现行级数据隔离
classDiagram
class BaseServiceImpl {
+新增()
+更新()
+删除()
+分页查询()
+批量操作()
}
class IBaseService {
<<interface>>
}
class MetaObjectFillHandler {
+填充审计字段()
}
class SnowflakeIdWorker {
+生成ID()
}
class RedisConfig {
+序列化配置()
+连接配置()
}
class DataScope {
<<annotation>>
}
BaseServiceImpl ..|> IBaseService
BaseServiceImpl --> MetaObjectFillHandler : "使用"
BaseServiceImpl --> SnowflakeIdWorker : "使用"
BaseServiceImpl --> RedisConfig : "使用"
图表来源
- BaseServiceImpl.java
- IBaseService.java
- MetaObjectFillHandler.java
- SnowflakeIdWorker.java
- RedisConfig.java
- DataScope.java
章节来源
- BaseServiceImpl.java
- IBaseService.java
- MetaObjectFillHandler.java
- SnowflakeIdWorker.java
- RedisConfig.java
- DataScope.java
依赖关系分析
- 模块依赖
- crm-app 依赖 crm-auth、crm-file
- crm-auth、crm-file 依赖 crm-base
- 运行时依赖
- Spring Security、JWT、MyBatis Plus、Redis、MinIO（文件服务）
- 关键耦合点
- 安全上下文与数据范围贯穿各模块
- 统一异常处理与结果封装在 base 层
graph LR
APP["crm-app"] --> AUTH["crm-auth"]
APP --> FILE["crm-file"]
AUTH --> BASE["crm-base"]
FILE --> BASE
图表来源
- CrmAppApplication.java
- application.yml
章节来源
- CrmAppApplication.java
- application.yml
性能考虑
- 数据库
- 合理使用索引，避免全表扫描；分页查询限制返回字段
- 批量操作优先使用批量插入/更新，减少往返次数
- 缓存
- 热点数据入缓存（如部门树、字典），注意一致性策略与过期时间
- 避免大对象缓存，合理序列化
- 异步与任务
- 耗时操作异步化（如文件处理、通知发送）
- 定时任务幂等设计，失败重试与告警
- 连接与线程池
- 合理配置线程池大小与超时时间，避免阻塞
- 监控慢 SQL，定期优化
[本节为通用指导，不直接分析具体文件]
故障排查指南
- 统一异常
- GlobalExceptionHandlerAdvice 捕获并返回标准错误码与消息
- 常见错误
- 认证失败：检查 JWT 配置、过滤器链顺序、TokenService 签名密钥
- 数据范围异常：确认 @DataScope 注解与拦截器生效，上下文用户信息正确
- 文件上传失败：检查 MinIO 配置、分片大小、临时目录权限
- 日志与追踪
- 开启必要日志级别，定位问题链路
- 使用 TraceId 贯穿请求链路
章节来源
- GlobalExceptionHandlerAdvice.java
- JwtAuthenticationFilter.java
- TokenService.java
- DataScopeInterceptor.java
结论
通过统一的 Base 能力与清晰的模块边界，团队可以快速扩展业务功能。遵循本指南中的规范与实践，可显著提升代码质量、可维护性与协作效率。建议在迭代中持续完善监控、测试与文档，保障系统稳定演进。
[本节为总结性内容，不直接分析具体文件]
附录
开发规范与命名约定
- 包与类
- 包名小写，按模块划分；类名大驼峰，动词+名词表示行为
- 接口以 I 开头，实现类以 Impl 结尾
- 方法与变量
- 方法名动宾结构，布尔方法用 is/has/can 前缀
- 常量全大写加下划线，枚举值全大写
- 注释与文档
- 复杂逻辑添加行内注释；接口使用 Swagger/Knife4j 注解描述
[本节为通用指导，不直接分析具体文件]
Git 工作流
- 分支模型
- main：生产分支；develop：开发主干；feature/：功能分支；hotfix/：热修复
- 提交规范
- 类型：feat/fix/docs/style/refactor/test/chore
- 格式：type(scope): subject
- 合并流程
- 功能分支合并至 develop，PR 需至少一名 Reviewer 批准
- 发布前打 tag，main 分支仅允许受保护合并
[本节为通用指导，不直接分析具体文件]
快速上手：从零到一开发业务模块
- 创建实体
- 继承 BaseEntity/OwnedEntity，标注表映射与字段属性
- 创建 Mapper
- 继承 CrmBaseMapper，定义必要方法或沿用默认 CRUD
- 创建 Service
- 继承 BaseServiceImpl，实现业务逻辑，必要时注入缓存
- 创建 Controller
- 定义 REST 接口，统一返回 Result/PageResult
- 数据范围与权限
- 需要数据隔离的方法上添加 @DataScope，并在拦截器中生效
- 示例参考
- 认证模块的 Controller/Service/Mapper 组织方式
章节来源
- BaseEntity.java
- OwnedEntity.java
- BaseServiceImpl.java
- AuthController.java
- AuthService.java
- AuthServiceImpl.java
高级特性
- 自定义注解
- 使用 @DataScope 实现数据范围控制；可扩展审计、限流等注解
- AOP 切面
- 基于注解的切面实现日志、性能统计、权限校验等横切逻辑
- 消息队列集成
- 引入 MQ 客户端，封装生产者/消费者模板，保证可靠投递与幂等消费
- 定时任务
- 使用 @Scheduled 或任务调度框架，实现幂等与失败重试
章节来源
- DataScope.java
- OrphanChunkCleanupTask.java
代码审查清单
- 结构与可读性
- 包结构清晰，类职责单一，方法长度适中
- 安全性
- 输入校验、越权防护、敏感信息脱敏、SQL 防注入
- 健壮性
- 异常处理完备，空值与边界条件覆盖
- 性能
- 避免 N+1 查询，合理使用缓存与索引
- 可测试性
- 单元测试覆盖核心逻辑，Mock 外部依赖
[本节为通用指导，不直接分析具体文件]
安全编码规范
- 认证与授权
- 最小权限原则，接口级鉴权，敏感操作二次确认
- 数据安全
- 传输加密（HTTPS）、存储加密（敏感字段）、日志脱敏
- 依赖安全
- 定期升级依赖，扫描漏洞，禁用不安全算法
[本节为通用指导，不直接分析具体文件]