2. 超时配置基础：超时定义、超时类型与系统稳定性影响

超时（Timeout）是 API Gateway 最基础也最关键的防御机制。它定义了系统等待某个操作完成的最长容忍时间——超过这个时间，Gateway 必须主动放弃等待并返回错误，而不是无限期阻塞资源。没有超时配置的 Gateway，本质上是一个“内存泄漏放大器”和“线程池黑洞”。

2.1 超时的本质定义

从系统视角看，超时是一个资源回收契约：

• 调用方视角：超时是客户端愿意等待响应的最大时长，超过即认为失败。
• 网关视角：超时是网关为每个请求分配的“生命周期预算”，超时后必须释放连接、线程、内存等资源。
• 后端视角：超时是上游服务处理请求的“死线”，网关不会无限等待慢响应。

2.2 三大超时类型详解

API Gateway 通常区分三种独立的超时维度，分别对应 TCP 连接建立、数据传输、响应写入三个阶段。下表总结了它们的差异：

2.3 连接超时（Connect Timeout）

连接超时控制的是 TCP 连接建立 的最大等待时间。当 Gateway 向后端发起 TCP 握手时，如果后端 IP 不可达、端口未监听、或网络发生丢包，连接超时就会触发。

• 典型场景：后端服务宕机、DNS 解析失败、防火墙丢包、网络分区。
• 配置建议：通常设为 500ms ~ 2s。内网服务建议 500ms，公网或跨区域服务可放宽到 2s。
• 常见错误：设为 0（无限等待）或超过 5s，会导致 Gateway 线程池被“死连接”快速填满。

2.4 读取超时（Read Timeout）

读取超时控制的是 从发送完请求到开始接收响应 的最大等待时间，也称为 Socket Timeout。这是最常被触发的超时类型，直接反映后端服务的处理速度。

• 典型场景：后端数据库慢查询、第三方 API 响应缓慢、业务逻辑死循环、GC 停顿。
• 配置建议：根据业务 SLA 设定。普通 API 建议 5s ~ 10s，文件导出或批量处理可放宽到 30s ~ 60s。
• 关键指标：P99 响应时间 × 2 ~ 3 倍，是读取超时的合理下限。

2.5 写入超时（Write Timeout）

写入超时控制的是 Gateway 向后端发送请求体 的最大时间。对于大请求体（文件上传、批量数据提交）场景尤为重要。

• 典型场景：大文件上传、请求体序列化慢、后端接收窗口过小。
• 配置建议：普通请求 1s ~ 3s；大请求体（>10MB）可放宽到 10s ~ 30s。
• 注意：写入超时通常不会单独触发，但如果后端 TCP 接收缓冲区满，写入操作会阻塞，此时写入超时能防止连接永久挂起。

2.6 超时对系统稳定性的影响

超时配置不当是导致 Gateway 级联故障的头号原因。下表总结了不同超时配置对系统稳定性的具体影响：

2.7 超时与资源泄漏的关联

超时配置直接决定 Gateway 的资源回收效率。以下是一个典型的资源泄漏链路：

1. 后端变慢：某个后端接口响应时间从 200ms 飙升到 30s。
2. 连接被占用：Gateway 的连接池中，所有连接都被这个慢请求占用。
3. 新请求排队：新请求无法获取连接，进入等待队列。
4. 线程池阻塞：等待连接的线程无法释放，线程池被占满。
5. 内存飙升：请求队列和线程栈占用大量内存，触发 GC 甚至 OOM。
6. 级联崩溃：Gateway 无法处理任何请求，整个系统不可用。

2.8 超时配置的黄金法则

基于以上分析，总结超时配置的核心原则：

• 分层配置：连接超时、读取超时、写入超时必须独立配置，不能混用。
• 值域递进：连接超时 < 写入超时 < 读取超时，通常比例为 1:2:5 ~ 1:3:10。
• 基于 SLA：读取超时 = 后端 P99 响应时间 × 2 ~ 3 倍，连接超时 = 网络 RTT × 3 ~ 5 倍。
• 动态调整：生产环境通过监控数据持续校准超时值，避免“一次配置，永远不变”。
• 兜底机制：全局超时作为最后防线，路由级超时作为精细化控制。