集成Resilience4j

pom.xml

@@ -12,6 +12,14 @@
     <name>Tacit Parent</name>
     <description>Tacit App Microservice Architecture Parent Project</description>
 
+
+    <modules>
+        <module>tacit-gateway</module>
+        <module>tacit-admin</module>
+        <module>tacit-app-api</module>
+        <module>tacit-common</module>
+    </modules>
+
     <properties>
         <java.version>21</java.version>
         <spring-boot.version>3.2.0</spring-boot.version>
@@ -20,6 +28,7 @@
         <mybatis-plus.version>3.5.5</mybatis-plus.version>
         <lombok.version>1.18.30</lombok.version>
         <jjwt.version>0.11.5</jjwt.version>
+        <resilience4j.version>2.1.0</resilience4j.version>
     </properties>
 
     <dependencyManagement>
@@ -83,15 +92,47 @@
                 <version>${jjwt.version}</version>
                 <scope>runtime</scope>
             </dependency>
+            
+            <!-- Resilience4j -->
+            <!-- Spring Boot 3集成模块，提供自动配置、注解支持和健康指标，是与Spring Boot集成的核心依赖 -->
+            <dependency>
+                <groupId>io.github.resilience4j</groupId>
+                <artifactId>resilience4j-spring-boot3</artifactId>
+                <version>${resilience4j.version}</version>
+            </dependency>
+            <!--  断路器模式   -->
+            <dependency>
+                <groupId>io.github.resilience4j</groupId>
+                <artifactId>resilience4j-circuitbreaker</artifactId>
+                <version>${resilience4j.version}</version>
+            </dependency>
+            <!--  限流功能  -->
+            <dependency>
+                <groupId>io.github.resilience4j</groupId>
+                <artifactId>resilience4j-ratelimiter</artifactId>
+                <version>${resilience4j.version}</version>
+            </dependency>
+            <!--   重试机制  -->
+            <dependency>
+                <groupId>io.github.resilience4j</groupId>
+                <artifactId>resilience4j-retry</artifactId>
+                <version>${resilience4j.version}</version>
+            </dependency>
+            <!--  舱壁隔离  -->
+            <dependency>
+                <groupId>io.github.resilience4j</groupId>
+                <artifactId>resilience4j-bulkhead</artifactId>
+                <version>${resilience4j.version}</version>
+            </dependency>
+            <!--  控制操作执行时间  -->
+            <dependency>
+                <groupId>io.github.resilience4j</groupId>
+                <artifactId>resilience4j-timelimiter</artifactId>
+                <version>${resilience4j.version}</version>
+            </dependency>
         </dependencies>
     </dependencyManagement>
 
-    <modules>
-        <module>tacit-gateway</module>
-        <module>tacit-admin</module>
-        <module>tacit-app-api</module>
-        <module>tacit-common</module>
-    </modules>
 
     <repositories>
         <repository>

resilience4j-usage-template.md

