Guava——并发（一）

并发

- 1、ListenableFuture
- 2、ListeningExecutorService
- - [2.1、核心 API 与创建方式](#2.1、核心 API 与创建方式)
  - 2.2、使用示例
  - 2.3、注意事项
- 3、Futures

com.google.common.util.concurrent 包拓展了 Java 标准库（java.util.concurrent）的并发能力，提供了基于回调的异步任务处理、令牌桶限流器、条件锁以及统一的服务生命周期管理。

API / 类名	说明
`ListenableFuture`	继承自 `Future`，允许在任务完成时自动触发非阻塞回调
`ListeningExecutorService`	装饰标准 `ExecutorService`，提交任务时直接返回 `ListenableFuture`
`Futures`	异步计算工具类，提供回调绑定、多 `Future` 聚合 (`allAsList`)、转换与异常捕捉
`RateLimiter`	基于令牌桶算法实现的单机限流器，支持平滑突发与预热限流
`Monitor`	替代 `ReentrantLock` + `Condition` 的高级锁，用逻辑谓词 `Guard` 简化条件等待
`Service` / `ServiceManager`	统一管理后台服务的启动、运行状态转换、健康检查与优雅停机

1、ListenableFuture

ListenableFuture 是 Guava（com.google.common.util.concurrent 包）对 JDK 标准 Future 的扩展，也是现代 Java 异步编程的重要基石（JDK 8 的 CompletableFuture 许多设计思想均借鉴于此）。

它最大的核心价值在于允许注册回调函数（Callbacks），当异步任务执行完毕时自动触发回调，从而彻底避免了传统 Future.get() 带来的阻塞等待问题。

1.1、核心组件与关键类

类 / 接口	作用与定位
`ListenableFuture<V>`	核心接口，继承自 `Future<V>`，新增 `addListener(Runnable, Executor)` 方法
`ListeningExecutorService`	装饰器接口，继承自 `ExecutorService`，`submit()` 提交任务时返回 `ListenableFuture`
`MoreExecutors`	静态工厂工具类，用于将 JDK 原生线程池包装为 `ListeningExecutorService`
`Futures`	最核心的静态工具类，提供绑定回调 (`addCallback`)、链式变换 (`transform`)、并行聚合 (`allAsList`) 等高阶操作
`FutureCallback<V>`	回调接口，包含 `onSuccess(V result)` 和 `onFailure(Throwable t)` 两个方法
`SettableFuture<V>`	可手动设置结果或异常的 `ListenableFuture` 实现类，常用于将回调式/事件驱动 API 包装为 `Future` 风格

1.2、使用示例

1. 基础用法：创建线程池与绑定回调（addCallback）

通过 Futures.addCallback 绑定回调，完全避免使用阻塞的 .get() 方法。

java 复制代码

import com.google.common.util.concurrent.*;
import java.util.concurrent.Executors;

public class ListenableFutureBasicDemo {
    public static void main(String[] args) {
        // 1. 将普通 JDK 线程池包装为 ListeningExecutorService
        ListeningExecutorService service = MoreExecutors.listeningDecorator(Executors.newFixedThreadPool(5));

        // 2. 提交异步任务，获取 ListenableFuture
        ListenableFuture<String> future = service.submit(() -> {
            // 模拟耗时任务
            Thread.sleep(1000);
            return "Task Success Result";
        });

        // 3. 注册回调函数（非阻塞）
        Futures.addCallback(future, new FutureCallback<String>() {
            @Override
            public void onSuccess(String result) {
                System.out.println("异步任务成功执行，结果: " + result);
            }

            @Override
            public void onFailure(Throwable t) {
                System.err.println("异步任务执行失败，异常: " + t.getMessage());
            }
        }, service); // 传入执行回调函数的 Executor

        try {
            Thread.sleep(10 * 1000);
        } catch (InterruptedException e) {
            e.printStackTrace();
        }

        // 资源关闭（实际项目中通常交由 Spring 容器或全局单例管理）
        service.shutdown();


    }
}

java 复制代码

异步任务成功执行，结果: Task Success Result

2. 结果转换：同步与异步变换（transform & transformAsync）

类似于 Java 8 Stream / Optional 中的 map 与 flatMap：

transform：同步变换（传入 Function<I, O>），用于对前一步的结果做轻量转换。
transformAsync：异步变换（传入 AsyncFunction<I, O>），用于需要发起第二次异步调用的场景（如连续两次 RPC）。

java 复制代码

import com.google.common.util.concurrent.*;
import java.util.concurrent.Executors;

public class ListenableFutureTransformDemo {
    public static void main(String[] args) {
        ListeningExecutorService service = MoreExecutors.listeningDecorator(Executors.newFixedThreadPool(2));

        // 任务 1：异步获取用户 ID
        ListenableFuture<String> userIdFuture = service.submit(() -> "User_1001");

        // 1. transform（同步转换）：将字符串转为大写
        ListenableFuture<String> upperUserIdFuture = Futures.transform(
                userIdFuture,
                userId -> userId.toUpperCase(),
                service
        );

        // 2. transformAsync（异步转换）：拿到 userId 后，发起第二次异步查询用户详情
        ListenableFuture<String> userDetailFuture = Futures.transformAsync(
                userIdFuture,
                userId -> service.submit(() -> "Details for " + userId + " (Age: 25)"),
                service
        );

        // 绑定最终回调
        Futures.addCallback(userDetailFuture, new FutureCallback<String>() {
            @Override
            public void onSuccess(String result) {
                System.out.println("链式调用最终结果: " + result);
            }

            @Override
            public void onFailure(Throwable t) {
                t.printStackTrace();
            }
        }, service);

        service.shutdown();
    }
}

java 复制代码

链式调用最终结果: Details for User_1001 (Age: 25)

3. 并行聚合与异常降级保底（allAsList & catching）

allAsList：并行等待多个 Future 完成，合并为一个 ListenableFuture<List>（若其中任意一个任务失败，整体直接失败）。
successfulAsList：与 allAsList 类似，但某个任务失败时不会抛出异常，而是在列表中对应的位置设为 null。
catching：为某个可能失败的 Future 提供降级逻辑（Fallback）。

java 复制代码

import com.google.common.util.concurrent.*;
import java.util.Arrays;
import java.util.List;
import java.util.concurrent.Executors;

public class ListenableFutureCombineDemo {
    public static void main(String[] args) {
        ListeningExecutorService service = MoreExecutors.listeningDecorator(Executors.newFixedThreadPool(5));

        ListenableFuture<String> task1 = service.submit(() -> "服务 A 数据");
        ListenableFuture<String> task2 = service.submit(() -> "服务 B 数据");

        // 模拟一个发生异常的异步任务，并添加降级保底处理 (catching)
        ListenableFuture<String> task3WithException = service.submit(() -> {
            if (true) throw new RuntimeException("服务 C 挂了");
            return "服务 C 数据";
        });

        // 降级处理：捕获 RuntimeException，返回保底默认值
        ListenableFuture<String> task3Fallback = Futures.catching(
                task3WithException,
                RuntimeException.class,
                throwable -> "服务 C 降级保底数据",
                service
        );

        // 并行等待所有任务完成并合并结果
        ListenableFuture<List<String>> combinedFuture = Futures.allAsList(
                Arrays.asList(task1, task2, task3Fallback)
        );

        Futures.addCallback(combinedFuture, new FutureCallback<List<String>>() {
            @Override
            public void onSuccess(List<String> results) {
                System.out.println("合并后的全部数据: " + results);
                // 输出: [服务 A 数据, 服务 B 数据, 服务 C 降级保底数据]
            }

            @Override
            public void onFailure(Throwable t) {
                System.err.println("聚合失败: " + t.getMessage());
            }
        }, service);

        service.shutdown();
    }
}

java 复制代码

合并后的全部数据: [服务 A 数据, 服务 B 数据, 服务 C 降级保底数据]

4. 可控赋值实现（SettableFuture）

SettableFuture 允许开发者在任意时刻手动调用 .set(value) 或 .setException(throwable) 来显式完成 Future。非常适合用于将传统第三方回调式/事件监听式 API 包装转换为 ListenableFuture。

java 复制代码

import com.google.common.util.concurrent.*;

public class SettableFutureDemo {
    public static void main(String[] args) {
        // 创建一个手动控制状态的 Future
        SettableFuture<String> settableFuture = SettableFuture.create();

        // 模拟第三方异步回调/消息队列收到消息
        new Thread(() -> {
            try {
                Thread.sleep(500);
                // 手动填充结果，触发外部绑定该 Future 的回调
                settableFuture.set("第三方 SDK 异步事件推送成功");
            } catch (Exception e) {
                settableFuture.setException(e);
            }
        }).start();

        // 绑定回调
        Futures.addCallback(settableFuture, new FutureCallback<String>() {
            @Override
            public void onSuccess(String result) {
                System.out.println("收到通知: " + result);
            }

            @Override
            public void onFailure(Throwable t) {
                t.printStackTrace();
            }
        }, MoreExecutors.directExecutor()); // directExecutor 表示在当前触发线程直接运行回调
    }
}

java 复制代码

收到通知: 第三方 SDK 异步事件推送成功

1.3、注意事项

与 JDK 原生 CompletableFuture 对比

特性 / 维度	Guava ListenableFuture	JDK 8+ CompletableFuture
引入来源	Guava 第三方库（历史悠久、极其稳定）	JDK 8+ 标准库
API 风格	接口与静态工具类配合（如 `Futures.addCallback(...)`）	富接口模式（链式调用，提供 50+ 个方法）
生态兼容性	广泛应用于 gRPC、Spring 4/5 异步组件、HBase 等中间件底层	现代 JDK 开发的标准选择

总结建议：

如果项目运行在 JDK 8 及以上且为新开发项目，建议直接使用 JDK 原生的 CompletableFuture；
如果项目深沉淀于 Guava 技术栈，或在使用 gRPC、HBase、Spring 等深度集成 ListenableFuture 的框架，它依然是高稳定、零负担的非阻塞异步编程利器。

2、ListeningExecutorService

Guava 中的 ListeningExecutorService（位于 com.google.common.util.concurrent 包）是专门用于替代 JDK 标准 ExecutorService 的扩展接口。

它的核心作用是：重写了 submit() 系列方法，使其不再返回传统的阻塞型 java.util.concurrent.Future，而是返回 Guava 的非阻塞 ListenableFuture。这使得提交给线程池的任务天然具备了注册异步回调（Callback）和响应式链式调用的能力。

2.1、核心 API 与创建方式

1. 核心 API 方法一览

方法签名	返回类型	说明
`submit(Callable<T> task)`	`ListenableFuture<T>`	提交一个有返回值的任务，返回 `ListenableFuture`
`submit(Runnable task)`	`ListenableFuture<?>`	提交一个无返回值的任务，返回 `ListenableFuture`
`submit(Runnable task, T result)`	`ListenableFuture<T>`	提交任务并在完成后返回预设的 `result`
`invokeAll(Collection tasks)`	`List<ListenableFuture<T>>`	批量提交任务并返回包含所有结果的 `ListenableFuture` 列表

注意：ListeningExecutorService 完全继承了 JDK ExecutorService 的所有生命周期管理 API（如 shutdown(), isShutdown(), awaitTermination() 等）。

2. 如何创建 ListeningExecutorService？

Guava 提供了 MoreExecutors 工具类，可以将 JDK 的任何线程池（如 Executors.newFixedThreadPool 或自定义 ThreadPoolExecutor）快速装饰（Decorate）为 ListeningExecutorService：

java 复制代码

import com.google.common.util.concurrent.ListeningExecutorService;
import com.google.common.util.concurrent.MoreExecutors;
import java.util.concurrent.Executors;
import java.util.concurrent.ThreadPoolExecutor;

// 1. 包装 Executors 工具类创建的线程池
ListeningExecutorService service1 = MoreExecutors.listeningDecorator(
    Executors.newFixedThreadPool(10)
);

// 2. 包装自定义配置的 ThreadPoolExecutor（生产环境强烈推荐这种方式，避免 OOM）
ThreadPoolExecutor customPool = new ThreadPoolExecutor(/* 参数配置 */);
ListeningExecutorService service2 = MoreExecutors.listeningDecorator(customPool);

2.2、使用示例

1. 基础提交任务与绑定异步回调（submit + addCallback）

这是 ListeningExecutorService 最基础也是最常用的模式，无需使用阻塞的 .get() 方法。

java 复制代码

import com.google.common.util.concurrent.*;
import java.util.concurrent.Executors;

public class ListeningExecutorBasicDemo {
    public static void main(String[] args) {
        // 1. 创建 ListeningExecutorService
        ListeningExecutorService service = MoreExecutors.listeningDecorator(
            Executors.newFixedThreadPool(5)
        );

        // 2. 提交 Callable 任务，直接返回 ListenableFuture
        ListenableFuture<String> future = service.submit(() -> {
            System.out.println("Executing task in thread: " + Thread.currentThread().getName());
            Thread.sleep(1000); // 模拟耗时业务
            return "Task completed successfully!";
        });

        // 3. 为 Future 注册异步回调
        Futures.addCallback(future, new FutureCallback<String>() {
            @Override
            public void onSuccess(String result) {
                System.out.println("【成功回调】收到处理结果: " + result);
            }

            @Override
            public void onFailure(Throwable t) {
                System.err.println("【失败回调】捕获到异常: " + t.getMessage());
            }
        }, service); // 指定执行回调函数的线程池

        // 4. 关闭线程池
        service.shutdown();
    }
}

2. 批量提交任务（invokeAll）

与 JDK 的 invokeAll 区别在于，ListeningExecutorService 返回的列表中每一个元素都是可添加回调的 ListenableFuture。

java 复制代码

import com.google.common.util.concurrent.*;
import java.util.Arrays;
import java.util.List;
import java.util.concurrent.Callable;
import java.util.concurrent.Executors;

public class ListeningExecutorInvokeAllDemo {
    public static void main(String[] args) throws InterruptedException {
        ListeningExecutorService service = MoreExecutors.listeningDecorator(
            Executors.newFixedThreadPool(3)
        );

        List<Callable<Integer>> tasks = Arrays.asList(
            () -> 10,
            () -> 20,
            () -> 30
        );

        // 批量提交任务
        List<ListenableFuture<Integer>> futures = service.invokeAll(tasks);

        // 将所有 ListenableFuture 聚合为一个单一的 ListenableFuture<List<Integer>>
        ListenableFuture<List<Integer>> combinedFuture = Futures.allAsList(futures);

        // 绑定一次回调，等待所有批量任务完成后统一处理
        Futures.addCallback(combinedFuture, new FutureCallback<List<Integer>>() {
            @Override
            public void onSuccess(List<Integer> results) {
                int sum = results.stream().mapToInt(Integer::intValue).sum();
                System.out.println("批量任务全部完成，汇总和为: " + sum); // 60
            }

            @Override
            public void onFailure(Throwable t) {
                t.printStackTrace();
            }
        }, service);

        service.shutdown();
    }
}

3. 支持定时/周期性任务（ListeningScheduledExecutorService）

如果你需要执行定时或周期性任务，Guava 提供了专门的子接口 ListeningScheduledExecutorService：

java 复制代码

import com.google.common.util.concurrent.*;
import java.util.concurrent.Executors;
import java.util.concurrent.TimeUnit;

public class ListeningScheduledDemo {
    public static void main(String[] args) {
        // 包装 ScheduledExecutorService
        ListeningScheduledExecutorService scheduledService = MoreExecutors.listeningDecorator(
            Executors.newScheduledThreadPool(2)
        );

        // 延迟 2 秒后提交任务，返回 ListenableScheduledFuture
        ListenableScheduledFuture<String> scheduledFuture = scheduledService.schedule(
            () -> "Scheduled Task Done",
            2,
            TimeUnit.SECONDS
        );

        Futures.addCallback(scheduledFuture, new FutureCallback<String>() {
            @Override
            public void onSuccess(String result) {
                System.out.println("定时任务执行完成: " + result);
            }

            @Override
            public void onFailure(Throwable t) {
                t.printStackTrace();
            }
        }, scheduledService);

        scheduledService.shutdown();
    }
}

2.3、注意事项

在使用 ListeningExecutorService 时，经常配合 MoreExecutors 中的其他工具方法：

MoreExecutors.directExecutor()
- 作用：返回一个在当前调用线程中同步直接运行任务的 Executor，避免额外的线程上下文切换开销。
- 适用场景：当回调函数极其轻量（例如仅仅是赋值、记录一行日志或修改内存中的轻量变量）时，可以直接传给 Futures.addCallback(future, callback, MoreExecutors.directExecutor())
MoreExecutors.shutdownAndAwaitTermination(ExecutorService service, long timeout, TimeUnit unit)
- 作用：优雅关闭线程池。会先调用 shutdown()，等待一段时间；若未停止则调用 shutdownNow()，再等待一段时间，确保资源安全释放。

最佳实践与注意事项

避免使用 Executors 默认无界队列
在生产环境中，不要使用 MoreExecutors.listeningDecorator(Executors.newFixedThreadPool(n))，因为默认的无界队列可能导致内存溢出（OOM）。建议使用自定义的 ThreadPoolExecutor 指定容量上限和拒绝策略，再用 MoreExecutors.listeningDecorator 进行包装。
回调线程池（Callback Executor）的选择
在调用 Futures.addCallback(future, callback, executor) 时：
- 避免将耗时的 IO 或 CPU 密集型逻辑放在 directExecutor() 中执行，这会直接阻塞触发回调的那个线程。
- 可以将处理业务逻辑的专用线程池传入 addCallback。
替代与演进
- 如果是在 JDK 8+ 的全新独立应用中，CompletableFuture + JDK 原生 ExecutorService 也是常见的选择。
- 如果技术栈深沉淀于 Guava、RPC 框架（如 gRPC）、HBase 或 Spring 异步组件，ListeningExecutorService 依然是性能表现极佳、线程协同非常清晰的标准组件。

3、Futures

Guava 中的 Futures（位于 com.google.common.util.concurrent 包）是专门配合 ListenableFuture 使用的核心静态工具类。

如果说 ListenableFuture 是异步任务的载体，那么 Futures 就是对这些异步任务进行绑定回调、链式转换、组合聚合、异常保底降级以及同步转换的"调度中心"与"组合器"。

3.1、核心API

分类	核心 API 方法	说明
异步回调	`addCallback`	为 `ListenableFuture` 注册非阻塞回调（成功/失败）
结果转换	`transform`, `transformAsync`	同步转换（Map）/ 异步转换（FlatMap/链式 RPC 调用）
并行聚合	`allAsList`, `successfulAsList`, `whenAllComplete`, `whenAllSucceed`	组合多个 Future：全成功合并、忽略失败合并或自定义阶段协同
异常处理	`catching`, `catchingAsync`	捕获指定异常并提供同步/异步降级保底策略（Fallback）
静态构建	`immediateFuture`, `immediateFailedFuture`	快速创建一个已完成（成功/失败）的预设 `ListenableFuture`
阻塞等待与提取	`getDone`, `getUnchecked`	从已完成的 `Future` 中安全或免检提取结果

3.2、使用示例

1. 异步回调注册（addCallback）

java 复制代码

import com.google.common.util.concurrent.*;
import java.util.concurrent.Executors;

public class FuturesCallbackDemo {
    public static void main(String[] args) {
        ListeningExecutorService service = MoreExecutors.listeningDecorator(Executors.newFixedThreadPool(2));

        ListenableFuture<String> future = service.submit(() -> {
            Thread.sleep(500);
            return "Data loaded from DB";
        });

        // 注册非阻塞回调
        Futures.addCallback(future, new FutureCallback<String>() {
            @Override
            public void onSuccess(String result) {
                System.out.println("成功收到结果: " + result);
            }

            @Override
            public void onFailure(Throwable t) {
                System.err.println("处理失败: " + t.getMessage());
            }
        }, service); // 传入执行回调逻辑的线程池

        service.shutdown();
    }
}

2. 结果转换：同步与异步变换（transform & transformAsync）

transform：同步转换。拿到前一步的结果后，进行轻量级的同步计算或数据格式转换（传入 Function<I, O>）。
transformAsync：异步转换。拿到前一步的结果后，发起第二次异步调用（如查询用户 ID 后再异步查询订单，传入 AsyncFunction<I, O>）。

java 复制代码

import com.google.common.util.concurrent.*;
import java.util.concurrent.Executors;

public class FuturesTransformDemo {
    public static void main(String[] args) {
        ListeningExecutorService service = MoreExecutors.listeningDecorator(Executors.newFixedThreadPool(2));

        // 步骤 1: 异步获取原始订单 Json
        ListenableFuture<String> orderJsonFuture = service.submit(() -> "{\"orderId\": \"ORD_999\", \"amount\": 100}");

        // 场景 A: transform (同步转换) - 解析 Json 为订单 ID 字符串
        ListenableFuture<String> orderIdFuture = Futures.transform(
                orderJsonFuture,
                json -> json.replaceAll(".*\"orderId\": \"(\\w+)\".*", "$1"),
                service
        );

        // 场景 B: transformAsync (异步转换) - 拿着提取出的 OrderId，再去异步调用支付服务
        ListenableFuture<Boolean> paymentStatusFuture = Futures.transformAsync(
                orderIdFuture,
                orderId -> service.submit(() -> {
                    System.out.println("正在为订单 " + orderId + " 发起远程支付检查...");
                    return true; // 支付成功
                }),
                service
        );

        // 查看最终结果
        Futures.addCallback(paymentStatusFuture, new FutureCallback<Boolean>() {
            @Override
            public void onSuccess(Boolean isPaid) {
                System.out.println("支付状态: " + isPaid);
            }

            @Override
            public void onFailure(Throwable t) {
                t.printStackTrace();
            }
        }, MoreExecutors.directExecutor());

        service.shutdown();
    }
}

3. 多任务并行聚合（allAsList 与 successfulAsList）

allAsList：严格聚合。并行等待所有 Future 完成，任何一个失败则整体 ListenableFuture 触发 onFailure。
successfulAsList：容错聚合。并行等待所有 Future 完成，如果有任务失败或取消，该位置在返回的 List 中记为 null，不会触发整体失败。

java 复制代码

import com.google.common.util.concurrent.*;
import java.util.Arrays;
import java.util.List;
import java.util.concurrent.Executors;

public class FuturesCombineDemo {
    public static void main(String[] args) {
        ListeningExecutorService service = MoreExecutors.listeningDecorator(Executors.newFixedThreadPool(3));

        ListenableFuture<String> task1 = service.submit(() -> "服务 A 正常");
        ListenableFuture<String> task2 = service.submit(() -> {
            throw new RuntimeException("服务 B 宕机");
        });
        ListenableFuture<String> task3 = service.submit(() -> "服务 C 正常");

        // 1. successfulAsList 模式（容错）
        ListenableFuture<List<String>> tolerantFuture = Futures.successfulAsList(Arrays.asList(task1, task2, task3));

        Futures.addCallback(tolerantFuture, new FutureCallback<List<String>>() {
            @Override
            public void onSuccess(List<String> results) {
                // 结果输出: [服务 A 正常, null, 服务 C 正常]
                System.out.println("容错聚合结果: " + results);
            }

            @Override
            public void onFailure(Throwable t) {
                System.err.println("整体失败（容错模式不会触发到这里）");
            }
        }, service);

        service.shutdown();
    }
}

4. 异常处理与保底降级（catching & catchingAsync）

类似于 Java 异常捕捉的 try-catch 块，为指定的异常类型提供兜底默认值（Fallback）。

java 复制代码

import com.google.common.util.concurrent.*;
import java.util.concurrent.Executors;

public class FuturesCatchingDemo {
    public static void main(String[] args) {
        ListeningExecutorService service = MoreExecutors.listeningDecorator(Executors.newFixedThreadPool(2));

        ListenableFuture<String> taskWithError = service.submit(() -> {
            if (true) throw new IllegalArgumentException("参数不合法!");
            return "正常数据";
        });

        // 捕获特定异常并进行降级兜底处理 (catching)
        ListenableFuture<String> fallbackFuture = Futures.catching(
                taskWithError,
                IllegalArgumentException.class, // 捕获的异常类
                e -> "降级保底默认数据: " + e.getMessage(), // 兜底逻辑
                service
        );

        Futures.addCallback(fallbackFuture, new FutureCallback<String>() {
            @Override
            public void onSuccess(String result) {
                System.out.println("最终获取结果: " + result); 
                // 输出: 最终获取结果: 降级保底默认数据: 参数不合法!
            }

            @Override
            public void onFailure(Throwable t) {
                System.err.println("未被捕捉到的其他严重异常");
            }
        }, service);

        service.shutdown();
    }
}

5. 快速构建与安全提取（immediateFuture & getDone）

immediateFuture(V value)：快速封装已有的同步数据，返回一个已成功完成的 ListenableFuture（非常适合在接口需要返回 Future 场景下直接返回缓存/预判值）。
getDone(Future<V> future)：从已知已经完成的 Future 中安全取出结果。如果任务尚未完成，会直接抛出 IllegalStateException，而不是像 .get() 那样陷入线程阻塞。

java 复制代码

import com.google.common.util.concurrent.Futures;
import com.google.common.util.concurrent.ListenableFuture;
import java.util.concurrent.ExecutionException;

public class FuturesUtilDemo {
    public static void main(String[] args) throws ExecutionException {
        // 1. 创建即时成功的 Future
        ListenableFuture<String> cachedFuture = Futures.immediateFuture("从 Redis 缓存中获取的数据");

        // 2. 对于确定已经完成的 Future，直接使用 getDone 提取结果（无阻塞开销）
        if (cachedFuture.isDone()) {
            String result = Futures.getDone(cachedFuture);
            System.out.println("快速提取: " + result);
        }

        // 3. 创建即时失败的 Future
        ListenableFuture<String> failedFuture = Futures.immediateFailedFuture(new RuntimeException("校验不通过"));
    }
}

3.3、注意事项

链式调用传参控制：
在调用 transform、transformAsync、catching 和 addCallback 时，都需要传入一个 Executor。如果任务非常轻量（如简单的对象属性赋值），可以传入 MoreExecutors.directExecutor() 以减少线程上下文切换；如果是耗时的 IO/计算操作，务必传入专门的线程池。
组合工具选择：
- 需要"全有或全无"的强一致性聚合，选用 Futures.allAsList；
- 需要"允许部分服务宕机/超时"的微服务网关聚合，选用 Futures.successfulAsList；
- 需要对复杂的多 Future 相互协同（例如： A A A 和 B B B 都完成后再触发 C C C），可以使用 Futures.whenAllSucceed / Futures.whenAllComplete 构造器链。