📚 课程目录第4章超时配置

超时配置：不同语言/框架中如何设置超时参数

说白了，超时配置就是给你的SDK设置一个“忍耐极限”。

我之前在维护一个Java网关服务时，发现下游接口偶尔会卡住整个线程池。查了半天，原来是HTTP客户端的连接超时没设，默认是0——永不超时。这问题很典型，很多新手会把超时参数当摆设。

今天咱们就把主流的语言和框架挨个捋一遍。你想想看，无论你用Python、Java、Go还是Node.js，超时配置的套路其实就那几样：连接超时、读取超时、写入超时，有的还额外给个“总超时”。不同地方名字不一样，但心思是一样的。

超时参数的“三层结构”

在具体讲语言之前，我先画个图，帮你快速看清超时配置的整体脉络。这三个层次你只要记住了，换什么语言都不会慌。

我个人习惯：先定好“连接超时 + 读取超时”这对组合，这两个参数能覆盖 95% 的异常场景。写超时其实大部分SDK都内置了缓冲区机制，单独配置的场景不多。

Python 中的超时配置

Python 这块我踩过不少坑，尤其 requests 库。以前写爬虫时总超时，后来才反应过来——requests 的 timeout 参数默认是 None，意味着永远不超时。

import requests

# 推荐写法：显式设置 (连接超时, 读取超时)
resp = requests.get('https://api.example.com', timeout=(3, 5))

# 只设一个值则同时作用于连接和读取
resp = requests.get('https://api.example.com', timeout=5)

# 如果用的是 httpx，写法也类似
import httpx
with httpx.Client(timeout=httpx.Timeout(5.0, connect=3.0)) as client:
    resp = client.get('https://api.example.com')

注意：Python 的 timeout 元组第一个元素是连接超时，第二个是读取超时。反过来写的话，你的读取超时可能会短得离谱——我就犯过这毛病。

除了 HTTP 调用，数据库连接池的超时也要留意。比如 psycopg2 连接 PostgreSQL：

import psycopg2

conn = psycopg2.connect(
    host='db.example.com',
    connect_timeout=10,   # 连接超时 10 秒
    options='-c statement_timeout=5000'  # 查询超时 5 秒
)

我曾经在线上环境把 connect_timeout 设成了 3 秒，刚好赶上数据库主从切换，连接恢复花了 4 秒——全挂了。建议连接超时不要低于 5 秒，除非你明确知道网络延迟。

Java / Spring Boot 中的超时配置

Java 这边，如果你直接用 HttpURLConnection，记得设 setConnectTimeout 和 setReadTimeout。但现在大多用 RestTemplate 或 WebClient。

// Spring Boot 中使用 RestTemplate
RestTemplate restTemplate = new RestTemplate();
SimpleClientHttpRequestFactory factory = new SimpleClientHttpRequestFactory();
factory.setConnectTimeout(3000);  // 3秒
factory.setReadTimeout(5000);     // 5秒
restTemplate.setRequestFactory(factory);

// 或者用 OkHttp，更现代的方式
OkHttpClient client = new OkHttpClient.Builder()
    .connectTimeout(3, TimeUnit.SECONDS)
    .readTimeout(5, TimeUnit.SECONDS)
    .writeTimeout(5, TimeUnit.SECONDS)
    .build();

Spring Cloud 中 Feign 客户端的超时配置也值得注意：feign.client.config.default.connect-timeout=3000，但如果你用了 Hystrix，那个熔断超时可能会覆盖 Feign 本身的读取超时，需要分别配。

Go 的超时配置

Go 的标准库 net/http 留了个 http.Client，它的 Timeout 字段是整个请求的超时。但很多新手会忽略 Transport 里的 DialContext 超时。

client := &http.Client{
    Timeout: 10 * time.Second,  // 总超时，包含连接+读取
    Transport: &http.Transport{
        DialContext: (&net.Dialer{
            Timeout:   3 * time.Second, // 连接超时
            KeepAlive: 30 * time.Second,
        }).DialContext,
    },
}

// 更地道的做法：用 context 控制超时
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
req, _ := http.NewRequestWithContext(ctx, "GET", "https://api.example.com", nil)
resp, err := client.Do(req)

我个人偏爱 context 的方式，因为可以跟上下游链路共享一个超时上下文，不会出现“连接超时3秒，但读取超时10秒”这种割裂问题。

Node.js / JavaScript 的超时配置

Node.js 的 axios 和 node-fetch 配置方式略有不同，核心思想一致。

// axios 写法
const resp = await axios.get('https://api.example.com', {
    timeout: 5000,                // 总超时 5s（包括连接和响应）
    transitional: {
        silentJSONParsing: true
    }
});

// 原生 http.request
const options = {
    hostname: 'api.example.com',
    port: 443,
    path: '/',
    method: 'GET',
    timeout: 5000                 // 注意：这个 timeout 是“空闲超时”
};
const req = http.request(options);
req.setTimeout(5000, () => {
    req.destroy(new Error('Request timeout'));
});

我之前用 Node.js 的 http.request 时，只设了 options.timeout，结果在 TLS 握手环节因证书验证过慢超时了，但那个 timeout 只针对连接空闲，不覆盖握手阶段。一定要同时监听 socket.setTimeout 或者用 req.setTimeout 手动补一刀。

各语言超时参数速查表

我整理了一张表，方便你写代码时快速参考。

语言/框架	连接超时	读取超时	总超时	常用方法/类
Python requests	`timeout=(con, read)`	同上（元组第二位）	无独立总超时	`requests.get(timeout=(3,5))`
Spring RestTemplate	`setConnectTimeout`	`setReadTimeout`	无	`SimpleClientHttpRequestFactory`
OkHttp	`connectTimeout`	`readTimeout`	无（可结合拦截器）	`OkHttpClient.Builder`
Go http.Client	`DialContext.Timeout`	总超时与读取共用	`Client.Timeout`	`Transport.DialContext`
Node.js axios	合并到`timeout`	合并到`timeout`	`timeout`	`axios({timeout:5000})`
Rust reqwest	`connect_timeout`	`timeout`（总超时）	`timeout` 覆盖读取	`reqwest::Client::builder()`

核心原则：连接超时一般设 2~5 秒，读取超时视业务特性而定（普通 API 5~30 秒，文件上传可能更长）。总超时最好在调用方（context/线程池）层面统一把控，而不是依赖 SDK 内部参数。

跨语言的避坑指南

默认值陷阱：Python requests 默认超时为 None，Java HttpURLConnection 默认 0（无限等待），Go http.Client 默认也为 0。只要你不写，它就是“永远等”。
单位混淆：Java 用毫秒，Go 用 Duration（秒/毫秒可灵活写），Node.js 用毫秒。我见过有人把毫秒当秒写，直接导致连接超时变成 3 毫秒——服务完全不可用。
超时叠加：如果你同时设了客户端超时、转发层超时（Nginx/Envoy）和业务超时，最小的那个会先生效。别让内层比外层大，否则外层卡死内层。
DNS 超时：很多 SDK 不单独提供 DNS 解析超时参数。Go 的 net.Dialer 默认 10 秒，Python 的 socket 默认全局解析超时，可以手动调 socket.setdefaulttimeout(3)。

我推荐你在项目启动时打印一份“SDK 超时配置清单”，把连接超时、读取超时、总超时、重试等待时间都列出来，方便线上排查。配置中心统一管理优于硬编码。

好了，不同语言怎么设超时就聊到这儿。记住那个三层结构图，换任何语言都是查参数名的事。真正关键的是：你得在真实场景里跑一下，看看设了超时后，到底能不能优雅降级。