凌晨两点,一个后台任务突然不动了。日志停在「开始调用对账接口」这一行,之后没有任何输出,进程还在,CPU 接近零。运维重启后任务恢复正常,第二天同一时间又卡住。查到最后,原因很简单:创建 HTTP 客户端时没设超时,对方服务那天恰好不响应,连接一直挂着,goroutine 也就一直等下去。

Go 的 net/http 用起来非常省事:服务端一个函数就能起,客户端一行 http.Get 就能发。但它的默认值几乎都是「不限制」:客户端没有超时,服务端没有读写超时,响应体必须自己关,连接复用有前提。这些默认值在本地开发时毫无存在感,一上生产就会以「卡住、连接泄漏、端口耗尽」的形式出现。

这篇分两部分:上半讲 HTTP 的服务端和客户端,重点是超时、请求体大小和连接复用;下半讲更底层的 TCP socket,重点是流式读写没有消息边界。最后给一张按现象定位的排查表。

默认没有超时,是很多故障的起点

先看两个默认值。本机 go1.27.3 打印出来:

fmt.Println("DefaultClient.Timeout:", http.DefaultClient.Timeout)
fmt.Println("空 Server 的 ReadTimeout:", (&http.Server{}).ReadTimeout)
DefaultClient.Timeout: 0s
空 Server 的 ReadTimeout: 0s

两个 0 都表示「永远不超时」。客户端的 Timeout 覆盖整个请求,包括建立连接、写请求、等响应头、读响应体;服务端的 ReadTimeout 是从连接建立起,到读完请求体的最长时间。没有这个限制,一个不说话的客户端可以一直占着连接,一个不响应的下游可以让调用方无限等待。

正确做法是两边都显式设置。客户端用 &http.Client{Timeout: 5 * time.Second},或者更细地用 context.WithTimeout 控制单次请求。服务端至少设 ReadHeaderTimeout,防止慢速发送请求头的攻击;再按业务设置 ReadTimeout、WriteTimeout、IdleTimeout。

不要依赖 http.DefaultClient。它是全局共享的,任何一处代码改了它的 Transport 或 Timeout,都会影响整个进程。自己构造一个 Client,把它作为依赖传下去,比到处用包级函数可控得多。

服务端几个超时参数各管一段,别混着设。ReadHeaderTimeout 只管请求头读完为止,用来防慢速攻击;ReadTimeout 管整个请求体的读取;WriteTimeout 从读完请求头开始,到响应写完为止;IdleTimeout 是 keep-alive 连接空闲多久后关闭。上传大文件的接口如果把 ReadTimeout 设得很短,正常用户也会被中断。

服务端:Handler、路由和请求体

服务端的核心是 http.Handler 接口,只有一个方法:接收响应写入器和请求对象。函数签名符合这个接口的,可以用 http.HandlerFunc 包成 Handler。http.ServeMux 是标准库自带的路由器,负责按路径把请求分给不同的 Handler。

mux := http.NewServeMux()
mux.HandleFunc("GET /hello", func(w http.ResponseWriter, r *http.Request) {
	w.Header().Set("Content-Type", "text/plain; charset=utf-8")
	fmt.Fprint(w, "你好,客户端")
})

mux.HandleFunc("POST /echo", func(w http.ResponseWriter, r *http.Request) {
	r.Body = http.MaxBytesReader(w, r.Body, 1 << 20)
	b, err := io.ReadAll(r.Body)
	if err != nil {
		http.Error(w, "请求体太大", http.StatusRequestEntityTooLarge)
		return
	}
	fmt.Fprintf(w, "收到 %d 字节", len(b))
})

srv := &http.Server{Addr: ":8080", Handler: mux, ReadHeaderTimeout: time.Second}
srv.ListenAndServe()

"GET /hello" 这种带方法的模式是 Go 1.22 之后支持的,方法不匹配会自动返回 405,不用自己在 Handler 里判断。http.MaxBytesReader 限制请求体大小,超过时读操作返回错误,配合 http.Error 返回 413。本机实测向这个 Handler 发送 2MB 正文,客户端收到的是状态码 413 和正文「请求体太大」。

不限制请求体会怎样?对方可以发一个几百 MB 的 body,你的 io.ReadAll 会把它全部读进内存,几个并发就能把进程打爆。标准库没有默认的 body 上限,这个保护必须自己加。请求头也有上限,超过会返回 431,但那是另一个层面。

