OpenMontage 实战:用「尽早启动、延迟 await」消除 API 路由瀑布链(Vercel React 最佳实践 async-api-routes 规则解析)
OpenMontage 实战:用「尽早启动、延迟 await」消除 API 路由瀑布链(Vercel React 最佳实践 async-api-routes 规则解析)
本文围绕 OpenMontage 仓库中随 .claude/skills/vercel-react-best-practices 技能包引入的 async-api-routes 规则展开,它针对 Next.js API 路由与 Server Actions 中最常见的性能杀手——串行瀑布链(waterfall chain)给出了一套明确的代码改写范式。读完本文,你将掌握「先创建 Promise、后统一 await」的并行化心法,学会用 Promise.all 与 better-all 重构存在部分依赖的数据获取代码,并了解该规则在本仓库技能体系中的位置与落地方式。
规则档案:一条被标记为 CRITICAL 的 Vercel 官方规则
该规则位于 .claude/skills/vercel-react-best-practices/rules/async-api-routes.md,其 YAML frontmatter 定义了规则的核心元信息:
---
title: Prevent Waterfall Chains in API Routes
impact: CRITICAL
impactDescription: 2-10× improvement
tags: api-routes, server-actions, waterfalls, parallelization
---
- title(规则名):Prevent Waterfall Chains in API Routes,即「在 API 路由中阻止瀑布链」;
- impact(影响级别):
CRITICAL,在 Vercel 的优先级体系中属于最高档; - impactDescription(影响说明):标注可带来 2~10 倍的改善(该数值来自 Vercel 官方指南的声明,作为本仓库技能包的参考指标,并非本项目实测数据);
- tags(标签):
api-routes、server-actions、waterfalls、parallelization,表明该规则同时作用于传统 Route Handler 与 Next.js Server Actions。
在技能体系中的位置
根据同目录 SKILL.md 的说明,这是 Vercel Engineering 维护的 React/Next.js 性能优化指南,共 65 条规则、8 大分类,并带有明确的优先级排序:
| 优先级 | 分类 | 影响 | 前缀 |
|---|---|---|---|
| 1 | Eliminating Waterfalls(消除瀑布) | CRITICAL | async- |
| 2 | Bundle Size Optimization(包体积优化) | CRITICAL | bundle- |
| 3 | Server-Side Performance(服务端性能) | HIGH | server- |
| 4 | Client-Side Data Fetching(客户端取数) | MEDIUM-HIGH | client- |
| 5 | Re-render Optimization(重渲染优化) | MEDIUM | rerender- |
| 6 | Rendering Performance(渲染性能) | MEDIUM | rendering- |
| 7 | JavaScript Performance(JS 微优化) | LOW-MEDIUM | js- |
| 8 | Advanced Patterns(高级模式) | LOW | advanced- |
async-api-routes 属于优先级最高的「消除瀑布」类别。同目录的 _sections.md 给出了该类别的定位理由:「Waterfalls are the #1 performance killer. Each sequential await adds full network latency. Eliminating them yields the largest gains.」——瀑布是头号性能杀手,每次串行 await 都会叠加一次完整的网络延迟,消除它们能带来最大的收益。
什么是瀑布链:串行 await 的延迟叠加
瀑布链(waterfall chain)指的是异步操作一个接一个地等待前一个完成后才开始执行的串行模式。在 API 路由或 Server Actions 中,每个 await 都会让当前请求挂起,直到该 I/O 完成;如果三个本来互不依赖的操作被写成三个连续的 await,那么总耗时就是三者延迟的算术和,而不是最大值。
假设 auth()、fetchConfig()、fetchData() 各自需要 200ms 的网络往返:
- 串行执行:200 + 200 + 200 = 600ms;
- 并行执行:max(200, 200, 200) ≈ 200ms。
在远程数据库、微服务、缓存服务混合调用的真实路由中,这个差距会随依赖链深度进一步放大——这正是该规则被标为 CRITICAL 的原因。
错误写法剖析:config 等待 auth,data 等待两者
规则文档给出了典型的反例:
export async function GET(request: Request) {
const session = await auth()
const config = await fetchConfig()
const data = await fetchData(session.user.id)
return Response.json({ data, config })
}
逐行分析其时间线:
await auth()—— 请求在此挂起,直到会话验证完成;await fetchConfig()—— 它并不依赖session,却要等第 1 步结束才开始;这是第一个可以并行却被串行化的操作;await fetchData(session.user.id)—— 它依赖session.user.id,但同时也被fetchConfig()的等待拖累:fetchData原本可以在auth完成后立即开始,却多等了整整一个fetchConfig的往返周期。
结果:config 的耗时被 auth 白白拖住,data 的耗时又被 config 白白拖住,三段时间完全叠加。这就是「config 等 auth,data 等两者」的代价。
正确写法剖析:auth 与 config 立即启动
规则文档给出的正确版本:
export async function GET(request: Request) {
const sessionPromise = auth()
const configPromise = fetchConfig()
const session = await sessionPromise
const [config, data] = await Promise.all([
configPromise,
fetchData(session.user.id)
])
return Response.json({ data, config })
}
关键差异在于:
- 第 2、3 行:先调用、不 await。
auth()与fetchConfig()在赋值给 Promise 变量的瞬间就已开始执行。JavaScript 中 Promise 在构造函数被调用时即进入 pending 状态并启动异步工作,await只是「等待结果」,并非「触发执行」; - 第 4 行:只等待真正需要的结果。
session是fetchData的依赖项,因此这里await sessionPromise是必要的最小等待; - 第 5~7 行:
Promise.all合并剩余并行分支。 此时configPromise大概率已经完成或接近完成,fetchData(session.user.id)在拿到session后立即启动。Promise.all会等待两者都 settle 后统一解构赋值。
三条操作的时间线变成:
auth ████████████░░░░░░░░
config ████████████░░░░░░░░
data ████████████░░░░░░░░ (只等 session,不等 config)
总耗时从三者之和收敛到「最长依赖路径」的长度,即 auth(或 config)的单项耗时加上 data 的耗时。
核心心法:尽早创建 Promise,延迟 await
规则原文的核心表述值得逐字理解:
In API routes and Server Actions, start independent operations immediately, even if you don't await them yet.
「立即启动独立的操作,哪怕此刻还不去 await 它们。」这条心法可以拆成三条可执行原则:
- 区分「启动」与「等待」:
fetchX()是启动,await fetchX()是启动加等待。把两者拆开,你就获得了调度的主动权; - 尽早启动、尽量并行:任何不依赖前序结果的操作,都应该在函数入口处就发起;
- 统一收敛、延迟 await:把真正需要的依赖 await 掉之后,用
Promise.all(或Promise.allSettled,当需要容忍部分失败时)一次性收敛所有并行分支。
这条心法与同目录的 async-defer-await.md(Defer Await Until Needed)互为补充:后者主张把 await 移进真正用到它的代码分支中,避免「提前等待、分支却根本不需要」的浪费。两者结合的最佳实践是——该并行的并行,该延迟的延迟,该提前结束的提前结束。
依赖链更复杂时:Dependency-Based Parallelization 与 better-all
async-api-routes.md 在文末给出了进阶指引:当操作的依赖关系更复杂时,使用 better-all 自动最大化并行度(即同目录规则 async-dependencies.md 所讲的 Dependency-Based Parallelization)。
先看纯手写 Promise.all 的局限。当只有部分依赖时,直接 Promise.all 会引入不必要的等待:
// 错误示例:profile 无谓地等待 config
const [user, config] = await Promise.all([
fetchUser(),
fetchConfig()
])
const profile = await fetchProfile(user.id)
这里 fetchProfile 只依赖 user,却被 config 的完成时间拖住——Promise.all 会等待所有 Promise 都完成后才返回。
better-all 的写法(来自 async-dependencies.md):
import { all } from 'better-all'
const { user, config, profile } = await all({
async user() { return fetchUser() },
async config() { return fetchConfig() },
async profile() {
return fetchProfile((await this.$.user).id)
}
})
它的机制是:把每个任务声明为对象字段,profile 通过 this.$.user 声明对 user 的依赖;库会在依赖就绪的最早时刻自动启动下游任务,从而让 config 与 profile 并行运行——这正是规则文档所述「automatically starts each task at the earliest possible moment」。
如果不想引入额外依赖,规则文档还给出了等价的纯 Promise 实现:先创建所有 Promise,再把依赖链手动串起来,最后统一 Promise.all:
const userPromise = fetchUser()
const profilePromise = userPromise.then(user => fetchProfile(user.id))
const [user, config, profile] = await Promise.all([
userPromise,
fetchConfig(),
profilePromise
])
这里 profilePromise 通过 .then 挂接在 userPromise 之后,fetchProfile 会在 user 就绪的第一时间启动,而 fetchConfig 从头到尾与两者无关、全程并行。三种方案(Promise.all、better-all、手动链式 .then)适用于不同复杂度,核心目标始终是:让每条数据依赖路径都保持最短。
与相邻规则的配合使用
async-api-routes 不是孤立的。在「消除瀑布」与「服务端性能」两个类别中,它与以下规则形成完整的工具箱:
- async-parallel.md:当操作完全无相互依赖时,直接用
Promise.all把三个串行await(3 次往返)压成 1 次往返。这是最基础、最高频的改写; - async-suspense-boundaries.md:在 React 组件层,用
<Suspense>边界让包装 UI 先渲染、数据后流入,并支持跨组件共享同一个 Promise(use(promise)),避免重复请求; - server-parallel-fetching.md:针对 React Server Components 树内串行执行的特点,用组件组合(composition)或
childrenprop 重构,让兄弟组件的数据获取并行发起; - server-after-nonblocking.md:把日志、埋点、通知等副作用放进
after(),在响应发出后再执行,避免阻塞响应路径。
一条典型的「全链路消除瀑布」的 API 路由,最终形态是:入口处并发启动所有独立请求 → 依赖项 await 后立刻接力 → 次要数据用 Suspense/流式输出 → 副作用交给 after()。
在本仓库中的定位与应用方式
OpenMontage 将 Vercel 的这套最佳实践以 Agent Skill 的形式内置于仓库的 .claude/skills/vercel-react-best-practices/ 目录下。根据 SKILL.md 的说明,该技能包在以下场景应被引用:
- 编写新的 React 组件或 Next.js 页面;
- 实现客户端或服务端数据获取;
- 审查代码中的性能问题;
- 重构既有 React/Next.js 代码;
- 优化包体积与加载时间。
仓库中实际使用 React/TypeScript 的模块是 remotion-composer(Remotion 视频合成器),例如 Root.tsx 中注册了 Explainer、CinematicRenderer、TalkingHead、TitledVideo 等 Composition,TitledVideo.tsx 中存在对 getVideoMetadata(resolveAsset(props.videoSrc)) 的 await 调用——这类异步渲染逻辑正是本规则可发挥作用的场景。当 Agent 或开发者在这个模块中编写异步取数、媒体元数据加载、字幕/音频资源解析等代码时,都应当遵循「尽早启动、延迟 await」的原则。
需要注意的是,该技能包是从 Vercel 上游 vendored 的参考指南(AGENTS.md 为其长文完整版,见 AGENTS.md),它只约束本仓库中的 React/Next.js 相关代码,不覆盖仓库根目录 AGENTS.md 与 AGENT_GUIDE.md 所定义的全局工程规范。
使用边界与注意事项
并行化并非无脑套用,规则文档与相邻规则共同划定了边界:
- 真正的依赖不能被绕过:
fetchData(session.user.id)必须先拿到session才能发起;并行化只作用于「可以并发」的段,依赖关系必须保持严格正确; - 错误处理要适配:
Promise.all任一失败即整体 reject;若希望部分失败不影响整体响应(如 config 失败但 data 可用),应改用Promise.allSettled并分别处理; - 不是所有场景都该拆 Promise:依据 async-suspense-boundaries.md 的说明,当数据用于布局决策、位于首屏 SEO 关键区、或查询极快而 Suspense 开销不划算时,保持同步等待反而是更优选择;同理,缓存命中的请求(如 server-cache-react.md 的
React.cache()去重场景)并行收益也有限。
总结
async-api-routes 规则用最朴素的两段代码,讲清了 Next.js API 路由与 Server Actions 中最重要的一条异步心法:调用即启动,await 才等待。把独立操作在入口处立刻发起、用 Promise.all 或 better-all 收敛结果、把 await 推迟到真正需要的分支,就能把瀑布链式的延迟叠加压缩到「最长依赖路径」,这也是 Vercel 将「消除瀑布」列为唯一一个全 CRITICAL 类别的原因。在 OpenMontage 的 React/Next.js 开发与代码审查中,这条规则配合 async-parallel、async-defer-await、async-suspense-boundaries 等相邻规则,构成一套完整、可复制、可验证的异步性能优化实践。