# 技术栈

<cite>
**本文引用的文件**   
- [pom.xml](file://pom.xml)
- [crm-app/pom.xml](file://crm-app/pom.xml)
- [crm-auth/pom.xml](file://crm-auth/pom.xml)
- [crm-base/pom.xml](file://crm-base/pom.xml)
- [crm-file/pom.xml](file://crm-file/pom.xml)
- [crm-app/src/main/resources/application.yml](file://crm-app/src/main/resources/application.yml)
- [crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java)
- [crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java](file://crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java)
- [crm-auth/src/main/java/com/crm/auth/service/client/DingTalkAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/DingTalkAuthClient.java)
- [crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java)
- [crm-base/src/main/java/com/crm/base/config/RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)
- [crm-base/src/main/java/com/crm/base/config/JacksonConfig.java](file://crm-base/src/main/java/com/crm/base/config/JacksonConfig.java)
- [crm-base/src/main/java/com/crm/base/config/Knife4jConfig.java](file://crm-base/src/main/java/com/crm/base/config/Knife4jConfig.java)
- [crm-file/src/main/java/com/crm/file/config/MinioConfig.java](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java)
- [crm-file/src/main/java/com/crm/file/service/KkFileViewClient.java](file://crm-file/src/main/java/com/crm/file/service/KkFileViewClient.java)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本技术栈文档面向CRM后端项目，系统性梳理并说明核心技术选型与集成方式，包括Spring Boot、MyBatis Plus、Redis、MySQL、MinIO等关键技术与版本信息；阐述Spring Security认证授权、Knife4j API文档、Jackson JSON处理等组件的作用与配置；解释第三方服务集成（如钉钉认证、文件预览服务）；总结开发工具链、构建工具与测试框架的选择理由；提供版本兼容性矩阵与升级建议，帮助开发者在统一规范下高效协作与演进。

## 项目结构
本项目采用多模块Maven工程组织：
- crm-app：应用启动入口与全局配置
- crm-base：公共基础能力（安全、数据访问、序列化、异常、分页、工具类等）
- crm-auth：认证授权与权限控制（含第三方登录）
- crm-file：文件上传下载与在线预览（对接MinIO与KKFileView）

```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
```

图表来源
- [crm-app/pom.xml](file://crm-app/pom.xml)
- [crm-auth/pom.xml](file://crm-auth/pom.xml)
- [crm-file/pom.xml](file://crm-file/pom.xml)
- [crm-base/pom.xml](file://crm-base/pom.xml)

章节来源
- [pom.xml](file://pom.xml)
- [crm-app/pom.xml](file://crm-app/pom.xml)
- [crm-auth/pom.xml](file://crm-auth/pom.xml)
- [crm-base/pom.xml](file://crm-base/pom.xml)
- [crm-file/pom.xml](file://crm-file/pom.xml)

## 核心组件
- Spring Boot：作为应用框架，提供自动装配、Web容器、配置管理、监控与扩展点。
- MyBatis Plus：增强ORM能力，简化CRUD、分页、条件构造与元数据填充。
- Redis：缓存与会话存储、分布式锁、热点数据加速。
- MySQL：关系型数据存储，承载业务主数据。
- MinIO：对象存储，用于文件上传、下载与生命周期管理。
- Spring Security + JWT：无状态认证授权，支持角色与数据权限。
- Knife4j：基于Swagger的API文档与调试工具。
- Jackson：JSON序列化与反序列化定制。
- 第三方集成：钉钉认证、KKFileView文件预览。

章节来源
- [crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java)
- [crm-base/src/main/java/com/crm/base/config/RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)
- [crm-base/src/main/java/com/crm/base/config/JacksonConfig.java](file://crm-base/src/main/java/com/crm/base/config/JacksonConfig.java)
- [crm-base/src/main/java/com/crm/base/config/Knife4jConfig.java](file://crm-base/src/main/java/com/crm/base/config/Knife4jConfig.java)
- [crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java)
- [crm-file/src/main/java/com/crm/file/config/MinioConfig.java](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java)

## 架构总览
系统以Spring Boot为底座，分层清晰：
- Web层：Controller暴露REST接口，Knife4j生成文档。
- 安全层：Spring Security拦截请求，JWT过滤器校验令牌，注入用户上下文。
- 业务层：Service编排领域逻辑，调用Mapper与外部客户端。
- 数据层：MyBatis Plus映射实体与SQL，Redis缓存热点数据，MySQL持久化。
- 文件层：MinIO对象存储，KKFileView在线预览。

```mermaid
graph TB
Client["客户端"] --> API["Web控制器"]
API --> SEC["Spring Security + JWT过滤器"]
SEC --> SVC["业务服务"]
SVC --> DB["MyBatis Plus -> MySQL"]
SVC --> CACHE["Redis"]
SVC --> MINIO["MinIO 对象存储"]
SVC --> PREVIEW["KKFileView 预览服务"]
API --> DOC["Knife4j 文档"]
```

图表来源
- [crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java)
- [crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java](file://crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java)
- [crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java)
- [crm-base/src/main/java/com/crm/base/config/RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)
- [crm-file/src/main/java/com/crm/file/config/MinioConfig.java](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java)
- [crm-file/src/main/java/com/crm/file/service/KkFileViewClient.java](file://crm-file/src/main/java/com/crm/file/service/KkFileViewClient.java)
- [crm-base/src/main/java/com/crm/base/config/Knife4jConfig.java](file://crm-base/src/main/java/com/crm/base/config/Knife4jConfig.java)

## 详细组件分析

### Spring Boot 与模块化
- 作用：统一依赖管理、自动装配、Web容器、配置中心、Actuator监控。
- 集成方式：各子模块通过Maven聚合，父POM集中声明版本与插件。
- 最佳实践：按功能拆分模块，避免循环依赖；使用Profile区分环境配置。

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

### MyBatis Plus 与数据库
- 作用：简化CRUD、分页、条件构造、自动填充、逻辑删除等。
- 集成方式：通过MybatisPlusConfig进行插件与全局策略配置。
- 性能要点：合理使用索引与分页参数，避免N+1查询；批量操作优先。

章节来源
- [crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java)

### Redis 缓存与会话
- 作用：缓存热点数据、分布式会话、限流与锁。
- 集成方式：RedisConfig定义连接与序列化策略。
- 注意事项：设置合理的过期时间，避免雪崩；键命名规范与分片策略。

章节来源
- [crm-base/src/main/java/com/crm/base/config/RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)

### Jackson JSON 处理
- 作用：统一日期、枚举、空值、时区等序列化规则。
- 集成方式：JacksonConfig注册模块与自定义处理器。
- 最佳实践：禁用未知字段报错或按需开启；统一响应体包装。

章节来源
- [crm-base/src/main/java/com/crm/base/config/JacksonConfig.java](file://crm-base/src/main/java/com/crm/base/config/JacksonConfig.java)

### Knife4j API 文档
- 作用：自动生成OpenAPI文档，支持在线调试与导出。
- 集成方式：Knife4jConfig启用注解扫描与UI路径。
- 建议：为每个Controller添加清晰的注解描述，保持文档与代码同步。

章节来源
- [crm-base/src/main/java/com/crm/base/config/Knife4jConfig.java](file://crm-base/src/main/java/com/crm/base/config/Knife4jConfig.java)

### Spring Security 与 JWT 认证
- 作用：统一鉴权、URL级权限控制、数据范围过滤。
- 集成方式：SecurityConfig定义放行与保护路径；JwtAuthenticationFilter解析Token并注入上下文。
- 最佳实践：最小权限原则；敏感接口强制HTTPS；Token刷新机制。

章节来源
- [crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java)
- [crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java](file://crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java)

### 钉钉第三方认证
- 作用：支持企业内用户免密登录与账号绑定。
- 集成方式：DingTalkAuthClient封装HTTP调用与回调处理。
- 注意事项：签名校验、网络超时与重试、错误码映射。

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

### MinIO 文件存储
- 作用：对象存储，支撑文件上传、下载、分片与生命周期管理。
- 集成方式：MinioConfig初始化客户端与桶策略。
- 最佳实践：分块上传提升大文件稳定性；CDN加速静态资源。

章节来源
- [crm-file/src/main/java/com/crm/file/config/MinioConfig.java](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java)

### KKFileView 文件预览
- 作用：将Office、PDF、图片等在线预览，减少前端复杂度。
- 集成方式：KkFileViewClient封装预览链接生成与转发。
- 注意事项：预览服务可用性探测与降级策略；缓存预览结果。

章节来源
- [crm-file/src/main/java/com/crm/file/service/KkFileViewClient.java](file://crm-file/src/main/java/com/crm/file/service/KkFileViewClient.java)

### 应用配置与环境
- 作用：统一管理数据库、Redis、MinIO、第三方服务等配置项。
- 集成方式：application.yml按环境划分，结合Profile加载。
- 建议：敏感信息走环境变量或密钥管理服务。

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

## 依赖分析
- 模块耦合：crm-base为所有模块提供基础能力；crm-auth与crm-file均依赖crm-base。
- 外部依赖：Spring Boot生态、MyBatis Plus、Redis、MinIO SDK、Knife4j、Jackson。
- 潜在风险：跨模块版本不一致导致兼容性问题；第三方SDK升级需回归测试。

```mermaid
graph LR
BASE["crm-base"] --> |被依赖| AUTH["crm-auth"]
BASE --> |被依赖| FILE["crm-file"]
APP["crm-app"] --> AUTH
APP --> FILE
AUTH --> |HTTP| DING["钉钉服务"]
FILE --> |HTTP| KKV["KKFileView"]
AUTH --> |JDBC| MYSQL["MySQL"]
AUTH --> |缓存| REDIS["Redis"]
FILE --> |对象存储| MINIO["MinIO"]
```

图表来源
- [crm-base/pom.xml](file://crm-base/pom.xml)
- [crm-auth/pom.xml](file://crm-auth/pom.xml)
- [crm-file/pom.xml](file://crm-file/pom.xml)
- [crm-app/pom.xml](file://crm-app/pom.xml)

章节来源
- [pom.xml](file://pom.xml)
- [crm-base/pom.xml](file://crm-base/pom.xml)
- [crm-auth/pom.xml](file://crm-auth/pom.xml)
- [crm-file/pom.xml](file://crm-file/pom.xml)
- [crm-app/pom.xml](file://crm-app/pom.xml)

## 性能考虑
- 数据库：合理索引设计、分页限制、读写分离与连接池调优。
- 缓存：热点数据优先入缓存，设置TTL与防穿透/击穿/雪崩策略。
- 文件：分片上传、断点续传、并发下载限速与CDN加速。
- 安全：JWT验签开销控制，必要时引入本地缓存或短效令牌。
- 监控：接入日志与指标采集，定位慢查询与异常热点。

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

## 故障排查指南
- 认证失败：检查JWT过滤器与Security配置路径放行；核对Token签发与校验逻辑。
- 权限异常：确认角色与菜单数据、数据范围注解生效。
- 文件上传失败：验证MinIO连通性与桶权限；检查分片大小与重试策略。
- 预览不可用：检测KKFileView服务健康状态，实现降级返回原文件或缩略图。
- 缓存问题：查看Redis连接与序列化配置，核对键空间与过期时间。

章节来源
- [crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java](file://crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java)
- [crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java)
- [crm-file/src/main/java/com/crm/file/config/MinioConfig.java](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java)
- [crm-file/src/main/java/com/crm/file/service/KkFileViewClient.java](file://crm-file/src/main/java/com/crm/file/service/KkFileViewClient.java)
- [crm-base/src/main/java/com/crm/base/config/RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)

## 结论
本项目以Spring Boot为核心，围绕MyBatis Plus、Redis、MySQL、MinIO构建了稳定可扩展的后端体系；借助Spring Security与JWT实现细粒度权限控制，Knife4j提升研发效率，Jackson保障数据一致性；通过钉钉与KKFileView完成第三方能力集成。建议在版本管理与依赖治理上持续优化，完善监控与容错，确保系统在演进中保持稳定与高性能。

[本节为总结性内容，不直接分析具体文件]

## 附录

### 技术栈版本与兼容性矩阵（示例）
- Spring Boot：推荐2.7.x 或 3.x（根据Java版本选择），注意与Spring Security、MyBatis Plus的版本匹配
- Java：11/17（依据Spring Boot版本要求）
- MyBatis Plus：3.5.x（与Spring Boot 2.7/3.x兼容）
- Redis：Lettuce或Jedis客户端，对应Redis Server 6.x/7.x
- MySQL：8.0.x（驱动与连接池版本需匹配）
- MinIO：官方SDK与MinIO Server最新稳定版
- Knife4j：与SpringDoc/Swagger版本对齐
- Jackson：随Spring Boot管理版本

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

### 升级指南
- 先升级基础库（Spring Boot、Jackson、MyBatis Plus），再升级业务依赖
- 逐步替换第三方SDK，关注弃用API与行为变更
- 全量回归测试，重点覆盖认证、文件、缓存与数据库路径
- 灰度发布与回滚预案，监控关键指标

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

### 开发工具链与测试框架
- 构建工具：Maven（多模块聚合、依赖与插件统一管理）
- 单元测试：JUnit 5 + Mockito（覆盖服务与工具类）
- 集成测试：基于内存数据库与Mock外部服务
- 代码质量：SonarQube、Checkstyle、SpotBugs（可选）
- 文档：Knife4j（API）、README与模块说明

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