# xtools-cloud 项目设计文档
## 一、功能和用途
### 1.1 项目概述
- **项目名称**：xtools-cloud
- **项目版本**：5.0.0
- **父POM**：org.xujun:xtools-parent-cloud:5.0.0
- **项目定位**：低调大师工具箱 Spring Cloud 微服务工具模块，适配 JDK 25，提供微服务基础设施集成能力
- **技术特点**：
- 采用最新的 JDK 25 版本，充分利用新特性
- 基于 Spring Boot 4.0.5 构建，支持自动配置和快速开发
- 集成 Spring Cloud 2025.1.1 微服务框架
- 支持 Nacos 3.1.1 服务注册与发现及配置中心
- 集成 Sentinel 1.8.9 实现流量控制和熔断降级
- 使用 Spring Cloud LoadBalancer 实现客户端负载均衡
- 集成微服务调用日志追踪，支持跨服务链路追踪
### 1.2 核心功能
```mermaid
graph TB
subgraph xtools-cloud 微服务工具模块
A1[Nacos服务注册与发现]
A2[Nacos配置中心]
A3[Sentinel流量控制]
A4[Sentinel熔断降级]
A5[REST远程调用]
A6[调用日志追踪]
A7[客户端负载均衡]
A8[自定义限流异常处理]
end
```
**核心功能详细说明**：
- **Nacos 服务注册与发现**：基于 Spring Cloud Alibaba Nacos Discovery 实现微服务自动注册与发现
- **Nacos 配置中心**：基于 Spring Cloud Alibaba Nacos Config 实现动态配置管理
- **Sentinel 流量控制**：集成 Sentinel 实现请求限流、熔断降级，支持 Nacos 持久化规则配置
- **REST 远程调用**：基于 Spring RestClient 封装，提供统一的微服务间 HTTP 调用能力
- **调用日志追踪**：通过拦截器实现微服务调用链路的请求/响应日志记录
- **客户端负载均衡**：集成 Spring Cloud LoadBalancer 实现客户端侧负载均衡
- **自定义限流异常处理**：支持自定义 Sentinel 限流异常处理器，可灵活扩展
```mermaid
mindmap
root((xtools-cloud
微服务工具模块))
xtools-cloud-alibaba
Nacos
服务注册与发现
配置中心
Sentinel
流量控制
熔断降级
自定义异常处理
xtools-cloud-call
REST远程调用
RestClient封装
请求拦截器
响应缓冲
调用追踪
链路日志
日志总线集成
负载均衡
Spring Cloud LoadBalancer
```
## 二、项目结构设计
### 2.1 整体架构
```mermaid
graph TD
xtools_cloud[xtools-cloud
微服务工具父模块] --> xtools_cloud_alibaba[xtools-cloud-alibaba
Alibaba微服务组件]
xtools_cloud --> xtools_cloud_call[xtools-cloud-call
微服务调用模块]
xtools_cloud_alibaba --> nacos[xtools-cloud-alibaba-nacos
Nacos配置]
xtools_cloud_alibaba --> sentinel[xtools-cloud-alibaba-sentinel
Sentinel配置]
xtools_cloud_call -.->|依赖| xtools_boot_core[xtools-boot-core
核心模块]
xtools_cloud_call -.->|依赖| xtools_boot_log[xtools-boot-log
日志模块]
nacos -.->|依赖| xtools_boot_core
sentinel -.->|依赖| xtools_boot_core
```
### 2.2 模块职责
| 模块 | 职责 |
|-------------------------------|--------------------------------|
| xtools-cloud | 父模块，管理子模块和公共属性配置 |
| xtools-cloud-alibaba | Alibaba 微服务组件聚合模块 |
| xtools-cloud-alibaba-nacos | Nacos 服务注册与发现、配置中心自动配置 |
| xtools-cloud-alibaba-sentinel | Sentinel 流量控制与熔断降级自动配置 |
| xtools-cloud-call | 微服务间 REST 调用封装，包含拦截器、日志追踪、负载均衡 |
### 2.3 包结构设计
```
xtools.cloud.alibaba.nacos
└── CloudAlibabaNacosConfiguration.java # Nacos自动配置入口
xtools.cloud.alibaba.sentinel
├── CloudAlibabaSentinelConfiguration.java # Sentinel自动配置入口
├── handler
│ ├── CustomBlockExceptionHandler.java # 自定义限流异常处理接口
│ └── SentinelBlockExceptionHandler.java # Sentinel限流异常处理器
└── selector
└── CloudAlibabaSentinelImportSelector.java # Sentinel Bean扫描注册器
xtools.cloud.call
├── CloudClientConfiguration.java # 调用模块自动配置入口
├── config
│ └── RestClientConfig.java # RestClient自定义配置
├── interceptor
│ ├── BufferedClientHttpResponse.java # 响应体缓冲包装器
│ ├── CallInterceptor.java # 调用拦截器接口
│ └── ClientHttpInterceptor.java # HTTP调用拦截器实现
└── selector
└── CloudClientImportSelector.java # 调用模块Bean扫描注册器
```
### 2.4 自动加载机制
```mermaid
flowchart TD
A[应用启动] --> B[xtools-boot-core 自动加载]
B --> C{检测模块依赖}
C -->|引入 xtools-cloud-alibaba-nacos| D[加载 Nacos 自动配置]
C -->|引入 xtools-cloud-alibaba-sentinel| E[加载 Sentinel 自动配置]
C -->|引入 xtools-cloud-call| F[加载 Call 自动配置]
D --> D1[注册 Nacos Discovery]
D --> D2[注册 Nacos Config]
E --> E1[注册 Sentinel Bean]
E --> E2[注册限流异常处理器]
E --> E3[扫描 sentinel 包下组件]
F --> F1[注册 RestClientCustomizer]
F --> F2[注册 ClientHttpInterceptor]
F --> F3[扫描 call 包下组件]
```
## 三、项目功能设计
### 3.1 Nacos 集成设计
**功能说明**：
- **服务注册与发现**：基于 `spring-cloud-starter-alibaba-nacos-discovery` 实现微服务自动注册到 Nacos 注册中心，并支持服务发现
- **配置中心**：基于 `spring-cloud-starter-alibaba-nacos-config` 实现从 Nacos 配置中心动态加载配置
**模块加载机制**：
```mermaid
flowchart TD
A[CloudAlibabaNacosConfiguration] --> B[构造方法调用]
B --> C[ModuleLoadUtils.loadSuccess
记录模块加载成功]
```
`CloudAlibabaNacosConfiguration` 作为自动配置入口类，通过 Spring Boot 的自动装配机制加载。模块本身无需额外配置，依赖 Spring
Cloud Alibaba Nacos Starter 提供的默认自动配置。
### 3.2 Sentinel 集成设计
**功能说明**：
- **流量控制**：基于 `spring-cloud-starter-alibaba-sentinel` 实现请求流量控制
- **熔断降级**：Sentinel 提供的熔断降级能力，保护微服务稳定性
- **规则持久化**：通过 `sentinel-datasource-nacos` 将限流规则持久化到 Nacos
- **自定义异常处理**：提供 `CustomBlockExceptionHandler` 接口，支持业务自定义限流异常处理逻辑
**限流异常处理流程**：
```mermaid
flowchart TD
A[请求触发Sentinel限流] --> B[SentinelBlockExceptionHandler.handle]
B --> C{是否存在自定义处理器?}
C -->|存在| D[调用 CustomBlockExceptionHandler]
D --> E{返回值是否为 true?}
E -->|true - 已处理| F[直接返回
不输出默认信息]
E -->|false - 需默认处理| G[输出默认JSON提示
TOO_MANY_REQUESTS]
C -->|不存在| H[记录warn日志]
H --> G
```
**模块加载机制**：
```mermaid
flowchart TD
A[CloudAlibabaSentinelConfiguration] --> B["@Import\nCloudAlibabaSentinelImportSelector"]
B --> C[ImportBeanDefinitionRegistrar]
C --> D[ClassPathBeanDefinitionScanner]
D --> E["扫描 xtools.cloud.alibaba.sentinel 包"]
E --> F[注册 SentinelBlockExceptionHandler]
E --> G[注册 CustomBlockExceptionHandler
如业务有实现]
```
### 3.3 微服务调用设计
**功能说明**：
- **REST 远程调用**：基于 Spring RestClient 封装，提供统一的微服务间 HTTP 调用能力
- **请求拦截**：通过 `ClientHttpInterceptor` 实现请求拦截，自动注入日志追踪信息和微服务标识
- **响应缓冲**：通过 `BufferedClientHttpResponse` 包装响应体，支持响应体重复读取
- **调用日志追踪**：记录请求和响应的完整日志信息，通过 LogBus 日志总线输出
- **负载均衡**：集成 `spring-cloud-starter-loadbalancer` 实现客户端负载均衡
- **扩展拦截**：提供 `CallInterceptor` 接口，支持业务自定义请求前置处理
**调用拦截流程**：
```mermaid
flowchart TD
A[发起REST远程调用] --> B[ClientHttpInterceptor.intercept]
B --> C{CallInterceptor 是否存在?}
C -->|存在| D[执行 before 方法
自定义前置处理]
C -->|不存在| E[跳过自定义处理]
D --> E
E --> F[注入请求头
日志追踪ID + 微服务标识]
F --> G[记录请求日志
URI + 请求头 + 请求体]
G --> H[执行HTTP请求]
H --> I[读取并缓冲响应体]
I --> J[记录响应日志
耗时 + 状态码 + 响应体]
J --> K[返回 BufferedClientHttpResponse]
```
**模块加载机制**：
```mermaid
flowchart TD
A[CloudClientConfiguration] --> B["@Import\nCloudClientImportSelector"]
B --> C[ImportBeanDefinitionRegistrar]
C --> D[ClassPathBeanDefinitionScanner]
D --> E["扫描 xtools.cloud.call 包"]
E --> F[注册 RestClientConfig]
F --> G[注册 RestClientCustomizer]
F --> H[注册 ClientHttpInterceptor]
```
### 3.4 跨服务链路追踪设计
**追踪信息传递**：
```mermaid
flowchart LR
A[服务A
发起调用] --> B[ClientHttpInterceptor]
B --> C[获取 LogTrack]
C --> D["请求头注入
LOG_TRACK + CLOUD标识"]
D --> E[服务B
接收请求]
E --> F[日志过滤组件
提取追踪信息]
F --> G[日志记录
关联同一链路ID]
```
**追踪字段说明**：
| 字段 | 说明 |
|---------------|--------------------------|
| LOG_TRACK | Base64 编码的日志追踪信息，包含链路ID等 |
| CLOUD | 标识当前请求为微服务间调用 |
| UID | 用户ID（透传） |
| AUTHORIZATION | 认证令牌（透传） |
## 四、编码规范设计
### 4.1 命名规范
**类命名**：
- **配置类**：以 `Configuration` 结尾，如 `CloudClientConfiguration`、`RestClientConfig`
- **选择器类**：以 `ImportSelector` 结尾，如 `CloudClientImportSelector`
- **拦截器接口**：以 `Interceptor` 结尾，如 `CallInterceptor`
- **拦截器实现**：以具体功能命名，如 `ClientHttpInterceptor`
- **异常处理器**：以 `Handler` 或 `ExceptionHandler` 结尾
- **包装器**：以具体功能 + 原始类型命名，如 `BufferedClientHttpResponse`
**方法命名**：
- 回调方法：`handle`、`before`
- 生命周期：`registerBeanDefinitions`、`loadSuccess`
- 工厂方法：`restClientCustomizer`、`clientHttpInterceptor`
### 4.2 注释规范
**类注释格式**：
```java
/**
* Title : 类名称
* Description : 类描述
* DevelopTools : Idea_x64_v2026.1
* DevelopSystem : macOS Sequoia 15.7.5
* Company : org.xujun
*
* @author : XuJun
* @version : 5.0.0
* @date : 2026/01/01 09:30
*/
```
**方法注释格式**：
```java
/**
* 方法描述
*
* @param param 参数说明
* @return 返回值说明
* @throws Exception 异常说明
*/
```
### 4.3 代码风格
- 使用 Lombok 简化代码（`@Slf4j`、`@AllArgsConstructor`）
- 使用 JSpecify `@NonNull` 注解标注非空参数
- 使用 `@Resource` 进行依赖注入
- 使用 Spring `@Configuration`、`@Bean`、`@Component` 注解
- 统一使用 `@Import` + `ImportBeanDefinitionRegistrar` 模式实现自动配置
- 通过 `ModuleLoadUtils.loadSuccess()` 记录模块加载状态
- 使用 `Objects.nonNull()` 进行空值判断
- 接口定义 default 方法提供默认实现
### 4.4 设计规范
- **模块化设计**：每个功能模块独立成子模块，通过 Maven 依赖引入
- **自动装配**：使用 `@Import` + `ImportBeanDefinitionRegistrar` 实现包扫描和自动配置
- **接口扩展**：核心功能提供接口（如 `CallInterceptor`、`CustomBlockExceptionHandler`），支持业务自定义扩展
- **包装器模式**：`BufferedClientHttpResponse` 包装原始响应，解决响应体只能读取一次的问题
### 4.5 安全规范
- 请求头中透传认证信息（AUTHORIZATION、UID），保持微服务间调用安全
- 通过 LogBus 日志总线记录调用日志，便于安全审计
- 使用 Sentinel 流量控制防止服务过载
## 五、项目依赖设计
### 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 Cloud LoadBalancer | 2025.1.1 | 客户端负载均衡 |
### 5.2 微服务组件依赖
| 依赖 | 版本 | 用途 |
|--------------|-------|--------------|
| Nacos Client | 3.1.1 | 服务注册与发现、配置中心 |
| Sentinel | 1.8.9 | 流量控制与熔断降级 |
### 5.3 xtools 内部框架依赖
| 依赖 | 版本 | 用途 |
|------------------|-------|---------------------------|
| xtools-boot-core | 5.0.0 | 核心工具模块（ModuleLoadUtils 等） |
| xtools-boot-log | 5.0.0 | 日志模块（LogBus、LogTrack 等） |
| xtools-core | 5.0.0 | 基础核心模块（枚举、常量等） |
| xtools-boot-api | 5.0.0 | API 模块（Result、常量等） |
### 5.4 工具库依赖（来自父POM管理）
| 依赖 | 版本 | 用途 |
|-----------|---------|-------------------------|
| Lombok | 1.18.44 | 代码简化 |
| MapStruct | 1.6.3 | 对象映射 |
| FastJSON2 | 2.0.60 | JSON 处理 |
| Jackson | 2.21.2 | JSON 处理（Spring Boot 管理） |
| JSpecify | - | 空值注解 |
### 5.5 Web 相关依赖
| 依赖 | 版本 | 用途 |
|---------------------|-------|----------------------|
| Jakarta Servlet API | 6.1.0 | Servlet 规范（provided） |
## 六、技术选型说明
### 6.1 JDK 25
- **选择原因**：采用最新 JDK 版本，利用性能优化、改进的垃圾回收器、增强的并发工具等新特性
- **要求**：项目最低 JDK 版本为 25
### 6.2 Spring Boot 4.0.5
- **Spring Framework 版本**：7.0.6
- **主要特性**：
- 支持 JDK 17+，充分利用现代 JDK 特性
- 支持 RestClient 作为新的 HTTP 客户端
- 响应式编程支持
- 内置可观测性支持
- 虚拟线程支持
- 改进的自动配置机制
### 6.3 Spring Cloud 2025.1.1
- **选择原因**：与 Spring Boot 4.0.5 配套的 Spring Cloud 版本
- **主要特性**：
- 基于 Spring Framework 7.0.x
- 支持服务注册与发现
- 客户端负载均衡
- 配置管理
- 熔断器模式
### 6.4 Spring Cloud Alibaba 2025.1.0.0
- **Nacos 版本**：3.1.1 - 服务注册与发现、配置中心
- **Sentinel 版本**：1.8.9 - 流量控制与熔断降级
- **选择原因**：国内主流微服务解决方案，与 Spring Cloud 无缝集成
### 6.5 RestClient
- **选择原因**：Spring Boot 4.x 推荐的 HTTP 客户端，替代 RestTemplate
- **主要特性**：
- 流式 API 设计
- 支持拦截器机制
- 支持自定义配置（RestClientCustomizer）
- 原生支持请求/响应日志记录
### 6.6 其他重要依赖版本
| 依赖 | 版本 | 用途 |
|-----------------------------|------------------|-------------|
| Spring Boot Admin | 4.0.3 | 应用监控 |
| Druid | 1.2.28 | 数据库连接池 |
| MyBatis Spring Boot Starter | 4.0.1 | MyBatis 集成 |
| MyBatis-Plus | 3.5.16 | ORM 增强工具 |
| Knife4j | 4.5.0 | API 文档增强 |
| SpringDoc OpenAPI | 3.0.3 | OpenAPI 文档 |
| Swagger Annotations | 2.2.48 | API 注解 |
| XXL-Job | 3.4.0 | 分布式任务调度 |
| Velocity | 2.4.1 | 模板引擎 |
| Easy Captcha | 1.6.2 | 验证码生成 |
| BouncyCastle | 1.84 | 加密库 |
| OSHI | 6.11.1 | 系统监控 |
| Fesod Sheet | 2.0.1-incubating | Excel 处理 |
| Caffeine | 3.2.3 | 本地缓存 |
| Java JWT | 4.5.1 | JWT 令牌 |
| Elasticsearch Client | 9.2.6 | ES 客户端 |
| Spring AMQP | 4.0.2 | RabbitMQ 集成 |
| Netty | 4.2.12.Final | 网络框架 |
| AspectJ | 1.9.25.1 | AOP 支持 |
| Commons Lang3 | 3.19.0 | 通用工具 |
---
**文档版本**：v1.0
**编写日期**：2026-04-16
**项目版本**：5.0.0
**父POM版本**：xtools-parent-cloud:5.0.0
**JDK版本**：25
**维护团队**：xujun.org