r.URL.Query() 取查询参数,r.FormValue 会先解析表单再取字段,看起来方便,但它会忽略解析错误,拿不到时返回空串。做严格校验时要自己调用 ParseForm 并检查错误,否则「参数没传」和「参数传了空值」分不出来。查询参数没有长度限制,超长 URL 可能在日志和代理层被截断。

写响应时,第一次调用 Write 或 WriteHeader 就把状态码和响应头定稿了,之后再改 Header 不会生效。常见的错误是先 fmt.Fprint 输出内容,再想设置状态码 404,结果返回的还是 200。正确顺序是先设置头、写状态码,最后写正文。

Handler 里发生 panic 时,net/http 会 recover 并记录堆栈,然后关闭这条连接,进程不会退出。但客户端看到的是连接中断,不是 500。需要统一返回 JSON 错误、记录请求 ID 的话,得自己包一层中间件,在 defer 里 recover 并写响应。

中间件本质上就是「接收一个 Handler,返回另一个 Handler」的函数。日志、鉴权、限流、recover 都可以这样一层层套,最后交给 ServeMux。标准库还提供了 http.TimeoutHandler,给单个请求设置处理时限,超时后返回 503;它不能中断已经卡在阻塞调用里的 goroutine,只能让客户端早点拿到响应。

路由模式除了固定路径,还支持通配段,例如 "GET /users/{id}",Handler 里用 r.PathValue("id") 取出值。带结尾斜杠和不带斜杠是两条不同的模式,ServeMux 不会自动帮你重定向。需要兼容两种写法时,要么注册两条,要么在外层统一处理。

每个请求由一个新的 goroutine 处理,这也是 Go 服务端的并发模型。一个请求处理得慢,不会阻塞其他请求,但会占着一条连接和一个 goroutine。遇到大量慢请求,仍然会耗尽内存和文件描述符,所以超时和并发限制一样不能省。

客户端:超时之外,还要把响应体读干净

客户端最容易漏的一步是关闭响应体。http.Client.Do 返回的 resp.Body 必须由调用方关闭,否则连接不会归还到连接池,底层 socket 一直占着。更隐蔽的是:只 Close 不读,也可能无法复用连接,因为响应体里还有没读完的数据。

本机用 httptrace 观察连接是否复用,连续发两次请求,每次都读完并关闭:

第一次请求:
  复用连接: false
第二次请求:
  复用连接: true

第一次新建连接,第二次复用同一条。再看「不读 body 也不关闭」的情况:

不读 body 也不 Close:
  复用连接: true
再来一次:
  复用连接: false

第一次显示复用,是因为这个 Client 用的是全局默认 Transport,池子里还留着上一次测试的连接;第二次就变成新建,因为上一条连接的响应体没被消费完,没法放回池子。真实服务里这种泄漏积累起来,就是大量 CLOSE_WAIT 或 TIME_WAIT,最后「cannot assign requested address」或者连不上新目标。

正确写法只有一句口诀:先读干净,再关闭。

resp, err := client.Do(req)
if err != nil {
	return err
}
defer resp.Body.Close()
body, err := io.ReadAll(resp.Body)
if err != nil {
	return err
}

如果响应体很大、你只关心状态码,也要用 io.Copy(io.Discard, resp.Body) 把它读完再关,或者用 resp.Body.Close() 并接受连接不复用。只读一部分就关,HTTP/1.1 的连接无法继续使用,客户端会丢弃它。

连接池挂在 Transport 上,不在 Client 上。多个 Client 如果都用默认 Transport,其实共享同一个池子;自己 new 一个 Transport 就会得到独立的池。默认每个目标主机的空闲连接上限是 2,高并发下可能不够,需要调 MaxIdleConnsPerHost,但调大之前先确认真的在复用,而不是每次都在泄漏。

构造请求时,需要带请求头或 body 就用 http.NewRequestWithContext,它把 context 和请求绑在一起,取消时能中断连接;http.Get 这类快捷函数没有 context,也没法设请求头。请求失败返回的错误通常是 *url.Error,里面包着具体原因,用 errors.As 取出来能看到是超时、DNS 失败还是连接被拒。不要把错误文本直接展示给用户,里面可能带完整 URL 和内网地址。

重定向默认最多 10 次,登录态、鉴权头在跨域重定向时可能被剥掉;需要控制时用 CheckRedirect。代理从环境变量读取,容器里如果设了 HTTP_PROXY 而目标地址不该走代理,会得到莫名其妙的连接失败。这些都不是超时问题,但现象很像「请求发不出去」。

