Codex写聚合接口为什么一个下游变慢就全部超时？用超时预算控制调用链

1. 一个下游抖动，整页跟着陪葬：聚合接口超时扩散的真实场景

先说结论：Codex 生成的聚合接口之所以“一个下游变慢就全部超时”，根因几乎从来不是某个服务慢，而是整条调用链没有定义时间预算和失败边界。你在/api/dashboard里同时调用户、订单、库存、推荐、通知五个服务，代码写起来就是几行await，本地全绿，上线后推荐服务抖 3 秒，首页就跟着慢 3 秒；推荐服务挂掉，整个接口直接 500。用户看到的不是“少一个推荐模块”，而是整页白屏。

我见过最典型的写法是这样的：

const user = await getUser(); // 100ms const orders = await getOrders(); // 200ms const stock = await getStock(); // 150ms const recommend = await getRecommend(); // 800ms return { user, orders, stock, recommend };

四个调用彼此没有依赖，却串行执行，总耗时是四段相加约 1250ms。改成Promise.all后接近最慢的那一个，约 800ms，看起来解决了。但Promise.all又带来第二个坑：只要一个 reject，整体就 reject。推荐服务失败，用户资料和订单数据明明已经拿到了，接口还是 500。

再往下走，问题会层层放大。上游网关给聚合接口 3 秒，聚合接口给每个下游也配 3 秒，链路一深就彻底失控：网关 2 秒就放弃了，Dashboard 还在等 Order，Order 还在等 Payment，Payment 默认等 5 秒。上游早已超时，下游还在查库、调第三方、生成推荐，连接、Socket、内存、Worker 全被占着。并发 1000 个请求时，光是等待那个变慢的推荐服务，就能把 HTTP 连接池和文件描述符耗尽，随后连正常的支付服务都拿不到连接。

这类问题的排查顺序我建议固定下来：先让 Codex 画出依赖调用图，标出哪些是串行、哪些可并行、哪些是核心依赖、哪些允许降级、每个下游当前超时多少、有没有自动重试、总预算多少。不要一看到“接口慢”就无脑加Promise.all，那只是把串行改成并行，失败边界和超时预算一个都没解决。真正要做的，是给整条调用链分配一笔“时间预算”，让每深入一层只能用剩余时间，再配合 Circuit Breaker 把故障锁在单分支内。下面从接入配置开始，一步步把这套东西落到可复制的代码里。

2. 接入前的准备：TaoToken 控制台拿 Key 与模型 ID

这一节是把 Codex 接进你日常开发流的前置动作，做完才能让它在真实项目里改聚合接口。整个流程不复杂，关键是三件套要拿全：Base URL、API Key、Model ID，缺一个后面请求就会报错。

先打开官网 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 注册并登录，进入控制台 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console 。在控制台左侧找到 API Keys 入口 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys ，点“创建密钥”，复制出来的一串就是你的 Key。注意这串只在创建时完整显示一次，建议直接存进本地环境变量，别写进代码仓库。

Base URL 统一用 https://taotoken.net/api ，这个地址后面在 Codex 配置、Cline、CC Switch 里都会反复用到，记牢。Model ID 在模型列表里选，做聚合接口改造这种需要读多文件、理解调用链的任务，选上下文长一点的模型更稳，具体以控制台当前可选的为准。

拿到三件套后，先在终端验证一下 Key 是否可用，避免后面配置全写完才发现 Key 错了：

export TAOTOKEN_API_KEY="sk-你的密钥" curl https://taotoken.net/api/v1/models \ -H "Authorization: Bearer $TAOTOKEN_API_KEY"

返回里能看到模型列表就说明 Key 和 Base URL 都没问题。如果返回 401，先检查 Key 有没有多余空格、是不是复制漏了尾部字符；如果返回连接类错误，检查 Base URL 是不是误写成了带/v1之外的路径。这一步花两分钟，能省掉后面半小时的排障。

