📚 课程目录第3章超时参数配置

超时参数的“三驾马车”：timeout、connectTimeout、readTimeout

讲重试机制，绕不开超时配置。你想想看，没有超时的重试，就像没有刹车的赛车，一旦网络卡住，请求就会无限挂起，线程池瞬间被打满。我见过不少线上事故，最后定位下来，就是超时配得太糙导致的。

这一节我们专门掰扯一下三个最核心的超时参数：connectTimeout、readTimeout，还有很多框架提供的总 timeout。它们各管一摊，千万别混用。

1. 概念辨析：三个超时各管什么

首先得搞清楚，一次HTTP请求到底分几个阶段。我习惯把它拆成建立连接和传输数据两个大阶段。connectTimeout控的是前者，readTimeout控的是后者。总timeout呢？它就是整个请求的保底死线。

参数	作用阶段	通俗解释
connectTimeout	TCP三次握手	跟对方说“在吗”，多久没回话就算失联
readTimeout	读取响应数据	对方说“我在”，但话一直没说完，等你多久
timeout (总超时)	全链路	从问出第一句到最后收到答案，总时长上限

说白了，connectTimeout解决的场景非常具体：服务器宕机、IP不可达、防火墙丢包。readTimeout解决的是另一种：服务器连上了，但处理太慢，或者数据量太大传不过来。总timeout则是一道不可逾越的墙，防止前两个参数都没兜住的情况。

我的一个小习惯：在非极端场景下，总timeout ≈ connectTimeout + readTimeout + 余量。余量通常是500ms到1s，用来补偿DNS解析和SSL握手的时间。别问我为什么，吃过大亏。

2. 配置策略：给每个参数一个合理的值

很多新手喜欢把三个参数设成一样的值，比如全都设成10秒。这其实挺浪费的。你想想看，连接超时如果用了10秒，那么是得有多差的网络环境才会让TCP握手超过10秒？而在内网环境中，连接超时超过3秒基本上就是异常了。

我在项目中遇到过一个典型事故：我们的SDK调用内部网关，connectTimeout设了5秒，readTimeout设了30秒。结果网关某次发布后，接口响应时间飙到20多秒。所有客户端线程都被readTimeout卡住，最终导致雪崩。如果当时把readTimeout压在10秒以内，损失会小很多。

这里给出我推荐的配置参考值：

环境	connectTimeout	readTimeout	总timeout
本地内网（机房）	500ms - 1s	2s - 5s	3s - 6s
同区域公网	1s - 3s	5s - 10s	8s - 15s
跨区域/弱网	3s - 5s	10s - 30s	15s - 45s

我曾经踩过的坑：把connectTimeout设得比readTimeout还大。想象一下，连接用了8秒才建立，然后readTimeout只有3秒，数据还没传完就直接超时了。connectTimeout的作用是快速失败，原则上要比readTimeout小。

3. 代码级配置示例

光说理论没意思，咱们来看看代码。以Java的Apache HttpClient和OkHttp为例，这两个是SDK里最常用的HTTP客户端。嗯，这里要注意的是，不同框架对参数的命名可能不一样，但本质是一样的。

// Apache HttpClient 示例
RequestConfig config = RequestConfig.custom()
    .setConnectTimeout(3000)       // 连接超时 3 秒
    .setSocketTimeout(10000)       // 读取超时 10 秒 (注意这里叫SocketTimeout)
    .setConnectionRequestTimeout(2000) // 从连接池获取连接的超时
    .build();

CloseableHttpClient httpClient = HttpClients.custom()
    .setDefaultRequestConfig(config)
    .build();

// OkHttp 示例
OkHttpClient client = new OkHttpClient.Builder()
    .connectTimeout(3, TimeUnit.SECONDS)       // 连接超时
    .readTimeout(10, TimeUnit.SECONDS)         // 读取超时
    .writeTimeout(10, TimeUnit.SECONDS)        // 写入超时 (上行的读取，一般配成和readTimeout一样)
    .build();

看到writeTimeout了吗？OkHttp多了一个参数。其实writeTimeout和readTimeout是对称的，一个管发请求，一个管收响应。SDK中如果请求体很大（比如上传文件），writeTimeout也要配一下。

4. 三种超时的关系：一张图看明白

咱们用一张SVG图来梳理一下这三个参数在时间轴上的位置。搞清楚这个，配置的时候心里就有谱了。

5. 常见误区与最佳实践

最后说说我见过的一些典型配置错误。嗯，这些坑几乎每个团队都会踩一遍。

误区一：三个超时配成一样。这样等于只做了一个总超时，失去了分阶段控制的灵活性。连接慢和数据传输慢，其实代表完全不同的故障类型。
误区二：connectTimeout设置过大。我曾经在某个老系统里看到connectTimeout设成了120秒，运维说是为了防止偶发网络抖动。结果一次机房断电，所有请求都卡在连接阶段，耗时两分钟才超时。连接超时应该重试，而不是傻等。
误区三：忽略writeTimeout。如果你的SDK有上传功能，writeTimeout不配，可能导致请求体还没发完就触发了readTimeout。这种错误特别隐蔽。

我的最佳实践总结：

总timeout作为兜底，比connectTimeout + readTimeout多20%左右。
connectTimeout尽量短，500ms到3秒之间，失败就快速重试。
readTimeout根据接口的P99响应时间来定，留一些余量。
所有超时参数做成可配置的，不要硬编码。线上环境需要根据实际情况做微调。

记住，超时参数不是一次配好就万事大吉的。随着业务迭代和网络环境变化，这些值需要定期审视。我建议每次大版本发布前，都检查一下SDK的超时配置是否还跟得上现状。