拿到响应后,先看 resp.StatusCode 再读 body。4xx 和 5xx 的响应体也可能是 JSON 错误信息,直接当成成功数据解析会得到莫名其妙的空结构。标准库会自动解压 gzip 响应,前提是它自己加的 Accept-Encoding 没有被覆盖;如果你手动设了这个头,解压就要自己负责。响应没有 Content-Length 时,读 body 只能读到连接关闭或分块结束,这也是必须设超时的原因之一。

TCP socket:流没有消息边界

HTTP 建立在 TCP 之上。HTTP 之所以能一问一答,是因为协议自己规定了报文格式和长度;直接用 TCP 时,这些都要你自己定。TCP 只保证字节按顺序到达,不保证「一次读到的正好是一条消息」。

ln, err := net.Listen("tcp", "127.0.0.1:0")
if err != nil {
	return err
}
defer ln.Close()

go func() {
	conn, err := ln.Accept()
	if err != nil {
		return
	}
	defer conn.Close()
	fmt.Fprintf(conn, "hello from server\n")
	line, _ := bufio.NewReader(conn).ReadString('\n')
	fmt.Println("服务端收到:", line)
}()

conn, err := net.Dial("tcp", ln.Addr().String())
if err != nil {
	return err
}
defer conn.Close()
conn.SetDeadline(time.Now().Add(2 * time.Second))
line, _ := bufio.NewReader(conn).ReadString('\n')
fmt.Println("客户端收到:", line)
fmt.Fprintf(conn, "hi server\n")

本机实际输出(端口是系统随机分配的,每次不同):

监听地址: 127.0.0.1:58205
客户端收到: hello from server

服务端收到: hi server

这段能正常工作,是因为双方都约定「一行一条消息」,用换行符做分隔。如果没有这个约定,服务端调用一次 Read,可能读到半条,也可能读到两条连在一起。这就是所谓的粘包和拆包,不是 TCP 的 bug,而是流式协议的常态。

解决办法是给消息加边界:固定长度、分隔符、或者「长度头加正文」。长度头最通用:先发 4 个字节表示正文长度,再发正文;接收方先读长度,再按长度读满。Go 里可以用 binary.BigEndian.Uint32 解析长度,用 io.ReadFull 读满指定字节。别用 Read 的返回值当消息长度,它只代表这一次读到了多少。

SetDeadline 设置的是这条连接上所有读写的绝对截止时间,读超时和写超时也可以分开设。net.Dial 本身也可能永久阻塞,生产代码用 net.DialTimeout 或带 context 的 Dialer。TCP 的读写是阻塞的,运行时会把等待的 goroutine 挂起,底层用操作系统的多路复用机制处理,感兴趣的可以看 操作系统:I/O 模型 那一篇。

写 TCP 数据时,fmt.Fprintf 或 conn.Write 返回的字节数可能小于你要发的长度,严格来说要循环写到写完。bufio.Writer 能减少系统调用,但它有缓冲,调用 Flush 之前数据可能还在内存里;忘了 Flush,对方就一直等不到。关闭连接时,如果只想关写方向、还要继续读对方的响应,用 CloseWrite(需要类型断言到 *net.TCPConn),直接 Close 会把两个方向都断掉。

判断连接是否还活着,不能只靠「上一次写成功了」。对方可能已经关闭,写操作要等到下一次才报错。需要长期保持的连接,要么定期发心跳,要么设置合理的读写超时,靠协议层发现断开。

写服务端时,典型的循环是 for { conn, err := ln.Accept(); go handle(conn) }。这里没有任何并发上限,每个连接一个 goroutine,连接不关,goroutine 就不退。必须在 handle 里 defer conn.Close(),并给读写设截止时间;否则一个只连不发的客户端就能慢慢耗光资源。接受连接出错时也要判断是不是临时错误,直接 return 会让服务彻底停止监听。

出问题时先看哪里

现象真实原因第一步查什么
请求永远不返回,进程还在客户端没设超时,或 context 没有截止时间看 Client.Timeout、context.WithTimeout;看 goroutine 栈停在哪
连接数持续上涨,最后端口耗尽响应体没关闭或没读完,连接无法归还池子搜所有 client.Do;确认 defer resp.Body.Close() 且读干净
每次请求都新建连接每次 new Transport,或响应体未消费完用 httptrace 看 GotConn.Reused;确认 Transport 是复用的
服务端返回 413请求体超过 MaxBytesReader 或中间层限制看请求的实际大小;确认限制值和业务需求
服务端被慢连接拖住没设 ReadHeaderTimeout、ReadTimeout看 Server 配置;确认超时不是 0
Handler panic 后客户端看到连接中断net/http 已 recover 并关闭连接,没有返回 500看服务端错误日志;加统一 recover 中间件
TCP 收到的数据缺一半或粘在一起流式协议没有消息边界看双方是否约定分隔符或长度头;检查 Read 返回值的使用
Dial 卡住或立刻失败DNS、防火墙、代理环境变量、地址写错看错误类型是超时还是拒绝;检查 HTTP_PROXY 和目标地址
重定向后鉴权失败跨域重定向时敏感头被剥离看 CheckRedirect 和重定向目标;确认是否需要手动带令牌

