如何为经代理的 API 请求拆分和验证超时预算
经代理的 API 请求需要区分客户端实际支持的连接、读取和端到端超时。本文说明如何按客户端版本记录超时覆盖范围、安排总 deadline 与重试，并用阶段日志定位延迟来源。
代理 API 请求可能在 DNS 解析、建立连接、TLS 握手、等待首字节或读取响应时耗尽时间。将总超时拆分到这些阶段，并计入代理认证与重试开销，可以根据失败阶段定位延迟来源，也能避免单次请求无限占用资源。
API 请求总超时由哪五段组成
以下阶段用于分析一次请求的耗时，并不代表客户端都能为每段单独配置超时。应选定客户端及版本，核对其连接池等待、DNS、TCP、代理协商、TLS、写入、读取和端到端 deadline 参数实际覆盖哪些阶段。HTTP 代理的接入背景可参考HTTP 代理指南。
- 耗时阶段：连接池等待 ｜ 可观测字段：排队/获取连接耗时 ｜ 客户端参数需核对的范围：是否有独立 pool-acquire 超时 ｜ 证据边界：按客户端库诊断信息记录
- 耗时阶段：DNS 与 TCP ｜ 可观测字段：解析、到代理的 TCP 建连时间 ｜ 客户端参数需核对的范围：是否由 connect timeout 覆盖，是否能分开配置 ｜ 证据边界：代理模式下客户端通常连接代理；目标解析位置依协议和实现确认
- 耗时阶段：代理协商与 TLS ｜ 可观测字段：CONNECT/认证结果、TLS 握手时间 ｜ 客户端参数需核对的范围：客户端是否暴露独立阶段超时 ｜ 证据边界：TLS 隧道内内容对普通代理不可见
- 耗时阶段：请求写入 ｜ 可观测字段：写入耗时、发送字节 ｜ 客户端参数需核对的范围：是否有 write timeout ｜ 证据边界：按客户端实际参数与传输事件记录
- 耗时阶段：响应等待与读取 ｜ 可观测字段：首字节时间、读取间隔与响应体耗时 ｜ 客户端参数需核对的范围：read timeout 是阶段总时长还是无数据间隔 ｜ 证据边界：结合响应头、首字节和读取中断事件说明
- 耗时阶段：端到端调用 ｜ 可观测字段：从逻辑调用开始到返回/取消 ｜ 客户端参数需核对的范围：是否有单一总 deadline ｜ 证据边界：应覆盖排队、解析、认证、传输、重试和退避
阶段日志有助于缩小延迟范围，但只有客户端确实支持相应参数时才能单独设定阶段超时。read timeout 可能表示连续无数据的等待上限，而非整个响应读取时长；应按库文档说明，并验证超时或取消后连接与响应资源是否释放。
为什么代理请求超时应参考 p95 和 p99
平均值可能掩盖长尾。预算可以参考端到端耗时分布、目标失败率和资源约束，并报告样本量与采样窗口；各阶段 p95/p99 可辅助分配预算，但不能简单相加后当作端到端同分位数保证。
阶段预算应结合实测分布、客户端参数语义和业务失败容忍度设定，并定期用新样本复核。超时请求属于截尾样本，应记录失败与超时情况，不能只用成功请求估算分布。不同代理产品或出口类型的耗时差异需要在相同客户端、目标、并发和时段条件下实测，不能预设动态出口必然慢于静态出口。
代理连接和重试会怎样增加请求总耗时
一次逻辑调用的总耗时包括排队、每次尝试的解析与传输、认证处理、重试间隔和退避。应区分“总尝试次数”和“额外重试次数”：例如最多重试三次通常意味着初次尝试加三次重试，而不是总共三次。记录每次实际耗时和退避时间，避免表格与说明使用不同口径。
端到端 deadline 应从逻辑调用开始只创建一次，并包含连接池等待、每次尝试、退避和取消时间。每个阶段的可用时限取阶段上限与剩余总预算中的较小值；不得在重试时重置总 deadline。认证失败和参数错误通常不应盲目重试，是否重试需按客户端和服务契约确认。
错误类型可以帮助定位超时发生的阶段
超时名称只能说明客户端报告的等待阶段，不能单独确定责任方。read timeout 可能发生在等待响应头/首字节之前，也可能发生在读取响应过程中；407 是代理认证响应，不是连接超时。遇到 502/504 应记录实际返回组件。通过客户端阶段事件、代理日志和源站记录核实候选原因。
把错误类型与阶段对照起来，排查就不用从零开始猜。建议在客户端日志里同时记录阶段与耗时字段，而不是只记一个总耗时。
端到端验证如何检查预算并触发降级
若客户端不支持每段独立超时，就记录它能配置的参数及未覆盖阶段，并使用一次性的端到端 deadline 控制逻辑调用。总 deadline 应与上游调用方的时限协调，预留处理和返回结果的时间；超时或取消后还要检查请求是否继续占用连接或资源。
部分可用场景下，可以先返回部分结果并标注缺失，而不是整体失败。
校验的对象是总预算，不是降级逻辑：构造慢响应与断流场景，确认总时限在预期内触发，并记录实际触发的是哪一段。
以下数值仅用于说明如何记录阶段预算，并不代表通用参数或某个客户端一定支持这些独立设置。实际字段应按选定客户端及版本替换；无法独立配置的阶段标为“由其他参数覆盖”或“不可单独设置”。
- 参数/阶段：连接池等待 ｜ 示例记录值：由客户端配置确认 ｜ 计时语义：获取连接前的排队时间 ｜ 客户端版本与覆盖范围：填写实际参数或“不支持独立设置”
- 参数/阶段：connect timeout ｜ 示例记录值：由客户端配置确认 ｜ 计时语义：TCP/代理连接阶段，具体范围查版本文档 ｜ 客户端版本与覆盖范围：记录是否包含 DNS 或代理协商
- 参数/阶段：read timeout ｜ 示例记录值：由客户端配置确认 ｜ 计时语义：可能是无数据等待间隔，不一定是整个响应期限 ｜ 客户端版本与覆盖范围：记录首字节前与读取中的行为
- 参数/阶段：总 deadline ｜ 示例记录值：由业务目标确认 ｜ 计时语义：从逻辑调用发起到完成/取消，仅创建一次 ｜ 客户端版本与覆盖范围：包含全部尝试和退避
- 参数/阶段：重试 ｜ 示例记录值：明确初次尝试 + 额外重试次数 ｜ 计时语义：每次记录耗时与退避 ｜ 客户端版本与覆盖范围：受同一个总 deadline 限制
FAQ
为什么平均耗时不能用来定预算？
平均值被少数快请求拉低，掩盖了长尾。超时设计关心的是最慢的那部分请求，必须看 p95 与 p99，并说明采样窗口。
代理超时和上游超时怎么区分？
407 表示代理认证挑战，不代表代理连接超时。应核对客户端实际连接阶段和响应来源，再对齐代理及目标服务日志；没有首字节可能涉及上游处理、代理转发、TLS/协议协商或中间层排队，不能仅凭等待阶段归因。
重试次数该怎么算进预算？
先明确总尝试次数等于初次尝试加额外重试次数。每次尝试和退避都消耗同一个端到端 deadline 的剩余时间；阶段预算取自身上限与剩余 deadline 的较小值。若客户端没有总 deadline，只能将多次尝试的放大作为该配置的风险示例，不能和有总 deadline 的策略混用。
记录各阶段耗时后，可以判断瓶颈出现在解析、代理连接还是上游响应。原 TLS/超时排障和重试策略链接当前返回 404；可先依据本文所列客户端版本文档核对具体参数，待站内存在有效专题页后再补充内链。