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