457 lines
16 KiB
Markdown
457 lines
16 KiB
Markdown
# 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
|