项目名称：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 核心功能

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 限流异常处理器，可灵活扩展

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

二、项目结构设计

2.1 整体架构

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 自动加载机制

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 配置中心动态加载配置

模块加载机制：

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 接口，支持业务自定义限流异常处理逻辑

限流异常处理流程：

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

模块加载机制：

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 接口，支持业务自定义请求前置处理

调用拦截流程：

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]

模块加载机制：

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 跨服务链路追踪设计

追踪信息传递：

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 注释规范

类注释格式：

/**
 * <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
 */

方法注释格式：

/**
 * 方法描述
 *
 * @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

README.md Unescape Escape

xtools-cloud 项目设计文档

一、功能和用途

1.1 项目概述

1.2 核心功能

二、项目结构设计

2.1 整体架构

2.2 模块职责

2.3 包结构设计

2.4 自动加载机制

三、项目功能设计

3.1 Nacos 集成设计

3.2 Sentinel 集成设计

3.3 微服务调用设计

3.4 跨服务链路追踪设计

四、编码规范设计

4.1 命名规范

4.2 注释规范

4.3 代码风格

4.4 设计规范

4.5 安全规范

五、项目依赖设计

5.1 核心框架依赖

5.2 微服务组件依赖

5.3 xtools 内部框架依赖

5.4 工具库依赖（来自父POM管理）

5.5 Web 相关依赖

六、技术选型说明

6.1 JDK 25

6.2 Spring Boot 4.0.5

6.3 Spring Cloud 2025.1.1

6.4 Spring Cloud Alibaba 2025.1.0.0

6.5 RestClient

6.6 其他重要依赖版本

README.md