如果你打算长期在微服务项目里用 Codex 做调用链分析、多轮压测和故障演练，可以看下 Coding Plan https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan ，它的定位就是给持续编码和 Agent 场景用的，上下文连续性更好，适合同时分析多个模块和日志。只是偶尔改一个聚合接口，按量用 API 就够了，不必一上来就上套餐。

3. 可复制配置：超时预算 + Deadline + Circuit Breaker 落地片段

这一节是全文的核心，给出能直接粘进项目的配置和代码。思路分三层：第一层是每个下游的独立超时，第二层是整条链共享的 Deadline，第三层是 Circuit Breaker 隔离持续失败的下游。三层配合，才能把局部慢调用限制在单分支内。

先看超时预算的配置片段。假设网关给聚合接口的总预算是 2000ms，我们按下游重要性分配，并留安全余量：

{ "aggregator": { "totalBudgetMs": 2000, "safetyMarginMs": 300, "downstreams": { "user-service": { "timeoutMs": 500, "core": true, "degradable": false }, "order-service": { "timeoutMs": 800, "core": true, "degradable": false }, "stock-service": { "timeoutMs": 400, "core": false, "degradable": true }, "recommend-service": { "timeoutMs": 400, "core": false, "degradable": true }, "notify-service": { "timeoutMs": 200, "core": false, "degradable": true } }, "circuitBreaker": { "failureRateThreshold": 0.5, "minimumRequests": 20, "openDurationMs": 10000, "halfOpenProbeCount": 3 } } }

这份配置的读法是：总预算 2000ms，扣掉 300ms 安全余量，实际可分配 1700ms；核心依赖 user 和 order 给足超时且不允许降级；非核心的 stock、recommend、notify 超时更短、允许降级；熔断器在 20 个请求样本里失败率超过 50% 就打开，打开 10 秒后进入半开，放 3 个探测请求试探恢复。

接着是 Deadline 传递的实现。入口处记录一个绝对截止时间，每次调下游前算剩余时间，剩余不够就直接降级，不再发起注定来不及的调用：

type Ctx = { deadline: number; traceId: string }; function remaining(ctx: Ctx): number { return ctx.deadline - Date.now(); } async function callWithBudget<T>( ctx: Ctx, name: string, timeoutMs: number, fn: (signal: AbortSignal) => Promise<T>, fallback: T ): Promise<T> { const left = remaining(ctx); if (left <= 0) return fallback; const budget = Math.min(timeoutMs, left); const controller = new AbortController(); const timer = setTimeout(() => controller.abort(), budget); try { return await fn(controller.signal); } catch (e) { return fallback; } finally { clearTimeout(timer); } }

注意Math.min(timeoutMs, left)这一行，它保证下游超时永远不超过上游剩余 Deadline，这是防止“上游已放弃、下游还在跑”的关键。AbortController的 signal 要一路透传到fetch，这样上游取消时下游请求也会终止，不再空占连接。

聚合入口的组装方式如下，核心依赖失败直接抛错，非核心依赖走降级：

async function dashboard(ctx: Ctx) { const [user, orders] = await Promise.all([ callWithBudget(ctx, "user-service", 500, (s) => getUser(s), null), callWithBudget(ctx, "order-service", 800, (s) => getOrders(s), null), ]); if (!user || !orders) throw new Error("core dependency failed"); const [stock, recommend, notify] = await Promise.all([ callWithBudget(ctx, "stock-service", 400, (s) => getStock(s), []), callWithBudget(ctx, "recommend-service", 400, (s) => getRecommend(s), []), callWithBudget(ctx, "notify-service", 200, (s) => getNotify(s), 0), ]); return { user, orders, stock, recommend, notify }; }

Circuit Breaker 用一个轻量实现即可，不必引入重框架。核心是三个状态和失败率统计，打开期间直接返回降级值，不再打下游：

