Java CompletableFuture delayedExecutor 怎样控制延迟任务

CompletableFuture.delayedExecutor 解决的是“什么时候允许任务开始提交”，不是“任务在哪个线程池里完成”。它返回一个延迟执行器：延迟到期后，再把任务交给默认执行器或你传入的基础 Executor。因此，想控制延迟任务，必须同时看触发时间、业务执行器和结果阶段。

官方文档：https://docs.oracle.com/en/java/javase/26/docs/api/java.base/java/util/concurrent/CompletableFuture.html

先分清延迟触发和真正执行

这个 API 有三个常用形态：只给延迟时间和单位、再给基础执行器、或者通过 delayedExecutor 返回的执行器提交一个 Runnable。延迟计时器到点后，任务才会被提交给基础执行器；基础执行器忙时，任务仍然要排队。

import java.util.concurrent.CompletableFuture;
import java.util.concurrent.TimeUnit;

CompletableFuture future = new CompletableFuture();
CompletableFuture.delayedExecutor(2, TimeUnit.SECONDS).execute(() -> {
    // 延迟到期后才提交这段工作，任务本身仍在后续执行器运行。
    future.complete("ready");
});

future.whenComplete((value, error) -> {
    // 统一观察完成或异常，避免只等待成功分支。
    if (error != null) {
        System.err.println(error.getMessage());
    }
});

上面的写法把结果 Future 和延迟提交分开了，适合展示边界；实际业务更常把它组合到 supplyAsync 中。这里的两秒只是示例配置，含义是“不早于两秒尝试提交”，不是严格的执行完成时间。

用延迟执行器组合一个可读的异步阶段

需要延迟后再发起工作时，可以把延迟执行器传给 supplyAsync。这样业务代码仍然返回一个 CompletableFuture，调用方可以继续接 thenApply、exceptionally 或 whenComplete。

import java.util.concurrent.CompletableFuture;
import java.util.concurrent.TimeUnit;

CompletableFuture loadWithDelay() {
    var delayed = CompletableFuture.delayedExecutor(500, TimeUnit.MILLISECONDS);
    return CompletableFuture.supplyAsync(() -> {
        // 延迟只控制这次 supplier 的提交时机，业务代码仍要快速失败。
        return queryRemoteCache();
    }, delayed).thenApply(value -> {
        // 成功阶段负责把远端值整理成调用方需要的格式。
        return value.trim();
    }).exceptionally(error -> {
        // 将异常转换为明确的降级值，避免调用方误把 null 当成功。
        return "cache-fallback";
    });
}

这个版本使用 JDK 的默认异步执行设施。它适合轻量、边界清晰的延迟任务；如果远端调用会占用连接、线程或较长时间，就应该显式传入隔离后的业务执行器，不要把共享公共资源当成无限容量。

传入基础 Executor，隔离业务线程池

delayedExecutor(delay, unit, executor) 的第三个参数是基础执行器。延迟到期后，任务会交给它，而不是让“延迟”本身变成一个可承载业务工作的线程池。可以用一个有界线程池来表达容量，并在服务关闭时释放资源。

import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.TimeUnit;

ExecutorService worker = Executors.newFixedThreadPool(4);
var delayed = CompletableFuture.delayedExecutor(1, TimeUnit.SECONDS, worker);

CompletableFuture task = CompletableFuture.supplyAsync(() -> {
    // 到期后由业务池执行，避免占用公共异步池。
    return loadReport();
}, delayed);

task.whenComplete((value, error) -> {
    // 生产代码应在应用生命周期结束时关闭自建执行器。
    if (error != null) {
        logFailure(error);
    }
});

线程池隔离解决的是执行资源边界，不会让延迟变得精确，也不会自动取消已经开始的 loadReport。如果任务需要重试，建议在每次重试之间重新构造延迟阶段，并设置总截止时间，而不是递归提交无限任务。

延迟不准、取消和异常怎样排查

取消有两个时间窗口：如果任务还在延迟等待阶段，取消更可能阻止后续完成；如果任务已经交给基础执行器，取消只能改变 Future 的完成状态，业务代码是否停止取决于它能否响应中断或自己的取消信号。不要把 cancel(true) 当成强制杀线程。

常见问题

delayedExecutor 能替代 ScheduledExecutorService 吗？

它更适合把一次延迟触发接入 CompletableFuture 链。需要周期调度、明确的任务句柄、复杂的调度策略或集中管理周期任务时，应比较 ScheduledExecutorService 等专用调度方案。

延迟一秒就一定一秒后执行吗？

不一定。延迟表示任务不早于该时间被提交；到期后的线程调度、基础执行器队列和系统负载都会影响实际开始时间。

怎样避免公共线程池被阻塞？

把阻塞工作交给容量明确的业务 Executor，并设置连接、调用和总链路截止时间；延迟执行器本身不能替你隔离阻塞资源。

排查 delayedExecutor 时，沿着“延迟触发器 → 基础 Executor → 业务任务 → Future 完成”四个边界看，通常比只盯着延迟数字更快找到问题。先明确资源归属，再决定是否需要重试、取消和降级。