当前位置：首页 > 文章列表 > 文章 > java教程 > Java CompletableFuture 超时处理实战：orTimeout 和兜底结果怎么选

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

来源：17golang原创 2026-06-12 23:07:11 0浏览收藏

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

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

摘要

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

适合人群

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

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

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

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

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

Java CompletableFuture 为异步聚合设置超时边界的示意图

二、准备一个模拟慢任务

为了演示，我们先写几个模拟方法。实际项目里可以替换成数据库查询、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();

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

Java CompletableFuture 超时后返回兜底结果的示意图

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

非核心任务除了超时，还可能出现普通异常。可以用 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()
    );
}

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