# 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<br/>微服务工具模块))
        xtools-cloud-alibaba
            Nacos
                服务注册与发现
                配置中心
            Sentinel
                流量控制
                熔断降级
                自定义异常处理
        xtools-cloud-call
            REST远程调用
                RestClient封装
                请求拦截器
                响应缓冲
            调用追踪
                链路日志
                日志总线集成
            负载均衡
                Spring Cloud LoadBalancer
```

## 二、项目结构设计

### 2.1 整体架构

```mermaid
graph TD
    xtools_cloud[xtools-cloud<br/>微服务工具父模块] --> xtools_cloud_alibaba[xtools-cloud-alibaba<br/>Alibaba微服务组件]
    xtools_cloud --> xtools_cloud_call[xtools-cloud-call<br/>微服务调用模块]

    xtools_cloud_alibaba --> nacos[xtools-cloud-alibaba-nacos<br/>Nacos配置]
    xtools_cloud_alibaba --> sentinel[xtools-cloud-alibaba-sentinel<br/>Sentinel配置]

    xtools_cloud_call -.->|依赖| xtools_boot_core[xtools-boot-core<br/>核心模块]
    xtools_cloud_call -.->|依赖| xtools_boot_log[xtools-boot-log<br/>日志模块]

    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<br/>记录模块加载成功]
```

`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[直接返回<br/>不输出默认信息]
    E -->|false - 需默认处理| G[输出默认JSON提示<br/>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<br/>如业务有实现]
```

### 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 方法<br/>自定义前置处理]
    C -->|不存在| E[跳过自定义处理]
    D --> E
    E --> F[注入请求头<br/>日志追踪ID + 微服务标识]
    F --> G[记录请求日志<br/>URI + 请求头 + 请求体]
    G --> H[执行HTTP请求]
    H --> I[读取并缓冲响应体]
    I --> J[记录响应日志<br/>耗时 + 状态码 + 响应体]
    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<br/>发起调用] --> B[ClientHttpInterceptor]
    B --> C[获取 LogTrack]
    C --> D["请求头注入<br/>LOG_TRACK + CLOUD标识"]
    D --> E[服务B<br/>接收请求]
    E --> F[日志过滤组件<br/>提取追踪信息]
    F --> G[日志记录<br/>关联同一链路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
/**
 * <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 : 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