如何通过 CompletableFuture 的 completeOnTimeout 方法为异步链路设置超时默认值保障？

本文共计722个文字，预计阅读时间需要3分钟。

《Java 11 CompletableFuture 方法解析》

本文将简要介绍 Java 11 引入的 CompletableFuture 方法，包括 completeOnTimeout 和 orTimeout 的用法和语义。

completeOnTimeout 是一个超时后填充默认值的方法。其语义为：

什么时候该用 completeOnTimeout 而不是 exceptionally + orTimeout

当你需要「业务上可接受降级结果」，且下游超时后仍希望继续执行、不阻断整个链路时，completeOnTimeout 更干净。
常见场景包括：

• 查缓存超时，用本地配置兜底
• 调用非核心推荐服务超时，返回空列表或热门默认项
• 聚合多个异步结果时，某个非关键字段缺失不影响主流程

反例：支付扣款、库存预占这类强一致性操作，不能用 completeOnTimeout —— 它不会取消原任务，可能造成“超时后又成功”的双写风险。这种必须用 orTimeout + 显式补偿。

completeOnTimeout 的实际写法和容易踩的坑

基本写法：future.completeOnTimeout("default", 2, TimeUnit.SECONDS)。