Cal.com 性能规则解析async-api-routes——消除 API Routes 与 Server Actions 中的串行等待瀑布【免费下载链接】cal.diyScheduling infrastructure for absolutely everyone.项目地址: https://gitcode.com/GitHub_Trending/ca/cal.diy本文基于 Cal.com 仓库内置的 Vercel React 性能规则库深入讲解async-api-routes规则Prevent Waterfall Chains in API Routes为什么 API 路由中逐个await会形成请求瀑布如何通过提前发起、延后等待重排 Promise 来并行化独立操作以及面对部分依赖的复杂调用链时如何借助better-all进一步最大化并行度。读完后你可以直接在 Next.js API Routes、Server Actions 乃至任意异步服务端代码中套用这套模式并对照本仓库中的规则原文与真实路由代码验证效果。规则定位与元数据async-api-routes是仓库中随 Agent 技能库分发的一条性能规则文件其完整路径为 async-api-routes.md。文件头部 frontmatter 声明了这条规则的元数据值得先完整看一遍--- title: Prevent Waterfall Chains in API Routes impact: CRITICAL impactDescription: 2-10× improvement tags: api-routes, server-actions, waterfalls, parallelization ---title规则主题——防止 API 路由中出现瀑布式Waterfall串行链impact: CRITICAL在 SKILL.md 定义的 8 个优先级类别中Eliminating Waterfalls消除瀑布是优先级第 1、影响级别 CRITICAL 的类别async-前缀正是该类别的命名前缀。也就是说这条规则属于整个规则库中优先级最高的一档impactDescription: 2-10× improvement这是规则文档自身给出的收益评级指瀑布链越长并行化后相对串行总耗时的提升倍数越大并非实测基准数据引用时需注意这是文档标注而非仓库测量结果tagsapi-routes, server-actions, waterfalls, parallelization明确了适用范围API Routes 与 Server Actions与手段并行化。同一规则文件在仓库中以两份完全相同的内容存放已验证逐字节一致一份在.opencode/skill/vercel-react-best-practices/rules/供 OpenCode 类 Agent 消费另一份在agents/skills/vercel-react-best-practices/rules/供其他 Agent 框架消费二者共享 AGENTS.md 这份将 45 条规则全部展开的编译版文档。核心原理提前发起 Promise延后 await规则正文的第一句话就是全部要点In API routes and Server Actions, start independent operations immediately, even if you dont await them yet. 在 API 路由和 Server Actions 中独立的操作应当立即开始即使你此刻还没有 await 它们。这里利用的是 JavaScript 异步模型的语义调用一个返回 Promise 的函数时底层工作网络请求、数据库查询在函数被调用的那一刻就启动了await只是挂起当前执行流直到结果就绪并不会推迟请求的发起。因此只要先调用、后等待多个独立请求的耗时就可以自然重叠串行await的总耗时 ≈ 各操作耗时之和Σ tᵢ并行发起后的总耗时 ≈ 依赖链上的关键路径耗时max 或分段串行。瀑布链越长、单次网络/IO 延迟越高差距越明显——这正是该规则被标注为 2-10× 改进空间的原因规则原文的口径。反例config 等待 authdata 再等两者规则给出的错误示例是一段典型的三段串行 GET 处理函数规则文件第 14-21 行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 }) }问题在于依赖关系被高估了fetchConfig()只读配置与auth()结果毫无关系却被排在其后白白等了一个auth()的完整延迟fetchData(session.user.id)确实依赖session这一点无法优化于是总耗时是t(auth) t(config) t(data)而其中config本可与前两者重叠。规则用一句话概括了这个反例的病灶config waits for auth, data waits for bothconfig 在等 authdata 在等前两者。正例auth 与 config 立即发起Promise.all 收口对应的正确写法规则文件第 26-36 行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 }) }逐行拆解其结构第 1-2 行提前发起auth()与fetchConfig()两个函数在被调用的瞬间就各自开始网络往返此时只是把 Promise 对象存入变量不做任何等待第 3 行依赖点才 awaitfetchData需要session.user.id这里才第一次await sessionPromise。由于config已经在途这一次等待并不阻塞 config 的完成第 4-7 行收口Promise.all([configPromise, fetchData(session.user.id)])把已在途的 config和刚启动的 data一起等待。configPromise大概率早已 resolve实际等待时间由fetchData主导最终总耗时≈t(auth 与 config 中的较慢者) t(data)config 的耗时被完全藏进了 auth/data 的窗口内。可以抽象成三步心智模型适用于任何 API Route / Server Action / 异步服务端函数列出所有操作的真实依赖谁的结果被谁消费无依赖的操作在函数开头立即调用保存 Promise只在真正需要结果的依赖点await最终用Promise.all收口避免顺手 await。复杂依赖链用 better-all 自动最大化并行规则原文的最后一句给出了进阶指引第 38 行For operations with more complex dependency chains, usebetter-allto automatically maximize parallelism (see Dependency-Based Parallelization).即当操作之间存在部分依赖A 独立、B 依赖 A、C 也依赖 A……时手动管理谁该提前发起容易出错仓库中配套的 async-dependencies.md 规则给出了better-all的all()辅助函数方案。它接收一个由命名异步任务组成的对象每个任务内部可以通过this.$.任务名引用其他任务返回 Promise自动等待其结果调度器会自动让每个任务在最早可能时刻启动反例profile 不必要地等待 config因为 config 与 user 串行在同一个Promise.all之前看似并行但 profile 被推迟到两者都完成后才开始const [user, config] await Promise.all([ fetchUser(), fetchConfig() ]) const profile await fetchProfile(user.id)正例config 与 profile 并行执行profile 只等 userimport { 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) } })对比async-api-routes的手动写法better-all的价值在于依赖关系以声明方式表达在任务体内并行度的最大化由库保证开发者不再需要心算哪些 Promise 应该提前挂起。在 Cal.com 仓库中的落地参照结合本仓库源码结构可以说明这条规则的实际适用面Next.js API RoutesCal.com 前端应用apps/web下的路由采用标准 App Router API Route 形态例如 csrf/route.ts 中直接导出export async function GET(req: Request)。该路由目前只有单一线性流程生成 token 并设置 Cookie无并行化需求但它展示了本仓库 API Route 的标准写法——任何在其中新增多个独立 IO 的场景如同时校验会话、查询用户配置、拉取第三方状态都应按提前发起、延后等待重排同目录下的 ip/route.ts 与 video/recording/route.ts 也是同类形态的处理函数Server Actions 与 tRPC 处理器apps/web中大量数据操作经由 tRPC 路由packages/trpc/server/与服务端组件完成。规则 tags 中明确包含server-actions因为 Server Action 内部的异步代码与 API Route 遵循同样的事件循环语义瀑布问题同源、解法同构NestJS API v2apps/api/v2 中的 NestJS 控制器方法同样是 async 函数其中对独立 Repository 查询的连续await同样构成瀑布链。从源码结构看该规则文件由规则库统一分发其适用对象不限于 Next.js而是覆盖所有在单个 async 函数中编排多个 IO的服务端代码。工程细节与注意事项套用该模式时以下几点属于从异步语义推导出的工程判断规则原文未展开属补充建议错误传播语义变化手动提前发起后Promise.all中任一 Promise reject 会拒绝整个集合且先于其失败的兄弟任务不会自动取消网络请求已发出。若需要部分失败可用可改用Promise.allSettled或对独立 Promise 单独catch副作用操作要谨慎提前纯读取auth、fetchConfig提前发起是安全的但若操作带有写入或扣减类副作用提前开始会改变前置校验失败则不执行的语义这类操作应保持串行资源与限流并行发起意味着瞬时并发请求数上升依赖服务有配额限制时需要考虑连接池与限流策略不要为了并行而并行规则的前提是独立操作。若 B 的入参来自 A 的结果B 就必须等到 A——强行提前只能传一个尚未 ready 的值属于逻辑错误。判断依据始终是真实数据依赖而非代码书写顺序。检查清单评审或编写 API Route / Server Action 时可按以下问题自检由规则正文直接推得函数开头是否存在先 await 操作 1、再 await 操作 2的连续语句而操作 2 并不消费操作 1 的结果若是把调用提前、await推迟是否存在多个相互独立、仅各自依赖不同上游的操作被写成串行用Promise.all收口是否存在部分依赖的复杂调用链考虑引入better-all的all()参见 async-dependencies.md每个await位置是否都对应一个真实的数据依赖点await late, only where needed综上async-api-routes规则虽然只有一页但它给出的start early, await late是服务端异步编排中最基础也收益最高的一条纪律先画依赖、再定发起顺序、最后在依赖点收口即可把多数 API Route 中的串行延迟压缩到关键路径长度。【免费下载链接】cal.diyScheduling infrastructure for absolutely everyone.项目地址: https://gitcode.com/GitHub_Trending/ca/cal.diy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Cal.com 性能规则解析：async-api-routes——消除 API Routes 与 Server Actions 中的串行等待瀑布
Cal.com 性能规则解析async-api-routes——消除 API Routes 与 Server Actions 中的串行等待瀑布【免费下载链接】cal.diyScheduling infrastructure for absolutely everyone.项目地址: https://gitcode.com/GitHub_Trending/ca/cal.diy本文基于 Cal.com 仓库内置的 Vercel React 性能规则库深入讲解async-api-routes规则Prevent Waterfall Chains in API Routes为什么 API 路由中逐个await会形成请求瀑布如何通过提前发起、延后等待重排 Promise 来并行化独立操作以及面对部分依赖的复杂调用链时如何借助better-all进一步最大化并行度。读完后你可以直接在 Next.js API Routes、Server Actions 乃至任意异步服务端代码中套用这套模式并对照本仓库中的规则原文与真实路由代码验证效果。规则定位与元数据async-api-routes是仓库中随 Agent 技能库分发的一条性能规则文件其完整路径为 async-api-routes.md。文件头部 frontmatter 声明了这条规则的元数据值得先完整看一遍--- title: Prevent Waterfall Chains in API Routes impact: CRITICAL impactDescription: 2-10× improvement tags: api-routes, server-actions, waterfalls, parallelization ---title规则主题——防止 API 路由中出现瀑布式Waterfall串行链impact: CRITICAL在 SKILL.md 定义的 8 个优先级类别中Eliminating Waterfalls消除瀑布是优先级第 1、影响级别 CRITICAL 的类别async-前缀正是该类别的命名前缀。也就是说这条规则属于整个规则库中优先级最高的一档impactDescription: 2-10× improvement这是规则文档自身给出的收益评级指瀑布链越长并行化后相对串行总耗时的提升倍数越大并非实测基准数据引用时需注意这是文档标注而非仓库测量结果tagsapi-routes, server-actions, waterfalls, parallelization明确了适用范围API Routes 与 Server Actions与手段并行化。同一规则文件在仓库中以两份完全相同的内容存放已验证逐字节一致一份在.opencode/skill/vercel-react-best-practices/rules/供 OpenCode 类 Agent 消费另一份在agents/skills/vercel-react-best-practices/rules/供其他 Agent 框架消费二者共享 AGENTS.md 这份将 45 条规则全部展开的编译版文档。核心原理提前发起 Promise延后 await规则正文的第一句话就是全部要点In API routes and Server Actions, start independent operations immediately, even if you dont await them yet. 在 API 路由和 Server Actions 中独立的操作应当立即开始即使你此刻还没有 await 它们。这里利用的是 JavaScript 异步模型的语义调用一个返回 Promise 的函数时底层工作网络请求、数据库查询在函数被调用的那一刻就启动了await只是挂起当前执行流直到结果就绪并不会推迟请求的发起。因此只要先调用、后等待多个独立请求的耗时就可以自然重叠串行await的总耗时 ≈ 各操作耗时之和Σ tᵢ并行发起后的总耗时 ≈ 依赖链上的关键路径耗时max 或分段串行。瀑布链越长、单次网络/IO 延迟越高差距越明显——这正是该规则被标注为 2-10× 改进空间的原因规则原文的口径。反例config 等待 authdata 再等两者规则给出的错误示例是一段典型的三段串行 GET 处理函数规则文件第 14-21 行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 }) }问题在于依赖关系被高估了fetchConfig()只读配置与auth()结果毫无关系却被排在其后白白等了一个auth()的完整延迟fetchData(session.user.id)确实依赖session这一点无法优化于是总耗时是t(auth) t(config) t(data)而其中config本可与前两者重叠。规则用一句话概括了这个反例的病灶config waits for auth, data waits for bothconfig 在等 authdata 在等前两者。正例auth 与 config 立即发起Promise.all 收口对应的正确写法规则文件第 26-36 行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 }) }逐行拆解其结构第 1-2 行提前发起auth()与fetchConfig()两个函数在被调用的瞬间就各自开始网络往返此时只是把 Promise 对象存入变量不做任何等待第 3 行依赖点才 awaitfetchData需要session.user.id这里才第一次await sessionPromise。由于config已经在途这一次等待并不阻塞 config 的完成第 4-7 行收口Promise.all([configPromise, fetchData(session.user.id)])把已在途的 config和刚启动的 data一起等待。configPromise大概率早已 resolve实际等待时间由fetchData主导最终总耗时≈t(auth 与 config 中的较慢者) t(data)config 的耗时被完全藏进了 auth/data 的窗口内。可以抽象成三步心智模型适用于任何 API Route / Server Action / 异步服务端函数列出所有操作的真实依赖谁的结果被谁消费无依赖的操作在函数开头立即调用保存 Promise只在真正需要结果的依赖点await最终用Promise.all收口避免顺手 await。复杂依赖链用 better-all 自动最大化并行规则原文的最后一句给出了进阶指引第 38 行For operations with more complex dependency chains, usebetter-allto automatically maximize parallelism (see Dependency-Based Parallelization).即当操作之间存在部分依赖A 独立、B 依赖 A、C 也依赖 A……时手动管理谁该提前发起容易出错仓库中配套的 async-dependencies.md 规则给出了better-all的all()辅助函数方案。它接收一个由命名异步任务组成的对象每个任务内部可以通过this.$.任务名引用其他任务返回 Promise自动等待其结果调度器会自动让每个任务在最早可能时刻启动反例profile 不必要地等待 config因为 config 与 user 串行在同一个Promise.all之前看似并行但 profile 被推迟到两者都完成后才开始const [user, config] await Promise.all([ fetchUser(), fetchConfig() ]) const profile await fetchProfile(user.id)正例config 与 profile 并行执行profile 只等 userimport { 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) } })对比async-api-routes的手动写法better-all的价值在于依赖关系以声明方式表达在任务体内并行度的最大化由库保证开发者不再需要心算哪些 Promise 应该提前挂起。在 Cal.com 仓库中的落地参照结合本仓库源码结构可以说明这条规则的实际适用面Next.js API RoutesCal.com 前端应用apps/web下的路由采用标准 App Router API Route 形态例如 csrf/route.ts 中直接导出export async function GET(req: Request)。该路由目前只有单一线性流程生成 token 并设置 Cookie无并行化需求但它展示了本仓库 API Route 的标准写法——任何在其中新增多个独立 IO 的场景如同时校验会话、查询用户配置、拉取第三方状态都应按提前发起、延后等待重排同目录下的 ip/route.ts 与 video/recording/route.ts 也是同类形态的处理函数Server Actions 与 tRPC 处理器apps/web中大量数据操作经由 tRPC 路由packages/trpc/server/与服务端组件完成。规则 tags 中明确包含server-actions因为 Server Action 内部的异步代码与 API Route 遵循同样的事件循环语义瀑布问题同源、解法同构NestJS API v2apps/api/v2 中的 NestJS 控制器方法同样是 async 函数其中对独立 Repository 查询的连续await同样构成瀑布链。从源码结构看该规则文件由规则库统一分发其适用对象不限于 Next.js而是覆盖所有在单个 async 函数中编排多个 IO的服务端代码。工程细节与注意事项套用该模式时以下几点属于从异步语义推导出的工程判断规则原文未展开属补充建议错误传播语义变化手动提前发起后Promise.all中任一 Promise reject 会拒绝整个集合且先于其失败的兄弟任务不会自动取消网络请求已发出。若需要部分失败可用可改用Promise.allSettled或对独立 Promise 单独catch副作用操作要谨慎提前纯读取auth、fetchConfig提前发起是安全的但若操作带有写入或扣减类副作用提前开始会改变前置校验失败则不执行的语义这类操作应保持串行资源与限流并行发起意味着瞬时并发请求数上升依赖服务有配额限制时需要考虑连接池与限流策略不要为了并行而并行规则的前提是独立操作。若 B 的入参来自 A 的结果B 就必须等到 A——强行提前只能传一个尚未 ready 的值属于逻辑错误。判断依据始终是真实数据依赖而非代码书写顺序。检查清单评审或编写 API Route / Server Action 时可按以下问题自检由规则正文直接推得函数开头是否存在先 await 操作 1、再 await 操作 2的连续语句而操作 2 并不消费操作 1 的结果若是把调用提前、await推迟是否存在多个相互独立、仅各自依赖不同上游的操作被写成串行用Promise.all收口是否存在部分依赖的复杂调用链考虑引入better-all的all()参见 async-dependencies.md每个await位置是否都对应一个真实的数据依赖点await late, only where needed综上async-api-routes规则虽然只有一页但它给出的start early, await late是服务端异步编排中最基础也收益最高的一条纪律先画依赖、再定发起顺序、最后在依赖点收口即可把多数 API Route 中的串行延迟压缩到关键路径长度。【免费下载链接】cal.diyScheduling infrastructure for absolutely everyone.项目地址: https://gitcode.com/GitHub_Trending/ca/cal.diy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