排查网络问题,先分清是「连不上」「连上了但不回」还是「回了但读不对」。连不上看地址、DNS、防火墙;不回看超时和下游状态;读不对看协议格式和响应体处理。三者混在一起查,最容易把简单问题拖成通宵。

边界与代价

  • net/http 不替你重试:连接失败、5xx、超时都不会自动重试。重试要自己加,而且必须只对幂等请求重试,否则会重复下单、重复扣款。
  • 默认 Transport 是全局的:改它的超时、代理、TLS 配置会影响整个进程。需要隔离时自己构造 Transport,但要注意每个 Transport 都有独立的连接池和 goroutine。
  • 连接复用有前提:读完 body、关闭 body、目标地址和协议一致。任何一条不满足,连接就会被丢弃,池子里的空闲连接也可能被对方先关掉。
  • 每请求一个 goroutine 不是无限容量:慢客户端、超大请求体、下游阻塞都会占住 goroutine。真正的容量控制要靠超时、请求体限制和并发信号量。
  • TCP 不提供消息语义:长度头、分隔符、心跳、重连、半关闭处理,全都要自己设计。直接用 TCP 传业务对象,复杂度远高于 HTTP。
  • HTTP 客户端超时不等于服务端取消:客户端放弃等待后,服务端可能还在处理。要让服务端也停下来,需要在请求里带 context,并在 Handler 里监听 r.Context().Done()。
  • TLS 配置需要显式处理:内部服务用自签证书时,要么把根证书装进信任链,要么自定义 tls.Config,不要图省事写 InsecureSkipVerify: true,那等于关掉了身份校验。
  • 优雅退出是另一套机制:Server.Shutdown 会停止接收新连接并等待在途请求结束,需要配合 context 和超时。这部分放到第 8 篇讲,这里先知道它不是自动完成的。

还有一个实际取舍:HTTP/1.1 的连接复用是「一问一答」,同一个连接上不能并行发两个请求;HTTP/2 支持多路复用,但需要 TLS 和服务端支持。大多数内部服务用 HTTP/1.1 加连接池就够,不要为了追求复用而引入不必要的复杂度。

写网络代码时,把所有「可能永远等待」的地方列出来,逐个加上时限:建立连接、读响应头、读响应体、写请求、等待空闲连接。这份清单比任何框架都可靠,因为默认值不会替你兜底。

当天能自己验证的练习

  1. 打印 http.DefaultClient.Timeout 和 (&http.Server{}).ReadTimeout,确认都是 0;再构造带超时的 Client 和 Server,确认字段变化。
  2. 起一个本地 Handler,连续发两次请求,用 httptrace 打印 GotConn.Reused;然后把读 body 的代码注释掉,再发两次,观察复用变成 false。
  3. 用 http.MaxBytesReader 限制 1MB,发送 2MB 正文,确认客户端收到 413 和自定义错误文本。
  4. 用 net.Listen 和 net.Dial 写一个回声服务,客户端一次发两行,服务端用 ReadString('\n') 读,确认能按行拆开;再把分隔符去掉,观察一次读到多条。
  5. 把客户端指向一个不响应的地址,分别在不设超时和设 1 秒超时的情况下运行,观察前者挂住、后者返回 context deadline exceeded 或超时错误。

小结

三句话收一下:net/http 的默认值几乎都不设限,客户端要自己设超时,服务端要设读写超时和请求体上限;响应体必须读干净再关闭,否则连接不会复用,泄漏积累起来会耗尽端口;TCP 是字节流,没有消息边界,粘包拆包要靠协议自己约定长度或分隔符。

下一篇更进一步,讲怎么从 Go 程序里启动别的进程。今天你用 net/http 和外部服务通信,下一篇会用 os/exec 调起外部命令,那里有另一套顺序问题:管道要在 Wait 之前读、子进程要单独回收、Windows 上杀父进程不会自动杀掉子进程。