Java CompletableFuture 超时处理实战：orTimeout 和兜底结果怎么选

Java 后端做接口聚合时，经常会把多个下游查询并行起来：订单主信息、库存状态、优惠提示、推荐内容一起查。并行能提升速度，但也带来一个问题：只要某个非核心任务很慢，整个接口就可能被拖住。

CompletableFuture 提供了几种实用的超时处理方式。本文用一个订单页案例，讲清楚 orTimeout 和 completeOnTimeout 的区别，以及如何写异常兜底和耗时日志。

摘要

本文会先搭建一个异步聚合场景，再分别演示失败型超时、默认值型超时、异常统一处理和接口总耗时控制。你可以把示例迁移到商品详情、订单详情、用户首页、报表聚合等场景中。

适合人群

适合已经会写 Java 基础代码、正在使用 Spring Boot 或普通 Java 服务做接口聚合的开发者。你需要了解 CompletableFuture、lambda 表达式和基础异常处理。

目录

1. 为什么异步聚合也需要超时
2. 准备一个模拟慢任务
3. orTimeout：超时后让任务失败
4. completeOnTimeout：超时后返回兜底值
5. 异常兜底和日志怎么写
6. 多个任务聚合的推荐写法
7. 常见坑和总结

一、为什么异步聚合也需要超时

假设订单页需要三个结果：

• 订单主信息：核心结果，必须返回。
• 优惠提示：非核心结果，慢了可以隐藏。
• 推荐商品：非核心结果，慢了可以返回空列表。

如果所有异步任务都一直等待，接口仍然会被最慢的任务拖住。更合理的做法是：核心任务失败就返回错误，非核心任务超时就给默认值。

二、准备一个模拟慢任务

为了演示，我们先写几个模拟方法。实际项目里可以替换成数据库查询、HTTP 调用或 RPC 调用。

import java.time.Duration;
import java.util.List;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.TimeUnit;

public class OrderPageDemo {
    record OrderInfo(String id, String status) {}
    record CouponTip(String text) {}

    static OrderInfo loadOrder(String orderId) {
        sleep(120);
        return new OrderInfo(orderId, "PAID");
    }

    static CouponTip loadCouponTip() {
        sleep(1500);
        return new CouponTip("满 100 减 10");
    }

    static List loadRecommendItems() {
        sleep(900);
        return List.of("book", "keyboard");
    }

    static void sleep(long millis) {
        try {
            Thread.sleep(millis);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            throw new IllegalStateException("interrupted", e);
        }
    }
}

这里故意让优惠提示变慢，后面用它观察超时效果。

三、orTimeout：超时后让任务失败

orTimeout 的语义是：如果任务在指定时间内没有完成，就让这个 CompletableFuture 以超时异常完成。它适合核心任务，因为核心任务不能随便给假数据。

CompletableFuture orderFuture =
    CompletableFuture.supplyAsync(() -> loadOrder("A1001"))
        .orTimeout(500, TimeUnit.MILLISECONDS);

OrderInfo order = orderFuture.join();

如果订单主信息超过 500 毫秒还没回来，这段代码会走异常路径。接口可以返回明确错误，或者交给上层统一异常处理。

四、completeOnTimeout：超时后返回兜底值

completeOnTimeout 的语义是：如果任务超时，就使用你给定的默认值完成。它适合非核心结果，例如优惠提示、推荐内容、装饰性统计。

CompletableFuture couponFuture =
    CompletableFuture.supplyAsync(OrderPageDemo::loadCouponTip)
        .completeOnTimeout(new CouponTip("暂无优惠提示"), 300, TimeUnit.MILLISECONDS);

CouponTip coupon = couponFuture.join();

这样优惠服务慢了不会拖住整个订单页。用户仍然能看到订单主信息，只是优惠提示用了默认文案。

五、异常兜底和日志怎么写

非核心任务除了超时，还可能出现普通异常。可以用 exceptionally 做兜底，并记录耗时。

static CompletableFuture> recommendFuture() {
    long start = System.nanoTime();
    return CompletableFuture.supplyAsync(OrderPageDemo::loadRecommendItems)
        .completeOnTimeout(List.of(), 400, TimeUnit.MILLISECONDS)
        .exceptionally(err -> {
            long costMs = Duration.ofNanos(System.nanoTime() - start).toMillis();
            System.out.println("recommend fallback, costMs=" + costMs + ", err=" + err.getClass().getSimpleName());
            return List.of();
        });
}

日志里至少建议记录：任务名、耗时、超时时间、是否走兜底。不要只打印“失败了”，否则排查时很难判断是哪个下游慢。

六、多个任务聚合的推荐写法

下面把三个任务合在一起。订单主信息使用失败型超时，优惠和推荐使用默认值型超时。

record OrderPage(OrderInfo order, CouponTip coupon, List recommends) {}

static OrderPage buildOrderPage(String orderId) {
    CompletableFuture orderFuture =
        CompletableFuture.supplyAsync(() -> loadOrder(orderId))
            .orTimeout(500, TimeUnit.MILLISECONDS);

    CompletableFuture couponFuture =
        CompletableFuture.supplyAsync(OrderPageDemo::loadCouponTip)
            .completeOnTimeout(new CouponTip("暂无优惠提示"), 300, TimeUnit.MILLISECONDS)
            .exceptionally(err -> new CouponTip("暂无优惠提示"));

    CompletableFuture> recommendFuture =
        CompletableFuture.supplyAsync(OrderPageDemo::loadRecommendItems)
            .completeOnTimeout(List.of(), 400, TimeUnit.MILLISECONDS)
            .exceptionally(err -> List.of());

    return new OrderPage(
        orderFuture.join(),
        couponFuture.join(),
        recommendFuture.join()
    );
}

这段代码的关键不是“全都异步”，而是每个任务都有明确策略：核心结果失败就暴露问题，非核心结果慢了就兜底。

七、常见坑和总结

1. 所有任务用同一个超时时间

核心任务和非核心任务的超时策略不应该完全一样。订单主信息可以等得久一点，推荐内容可以更快降级。

2. 只写超时，不记录任务名

线上看到超时异常时，如果没有任务名和耗时，很难知道是优惠服务慢，还是推荐服务慢。建议把这些信息写进日志。

3. 兜底值随便写

兜底值也要符合业务语义。比如推荐列表可以为空，优惠提示可以隐藏，但订单金额不能随便给默认值。

4. 误以为超时一定会立刻停止底层工作

CompletableFuture 的超时表示当前结果已经走超时路径，但底层阻塞调用是否真正停止，还取决于具体下游调用是否支持取消或超时。HTTP 客户端、数据库客户端也应该设置自己的超时参数。

总结

orTimeout 适合核心任务：慢了就失败，让上层知道问题；completeOnTimeout 适合非核心任务：慢了就返回兜底值，保护接口体验。真正稳定的异步聚合，不是把所有任务都并行起来，而是给每个任务定义清楚的时间边界、异常策略和日志字段。

参考资料

本文参考 Java 官方 CompletableFuture API 文档中关于超时方法的说明，示例和业务场景为原创整理。