Go / 系统课时
配置服务端超时
配置服务端超时
Go HTTP 服务端的超时不是一个统一开关。ReadHeaderTimeout、ReadTimeout、WriteTimeout 与 IdleTimeout 分别约束请求头、请求读取、响应写入和 keep-alive 空闲阶段。正确划分这些边界,可以阻止慢连接长期占用资源,也能避免正常上传或流式响应被误杀。
学习目标
- 说清四个服务端超时分别覆盖连接生命周期的哪一段
- 为普通 JSON API 配置一组可验证的基础超时
- 识别大请求体、流式响应与 keep-alive 场景中的配置边界
四个超时分别约束什么
ReadHeaderTimeout 只限制读取请求头的时间,适合尽早挡住迟迟不发完 Header 的连接;如果它为 0,会使用 ReadTimeout 的值。ReadTimeout 限制读取整个请求的时间,包括请求体,因此大文件上传或低速客户端需要特别评估。
WriteTimeout 限制响应写入能够持续的时间,并在读取到新请求头时重置写截止时间。它适合普通短响应,但对 SSE、流式下载等长时间持续写入场景可能过于严格。IdleTimeout 则限制 keep-alive 连接在两次请求之间等待下一次请求的空闲时间,它不是单次 Handler 的执行超时。

为普通 API 建立基础配置
下面是一个完整可运行的 HTTP 服务。示例假设接口主要处理较小的 JSON 请求与短响应,因此给请求头较短预算,同时让读取请求体和写响应拥有更宽松的窗口。具体数值不是通用答案,应根据接口负载、客户端网络和延迟目标调整。
package main
import (
"fmt"
"net"
"net/http"
"time"
)
func main() {
mux := http.NewServeMux()
mux.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "text/plain; charset=utf-8")
_, _ = fmt.Fprintln(w, "ok")
})
srv := &http.Server{
Handler: mux,
ReadHeaderTimeout: 2 * time.Second,
ReadTimeout: 10 * time.Second,
WriteTimeout: 15 * time.Second,
IdleTimeout: 60 * time.Second,
}
// 使用随机空闲端口,避免示例与本机已有服务冲突。
ln, err := net.Listen("tcp", "127.0.0.1:0")
if err != nil {
panic(err)
}
fmt.Printf("listening on http://%s\n", ln.Addr())
if err := srv.Serve(ln); err != nil && err != http.ErrServerClosed {
panic(err)
}
}预期输出:
listening on http://127.0.0.1:<PORT><PORT> 是系统分配的空闲端口,实际值每次可能不同。程序会持续监听,直到进程被停止。这里显式创建 http.Server,让四类超时边界都在服务入口处可见并可审查,而不是依赖没有这些字段配置入口的便捷启动函数。
根据请求形态调整边界
普通 JSON API 通常可以设置较短的 ReadHeaderTimeout,再根据最大请求体和允许的上传速度决定是否启用固定 ReadTimeout。如果请求体可能很大,过短的 ReadTimeout 会把正常上传当成慢请求;此时更适合保留请求头保护,并针对具体 Handler 设计请求体大小、速率和截止时间策略。
流式响应要重点检查 WriteTimeout。SSE、持续下载或其他长时间写连接可能天然超过普通 API 的写入窗口,不能直接照搬短请求配置。若选择放宽甚至关闭该值,就应由更细粒度的应用协议、连接管理和上游代理超时继续承担保护责任。
IdleTimeout 主要控制 keep-alive 连接复用成本。值太短会降低连接复用率,值太长则会让大量空闲连接占用资源。还要同时核对反向代理、负载均衡器和客户端的超时,因为一条请求链最终能活多久,取决于链路中最先到期的那个边界。