# 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