📝Docs: 更新 README

README.md

@@ -1,239 +1,249 @@
-# spring-boot-threadpool-demo
+# 使用 `@Async` 实现线程池
 
-> 📚 适用于 SpringBoot 的多种线程池实现
+## 前置知识
 
-**注意：Main 分支不包含具体实现，具体实现在项目的不同分支上**
+### **`@Async`**
 
-## 项目结构
+`@Async` 是 Spring 框架提供的一个注解，用于支持**异步方法调用**。它允许我们标记一个方法为异步方法，这样该方法将在**单独的线程**中执行，而不是阻塞当前线程。
-```
-spring-boot-threadpool-demo/
-├── src/
-│   ├── main/
-│   │   ├── java/cn/hezhaohui/threadpool/
-│   │   │   ├── ThreadpoolApplication.java
-│   │   │   ├── config/
-│   │   │   ├── service/
-│   │   │   ├── controller/
-│   │   │   └── model/
-│   └── resources/
-└── README.md
-```
 
-## 分支大纲
+#### 优点：
+- 提高应用程序的响应速度
+- 避免长时间运行的操作阻塞主线程
+- 适用于处理耗时操作、并行任务、异步通知等场景
 
-### 分支 1: `basic-async-config`
+#### 使用场景：
-**主题：基础 @Async 注解方式**
+- 异步发送邮件、短信
-- 实现简单的异步任务执行
+- 异步日志记录
-- 配置基本的线程池参数
+- 异步计算任务
-- 测试异步方法调用
+- 异步调用第三方服务
-- 包含线程安全性验证
 
-### 分支 2: `custom-executor-config`
+---
-**主题：自定义 Executor 配置**
-- 使用 ThreadPoolTaskExecutor 自定义配置
-- 配置核心线程数、最大线程数、队列容量
-- 设置线程名称前缀和拒绝策略
-- 添加线程池监控和管理
 
-### 分支 3: `application-properties-config`
+## 一、开启异步支持
-**主题：配置文件驱动方式**
-- 使用 application.yml 配置线程池
-- 支持不同环境的配置切换
-- 动态配置线程池参数
-- 配置文件验证和异常处理
 
-### 分支 4: `completable-future-config`
+要使用 `@Async` 注解，必须在 Spring 应用中开启**异步支持**。可以通过在主类或配置类上添加 `@EnableAsync` 注解来实现。
-**主题：CompletableFuture 方式**
-- 使用 CompletableFuture 实现异步编程
-- 异步任务链式调用
-- 异常处理和结果聚合
-- 异步回调机制实现
 
-### 分支 5: `scheduled-task-config`
-**主题：定时任务线程池**
-- 配置定时任务线程池
-- 定时任务执行示例
-- 任务调度和管理
-- 定时任务与异步任务结合
-
-### 分支 6: `advanced-monitoring-config`
-**主题：高级监控和管理**
-- 线程池状态监控
-- 自定义线程池管理器
-- 性能指标收集
-- 健康检查和告警机制
-
-### 分支 7: `multiple-pool-config`
-**主题：多线程池配置**
-- 不同业务场景的线程池隔离
-- 配置多个不同的线程池
-- 线程池路由和选择机制
-- 资源隔离和性能优化
-
-### 分支 8: `error-handling-config`
-**主题：异常处理和容错**
-- 异步任务异常处理
-- 重试机制实现
-- 降级策略
-- 异常日志记录和监控
-
-## 各分支详细实现内容
-
-### 分支 1: basic-async-config
 ```java
-// 配置类
 @Configuration
 @EnableAsync
-public class AsyncConfig { }
+public class AppConfig {
-
-// 服务类
-@Service
-public class AsyncService {
-    @Async
-    public void simpleAsyncTask() { }
 }
-
-// 测试类
-@SpringBootTest
-public class AsyncTest { }
 ```
 
-### 分支 2: custom-executor-config
+或者在 Spring Boot 主类上添加：
+
 ```java
-// 配置类
+@SpringBootApplication
-@Configuration
 @EnableAsync
-public class CustomAsyncConfig {
+public class Application {
-    @Bean("customExecutor")
+    public static void main(String[] args) {
-    public Executor customExecutor() { }
+        SpringApplication.run(Application.class, args);
-}
-
-// 服务类
-@Service
-public class CustomAsyncService {
-    @Async("customExecutor")
-    public void customAsyncTask() { }
-}
-```
-
-### 分支 3: application-properties-config
-```yaml
-# application.yml
-spring:
-  task:
-    execution:
-      pool:
-        core-size: 5
-        max-size: 10
-        queue-capacity: 100
-```
-
-### 分支 4: completable-future-config
-```java
-// 服务类
-@Service
-public class CompletableFutureService {
-    public CompletableFuture<String> asyncMethod() {
-        return CompletableFuture.supplyAsync(() -> "result");
     }
 }
 ```
 
