completeOnTimeout为CompletableFuture提供超时后备值，不中断原任务；仅当future未完成时生效，返回自身引用，超时后以指定值完成，适用于降级场景。
Java 中使用 completeOnTimeout 为异步任务兜底，核心是给 CompletableFuture 设置一个超时后备值，避免调用方无限等待。它不是中断原任务，而是当原始计算未在指定时间内完成时，主动用默认值“完成”该 future。
completeOnTimeout 的基本用法
该方法签名如下：
public CompletableFuture它返回的是**当前 CompletableFuture 的引用**（即链式调用），但注意：它只在原始 future 尚未完成时才生效；一旦原始任务提前完成，兜底逻辑就自动忽略。
- 参数
value是超时时要设置的默认结果（不能为 null，否则抛 NPE） -
timeout是从调用completeOnTimeout这一刻开始计时，不是从任务启动时算起 - 该方法本身不触发异步执行，只是注册一个延迟任务（底层用 ScheduledExecutorService）
和 orTimeout 的关键区别
别混淆 completeOnTimeout 和 orTimeout：
Java注释规范Skills
下载
当用户要求为 Java 代码添加注释、修改注释、审查注释、整理注释格式，或要求按照代码注释规范处理 Java 文件时，使用本技能。本技能用于统一生成和维护 Java 类注释模板、按 Git 对比 release 判断版本号、补充每行代码上方中文块注释、调整注释空行规则，并保持 Java 文件 UTF-8 无 BOM 编码。典型触发场景包括：补充类注释、更新 @version、检查 @author 来源、整理行尾注释、把注释放到代码上一行、检查注释是否符合规范、构建前检查 Java 注释风格。
立即学习“Java免费学习笔记（深入）”；
-
orTimeout：超时后会以TimeoutException异常完成 future，调用get()会抛异常，适合“必须成功否则报错”的场景 -
completeOnTimeout：超时后以你指定的普通值完成 future，调用get()返回该值，适合“尽力而为、有备选”的场景（比如降级返回缓存、空列表、默认文案）
典型使用示例（带 fallback 的 HTTP 调用）
假设你用 CompletableFuture 异步调用一个可能慢的远程接口：
CompletableFuturetry {
Thread.sleep(3000); // 模拟耗时请求
return "real-data";
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
return "error";
}
})
.completeOnTimeout("fallback-data", 2, TimeUnit.SECONDS); // 2秒超时，返回兜底值
此时：
- 若 sleep 在 2 秒内结束 → future 完成为
"real-data" - 若 sleep 超过 2 秒 → 2 秒后 future 完成为
"fallback-data"，后续 sleep 仍会执行但结果被忽略（future 已完成，无法再 set）
注意事项与常见坑
-
原始任务不会被取消：超时后原线程还在跑，可能造成资源浪费或重复写库。如需真正停止，得配合
cancel(true)或用可中断逻辑（如检查Thread.interrupted()） -
不能链式多次调用：对同一个 future 多次调用
completeOnTimeout只有第一个生效（因为 future 完成后无法再 complete） -
慎用于有副作用的任务：比如异步发短信 +
completeOnTimeout("sent")，实际没发成功却返回“已发送”，业务语义错误 - 如果需要“超时后执行清理动作”，建议用
whenComplete或handle判断是否超时完成（例如对比结果是否等于 fallback 值）