@@ -0,0 +1,382 @@
+# Resilience4j 使用模板与文档
+
+## 1. 概述
+Resilience4j 是一个轻量级的容错库，专为 Java 8+ 和函数式编程设计。它提供了断路器、限流、重试、舱壁隔离和超时控制等功能，帮助构建弹性和可靠的系统。
+
+## 2. 配置文件示例
+
+### 2.1 application.yml 配置
+```yaml
+resilience4j:
+  # 断路器配置
+  circuitbreaker:
+    instances:
+      userServiceCircuitBreaker:
+        # 失败阈值百分比
+        failureRateThreshold: 50
+        # 滑动窗口类型（count-based 或 time-based）
+        slidingWindowType: COUNT_BASED
+        # 滑动窗口大小
+        slidingWindowSize: 10
+        # 最小请求数
+        minimumNumberOfCalls: 5
+        # 半开状态下允许的最大请求数
+        permittedNumberOfCallsInHalfOpenState: 3
+        # 等待时间（毫秒）
+        waitDurationInOpenState: 10000
+        # 自动从半开状态恢复到关闭状态
+        automaticTransitionFromOpenToHalfOpenEnabled: true
+        # 忽略的异常类型
+        ignoreExceptions:
+          - org.springframework.web.client.HttpClientErrorException$BadRequest
+
+  # 限流配置
+  ratelimiter:
+    instances:
+      userServiceRateLimiter:
+        # 每秒允许的请求数
+        limitForPeriod: 100
+        # 时间窗口（毫秒）
+        limitRefreshPeriod: 1000
+        # 等待获取许可的超时时间（毫秒）
+        timeoutDuration: 500
+
+  # 重试配置
+  retry:
+    instances:
+      userServiceRetry:
+        # 最大重试次数
+        maxAttempts: 3
+        # 初始重试间隔（毫秒）
+        waitDuration: 1000
+        # 重试退避策略
+        retryExponentialBackoff:
+          initialInterval: 1000
+          multiplier: 2
+          maxInterval: 10000
+        # 重试的异常类型
+        retryExceptions:
+          - org.springframework.web.client.HttpServerErrorException
+        # 忽略的异常类型
+        ignoreExceptions:
+          - org.springframework.web.client.HttpClientErrorException$BadRequest
+
+  # 舱壁配置
+  bulkhead:
+    instances:
+      userServiceBulkhead:
+        # 最大并行执行的任务数
+        maxConcurrentCalls: 20
+        # 等待队列大小
+        maxWaitDuration: 1000
+
+  # 超时控制配置
+  timelimiter:
+    instances:
+      userServiceTimeLimiter:
+        # 超时时间（毫秒）
+        timeoutDuration: 3000
+```
+
+## 3. 使用示例
+
+### 3.1 Service 层使用示例
+
+```java
+package com.tacit.admin.service.impl;
+
+import io.github.resilience4j.bulkhead.annotation.Bulkhead;
+import io.github.resilience4j.circuitbreaker.annotation.CircuitBreaker;
+import io.github.resilience4j.ratelimiter.annotation.RateLimiter;
+import io.github.resilience4j.retry.annotation.Retry;
+import io.github.resilience4j.timelimiter.annotation.TimeLimiter;
+import org.springframework.stereotype.Service;
+import org.springframework.web.client.RestTemplate;
+
+import java.util.concurrent.CompletableFuture;
+
+@Service
+public class UserService {
+
+    private final RestTemplate restTemplate;
+
+    public UserService(RestTemplate restTemplate) {
+        this.restTemplate = restTemplate;
+    }
+
+    /**
+     * 使用断路器示例
+     * @param userId 用户ID
+     * @return 用户信息
+     */
+    @CircuitBreaker(
+            name = "userServiceCircuitBreaker",
+            fallbackMethod = "getUserFallback"
+    )
+    public String getUserById(Long userId) {
+        return restTemplate.getForObject("http://user-service/users/{id}", String.class, userId);
+    }
+
+    /**
+     * 使用限流示例
+     * @param userId 用户ID
+     * @return 用户信息
+     */
+    @RateLimiter(
+            name = "userServiceRateLimiter",
+            fallbackMethod = "getUserFallback"
+    )
+    public String getUserWithRateLimit(Long userId) {
+        return restTemplate.getForObject("http://user-service/users/{id}", String.class, userId);
+    }
+
+    /**
+     * 使用重试示例
+     * @param userId 用户ID
+     * @return 用户信息
+     */
+    @Retry(
+            name = "userServiceRetry",
+            fallbackMethod = "getUserFallback"
+    )
+    public String getUserWithRetry(Long userId) {
+        return restTemplate.getForObject("http://user-service/users/{id}", String.class, userId);
+    }
+
+    /**
+     * 使用舱壁示例
+     * @param userId 用户ID
+     * @return 用户信息
+     */
+    @Bulkhead(
+            name = "userServiceBulkhead",
+            fallbackMethod = "getUserFallback"
+    )
+    public String getUserWithBulkhead(Long userId) {
+        return restTemplate.getForObject("http://user-service/users/{id}", String.class, userId);
+    }
+
+    /**
+     * 使用超时控制示例
+     * @param userId 用户ID
+     * @return 用户信息
+     */
+    @TimeLimiter(
+            name = "userServiceTimeLimiter",
+            fallbackMethod = "getUserAsyncFallback"
+    )
+    public CompletableFuture<String> getUserWithTimeout(Long userId) {
+        return CompletableFuture.supplyAsync(() -> 
+            restTemplate.getForObject("http://user-service/users/{id}", String.class, userId)
+        );
+    }
+
+    /**
+     * 组合使用多个功能示例
+     * @param userId 用户ID
+     * @return 用户信息
+     */
+    @CircuitBreaker(
+            name = "userServiceCircuitBreaker",
+            fallbackMethod = "getUserFallback"
+    )
+    @Retry(
+            name = "userServiceRetry"
+    )
+    @RateLimiter(
+            name = "userServiceRateLimiter"
+    )
+    public String getUserWithMultipleFeatures(Long userId) {
+        return restTemplate.getForObject("http://user-service/users/{id}", String.class, userId);
+    }
+
+    /**
+     * 同步回退方法
+     * @param userId 用户ID
+     * @param ex 异常
+     * @return 回退结果
+     */
+    private String getUserFallback(Long userId, Exception ex) {
+        return "{\"id\":0,\"name\":\"Fallback User\",\"message\":\"服务暂时不可用，请稍后重试\"}";
+    }
+
+    /**
+     * 异步回退方法
+     * @param userId 用户ID
+     * @param ex 异常
+     * @return 回退结果
+     */
+    private CompletableFuture<String> getUserAsyncFallback(Long userId, Exception ex) {
+        return CompletableFuture.completedFuture(
+            "{\"id\":0,\"name\":\"Async Fallback User\",\"message\":\"服务暂时不可用，请稍后重试\"}"
+        );
+    }
+}
+```
+
+### 3.2 Controller 层使用示例
+
+```java
+package com.tacit.admin.controller;
+
+import com.tacit.admin.service.UserService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.concurrent.CompletableFuture;
+
+@RestController
+@RequestMapping("/user")
+@Tag(name = "用户管理", description = "用户管理相关接口")
+public class UserController {
+
+    @Autowired
+    private UserService userService;
+
+    @Operation(summary = "获取用户信息", description = "使用断路器模式获取用户信息")
+    @GetMapping("/get/{id}")
+    public String getUser(@PathVariable Long id) {
+        return userService.getUserById(id);
+    }
+
+    @Operation(summary = "限流获取用户信息", description = "使用限流模式获取用户信息")
+    @GetMapping("/rate-limit/{id}")
+    public String getUserWithRateLimit(@PathVariable Long id) {
+        return userService.getUserWithRateLimit(id);
+    }
+
+    @Operation(summary = "重试获取用户信息", description = "使用重试模式获取用户信息")
+    @GetMapping("/retry/{id}")
+    public String getUserWithRetry(@PathVariable Long id) {
+        return userService.getUserWithRetry(id);
+    }
+
+    @Operation(summary = "超时控制获取用户信息", description = "使用超时控制获取用户信息")
+    @GetMapping("/timeout/{id}")
+    public CompletableFuture<String> getUserWithTimeout(@PathVariable Long id) {
+        return userService.getUserWithTimeout(id);
+    }
+
+    @Operation(summary = "组合功能获取用户信息", description = "组合使用多个容错功能获取用户信息")
+    @GetMapping("/multiple/{id}")
+    public String getUserWithMultipleFeatures(@PathVariable Long id) {
+        return userService.getUserWithMultipleFeatures(id);
+    }
+}
+```
+
+## 4. 使用说明
+
+### 4.1 注解说明
+
+| 注解 | 功能 | 主要属性 |
+|------|------|----------|
+| `@CircuitBreaker` | 断路器 | name, fallbackMethod |
+| `@RateLimiter` | 限流 | name, fallbackMethod |
+| `@Retry` | 重试 | name, fallbackMethod |
+| `@Bulkhead` | 舱壁隔离 | name, fallbackMethod, type |
+| `@TimeLimiter` | 超时控制 | name, fallbackMethod |
+
+### 4.2 回退方法注意事项
+
+1. 回退方法必须与原始方法在同一个类中
+2. 回退方法的参数列表必须与原始方法相同，并且最后一个参数是 Throwable 类型
+3. 回退方法的返回类型必须与原始方法相同
+4. 异步方法的回退方法必须返回 CompletableFuture
+
+### 4.3 监控与指标
+
+Resilience4j 提供了与 Micrometer 和 Prometheus 的集成，可以监控各种指标：
+
+```yaml
+# 启用 Resilience4j 指标management:
+  endpoints:
+    web:
+      exposure:
+        include: health,info,metrics,prometheus
+  endpoint:
+    health:
+      show-details: always
+  metrics:
+    export:
+      prometheus:
+        enabled: true
+```
+
+## 5. 最佳实践
+
+1. **合理配置参数**：根据实际业务场景调整各功能的参数
+2. **使用回退策略**：为每个容错功能提供适当的回退方法
+3. **监控与告警**：定期监控各功能的指标，设置合理的告警阈值
+4. **组合使用**：根据需求组合使用多个容错功能
+5. **异常处理**：区分可重试和不可重试的异常类型
+6. **性能测试**：在生产环境部署前进行充分的性能测试
+
+## 6. 常见问题与解决方案
+
+### 6.1 断路器一直处于打开状态
+- 检查失败率阈值是否设置过低
+- 检查是否有足够的请求数触发断路器
+- 检查忽略的异常类型是否正确
+
+### 6.2 限流不生效
+- 检查限流配置是否正确
+- 检查限流实例名称是否与注解中的名称一致
+- 检查是否有其他限流机制影响
+
+### 6.3 重试不生效
+- 检查重试的异常类型是否正确
+- 检查重试次数和间隔是否合理
+- 检查是否有其他重试机制影响
+
+## 7. 依赖管理
+
+如果使用 Spring Boot，可以只引入以下依赖：
+
+```xml
+<dependency>
+    <groupId>io.github.resilience4j</groupId>
+    <artifactId>resilience4j-spring-boot3</artifactId>
+    <version>${resilience4j.version}</version>
+</dependency>
+```
+
+如果需要更精细的控制，可以单独引入所需的模块：
+
+```xml
+<!-- 核心模块 -->
+<dependency>
+    <groupId>io.github.resilience4j</groupId>
+    <artifactId>resilience4j-core</artifactId>
+    <version>${resilience4j.version}</version>
+</dependency>
+
+<!-- 各功能模块 -->
+<dependency>
+    <groupId>io.github.resilience4j</groupId>
+    <artifactId>resilience4j-circuitbreaker</artifactId>
+    <version>${resilience4j.version}</version>
+</dependency>
+
+<dependency>
+    <groupId>io.github.resilience4j</groupId>
+    <artifactId>resilience4j-ratelimiter</artifactId>
+    <version>${resilience4j.version}</version>
+</dependency>
+
+<!-- 其他模块... -->
+```
+
+## 8. 版本兼容
+
+| Resilience4j 版本 | Spring Boot 版本 | Java 版本 |
+|-------------------|------------------|-----------|
+| 2.x               | 3.x              | 17+       |
+| 1.x               | 2.x              | 8+        |
+
+请根据您的 Spring Boot 版本选择合适的 Resilience4j 版本。