-### 分支 5: scheduled-task-config
+---
+
+## 二、配置线程池（推荐）
+
+Spring 提供了多种方式来配置异步任务执行的线程池，推荐使用 `TaskExecutor` 来自定义线程池，以控制并发行为。
+
+### 1. 使用 `@Bean` 配置自定义线程池
+
 ```java
-// 配置类
-@Configuration
-@EnableScheduling
-public class ScheduledConfig {
-    @Bean("scheduledExecutor")
-    public Executor scheduledExecutor() { }
-}
-
-// 定时任务
-@Component
-public class ScheduledTask {
-    @Scheduled(fixedRate = 5000)
-    @Async("scheduledExecutor")
-    public void scheduledTask() { }
-}
-```
-
-### 分支 6: advanced-monitoring-config
-```java
-// 线程池监控
-@Component
-public class ThreadPoolMonitor {
-    public void monitorThreadPool() { }
-}
-
-// 健康检查
-@RestController
-public class ThreadPoolHealthController { }
-```
-
-### 分支 7: multiple-pool-config
-```java
-// 多个线程池配置
 @Configuration
 @EnableAsync
-public class MultiplePoolConfig {
+public class AsyncConfig {
-    @Bean("businessExecutor")
-    public Executor businessExecutor() { }
 
-    @Bean("ioExecutor")
+    @Bean(name = "customTaskExecutor")
-    public Executor ioExecutor() { }
+    public Executor customTaskExecutor() {
-}
+        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
-
+        executor.setCorePoolSize(5);
-// 服务类使用不同线程池
+        executor.setMaxPoolSize(10);
-@Service
+        executor.setQueueCapacity(100);
-public class MultiPoolService {
+        executor.setThreadNamePrefix("Custom-Async-");
-    @Async("businessExecutor")
+        executor.initialize();
-    public void businessTask() { }
+        return executor;
-  
+    }
-    @Async("ioExecutor")
-    public void ioTask() { }
 }
 ```
 
-### 分支 8: error-handling-config
+### 2. 指定使用哪个线程池
+
+可以通过 `@Async("customTaskExecutor")` 指定使用自定义的线程池。
+
 ```java
-// 异常处理配置
 @Service
-public class ErrorHandlingService {
+public class MyService {
-    @Async("errorHandlingExecutor")
-    public void taskWithErrorHandling() { }
-}
 
-// 全局异常处理器
+    @Async("customTaskExecutor")
-@RestControllerAdvice
+    public void asyncMethod() {
-public class AsyncExceptionHandler { }
+        // 异步执行的操作
+    }
+}
 ```
 
-## 测试用例设计
+---
 
-### 每个分支都需要包含的测试：
+## 三、使用默认线程池
-1. **线程池配置验证**
-2. **异步任务执行验证**
-3. **性能基准测试**
-4. **异常处理测试**
-5. **资源使用监控**
 
-## 部署和监控
+如果未配置自定义线程池，Spring 会使用默认的 `SimpleAsyncTaskExecutor`，但这个线程池不推荐用于生产环境，因为它**每次都会创建新线程**，容易引发资源耗尽问题。
 
-### 分支 9: `monitoring-deployment`
+可以使用 `@Async` 并不指定线程池名称，Spring 会自动使用默认的线程池（需确保 `@EnableAsync` 已开启）：
-**主题：部署和监控配置**
-- Docker 部署配置
-- Prometheus 监控集成
-- Grafana 可视化
-- 日志收集和分析
 
-## 文档和说明
+```java
+@Service
+public class MyService {
 
-### README.md 包含：
+    @Async
-1. 各分支功能说明
+    public void defaultAsyncMethod() {
-2. 配置参数说明
+        // 默认线程池执行
-3. 使用示例
+    }
-4. 性能测试结果
+}
-5. 最佳实践建议
+```
 
