Go HTTP 服务超时怎么配：ReadHeaderTimeout、WriteTimeout 和 IdleTimeout 实战

用Go写HTTP服务的时候，很多项目初期图方便直接调用 http.ListenAndServe，本地跑起来顺得很，等上线碰到慢连接、客户端慢吞吞发请求体、响应写半天发不出去、长连接占满资源的情况，才会发现默认配置根本没做边界防护。更稳妥的方案是显式初始化 http.Server，顺着请求的整个生命周期配置 ReadHeaderTimeout、ReadTimeout、WriteTimeout 和 IdleTimeout。这些超时值绝对不是设得越短越好，核心是搞清楚每个超时规则管控的是哪一段运行流程。

HTTP 超时要按请求生命周期拆开看

服务端处理一次请求，并不是“收到请求然后返回响应”这么简单的单段流程。它至少要经过连接接入、读取请求头、读取请求体、业务逻辑处理、写出响应、长连接空闲等待几个阶段。不同阶段出现卡住的情况，对服务器资源的消耗影响也完全不一样。

比如有恶意客户端每隔几秒才发一点点请求头，业务代码根本没机会执行，但连接资源却一直被占着；也有客户端传超大请求体，后端还没走到业务逻辑就被拖得资源不足；还有场景是响应往慢客户端传输时长期阻塞。如果所有情况都用同一个超时值兜底，大概率会误伤正常业务接口。

一套普通接口可以先这样配

如果你的服务主要提供JSON API，没有长轮询、SSE、大文件上传下载这类场景，可以先用下面这类保守配置作为起点，后续再根据接口平均耗时、网关限制和客户端网络情况逐步调整。

package main

import (
    "log"
    "net/http"
    "time"
)

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) {
        w.WriteHeader(http.StatusOK)
        _, _ = w.Write([]byte("ok"))
    })

    srv := &http.Server{
        Addr:              ":8080",
        Handler:           mux,
        ReadHeaderTimeout: 3 * time.Second,
        ReadTimeout:       10 * time.Second,
        WriteTimeout:      15 * time.Second,
        IdleTimeout:       60 * time.Second,
    }

    log.Println("server listening on :8080")
    if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
        log.Fatal(err)
    }
}

这里给出的数值不是通用标准答案，只是用来演示超时字段的拆分逻辑。ReadHeaderTimeout 通常可以设得短一些，因为正常请求头体量很小，很快就能读完；WriteTimeout 要看接口响应体的大小和客户端网络环境；IdleTimeout 则和长连接复用策略、负载均衡的空闲超时配置强相关。

几个字段分别挡住什么问题

生产环境更建议先把 ReadHeaderTimeout 和 IdleTimeout 补上，再按接口类型的特性评估 ReadTimeout 和 WriteTimeout 的值。这样既能先挡住一部分低成本的慢连接攻击，又不容易直接把正常业务接口卡得太死。

不要把所有接口都套同一组值

最容易出问题的是流式接口和上传接口。比如 SSE、日志实时输出、AI 流式返回这类场景，本来就可能持续向外写数据很久；如果直接套用普通接口的 WriteTimeout: 15 * time.Second，哪怕是正常连接也可能被强制断开。文件上传、批量导入场景则会受到 ReadTimeout 的限制，移动网络和大文件场景下这个问题尤其明显。

这类接口可以分开处理：

• 普通 JSON API 使用统一的全局超时配置。
• 上传入口先限制请求体最大大小，再单独给更明确的上传时长预算。
• 流式响应单独设计心跳机制、最大连接时长和断线重连逻辑。
• 网关层和 Go 服务层的配置不要互相冲突，外层的超时值应该略大于内层业务的最大允许时长。

上线前用检查板过一遍

修改超时配置前，先找几条真实业务接口的历史日志核对：普通查询接口平均耗时多少，上传接口常见的请求体多大，响应体最大能到多大，客户端有没有开启长连接复用。凭感觉随便写一个统一的超时值，很容易把故障从“偶发慢连接占资源”变成“正常请求被意外截断”。

• 压测慢请求头场景：确认 ReadHeaderTimeout 能正常释放被占用的连接。
• 模拟大请求体上传：确认 ReadTimeout 不会误伤业务范围内允许的上传操作。
• 模拟慢客户端传输：观察 WriteTimeout 会不会提前截断合法的响应内容。
• 观察连接池指标：确认 IdleTimeout 和网关的空闲超时配置不会出现逻辑冲突。

常见问题

只设置 ReadHeaderTimeout 可以吗？

可以作为第一步优化方案，尤其是普通的API服务。它能解决慢请求头带来的连接占用问题，但请求体读取、响应写出和长连接空闲场景的防护，仍然需要其他字段配合完成。

ReadTimeout 和 ReadHeaderTimeout 会不会重复？

它们的管控范围不一样。ReadHeaderTimeout 只负责请求头读取这个阶段，ReadTimeout 覆盖的是从连接建立到完整读完整个请求的全流程时间。设置的时候要充分考虑请求体大小和业务允许的最大时长。

WriteTimeout 为什么会影响 SSE 或流式接口？

流式接口需要持续往外写响应数据，持续时间可能远超普通 API。如果全局的 WriteTimeout 设得太短，连接可能还没传完内容就被提前关闭。流式接口更适合单独设计心跳和最大连接时长逻辑。

这些超时应该放在 Nginx 还是 Go 服务里？

两边都需要配置合理的边界。网关负责外层连接和请求体大小的限制，Go 服务负责应用进程内部的读写时长预算。核心是两个层级的配置要协调，别让外层比内层更早截断还在正常运行的业务请求。

小结

Go HTTP 服务的超时配置，本质上是给请求生命周期的不同阶段划定合理边界。ReadHeaderTimeout 处理慢请求头问题，ReadTimeout 管控完整请求的读取时长，WriteTimeout 约束响应写出的最长时间，IdleTimeout 负责释放空闲的长连接。先按接口类型拆分配置规则，再结合日志和压测结果调整具体数值，比盲目直接抄网上的通用配置要稳妥得多。