Java 25 Structured Concurrency 实战：别让 CompletableFuture 把超时拖散

Java 25 继续预览 Structured Concurrency。它不是为了替代所有 CompletableFuture，而是解决一个生产里很具体的问题：一次请求里拉起多个子任务后，超时、失败、取消和日志归因要能一起收口。

本文适用于 Java 21/25 虚拟线程评估、Spring Boot 聚合接口、并行 I/O 调用、JDK 25 预览 API 验证。OpenJDK JEP 505 资料只用于核对事实，正文按一次生产接口治理复盘写。

业务场景：订单页聚合四个下游，超时后任务还在跑

订单详情页要同时查用户、价格、库存、风控。以前我们用 CompletableFuture 拼起来，接口层设置 800ms 超时。线上问题是：入口已经返回超时，某些下游调用还在跑；日志里只能看到一个 TimeoutException，看不出哪个子任务拖慢。

这类问题不是 CompletableFuture 不能用，而是任务生命周期散了。创建任务、等待任务、处理失败、取消任务分别落在不同代码块里，review 很难确认每条路径都收得住。

Structured Concurrency 解决的是收口，不是并发本身

StructuredTaskScope 的思路是把一组子任务放进同一个作用域：一起启动、一起等待、一起处理成功或失败。它特别适合请求级并发，而不是后台常驻任务。

Java 25 的 JEP 505 仍是预览特性，所以生产评估必须带上 preview 开关、回退实现和灰度策略。我的原则是：先在边界清楚的聚合接口试，不要在基础框架里一口气扩散。

代码案例：别把同一个 SLA 拆散

CompletableFuture 链式组合很灵活，但灵活也意味着边界容易散。Structured Concurrency 更像把并发调用重新拉回结构化代码块里，读代码时能看到任务从哪里开始、在哪里等待、失败后怎么退出。

诊断步骤：先证明取消真的生效

改造后我会压三类场景：一个下游慢、一个下游直接失败、入口 deadline 提前到期。看日志里是否能定位子任务，看 JFR 或客户端指标里是否还有超时后继续跑的请求。

如果下游客户端不响应中断，scope 再好也只是把调用关系写清楚，资源仍然可能拖住。所以 HTTP/JDBC 客户端的超时、连接池和取消语义必须一起检查。

上线检查清单

• 确认 Java 25 预览 API 的编译、测试、运行链路都开启 preview。
• 入口请求是否有唯一 deadline，子任务是否共享同一个时间预算。
• 关键子任务失败后，非必要子任务是否能取消。
• 下游客户端是否正确设置连接超时、读取超时和取消语义。
• 日志是否记录每个子任务耗时、异常类型和取消原因。
• 是否保留 CompletableFuture 或 ExecutorService 回退实现。

我的经验

Structured Concurrency 的价值不是让并发更快，而是让并发更像普通代码：有入口、有出口、有失败边界。生产里最贵的不是多写几行 CompletableFuture，而是超时后资源没释放、故障归因说不清。