在分布式服务里，一次业务操作往往要同时调用多个下游接口：查商品详情要并发拉取价格、库存和评论；聚合搜索要同时请求多个数据源。这些外部调用的响应时间不可控，如果不做超时控制，一个慢接口就能把整个服务拖垮。Scala的Future体系提供了非常灵活的组合能力，本文从单请求超时讲起，逐步扩展到多请求场景下的几种超时聚合策略，并覆盖异常传播和资源清理等实践细节。
单个Future的超时实现方式
先解决最基础的问题：给一个Future加上超时。最常用的做法是利用Future的伴生对象里的after方法，它会在指定延迟后完成一个备选Future，然后与原Future做竞争。谁的值先到就取谁，这就天然形成了超时语义。
import scala.concurrent.Future
import scala.concurrent.duration._
import scala.concurrent.ExecutionContext.Implicits.global
import scala.util.{Try, Success, Failure}
def withTimeout[T](f: Future[T], timeout: FiniteDuration): Future[T] = {
val timeoutFuture = Future.failed(
new java.util.concurrent.TimeoutException(s"请求超过 $timeout 仍未完成")
)
// after 在超时时间后才失败，与原 Future 竞争
Future.firstCompletedOf(Seq(f, Future.after(timeout, timeoutFuture)))
}需要注意一个关键点：after方法的调度依赖传入的Timer。上面的简化写法在一些Scala版本中需要额外引入scala.concurrent.ExecutionContext与调度支持，如果用的是Akka生态，更推荐用AkkaTimeout或者after的完整签名，显式传入Scheduler，避免与全局执行上下文耦合。
另一种思路是直接使用Java的ScheduledThreadPoolExecutor手工实现。这种方式的好处是可控性更强，可以精确选择调度线程池，避免在高并发场景下让全局的调度器成为瓶颈：
import java.util.concurrent._
import scala.concurrent.{Future, Promise}
object TimeoutScheduler {
private val scheduler = new ScheduledThreadPoolExecutor(
4, r => { val t = new Thread(r, "timeout-scheduler"); t.setDaemon(true); t }
)
def addTimeout[T](f: Future[T], after: FiniteDuration): Future[T] = {
val p = Promise[T]()
val cancellable = scheduler.schedule(
new Runnable {
override def run(): Unit =
p.tryFailure(new TimeoutException(s"超时 ${after}"))
},
after.length, after.unit
)
f.onComplete { result =>
cancellable.cancel(false)
p.tryComplete(result)
}
p.future
}
}两种方式各有取舍：after写法简洁、无额外资源，但超时粒度依赖隐式参数；手工Promise方案代码稍多，却把调度线程完全握在自己手里，适合框架类代码。无论哪种方式，超时触发后原Future仍在运行，只是不再等待它的结果，这个事实在后面讨论资源清理时还会再提到。
多个Future的超时聚合策略
单个超时解决后，多请求场景的核心问题是：超时语义应该作用于整体还是个体？不同的业务语义对应不同的实现方式，这里给出三种典型方案。
策略一：全成功语义，统一超时
最常见的需求是所有请求都要成功，且总耗时不能超过上限。实现思路是先给每个Future单独加超时，再用Future.sequence聚合，最后对整体再做一次兜底超时。为什么要做两层？因为sequence会在任一Future失败时立刻让整体失败，单个超时保证快速失败，整体超时则兜住调度延迟等意外情况。
def allWithTimeout[T](fs: Seq[Future[T]], timeout: FiniteDuration): Future[Seq[T]] = {
val individuallyTimed = fs.map(f => TimeoutScheduler.addTimeout(f, timeout))
// 对整体结果再加一层兜底超时
TimeoutScheduler.addTimeout(Future.sequence(individuallyTimed), timeout * 2)
}策略二：任一成功语义，快速返回
有些场景是多个数据源都有相同数据，谁快用谁，比如多CDN回源或多机房读取。Future.firstCompletedOf直接对多个Future做竞争，配合整体超时即可：
def anyWithTimeout[T](fs: Seq[Future[T]], timeout: FiniteDuration): Future[T] = TimeoutScheduler.addTimeout(Future.firstCompletedOf(fs), timeout)
值得注意，firstCompletedOf在某个Future失败时不会立即返回失败，它会继续等其他Future，直到有一个成功或全部失败。如果你希望失败也快速返回，需要自己用Promise实现竞速逻辑，这一点在官方文档中没有强调，却是实际踩坑的高发区。
策略三：部分成功语义，收集已完成结果
更宽容的需求是：超时时间到，能拿到多少算多少，缺的部分降级处理。Future.traverse配合recover可以把失败或超时的请求转成默认值：
def partialWithTimeout[T](fs: Seq[Future[T]], timeout: FiniteDuration,
fallback: T): Future[Seq[T]] = {
Future.traverse(fs) { f =>
TimeoutScheduler.addTimeout(f, timeout)
.recover { case _: TimeoutException => fallback }
}
}三种策略的选择标准很明确：下游数据是否强一致要求全成功，可替换数据源用任一成功，允许降级则用部分成功。切忌在聚合搜索这种明显允许部分失败的场景里硬套sequence，那会让最快的接口陪最慢的一起超时。
异常传播与资源清理的细节
超时控制写完不代表万事大吉，还有几个容易被忽视的问题。第一是异常传播粒度。sequence默认只保留第一个失败的异常，其他失败会被丢弃。如果需要拿到全部失败原因做监控上报，可以自己实现一个聚合版本，用Future.sequence(fs.map(_.transform(Success(_))))先收集所有Try，再统一分析。
第二是超时后的资源泄漏。前面提到超时触发时原任务仍在执行，如果是数据库查询或HTTP调用，这些连接依然被占用。生产环境务必让下游调用本身支持取消，比如在runWith上使用Akka Stream的kill switch，或者HTTP客户端支持请求取消，超时时主动触发。仅靠Future层面的超时只能保护调用方，保护不了被压垮的下游。
第三是线程池的隔离。超时调度虽然轻量，但如果复用业务执行上下文，大量超时任务的排队会挤占正常任务。把调度逻辑放在独立的ScheduledThreadPoolExecutor上，大小设为CPU核数即可，能显著降低互相干扰的风险。同时建议给超时异常带上上下文信息（请求ID、下游服务名），否则排查线上问题时只能看到一堆裸的TimeoutException，很难定位到具体环节。
最后总结一下实践路径：单请求用after或手工Promise加超时，多请求根据语义在sequence、firstCompletedOf、traverse三种聚合方式中选择，再补上取消传播和线程池隔离，一套完整的多异步请求超时控制方案就成型了。核心原则只有一条：超时语义要跟业务语义对齐，而不是简单地在每个Future上机械地加一个时间上限。
Scala异步编程Future超时AsyncCallback修改时间：2026-09-07 18:08:49