-这种分层结构可以让你清楚地看到不同线程池配置方式的特点和适用场景，便于学习和实际项目应用。
+---
+
+## 四、异步方法调用注意事项
+
+- `@Async` 注解的方法不能和调用它的方法在同一个类中，否则不会生效。因为 Spring 的 AOP 机制需要通过代理来实现异步调用，若在同一个类中调用，代理无法生效。
+- 异步方法不能返回 `void`，否则无法捕获异常。**建议返回 `Future<T>` 或 `CompletableFuture<T>`**。
+- 异步方法的异常处理：如果希望捕获异步方法中的异常，可以在方法中使用 `try-catch`，或者通过 `Future` 返回异常信息。
+- 如果异步方法中涉及事务控制，需注意事务的传播机制。
+
+---
+
+## 五、示例代码
+
+### 示例 1：简单异步方法
+
+```java
+@Service
+public class AsyncService {
+
+    @Async
+    public void sendNotification(String message) {
+        System.out.println("Sending notification: " + message);
+        // 模拟耗时操作
+        try {
+            Thread.sleep(1000);
+        } catch (InterruptedException e) {
+            e.printStackTrace();
+        }
+    }
+}
+```
+
+### 示例 2：使用自定义线程池并返回 Future
+
+```java
+@Service
+public class AsyncService {
+
+    @Async("customTaskExecutor")
+    public Future<String> asyncTask(String input) {
+        try {
+            Thread.sleep(2000);
+            return new AsyncResult<>("Processed: " + input);
+        } catch (InterruptedException e) {
+            return new AsyncResult<>("Error occurred");
+        }
+    }
+}
+```
+
+在调用处使用：
+
+```java
+@Autowired
+private AsyncService asyncService;
+
+public void callAsyncTask() {
+    Future<String> result = asyncService.asyncTask("test");
+    try {
+        System.out.println(result.get());
+    } catch (Exception e) {
+        e.printStackTrace();
+    }
+}
+```
+
+---
+
+## 六、线程池配置属性说明
+
+| 属性名                | 描述                                       |
+|-----------------------|--------------------------------------------|
+| `corePoolSize`        | 核心线程数（常驻线程数量）                 |
+| `maxPoolSize`         | 最大线程数（允许创建的最大线程数）         |
+| `queueCapacity`       | 任务队列容量（缓存未被立即执行的任务）     |
+| `keepAliveSeconds`    | 非核心线程的空闲时间（超过后会被销毁）     |
+| `threadNamePrefix`    | 线程名称前缀（用于调试和日志区分）         |
+| `allowCoreThreadTimeOut` | 是否允许核心线程超时（默认 false）        |
+
+---
+
+## 七、异步方法异常处理
+
+由于异步方法在独立线程中执行，不能直接抛出异常。可使用 `Future` 或 `CompletableFuture` 来捕获和处理异常。
+
+### 使用 `Future`
+
+```java
+@Async
+public Future<String> asyncMethod() {
+    try {
+        // …
+        return new AsyncResult<>("Success");
+    } catch (Exception e) {
+        return new AsyncResult<>("Error: " + e.getMessage());
+    }
+}
+```
+
+### 使用 `CompletableFuture`
+
+```java
+@Async
+public CompletableFuture<String> asyncMethod() {
+    return CompletableFuture.supplyAsync(() -> {
+        try {
+            // …
+            return "Success";
+        } catch (Exception e) {
+            throw new RuntimeException(e);
+        }
+    });
+}
+```
+
+---
+
+## 八、常见问题与排查
+
+| 问题 | 解决方案 |
+|------|----------|
+| `@Async` 方法未执行 | 检查是否开启 `@EnableAsync`，是否在不同类中调用 |
+| 线程池配置无效 | 确保 `@Bean` 配置正确，且 `@Async` 指定了正确的 bean 名称 |
+| 线程池资源耗尽 | 调整线程池大小和队列容量，增加 `queueCapacity` |
+| 异常未被捕获 | 使用 `Future` 或 `CompletableFuture` 返回结果，避免 `void` 返回 |
+
+---
+
+## 九、相关类与接口
+
+- `org.springframework.scheduling.annotation.Async`
+- `org.springframework.scheduling.annotation.EnableAsync`
+- `org.springframework.core.task.AsyncTaskExecutor`
+- `org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor`
+- `org.springframework.util.concurrent.AsyncTask`
+
+---
+
+## 十、最佳实践
+
+- 为不同业务场景配置不同的线程池
+- 使用 `CompletableFuture` 来处理异步任务中的返回结果和异常
+- 避免在异步方法中使用共享变量，防止线程安全问题
+- 控制线程池的大小和任务队列，防止资源浪费或阻塞
+- 结合 `@Scheduled` 注解实现定时异步任务