874 lines
29 KiB
Markdown
874 lines
29 KiB
Markdown
# xtools-app 项目设计文档
|
||
|
||
## 一、功能和用途
|
||
|
||
### 1.1 项目概述
|
||
|
||
- **项目名称**：xtools-app
|
||
- **项目版本**：1.0.0
|
||
- **父POM**：org.xujun:xtools-parent-cloud:5.0.0
|
||
- **项目定位**：基础应用平台，提供企业级应用开发的核心功能和公共模块，支持单体部署和微服务部署两种模式
|
||
- **组织**：org.xujun
|
||
|
||
#### 1.2 技术特点
|
||
|
||
- 采用最新的 **JDK 25** 版本，充分利用新特性（ScopedValue、虚拟线程、Record等）
|
||
- 基于 **Spring Boot 4.0.5** 构建，支持自动配置和快速开发
|
||
- 集成 **Spring Cloud 2025.1.1** 微服务框架
|
||
- 使用 **Spring Cloud Alibaba 2025.1.0.0** 微服务组件
|
||
- 使用 **MyBatis-Plus 3.5.16** 简化数据访问层开发（基于 MyBatis 4.0.1）
|
||
- 使用 **Spring Data Elasticsearch**（基于 Elasticsearch Client 9.2.6）实现日志存储和检索
|
||
- 支持 **Nacos 3.1.1** 服务注册与发现、配置中心
|
||
- 集成 **Sentinel 1.8.9** 实现流量控制和熔断降级
|
||
- 使用 **Spring Data Redis**（基于 Lettuce 6.8.2）实现分布式缓存
|
||
- 使用 **Spring AMQP 4.0.2**（RabbitMQ Client 5.27.1）实现异步消息处理
|
||
- 支持 **Knife4j 4.5.0**（基于 SpringDoc OpenAPI 3.0.3）自动生成 API 文档
|
||
- 使用 **Druid 1.2.28** 数据库连接池
|
||
- 使用 **SM2/SM3** 国密算法保障密码和数据安全
|
||
|
||
### 1.3 核心功能
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph 系统管理模块
|
||
A1[用户管理<br/>用户增删改查,角色分配,密码管理]
|
||
A2[角色管理<br/>角色配置,权限分配,菜单分配]
|
||
A3[菜单管理<br/>树形结构,动态加载,按钮权限]
|
||
A4[部门管理<br/>树形结构,人员管理]
|
||
A5[字典管理<br/>类型管理,字典项管理]
|
||
A6[日志管理<br/>操作日志,登录日志,ES存储]
|
||
A7[通知管理<br/>通知发布,用户通知,已读未读]
|
||
A8[任务管理<br/>定时任务配置,任务监控]
|
||
A9[系统监控<br/>服务器监控,JVM监控]
|
||
A10[JAR管理<br/>JAR加载,JAR监控]
|
||
A11[文件管理<br/>文件上传,S3存储]
|
||
A12[参数管理<br/>系统参数配置]
|
||
A13[风控管理<br/>IP限流,URI限流]
|
||
A14[地址管理<br/>地址解析,IP归属]
|
||
end
|
||
|
||
subgraph 代码生成模块
|
||
B1[数据源管理<br/>多数据源,连接测试]
|
||
B2[表结构管理<br/>表查询,字段配置,同步]
|
||
B3[代码生成<br/>参数配置,模板渲染,ZIP下载]
|
||
B4[代码预览<br/>代码查看,多模板支持]
|
||
end
|
||
|
||
subgraph 公共模块
|
||
C1[缓存模块<br/>Redis缓存,缓存枚举,AOP缓存]
|
||
C2[远程调用<br/>OpenFeign,微服务通信]
|
||
C3[JAR管理<br/>动态JAR加载,运行时扩展]
|
||
C4[日志总线<br/>事件发布,MQ异步写入ES]
|
||
C5[日志过滤<br/>请求拦截,操作日志采集]
|
||
C6[消息队列<br/>RabbitMQ,异步处理,错误重试]
|
||
C7[任务调度<br/>异步任务,定时任务,Redis分布式锁]
|
||
C8[限流模块<br/>Sentinel集成,流量控制]
|
||
end
|
||
|
||
subgraph 监控模块
|
||
D1[监控服务端<br/>Spring Boot Admin Server]
|
||
D2[监控客户端<br/>Spring Boot Admin Client]
|
||
end
|
||
```
|
||
|
||
```mermaid
|
||
mindmap
|
||
root((xtools-app<br/>基础应用平台))
|
||
系统管理
|
||
用户管理
|
||
增删改查
|
||
角色分配
|
||
密码管理
|
||
状态管理
|
||
角色管理
|
||
角色配置
|
||
权限分配
|
||
菜单分配
|
||
菜单管理
|
||
树形结构
|
||
动态加载
|
||
按钮权限
|
||
部门管理
|
||
树形结构
|
||
人员管理
|
||
字典管理
|
||
类型管理
|
||
字典项管理
|
||
日志管理
|
||
操作日志
|
||
ES存储检索
|
||
通知管理
|
||
通知发布
|
||
用户通知
|
||
文件管理
|
||
本地上传
|
||
S3存储
|
||
风控管理
|
||
IP限流
|
||
URI限流
|
||
代码生成
|
||
数据源管理
|
||
多数据源
|
||
连接测试
|
||
表结构管理
|
||
表同步
|
||
字段配置
|
||
代码生成
|
||
Velocity模板
|
||
ZIP下载
|
||
代码预览
|
||
多模板预览
|
||
公共模块
|
||
缓存管理
|
||
Redis缓存
|
||
缓存枚举
|
||
远程调用
|
||
OpenFeign
|
||
日志处理
|
||
日志总线
|
||
日志过滤
|
||
消息队列
|
||
RabbitMQ
|
||
任务调度
|
||
异步任务
|
||
定时任务
|
||
```
|
||
|
||
```mermaid
|
||
graph LR
|
||
User[用户] --> Login[登录认证]
|
||
User --> Menu[菜单访问]
|
||
User --> Data[数据操作]
|
||
|
||
Login --> Auth[认证授权]
|
||
Auth --> Token[Token管理]
|
||
Auth --> Redis[Redis缓存]
|
||
|
||
Menu --> Perm[权限验证]
|
||
Role[角色] --> Perm
|
||
|
||
Data --> LogFilter[日志过滤器]
|
||
LogFilter --> LogBus[日志总线]
|
||
LogBus --> MQ[RabbitMQ]
|
||
MQ --> LogMq[日志消费者]
|
||
LogMq --> ES[Elasticsearch]
|
||
|
||
Cache[Redis缓存] --> Data
|
||
|
||
Gen[代码生成] --> DB[数据库]
|
||
Gen --> Velocity[Velocity模板]
|
||
```
|
||
|
||
## 二、项目结构设计
|
||
|
||
### 2.1 整体架构
|
||
|
||
```mermaid
|
||
graph TD
|
||
xtools-app[xtools-app<br/>基础应用平台<br/>v1.0.0] --> common[xtools-app-common<br/>公共模块]
|
||
xtools-app --> sys[xtools-app-sys<br/>系统管理模块]
|
||
xtools-app --> gen[xtools-app-gen<br/>代码生成模块]
|
||
xtools-app --> monitor[xtools-app-monitor<br/>监控模块]
|
||
xtools-app --> standalone[xtools-app-standalone<br/>单体部署模块]
|
||
|
||
common --> cache[common-cache<br/>缓存模块]
|
||
common --> call[common-call<br/>远程调用模块]
|
||
common --> jar[common-jar<br/>JAR管理模块]
|
||
common --> job[common-job<br/>任务调度模块]
|
||
common --> log[common-log<br/>日志模块]
|
||
common --> mq[common-mq<br/>消息队列模块]
|
||
common --> sentinel[common-sentinel<br/>限流模块]
|
||
common --> task[common-task<br/>异步任务模块]
|
||
|
||
log --> log-bus[log-bus<br/>日志总线]
|
||
log --> log-filter[log-filter<br/>日志过滤器]
|
||
|
||
sys --> sys-api[sys-api<br/>系统API接口]
|
||
sys --> sys-auth[sys-auth<br/>认证授权]
|
||
sys --> sys-biz[sys-biz<br/>系统业务逻辑]
|
||
sys --> sys-boot[sys-boot<br/>系统微服务启动]
|
||
sys --> sys-call[sys-call<br/>系统远程调用]
|
||
sys --> sys-file[sys-file<br/>文件管理]
|
||
sys --> sys-file-web[sys-file-web<br/>文件Web服务]
|
||
sys --> sys-log-es[sys-log-bus-elasticsearch<br/>日志ES存储]
|
||
sys --> sys-param[sys-param<br/>系统参数]
|
||
sys --> sys-scheduled[sys-scheduled<br/>定时任务]
|
||
sys --> sys-risk[sys-risk<br/>风控管理]
|
||
|
||
gen --> gen-biz[gen-biz<br/>代码生成业务]
|
||
gen --> gen-boot[gen-boot<br/>代码生成微服务启动]
|
||
|
||
monitor --> monitor-boot[monitor-boot<br/>监控服务端]
|
||
monitor --> monitor-client[monitor-client<br/>监控客户端]
|
||
```
|
||
|
||
### 2.2 分层架构
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph Controller层
|
||
A1[接收HTTP请求]
|
||
A2[参数验证<br/>Valid]
|
||
A3[调用Service层]
|
||
A4[返回统一响应<br/>Result]
|
||
end
|
||
|
||
subgraph Service层
|
||
B1[业务逻辑处理]
|
||
B2[事务控制<br/>Transactional]
|
||
B3[调用Mapper层]
|
||
B4[缓存操作<br/>Redis]
|
||
end
|
||
|
||
subgraph Mapper层
|
||
C1[MyBatis-Plus<br/>BaseMapper]
|
||
C2[数据库访问]
|
||
C3[SQL执行]
|
||
end
|
||
|
||
subgraph 横切关注点
|
||
D1[AuthFilter<br/>认证过滤器]
|
||
D2[LogBus<br/>日志总线]
|
||
D3[Sentinel<br/>流量控制]
|
||
D4[MqErrorHandle<br/>消息错误处理]
|
||
end
|
||
|
||
A1 --> A2 --> A3 --> B1
|
||
B1 --> B2 --> B3 --> C1
|
||
C1 --> C2 --> C3
|
||
|
||
A1 -.-> D1
|
||
A1 -.-> D2
|
||
A1 -.-> D3
|
||
B1 -.-> D4
|
||
```
|
||
|
||
### 2.3 模块职责
|
||
|
||
| 层级 | 模块 | 职责说明 |
|
||
|------|------|----------|
|
||
| **Controller层** | SysUserController、SysLoginController等 | 接收HTTP请求、参数验证（@Valid）、调用Service层、返回统一响应（Result） |
|
||
| **Service层** | SysUserServiceImpl、SysLoginServiceImpl等 | 实现业务逻辑、事务控制（@Transactional）、调用Mapper层、缓存操作 |
|
||
| **BaseService层** | SysUserBaseService等 | 继承MyBatis-Plus ServiceImpl，提供基础CRUD操作 |
|
||
| **Mapper层** | SysUserMapper、SysRoleMapper等 | 继承MyBatis-Plus BaseMapper，数据库访问、SQL执行 |
|
||
| **Entity层** | SysUser、SysRole、SysMenu等 | 数据库实体映射 |
|
||
| **DTO层** | Req（请求）、Resp（响应）、Excel | 数据传输对象 |
|
||
| **Convert层** | SysUserConvert、SysRoleConvert等 | MapStruct对象转换 |
|
||
| **Config层** | SysConfig、ApiConfig等 | 配置类 |
|
||
| **MQ层** | SysLogMq、SysTaskMq等 | 消息队列消费者 |
|
||
| **Job层** | BaseJob、SysLogJob等 | 定时任务、异步任务 |
|
||
| **Utils层** | PasswdUtils、AuthUtils等 | 工具类 |
|
||
|
||
### 2.4 包结构设计
|
||
|
||
```
|
||
xtools.app.{module}
|
||
├── controller # 控制器层
|
||
├── service # 服务接口
|
||
│ ├── base # 基础服务（继承ServiceImpl）
|
||
│ └── impl # 服务实现
|
||
├── mapper # 数据访问层
|
||
├── model
|
||
│ ├── entity # 实体类
|
||
│ ├── dto
|
||
│ │ ├── req # 请求DTO（AddReq、UpdateReq、PageReq）
|
||
│ │ ├── resp # 响应DTO
|
||
│ │ └── excel # Excel导入导出DTO
|
||
│ └── vo # 视图对象
|
||
├── convert # MapStruct转换器
|
||
├── config # 配置类
|
||
├── utils # 工具类
|
||
├── mq # 消息队列处理
|
||
├── job # 定时任务
|
||
└── es # Elasticsearch相关
|
||
```
|
||
|
||
### 2.5 启动模块
|
||
|
||
项目支持两种部署模式：
|
||
|
||
| 模块 | 说明 |
|
||
|------|------|
|
||
| **xtools-app-standalone** | 单体部署模式，包含所有模块，通过 spring-boot-maven-plugin 打包为可执行JAR |
|
||
| **xtools-app-sys-boot** | 微服务模式 - 系统管理服务 |
|
||
| **xtools-app-gen-boot** | 微服务模式 - 代码生成服务 |
|
||
| **xtools-app-monitor-boot** | 微服务模式 - 监控服务 |
|
||
|
||
## 三、项目功能设计
|
||
|
||
### 3.1 认证授权设计
|
||
|
||
#### 认证流程
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[用户请求登录] --> B[前端获取SM2公钥]
|
||
B --> C[用户输入账号密码<br/>使用SM2公钥加密]
|
||
C --> D{验证验证码}
|
||
D -->|验证码已过期| E[返回验证码已过期]
|
||
D -->|验证码错误| F[返回验证码错误]
|
||
D -->|验证成功| G[后端SM2解密密码]
|
||
G --> H{查询账号}
|
||
H -->|账户不存在| I[返回账户不存在]
|
||
H -->|账户被禁用| J[返回账户被禁用]
|
||
H -->|账户正常| K{SM3密码比对}
|
||
K -->|密码错误| L[返回密码错误]
|
||
K -->|密码正确| M[查询用户角色]
|
||
M --> N[生成Token<br/>缓存用户信息到Redis]
|
||
N --> O[返回TokenDto]
|
||
```
|
||
|
||
#### 验证码机制
|
||
|
||
系统支持两种验证码模式（随机切换）：
|
||
- **GIF动态验证码**：基于 Easy Captcha 生成动态图片验证码
|
||
- **算术验证码**：随机生成加减法算术题图片
|
||
|
||
验证码通过 Redis 缓存（`AppCache.UID_CAPTCHA`，过期时间60秒）。
|
||
|
||
#### RBAC权限模型
|
||
|
||
```mermaid
|
||
graph TD
|
||
User[用户 SysUser] -->|多对多| UserRole[用户角色关联<br/>SysUserRole]
|
||
UserRole -->|多对多| Role[角色 SysRole]
|
||
|
||
Role -->|多对多| RoleMenu[角色菜单关联<br/>SysRoleMenu]
|
||
RoleMenu -->|多对多| Menu[菜单权限 SysMenu]
|
||
|
||
Menu --> M1[页面菜单]
|
||
Menu --> M2[按钮权限]
|
||
Menu --> M3[接口权限]
|
||
```
|
||
|
||
#### 权限验证流程
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[用户发起请求] --> B{判断请求类型}
|
||
B -->|微服务请求| C[验证Cloud Token]
|
||
B -->|常规请求| D[获取请求URI]
|
||
|
||
C --> C1{Token有效?}
|
||
C1 -->|无效| C2[返回UNAUTHORIZED]
|
||
C1 -->|有效| C3[传递头部信息]
|
||
C3 --> C4[校验掩码设置]
|
||
C4 --> C5[放行请求]
|
||
|
||
D --> D1{URI在权限白名单?}
|
||
D1 -->|是| D2[放行请求]
|
||
D1 -->|否| D3{获取UID}
|
||
D3 -->|UID为空| D4[返回METHOD_NOT_ALLOWED]
|
||
D3 -->|UID存在| D5{URI在登录白名单?}
|
||
D5 -->|是| D2
|
||
D5 -->|否| D6{验证AccessToken}
|
||
D6 -->|无效| D7[返回UNAUTHORIZED]
|
||
D6 -->|有效| D8{校验URI访问权限}
|
||
D8 -->|无权限| D9[返回FORBIDDEN]
|
||
D8 -->|有权限| D10[设置上下文信息]
|
||
D10 --> D11[校验掩码设置]
|
||
D11 --> D2
|
||
```
|
||
|
||
#### 认证模式
|
||
|
||
系统支持两种认证模式，通过请求头 `Cloud` 标识区分：
|
||
- **微服务认证**：验证 Cloud Token（一次性令牌，Redis Hash存储）
|
||
- **常规认证**：验证 UID + AccessToken + URI权限
|
||
|
||
### 3.2 日志管理设计
|
||
|
||
#### 日志处理流程
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A[HTTP请求] --> B[LogFilter<br/>日志过滤器]
|
||
B --> C[采集请求信息<br/>URI,参数,IP,UserAgent]
|
||
C --> D[LogBus<br/>日志总线]
|
||
D --> E[RabbitMQ<br/>异步消息队列]
|
||
E --> F[SysLogMq<br/>日志消费者]
|
||
F --> G[LogBusService<br/>日志处理服务]
|
||
G --> H[Elasticsearch<br/>日志存储]
|
||
```
|
||
|
||
#### 日志类型
|
||
|
||
| 类型 | 说明 | 处理方式 |
|
||
|------|------|----------|
|
||
| 操作日志 | 用户操作行为记录 | LogFilter采集 -> MQ -> ES |
|
||
| 系统日志 | 系统运行日志 | LogBus记录 -> MQ -> ES |
|
||
| 任务日志 | 定时任务执行日志 | BaseJob记录 -> LogBus -> MQ -> ES |
|
||
| 错误日志 | 异常和错误信息 | 异常捕获 -> LogBus -> MQ -> ES |
|
||
|
||
#### 日志配置
|
||
|
||
- **日志总线**：基于 `xtools-boot-log` 封装，支持通过 `LogBus.init()` 链式调用记录日志
|
||
- **消息队列**：使用 RabbitMQ 异步处理，并发度配置为 5-10
|
||
- **存储**：日志存储到 Elasticsearch，通过 `EsSysLogRepository` 和 `EsSysLogServiceImpl` 实现
|
||
- **日志追踪**：使用 `LogTrackHolder`（基于 ScopedValue）实现日志链路追踪
|
||
|
||
### 3.3 代码生成设计
|
||
|
||
#### 代码生成流程
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[配置数据源] --> B[测试连接]
|
||
B --> C[同步数据库]
|
||
C --> D{读取表信息}
|
||
|
||
D --> E[获取表列表<br/>DatabaseMetaData]
|
||
E --> F[过滤排除表]
|
||
F --> G[生成表信息<br/>GenTable]
|
||
|
||
G --> H[获取字段信息<br/>DatabaseMetaData]
|
||
H --> I[处理字段类型<br/>类型映射,表单类型]
|
||
I --> J[生成字段信息<br/>GenTableColumn]
|
||
|
||
J --> K[保存到数据库]
|
||
K --> L{用户操作}
|
||
|
||
L -->|预览代码| M[Velocity渲染模板]
|
||
L -->|下载代码| N[Velocity渲染模板]
|
||
L -->|修改配置| O[保存表和字段配置]
|
||
|
||
M --> P[返回代码列表<br/>GenCodeDto]
|
||
N --> Q[打包ZIP下载]
|
||
```
|
||
|
||
#### 模板引擎
|
||
|
||
- 使用 **Apache Velocity 2.4.1** 模板引擎
|
||
- 通过 `GenProperties` 配置模板路径和生成参数
|
||
- 支持多种模板类型：Entity、Service、ServiceImpl、Mapper、Controller、Vue、TS API、SQL等
|
||
- 支持微服务 API 模块生成（可配置开关 `openApi`）
|
||
- 支持字典数据、脱敏数据等高级配置
|
||
|
||
#### 代码生成特性
|
||
|
||
| 特性 | 说明 |
|
||
|------|------|
|
||
| 多数据源 | 支持 MySQL 等多种数据库类型 |
|
||
| 表结构同步 | 自动读取表和字段元数据 |
|
||
| 智能类型映射 | 自动将数据库类型映射为 Java 类型 |
|
||
| 表单类型推断 | 根据字段类型自动推断表单组件 |
|
||
| 查询方式推断 | String类型默认LIKE，时间类型默认范围查询 |
|
||
| 模板配置 | 可配置后端和前端项目名称、模块路径等 |
|
||
| ZIP下载 | 生成的代码打包为ZIP文件下载 |
|
||
|
||
### 3.4 任务调度设计
|
||
|
||
#### 任务实现
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[任务触发] --> B[BaseJob.run]
|
||
B --> C[初始化日志追踪<br/>ScopedValue]
|
||
C --> D[获取Redis锁<br/>tryLock]
|
||
D --> E{获取锁成功?}
|
||
E -->|否| F[记录日志:已存在]
|
||
E -->|是| G[执行runJob方法]
|
||
G --> H{执行成功?}
|
||
H -->|异常| I[记录错误日志]
|
||
H -->|成功| J[记录成功日志]
|
||
I --> K[释放锁<br/>releaseLock]
|
||
J --> K
|
||
```
|
||
|
||
#### 任务类型
|
||
|
||
| 类型 | 实现方式 | 说明 |
|
||
|------|----------|------|
|
||
| 异步任务 | `BaseJob implements Runnable` | 支持分布式锁，防止重复执行 |
|
||
| XXL-JOB | `xtools-boot-job-xxl`（可选） | 分布式任务调度平台 |
|
||
| 定时任务 | `SysScheduled` | Spring Task 定时任务管理 |
|
||
| Spring任务 | `JobInterface.execute()` | Spring 原生任务执行接口 |
|
||
|
||
#### 任务调度特性
|
||
|
||
- **分布式锁**：使用 Redis `tryLock` / `releaseLock` 实现分布式锁，防止多实例重复执行
|
||
- **日志追踪**：通过 `ScopedValue`（JDK 25特性）实现任务执行上下文传递
|
||
- **异常处理**：任务执行异常自动记录错误日志
|
||
- **超时控制**：支持自定义锁超时时间
|
||
|
||
### 3.5 缓存设计
|
||
|
||
#### 缓存策略
|
||
|
||
| 缓存Key | 说明 | 过期时间 |
|
||
|---------|------|----------|
|
||
| `xtools-app:uid:{uid}:sm2` | SM2公钥缓存 | 5分钟 |
|
||
| `xtools-app:uid:{uid}:captcha` | 验证码缓存 | 60秒 |
|
||
| `xtools-app:auth:sys:user:{token}` | 用户认证信息 | 1小时 |
|
||
| `xtools-app:auth:sys:uri` | 权限URI缓存 | 永不过期 |
|
||
| `xtools-app:auth:cloud:token` | 微服务Token | 60秒 |
|
||
| `xtools-app:mq:msg:err:{id}` | MQ消息错误次数 | 60秒 |
|
||
| `xtools-app:lock:job:{className}` | 任务分布式锁 | 5分钟 |
|
||
| `xtools-app:risk:ip:{ip}` | 风控IP | 永不过期 |
|
||
| `xtools-app:risk:uri:{uri}` | 风控URI | 永不过期 |
|
||
| `xtools-app:sys:cache:param:{key}` | 系统参数缓存 | 永不过期 |
|
||
| `xtools-app:sys:cache:jar:{name}` | JAR包缓存 | 永不过期 |
|
||
| `xtools-app:sys:cache:addr:{key}` | 地址缓存 | 1小时 |
|
||
|
||
#### 缓存架构
|
||
|
||
```mermaid
|
||
graph TD
|
||
A[应用层] --> B[AppCache<br/>缓存枚举]
|
||
B --> C[RedisService<br/>Redis操作服务]
|
||
|
||
subgraph Redis缓存
|
||
D1[认证缓存<br/>Token,用户信息]
|
||
D2[业务缓存<br/>参数,地址,JAR]
|
||
D3[风控缓存<br/>IP,URI限流]
|
||
D4[分布式锁<br/>任务锁]
|
||
D5[临时数据<br/>验证码,SM2密钥]
|
||
end
|
||
|
||
C --> D1
|
||
C --> D2
|
||
C --> D3
|
||
C --> D4
|
||
C --> D5
|
||
```
|
||
|
||
### 3.6 文件存储设计
|
||
|
||
项目支持多种文件存储方式（通过 `xtools-app-standalone` 可选配置）：
|
||
|
||
| 存储方式 | 模块 | 说明 |
|
||
|---------|------|------|
|
||
| S3存储 | `xtools-boot-storage-s3` | 兼容S3协议的对象存储 |
|
||
| 本地文件 | `xtools-boot-storage-file` | 本地文件系统存储（可选） |
|
||
|
||
## 四、编码规范设计
|
||
|
||
### 4.1 命名规范
|
||
|
||
#### 类命名
|
||
|
||
| 类型 | 命名规范 | 示例 |
|
||
|------|----------|------|
|
||
| 实体类 | `Sys` + 模块名 | `SysUser`、`SysRole`、`SysMenu` |
|
||
| 请求DTO | 模块名 + `Req` | `SysUserAddReq`、`SysUserPageReq` |
|
||
| 响应DTO | 模块名 + `Resp` | `GenTableInfoResp` |
|
||
| Excel DTO | 模块名 + `Excel` | `SysDictExcel` |
|
||
| Service接口 | 模块名 + `Service` | `SysUserService` |
|
||
| Service实现 | 模块名 + `ServiceImpl` | `SysUserServiceImpl` |
|
||
| Base Service | 模块名 + `BaseService` | `SysUserBaseService` |
|
||
| Controller | 模块名 + `Controller` | `SysUserController` |
|
||
| Mapper | 模块名 + `Mapper` | `SysUserMapper` |
|
||
| 转换器 | 模块名 + `Convert` | `SysUserConvert` |
|
||
| 工具类 | 功能名 + `Utils` | `PasswdUtils`、`AuthUtils` |
|
||
| 配置类 | 功能名 + `Config` 或 `Properties` | `SysConfig`、`GenProperties` |
|
||
|
||
#### 方法命名
|
||
|
||
| 操作 | 命名规范 | 示例 |
|
||
|------|----------|------|
|
||
| 查询单个 | `getXxx` | `getUserInfo()` |
|
||
| 分页查询 | `pageXxx` | `pageSysUser()` |
|
||
| 新增 | `addXxx` / `saveXxx` | `addSysUser()` |
|
||
| 修改 | `updateXxx` / `editXxx` | `editUserInfo()` |
|
||
| 删除 | `delXxx` / `deleteXxx` | `delSysUser()` |
|
||
| 统计 | `countXxx` | — |
|
||
|
||
### 4.2 注释规范
|
||
|
||
#### 类注释格式
|
||
|
||
```java
|
||
/**
|
||
* <p>Title : 类名称</p>
|
||
* <p>Description : 类描述</p>
|
||
* <p>DevelopTools : Idea_x64_v2026.1</p>
|
||
* <p>DevelopSystem : macOS Sequoia 15.7.5</p>
|
||
* <p>Company : org.xujun</p>
|
||
*
|
||
* @author : XuJun
|
||
* @version : 1.0.0
|
||
* @date : 2026/1/31 21:18
|
||
*/
|
||
```
|
||
|
||
#### 方法注释格式
|
||
|
||
```java
|
||
/**
|
||
* 方法描述
|
||
*
|
||
* @param param 参数说明
|
||
* @return 返回值说明
|
||
*/
|
||
```
|
||
|
||
#### 常量注释格式
|
||
|
||
```java
|
||
/**
|
||
* 微服务标识
|
||
*/
|
||
private static final String CLOUD_FLAG = String.valueOf(Boolean.TRUE);
|
||
```
|
||
|
||
### 4.3 代码风格
|
||
|
||
- **Lombok**：使用 `@RequiredArgsConstructor` 构造器注入，减少样板代码
|
||
- **MapStruct**：使用接口定义对象转换器，编译时自动生成实现
|
||
- **MyBatis-Plus**：继承 `ServiceImpl` 和 `BaseMapper`，简化CRUD操作
|
||
- **依赖注入**：使用 `@RequiredArgsConstructor` + `final` 字段（构造器注入）和 `@Resource`（特殊场景）
|
||
- **统一返回**：使用 `Result<T>` 统一响应格式
|
||
- **统一异常**：使用 `BizError`（业务错误）和 `BizWarning`（业务警告）异常类
|
||
- **JDK特性**：使用 `ScopedValue`、`switch表达式`、`record` 等JDK 25特性
|
||
- **常量管理**：通过 `BaseParams` 接口提供通用常量（`CP_NUM0`、`CP_NUM1` 等）
|
||
|
||
### 4.4 设计规范
|
||
|
||
- **分层原则**：Controller -> Service -> Mapper 严格分层，禁止跨层调用
|
||
- **单一职责**：每个模块负责单一业务领域
|
||
- **开闭原则**：通过继承 `BaseJob`、`BaseMessageHandle` 等基类扩展功能
|
||
- **接口隔离**：Service接口与BaseService接口分离，基础CRUD与业务逻辑分离
|
||
|
||
### 4.5 安全规范
|
||
|
||
- **密码加密**：使用 SM3 国密算法加密存储密码，SM2 非对称加密传输密码
|
||
- **SQL安全**：使用 MyBatis-Plus 参数化查询，防止SQL注入
|
||
- **数据验证**：使用 `@Valid` 注解进行请求参数验证
|
||
- **权限控制**：基于 RBAC 模型的接口级别权限控制
|
||
- **数据脱敏**：集成掩码机制（MaskIgnore），支持动态开关
|
||
|
||
## 五、项目依赖设计
|
||
|
||
### 5.1 核心框架依赖
|
||
|
||
| 依赖 | 版本 | 用途 |
|
||
|------|------|------|
|
||
| Spring Boot | 4.0.5 | 应用框架 |
|
||
| Spring Framework | 7.0.6 | 核心框架 |
|
||
| Spring Cloud | 2025.1.1 | 微服务框架 |
|
||
| Spring Cloud Alibaba | 2025.1.0.0 | 微服务组件 |
|
||
| Spring Data BOM | 2025.1.4 | 数据访问版本管理 |
|
||
| MyBatis-Plus | 3.5.16 | ORM增强工具 |
|
||
| MyBatis Spring Boot Starter | 4.0.1 | MyBatis集成 |
|
||
|
||
### 5.2 数据存储依赖
|
||
|
||
| 依赖 | 版本 | 用途 |
|
||
|------|------|------|
|
||
| Druid | 1.2.28 | 数据库连接池 |
|
||
| MySQL Connector/J | 9.6.0 | MySQL数据库驱动 |
|
||
| Elasticsearch Client | 9.2.6 | ES搜索引擎客户端 |
|
||
| Spring Data Redis | （Spring Boot管理） | Redis集成 |
|
||
| Lettuce | 6.8.2 | Redis客户端 |
|
||
| Spring AMQP | 4.0.2 | RabbitMQ集成 |
|
||
| RabbitMQ Client | 5.27.1 | RabbitMQ客户端 |
|
||
|
||
### 5.3 微服务相关依赖
|
||
|
||
| 依赖 | 版本 | 用途 |
|
||
|------|------|------|
|
||
| Nacos Client | 3.1.1 | 服务注册与配置中心 |
|
||
| Sentinel | 1.8.9 | 流量控制与熔断降级 |
|
||
| Seata | 2.5.0 | 分布式事务（可用） |
|
||
| RocketMQ | 5.3.1 | 消息队列（可用） |
|
||
|
||
### 5.4 工具库依赖
|
||
|
||
| 依赖 | 版本 | 用途 |
|
||
|------|------|------|
|
||
| Lombok | 1.18.44 | 代码简化 |
|
||
| MapStruct | 1.6.3 | 对象映射 |
|
||
| FastJSON2 | 2.0.60 | JSON处理 |
|
||
| Velocity | 2.4.1 | 模板引擎（代码生成） |
|
||
| Jackson | 2.21.2 | JSON序列化 |
|
||
| Commons Lang3 | 3.20.0 | 通用工具 |
|
||
| Commons IO | 2.21.0 | IO工具 |
|
||
| Commons Text | 1.15.0 | 文本处理 |
|
||
| Caffeine | 3.2.3 | 本地缓存 |
|
||
|
||
### 5.5 安全相关依赖
|
||
|
||
| 依赖 | 版本 | 用途 |
|
||
|------|------|------|
|
||
| BouncyCastle (bcprov-jdk18on) | 1.84 | 国密算法（SM2/SM3） |
|
||
| Easy Captcha | 1.6.2 | 验证码生成 |
|
||
| java-jwt | 4.5.1 | JWT令牌 |
|
||
|
||
### 5.6 文档相关依赖
|
||
|
||
| 依赖 | 版本 | 用途 |
|
||
|------|------|------|
|
||
| Knife4j | 4.5.0 | API文档增强 |
|
||
| SpringDoc OpenAPI | 3.0.3 | OpenAPI文档 |
|
||
| Swagger Annotations | 2.2.48 | API注解 |
|
||
|
||
### 5.7 系统监控依赖
|
||
|
||
| 依赖 | 版本 | 用途 |
|
||
|------|------|------|
|
||
| Spring Boot Admin | 4.0.3 | 应用监控 |
|
||
| OSHI Core | 6.11.1 | 系统信息采集 |
|
||
| Micrometer | 1.16.4 | 指标采集 |
|
||
|
||
### 5.8 文件处理依赖
|
||
|
||
| 依赖 | 版本 | 用途 |
|
||
|------|------|------|
|
||
| Fesod Sheet | 2.0.1-incubating | Excel处理 |
|
||
| PDFBox | 3.0.7 | PDF处理 |
|
||
| Thumbnailator | 0.4.21 | 图片压缩 |
|
||
| S3 SDK | 2.42.34 | S3对象存储客户端 |
|
||
|
||
### 5.9 其他工具依赖
|
||
|
||
| 依赖 | 版本 | 用途 |
|
||
|------|------|------|
|
||
| XXL-Job Core | 3.4.0 | 分布式任务调度 |
|
||
| IP2Region | 3.3.7 | IP归属地查询 |
|
||
| UserAgentUtils | 1.21 | 浏览器标识解析 |
|
||
| Pinyin4j | 2.5.1 | 拼音转换 |
|
||
| ZXing | 3.5.4 | 二维码/条形码 |
|
||
| JSoup | 1.22.1 | HTML解析 |
|
||
| MMSEG4J | 1.10.0 | 中文分词 |
|
||
|
||
### 5.10 xtools 内部框架依赖
|
||
|
||
| 依赖 | 版本 | 用途 |
|
||
|------|------|------|
|
||
| xtools-core | 5.0.0 | 核心工具库 |
|
||
| xtools-web | 5.0.0 | Web工具库 |
|
||
| xtools-extend | 5.0.0 | 扩展工具库 |
|
||
| xtools-api | 5.0.0 | API基础库 |
|
||
| xtools-boot-api | 5.0.0 | Boot API基础（Result、异常） |
|
||
| xtools-boot-core | 5.0.0 | Boot核心（Holder、工具） |
|
||
| xtools-boot-cache-redis | 5.0.0 | Redis缓存封装 |
|
||
| xtools-boot-db-mybatis-plus | 5.0.0 | MyBatis-Plus封装 |
|
||
| xtools-boot-elasticsearch | 5.0.0 | Elasticsearch封装 |
|
||
| xtools-boot-ip | 5.0.0 | IP工具封装 |
|
||
| xtools-boot-knife4j | 5.0.0 | Knife4j封装 |
|
||
| xtools-boot-log | 5.0.0 | 日志封装 |
|
||
| xtools-boot-mask | 5.0.0 | 数据脱敏封装 |
|
||
| xtools-boot-mq-base | 5.0.0 | 消息队列基础 |
|
||
| xtools-boot-mq-rabbit | 5.0.0 | RabbitMQ封装 |
|
||
| xtools-boot-storage-base | 5.0.0 | 存储基础 |
|
||
| xtools-boot-storage-file | 5.0.0 | 本地文件存储 |
|
||
| xtools-boot-storage-s3 | 5.0.0 | S3对象存储 |
|
||
| xtools-boot-task | 5.0.0 | 异步任务封装 |
|
||
| xtools-boot-thread | 5.0.0 | 线程池封装 |
|
||
| xtools-boot-web-base | 5.0.0 | Web基础 |
|
||
| xtools-boot-web-filter | 5.0.0 | Web过滤器基础 |
|
||
| xtools-boot-job-xxl | 5.0.0 | XXL-Job集成 |
|
||
| xtools-cloud-alibaba-nacos | 5.0.0 | Nacos集成 |
|
||
| xtools-cloud-alibaba-sentinel | 5.0.0 | Sentinel集成 |
|
||
| xtools-cloud-call | 5.0.0 | 微服务远程调用 |
|
||
|
||
## 六、技术选型说明
|
||
|
||
### 6.1 JDK 25
|
||
|
||
- **选择原因**：采用最新LTS版本，充分利用JDK新特性提升开发效率和运行性能
|
||
- **主要特性**：
|
||
- **ScopedValue**：用于任务执行的上下文传递（LogTrackHolder），替代ThreadLocal
|
||
- **Virtual Threads（虚拟线程）**：轻量级线程，提升高并发处理能力
|
||
- **Switch表达式**：简化条件分支代码
|
||
- **Record**：用于不可变数据载体
|
||
- **Pattern Matching**：增强的模式匹配能力
|
||
- **性能优化**：ZGC/Shenandoah垃圾回收器优化
|
||
|
||
### 6.2 Spring Boot 4.0.5
|
||
|
||
- **Spring Framework版本**：7.0.6
|
||
- **主要特性**：
|
||
- 支持JDK 17+，完美适配JDK 25
|
||
- 响应式编程支持（WebFlux）
|
||
- 可观测性增强（Micrometer 1.16.4集成）
|
||
- 虚拟线程支持
|
||
- Jakarta EE 10+ 规范支持
|
||
- GraalVM Native Image 支持
|
||
|
||
### 6.3 MyBatis-Plus 3.5.16
|
||
|
||
- **MyBatis版本**：4.0.1
|
||
- **主要特性**：
|
||
- 简化CRUD操作，通过 `ServiceImpl` 和 `BaseMapper` 提供通用方法
|
||
- Lambda查询包装器，类型安全的条件构造
|
||
- 内置分页插件
|
||
- 代码生成器（本项目自研代码生成模块）
|
||
- 性能分析拦截器
|
||
|
||
### 6.4 Elasticsearch 9.2.6
|
||
|
||
- **Spring Data BOM**：2025.1.4
|
||
- **主要特性**：
|
||
- 全文搜索引擎，用于日志存储和检索
|
||
- 高性能、分布式架构
|
||
- 支持近实时搜索
|
||
- 通过 Spring Data Elasticsearch 集成
|
||
|
||
### 6.5 Redis
|
||
|
||
- **客户端**：Lettuce 6.8.2
|
||
- **主要特性**：
|
||
- 高性能缓存，支持多种数据结构
|
||
- 分布式锁（tryLock/releaseLock）
|
||
- 认证信息缓存、权限缓存
|
||
- 会话管理、限流计数
|
||
|
||
### 6.6 RabbitMQ
|
||
|
||
- **Spring AMQP**：4.0.2
|
||
- **RabbitMQ Client**：5.27.1
|
||
- **主要特性**：
|
||
- 可靠消息传递（消息确认机制）
|
||
- 灵活路由（Exchange + Queue + RoutingKey）
|
||
- 并发消费控制（concurrency配置）
|
||
- 错误处理和重试机制（MqErrorHandle）
|
||
|
||
### 6.7 Nacos 3.1.1
|
||
|
||
- **用途**：服务注册与发现、配置中心
|
||
- **主要特性**：
|
||
- 服务注册与发现
|
||
- 动态配置管理
|
||
- 服务健康检查
|
||
|
||
### 6.8 Sentinel 1.8.9
|
||
|
||
- **用途**：流量控制与熔断降级
|
||
- **主要特性**：
|
||
- 流量控制
|
||
- 熔断降级
|
||
- 系统保护
|
||
- 热点参数限流
|
||
|
||
### 6.9 其他重要依赖版本
|
||
|
||
| 依赖 | 版本 | 用途 |
|
||
|------|------|------|
|
||
| Spring Cloud Alibaba | 2025.1.0.0 | 微服务框架 |
|
||
| Nacos | 3.1.1 | 服务注册与配置中心 |
|
||
| Sentinel | 1.8.9 | 流量控制与熔断 |
|
||
| FastJSON2 | 2.0.60 | JSON序列化 |
|
||
| Lombok | 1.18.44 | 代码简化 |
|
||
| MapStruct | 1.6.3 | 对象映射 |
|
||
| Velocity | 2.4.1 | 模板引擎 |
|
||
| Knife4j | 4.5.0 | API文档增强 |
|
||
| BouncyCastle | 1.84 | 加密库 |
|
||
| OSHI | 6.11.1 | 系统监控 |
|
||
| Easy Captcha | 1.6.2 | 验证码生成 |
|
||
| Fesod Sheet | 2.0.1-incubating | Excel处理 |
|
||
| Jackson | 2.21.2 | JSON处理 |
|
||
| Druid | 1.2.28 | 数据库连接池 |
|
||
| Spring Boot Admin | 4.0.3 | 应用监控 |
|
||
| java-jwt | 4.5.1 | JWT令牌 |
|
||
| XXL-Job | 3.4.0 | 分布式任务调度 |
|
||
|
||
---
|
||
|
||
**文档版本**：v1.0
|
||
**编写日期**：2026-04-16
|
||
**项目版本**：1.0.0
|
||
**父POM版本**：xtools-parent-cloud:5.0.0
|
||
**JDK版本**：25
|
||
**维护团队**：xujun.org
|