4. 超时问题全景分析：网络超时、服务端超时、客户端超时、超时导致的重复请求
在异步导出任务中，超时是触发重复请求与幂等性校验失效的首要诱因。超时并非单一现象，而是横跨网络传输、服务端处理、客户端等待三个维度的复合问题。本章从全景视角拆解每一类超时的成因、表现与连锁反应，为后续设计幂等性方案奠定基础。
4.1 超时问题的三维分类
超时按发生位置可分为三类：网络超时、服务端超时、客户端超时。三者相互独立又可能级联触发，最终导致客户端发起重复请求。
| 超时类型 | 发生位置 | 典型触发条件 | 对幂等性的影响 |
|---|---|---|---|
| 网络超时 | 传输链路（网关、负载均衡、DNS） | 丢包、带宽瓶颈、连接池耗尽 | 请求已到达服务端但响应未返回，客户端重试导致重复 |
| 服务端超时 | 应用层（业务逻辑、数据库、队列） | 慢查询、资源争抢、死锁、GC停顿 | 任务实际已创建但未及时应答，客户端重试产生重复任务 |
| 客户端超时 | 调用方（SDK、浏览器、定时器） | 连接超时设置过短、线程阻塞、用户主动刷新 | 客户端不等响应直接重试，造成服务端重复处理 |
关键认知：超时不等同于失败。网络超时和服务端超时发生时，请求可能已经在服务端被成功处理。客户端仅因未收到响应而重试，是幂等性校验必须覆盖的核心场景。
4.2 网络超时：最隐蔽的重复请求源头
网络超时发生在请求或响应报文在传输途中丢失、延迟或阻塞。常见场景包括：
- TCP 连接超时：三次握手未完成，客户端抛出
connect timeout。 - 读取超时：服务端已写入响应，但网络拥塞导致客户端迟迟收不到数据，触发
read timeout。 - 网关/代理超时：Nginx、Kong 等网关在 upstream 响应超时后返回 504，但上游服务实际已完成处理。
网络超时的核心风险在于：服务端无法感知客户端是否收到响应。即使服务端正确返回了 200，只要网络层截断了报文，客户端就会认为请求失败并重试。
4.3 服务端超时：业务处理时间超出预期
异步导出任务的服务端超时通常发生在任务创建阶段或任务执行阶段：
- 任务创建接口超时：数据库写入慢、队列推送阻塞、文件系统锁等待，导致 API 响应时间超过客户端设置的超时阈值。
- 任务状态查询超时：轮询任务进度时，服务端因查询量过大或缓存失效而响应缓慢。
- 导出执行超时：后台任务本身因数据量大、资源不足而执行超时，但此超时通常由服务端内部监控处理，不直接触发客户端重试。
避坑提示：服务端超时后，如果任务创建接口采用了“先写入再返回”的模式，那么即使接口超时，任务记录已经持久化。客户端重试时若未携带幂等键，将产生两条相同的导出任务。
4.4 客户端超时：调用方的自我保护与误判
客户端超时是调用方主动设置的等待上限，常见于以下配置：
| 客户端类型 | 超时参数 | 默认值（常见） | 重试行为 |
|---|---|---|---|
| HTTP 客户端（OkHttp） | connectTimeout / readTimeout | 10s / 30s | 抛出异常，由业务层决定是否重试 |
| 浏览器 Fetch API | signal + AbortController | 无默认值 | 用户手动刷新或前端自动重试 |
| 微服务 RPC（gRPC） | deadline | 无默认值，建议设置 | 客户端拦截器自动重试（需配置） |
| 定时任务调度器 | 任务执行超时 | 取决于框架 | 标记失败并重新调度 |
客户端超时设置过短会频繁触发重试，过长则影响用户体验。在异步导出场景中，建议客户端超时时间至少为服务端 P99 响应时间的 3 倍，以减少误判。
4.5 超时导致的重复请求链路
下图展示了从超时发生到重复请求产生的完整链路：
4.6 超时与幂等性的关键关联
从全景分析可以提炼出以下与幂等性设计直接相关的结论：
- 超时是重复请求的最大诱因：超过 70% 的重复请求源于客户端超时或网络超时后的重试，而非业务逻辑错误。
- 服务端无法区分超时与失败：服务端收到重试请求时，无法判断是因为超时还是真正的业务失败，必须依赖幂等键进行去重。
- 幂等键必须在首次请求时生成：客户端在发起首次请求前就应生成全局唯一的幂等键（如 UUID），并随请求发送。重试时携带相同的幂等键。
- 超时时间与幂等键有效期需联动：幂等键的保留时间应大于客户端最大重试窗口 + 网络最大延迟，否则重试到达时幂等键已过期，导致重复创建。
设计原则：在异步导出系统中，应将超时视为“不确定状态”，而非“失败状态”。所有超时后的重试请求必须携带幂等键，服务端通过幂等键判断请求是否已被处理，从而避免重复创建导出任务。
4.7 超时场景下的幂等性校验时机
下图展示了在超时发生后，幂等性校验在请求处理流程中的正确介入位置：
4.8 本章小结
- 超时分为网络超时、服务端超时、客户端超时三类，每一类都可能独立触发重复请求。
- 网络超时是最隐蔽的重复请求源头，服务端无法感知响应是否到达客户端。
- 客户端超时设置过短会频繁误判，建议基于服务端 P99 响应时间合理配置。
- 超时后的重试请求必须携带幂等键，幂等校验应在业务逻辑执行之前完成。
- 幂等键的有效期需覆盖客户端最大重试窗口与网络最大延迟之和。