Go / 系统课时
配置 Server 的超时边界
配置 Server 的超时边界
公开 HTTP 服务不能让客户端无限期占用连接。本节聚焦四类 http.Server 超时,说明它们分别约束请求头、请求读取、响应写入与空闲等待,并给出可运行配置。
学习目标
- 区分
ReadHeaderTimeout、ReadTimeout、WriteTimeout与IdleTimeout - 用显式
http.Server配置基础超时边界 - 避免把连接超时误当成业务 Handler 的执行超时
四个超时分别拦什么
ReadHeaderTimeout 专门限制读取请求头的时间,适合尽早挡住缓慢发送请求头的连接。ReadTimeout 限制读取完整请求的时间,包括请求体,因此上传接口或慢速网络场景不能照搬很小的值。WriteTimeout 为响应写入设置截止边界,但它不是“Handler 最多只能运行多久”的通用定时器。IdleTimeout 则限制 Keep-Alive 连接等待下一次请求的空闲时间。

其中两个零值有继承关系:ReadHeaderTimeout 为零时会使用 ReadTimeout;IdleTimeout 为零时也会使用 ReadTimeout。如果相关值最终都没有提供有效超时,就可能没有对应边界,因此面向公网的服务通常更适合显式创建 http.Server。
建立有边界的 Server
下面的程序在随机本地端口启动服务,设置四个超时,然后主动请求 /health 验证正常请求仍能完成。随机端口避免与本机已有服务冲突。
package main
import (
"context"
"fmt"
"io"
"net"
"net/http"
"time"
)
func main() {
mux := http.NewServeMux()
mux.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
_, _ = io.WriteString(w, "ok\n")
})
srv := &http.Server{
Handler: mux,
ReadHeaderTimeout: 2 * time.Second,
ReadTimeout: 5 * time.Second,
WriteTimeout: 5 * time.Second,
IdleTimeout: 30 * time.Second,
}
ln, err := net.Listen("tcp", "127.0.0.1:0")
if err != nil {
panic(err)
}
go func() {
if err := srv.Serve(ln); err != nil && err != http.ErrServerClosed {
panic(err)
}
}()
fmt.Printf("listening=%s\n", ln.Addr().String())
client := &http.Client{Timeout: 2 * time.Second}
resp, err := client.Get("http://" + ln.Addr().String() + "/health")
if err != nil {
panic(err)
}
body, err := io.ReadAll(resp.Body)
resp.Body.Close()
if err != nil {
panic(err)
}
fmt.Printf("status=%s body=%s", resp.Status, body)
ctx, cancel := context.WithTimeout(context.Background(), time.Second)
defer cancel()
if err := srv.Shutdown(ctx); err != nil {
panic(err)
}
}预期输出
listening=127.0.0.1:<PORT>
status=200 OK body=ok<PORT> 是系统分配的实际端口,每次运行可能不同。正常请求远小于配置的超时,因此会得到 200 OK;真正的慢连接则会在命中的读写阶段受到对应截止时间约束。
超时值要跟请求类型一起定
短请求 API 可以给请求头较紧的边界,并让读写超时覆盖正常高分位延迟再留出余量。上传接口要重点评估 ReadTimeout,因为较大的请求体可能合法地读取很久;流式下载则要谨慎设置 WriteTimeout,否则长时间持续输出可能被服务器截止。
IdleTimeout 过短会让客户端频繁重新建连,过长则会保留更多空闲连接。生产环境不要照抄某组秒数,应该结合请求大小、网络条件、反向代理超时和延迟分位数一起调整,并通过连接数、超时错误和请求耗时指标验证。
不要把连接超时当成业务超时
WriteTimeout 主要约束网络写入的截止时间,并不会安全地中止任意阻塞的业务逻辑。数据库查询、RPC 调用和长计算仍应依赖请求 Context、下游客户端超时或业务层截止时间,让取消信号能够真正传递到耗时操作。
合理的 Server 超时不是把所有时间都设得很短,而是让每个阶段都有明确边界,同时不给正常慢请求制造误伤。