tacit-admin/pom.xml

@@ -78,6 +78,12 @@
             <scope>provided</scope>
         </dependency>
 
+        <!-- Resilience4j -->
+        <dependency>
+            <groupId>io.github.resilience4j</groupId>
+            <artifactId>resilience4j-spring-boot3</artifactId>
+        </dependency>
+
         <!-- Testing -->
         <dependency>
             <groupId>org.springframework.boot</groupId>

tacit-admin/src/main/java/com/tacit/admin/AdminApplication.java

@@ -13,5 +13,6 @@ import org.springframework.cloud.openfeign.EnableFeignClients;
 public class AdminApplication {
     public static void main(String[] args) {
         SpringApplication.run(AdminApplication.class, args);
+        System.out.println("====== admin start ======");
     }
 }

tacit-admin/src/main/java/com/tacit/admin/config/SecurityConfig.java

@@ -44,7 +44,7 @@ public class SecurityConfig {
                 // 设置请求授权规则
                 .authorizeHttpRequests(auth -> auth
                         // 允许访问的路径
-                        .requestMatchers("/test/**", "/user/login", "/v3/api-docs/**", "/swagger-ui/**", "/swagger-ui.html").permitAll()
+                        .requestMatchers("/test/**", "/v3/api-docs/**", "/swagger-ui/**", "/swagger-ui.html").permitAll()
                         // 其他请求需要认证
                         .anyRequest().authenticated()
                 );

tacit-app-api/src/main/java/com/tacit/app/AppApiApplication.java

@@ -13,5 +13,6 @@ import org.springframework.cloud.openfeign.EnableFeignClients;
 public class AppApiApplication {
     public static void main(String[] args) {
         SpringApplication.run(AppApiApplication.class, args);
+        System.out.println("====== app api start ======");
     }
 }

tacit-gateway/src/main/java/com/tacit/gateway/GatewayApplication.java

@@ -9,5 +9,6 @@ import org.springframework.cloud.client.discovery.EnableDiscoveryClient;
 public class GatewayApplication {
     public static void main(String[] args) {
         SpringApplication.run(GatewayApplication.class, args);
+        System.out.println("====== gateway start ======");
     }
 }