class Breaker { private failures = 0; private total = 0; private state: "closed" | "open" | "half" = "closed"; private openedAt = 0; constructor(private cfg: { threshold: number; minReq: number; openMs: number }) {} allow(): boolean { if (this.state === "closed") return true; if (this.state === "open") { if (Date.now() - this.openedAt > this.cfg.openMs) { this.state = "half"; return true; } return false; } return true; // half-open 放少量探测 } record(ok: boolean) { this.total++; if (!ok) this.failures++; if (this.state === "half" && ok) { this.state = "closed"; this.failures = 0; this.total = 0; } if (this.total >= this.cfg.minReq && this.failures / this.total > this.cfg.threshold) { this.state = "open"; this.openedAt = Date.now(); } } }

把allow()判断放在callWithBudget之前，熔断打开时直接返回 fallback，请求连发都不发，这才是“快速失败”的意义。另外提醒一句，重试必须服从总预算：剩余 300ms 时不要再启动一个预计 800ms 的重试，否则重试风暴会把轻微故障放大成全面故障。重试只针对可恢复错误，加指数退避和随机抖动，次数封顶。

4. 验证请求与成功结果：压测一个下游变慢时接口是否守住预算

配置写完必须验证，否则你只是“看起来加了超时”。验证的核心动作只有一个：人为让一个非核心下游变慢，看主接口是否仍在预算内返回，且降级字段是空数组而不是 500。

先起一个可控的慢下游模拟。用一段简单脚本让推荐服务固定延迟 5 秒：

# 模拟 recommend-service 延迟 5s node -e ' const http = require("http"); http.createServer((req, res) => { setTimeout(() => { res.writeHead(200, {"Content-Type":"application/json"}); res.end(JSON.stringify([{id:1,title:"mock"}])); }, 5000); }).listen(9101, () => console.log("slow recommend on 9101")); '

把聚合接口的recommend-service地址指向http://127.0.0.1:9101，然后发请求并计时：

time curl -s http://127.0.0.1:8080/api/dashboard \ -H "x-trace-id: test-slow-recommend"

预期结果是：接口在 2000ms 预算内返回，recommend字段为[]，user和orders正常有值，HTTP 状态 200。如果返回 500 或者耗时超过 2500ms，说明降级没生效或 Deadline 没传下去。实测下来，最容易漏的是AbortController的 signal 没透传到fetch，导致超时了但请求还在后台跑。

再验证熔断。连续打 30 个请求，让推荐服务持续失败（把模拟脚本改成直接返回 500），观察日志里熔断器是否在失败率超阈值后打开，打开期间请求耗时应该骤降到几十毫秒，因为根本没发下游请求：

for i in $(seq 1 30); do curl -s -o /dev/null -w "%{http_code} %{time_total}\n" \ http://127.0.0.1:8080/api/dashboard done

成功的结果形态是：前若干个请求耗时较高（在等超时），熔断打开后耗时明显下降，接口始终返回 200 且降级字段为空。等 10 秒恢复窗口过后，把模拟服务改回正常，再打几个请求，应能看到半开探测成功后熔断关闭，推荐数据恢复。

最后验证核心依赖失败的行为。把order-service停掉，请求应返回明确的错误（比如 503 加错误码），而不是静默返回空订单——核心依赖不允许降级，这一点必须在测试里锁死。测试矩阵建议至少覆盖：非核心超时、核心失败、多个非核心同时失败、下游持续失败触发熔断、下游恢复后半开重连、上游取消后下游请求终止。普通测试“所有下游 100ms 全成功”几乎没有价值，因为它永远测不出故障边界。

5. 常见报错排查：401、local proxy failed、reading choices、OAuth 逐条对照

接入和改造过程中，报错基本集中在几类，逐条对照能快速定位。

401 Unauthorized最常见。先确认请求头是Authorization: Bearer $TAOTOKEN_API_KEY，Bearer 后面有一个空格；再确认 Key 没有过期或被删除，回控制台 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys 看一眼状态。如果 Key 是从别处复制来的，注意首尾不可见字符，用echo -n "$TAOTOKEN_API_KEY" | wc -c核对长度。

local proxy failed这类报错通常出现在客户端配置了本地转发但目标地址不通。检查 Base URL 是否严格写成 https://taotoken.net/api ，不要多加/v1或尾部斜杠；检查本机网络是否能正常访问该地址，用前面的curl命令单独验证，把客户端配置和网络问题分开定位。

reading choices报错一般意味着返回体结构和你代码里解析的字段对不上，常见于流式响应被中途截断或返回了错误对象。先打印原始响应体看error字段，再确认请求的 Model ID 在控制台模型列表里存在。如果用了流式，检查是否在finish_reason之前就关闭了连接。

OAuth相关报错多出现在 Claude Code 这类工具的登录环节。如果你是用 API Key 方式接入，就不该走 OAuth 流程，检查配置里是否误开了 OAuth 模式；如果是 CC Switch 管理多套配置，确认当前激活的 profile 里 Base URL、Key、Model ID 三件套齐全且互相匹配，切换后重启客户端让配置生效。

还有一个隐蔽的坑：Codex 改完代码后接口仍然超时，但日志显示每个下游耗时都正常。这时要查是不是Promise.all里混进了串行await，或者降级分支里又同步调了另一个慢服务。把每个下游的耗时、状态、是否超时、重试次数、traceId 都打进日志，聚合接口只记一个总耗时是排不出问题的。Trace ID 要从网关一路透传到最深层，否则你只能看到一堆孤立日志，还原不出“Dashboard 2.1s 里 Recommend 占了 1.8s 且 timeout”这种关键信息。

6. 把调用链规则固化下来：让 Codex 下次改聚合接口不再只盯“数据有没有返回”

改造完成后，最有价值的动作不是记住这次改了哪些代码，而是把规则写进项目里，让 Codex 后续每次动聚合接口都自动遵守。在仓库根目录放一个AGENTS.md，把下游调用规则写清楚：

# Downstream Call 规则 - 无依赖的下游请求优先并行 - 聚合接口必须区分核心与非核心依赖 - 所有外部调用必须配置明确超时 - 下游超时不得超过上游剩余 Deadline - 非核心服务失败必须评估降级 - 自动重试必须服从总时间预算，禁止无限重试 - 持续失败的下游必须评估 Circuit Breaker - 大量外部请求禁止无限 Promise.all 并发，需用并发池 - 每个下游必须记录耗时、状态、timeout、retryCount、traceId

有了这份规则，你下次让 Codex 改聚合接口时，它就不会只关注“所有数据最终有没有返回”，而会同时关注“需要在多久以内返回”。这两者的差别，就是稳定接口和雪崩接口的差别。

再补两个实战细节。第一，重要依赖考虑独立连接池和独立并发上限，别让推荐服务和支付服务共用一个 HTTP 连接池，否则推荐卡住会把支付也拖死，这就是 Bulkhead 隔舱思路。第二，非核心接口不要和核心接口同优先级，资源紧张时优先保登录、支付、订单，对推荐、统计、预加载更激进地超时、降级、限流。缓存也能帮大忙：商品分类、首页配置、推荐结果这类非实时数据，优先读缓存，下游失败时返回短时间旧缓存，业务允许的前提下能挡掉大量抖动。

如果你在验证模型返回、调试降级逻辑时需要快速对话确认，可以用模型对话 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=chat 直接试；接入细节和参数说明看文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc ；长期在微服务项目里做调用链治理和故障演练，Coding Plan https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan 的连续上下文会更省心。真正稳定的聚合接口，不是要求所有下游永远正常，而是推荐超时、通知故障时，核心业务仍能在明确时间内给用户一个可用结果。