当前位置：首页 > news >正文

踩坑了！Spring Boot 异步调用 CompletableFuture 的坑你踩过几个

news 2026/3/26 17:38:40

踩坑了！Spring Boot 异步调用 CompletableFuture 的坑你踩过几个

说实话，我第一次用 CompletableFuture 的时候，觉得这玩意儿真香异步并行、线程池管理，比原来的 Future 好用太多了。结果上线后，BUG 一个接一个，内存飙升、线程阻塞、异常丢失…踩了整整两天的坑，才把问题全部排查清楚。今天就把这些血泪教训分享出来，希望能帮大家少走弯路。

坑一：默认线程池 - 异步调用变成同步阻塞

我一开始这么写：

@ServicepublicclassOrderService{publicOrderDTOgetOrderDetail(LongorderId){// 异步查询用户信息和订单信息CompletableFuture<UserDTO>userFuture=CompletableFuture.supplyAsync(()->userMapper.findById(orderId));CompletableFuture<OrderDTO>orderFuture=CompletableFuture.supplyAsync(()->orderMapper.findById(orderId));// 等待结果OrderDTOorder=orderFuture.join();UserDTOuser=userFuture.join();// 组装返回order.setUser(user);returnorder;}}

看起来没问题，两个查询并行执行，性能应该不错。结果压测的时候，接口响应时间越来越长，最后直接超时。

原因分析

CompletableFuture.supplyAsync()默认使用ForkJoinPool.commonPool()，这个线程池的线程数是CPU 核心数 - 1。在 Spring Boot 应用中，很多组件（Tomcat、数据库连接池等）都会抢占这个线程池，一旦线程池耗尽，异步任务就会排队等待，变成实际上的同步执行。

解决方案

自定义线程池，根据业务场景配置合理的线程数：

@ConfigurationpublicclassThreadPoolConfig{@Bean("asyncExecutor")publicExecutorasyncExecutor(){ThreadPoolTaskExecutorexecutor=newThreadPoolTaskExecutor();// 核心线程数executor.setCorePoolSize(10);// 最大线程数executor.setMaxPoolSize(20);// 队列容量executor.setQueueCapacity(100);// 线程名前缀executor.setThreadNamePrefix("async-");// 拒绝策略executor.setRejectedExecutionHandler(newThreadPoolExecutor.CallerRunsPolicy());executor.initialize();returnexecutor;}}

使用时指定线程池：

CompletableFuture<UserDTO>userFuture=CompletableFuture.supplyAsync(()->userMapper.findById(orderId),asyncExecutor);

最佳实践：为不同类型的异步任务配置不同的线程池，避免相互影响。比如 IO 密集型任务可以设置更大的线程数，CPU 密集型任务则需要控制线程数。

坑二：异常丢失 - 异步任务抛异常却没人管

遇到这种情况：

@ServicepublicclassPaymentService{publicvoidprocessPayment(OrderDTOorder){CompletableFuture.runAsync(()->{// 调用第三方支付接口paymentGateway.pay(order);// 更新订单状态orderMapper.updateStatus(order.getId(),"PAID");});// 直接返回成功log.info("支付处理已提交");}}

问题是：如果第三方支付接口抛出异常，orderMapper.updateStatus()不会执行，订单状态永远是"待支付"，但用户却收到了"成功"的提示。钱没了，状态没改，这可就是严重的事故了。

原因分析

CompletableFuture.runAsync()没有返回值，默认也不会处理异常。即使加了exceptionally()，如果忘记加，异常就会被吞掉，悄无声息。

解决方案

一定要处理异常，至少要记录日志：

CompletableFuture.runAsync(()->{paymentGateway.pay(order);orderMapper.updateStatus(order.getId(),"PAID");},asyncExecutor).exceptionally(ex->{// 记录异常日志log.error("支付处理失败，订单ID: {}, 异常: {}",order.getId(),ex.getMessage(),ex);// 发送告警通知alertService.sendAlert("支付异常",order.getId(),ex);// 更新订单状态为失败orderMapper.updateStatus(order.getId(),"PAY_FAILED");returnnull;});

或者使用handle()方法，可以处理正常结果和异常：

CompletableFuture.runAsync(()->{paymentGateway.pay(order);orderMapper.updateStatus(order.getId(),"PAID");},asyncExecutor).handle((result,ex)->{if(ex!=null){log.error("支付处理失败",ex);orderMapper.updateStatus(order.getId(),"PAY_FAILED");}returnresult;});

重要提醒：如果是核心业务流程，异步任务失败后一定要有补偿机制，比如重试、人工介入、告警通知等。

坑三：线程上下文丢失 - @Async 和 ThreadLocal 的坑

遇到这种问题：

@ServicepublicclassUserService{privatestaticfinalThreadLocal<String>TRACE_ID=newThreadLocal<>();publicvoidcreateUser(UserDTOuser){TRACE_ID.set(generateTraceId());CompletableFuture.runAsync(()->{// 在异步线程中获取 traceIdStringtraceId=TRACE_ID.get();// null!log.info("创建用户，traceId: {}",traceId);userMapper.insert(user);});}}

在主线程设置的TRACE_ID，在异步线程中获取不到，导致日志追踪链路中断，排查问题的时候根本找不到完整的调用链。

原因分析

CompletableFuture.supplyAsync()会使用新的线程去执行任务，新线程和主线程不是同一个线程，ThreadLocal的数据无法共享。

解决方案

使用阿里巴巴开源的TransmittableThreadLocal：

importcom.alibaba.ttl.TransmittableThreadLocal;importcom.alibaba.ttl.TtlRunnable;@ServicepublicclassUserService{privatestaticfinalTransmittableThreadLocal<String>TRACE_ID=newTransmittableThreadLocal<>();publicvoidcreateUser(UserDTOuser){TRACE_ID.set(generateTraceId());// 使用 TtlRunnable 包装Runnabletask=TtlRunnable.get(()->{StringtraceId=TRACE_ID.get();// 可以获取到！log.info("创建用户，traceId: {}",traceId);userMapper.insert(user);});CompletableFuture.runAsync(task,asyncExecutor);}}

如果使用 Spring 的@Async注解，TTL 也提供了自动支持的代理：

@ConfigurationpublicclassAsyncConfigimplementsAsyncConfigurer{@OverridepublicExecutorgetAsyncExecutor(){ThreadPoolTaskExecutorexecutor=newThreadPoolTaskExecutor();executor.setCorePoolSize(10);executor.setMaxPoolSize(20);executor.setQueueCapacity(100);executor.setThreadNamePrefix("async-");executor.initialize();// 使用 TtlExecutorWrapper 包装returnTtlExecutorWrapper.get(executor);}}

这样无论是手动创建的CompletableFuture还是@Async注解，ThreadLocal 都能正常传递。

坑四：CompletableFuture 组合调用 - allOf 导致的资源泄露

这种写法有潜在问题：

publicvoidprocessBatchOrders(List<Long>orderIds){List<CompletableFuture<Void>>futures=orderIds.stream().map(id->CompletableFuture.runAsync(()->{processOrder(id);},asyncExecutor)).collect(Collectors.toList());// 等待所有任务完成CompletableFuture.allOf(futures.toArray(newCompletableFuture[0])).join();log.info("批量处理完成");}

在高频调用场景下，如果processOrder()抛出异常，allOf.join()会抛出异常。但关键是：如果某些任务已经创建但还没开始执行，线程池中的任务可能会被取消，导致资源未正确释放。

原因分析

CompletableFuture.allOf()的行为是：如果任意一个任务抛出异常，allOf会立即抛出异常，但其他正在执行的任务会继续运行（不会取消）。如果任务中有占用资源（数据库连接、文件句柄、网络连接等），可能会导致资源泄露。

解决方案

使用orTimeout()防止无限等待：

CompletableFuture.allOf(futures.toArray(newCompletableFuture[0])).orTimeout(30,TimeUnit.SECONDS).join();

使用whenComplete确保资源释放：

List<CompletableFuture<Void>>futures=orderIds.stream().map(id->CompletableFuture.runAsync(()->{try{processOrder(id);}finally{// 确保资源释放releaseResources(id);}},asyncExecutor)).collect(Collectors.toList());CompletableFuture.allOf(futures.toArray(newCompletableFuture[0])).whenComplete((result,ex)->{if(ex!=null){log.error("批量处理出现异常",ex);}}).join();

使用信号量控制并发数：

Semaphoresemaphore=newSemaphore(10);// 最多10个并发List<CompletableFuture<Void>>futures=orderIds.stream().map(id->CompletableFuture.runAsync(()->{try{semaphore.acquire();processOrder(id);}catch(InterruptedExceptione){Thread.currentThread().interrupt();}finally{semaphore.release();}},asyncExecutor)).collect(Collectors.toList());