Go HTTP2Config.SendPingTimeout 怎样设置空闲连接健康检查

如果 HTTP/2 长连接长时间没有收到任何帧，想用 PING 判断连接是否还活着，关键不是把一个总连接超时写大或写小，而是分清两个等待窗口：SendPingTimeout 负责“多久没有收到帧后发起健康检查”，PingTimeout 负责“发出 PING 后多久收不到响应就关闭连接”。

官方文档：https://pkg.go.dev/net/http#HTTP2Config

实用配置可以先把 SendPingTimeout 设为业务允许的空闲间隔，再把 PingTimeout 设为更短的响应窗口。前者为零表示不做健康检查，后者为零则使用官方默认的 15 秒。

先把两个超时放回各自的位置

HTTP2Config 是 Go 1.24 加入的 HTTP/2 配置集合，可以挂到 http.Server.HTTP2 或 http.Transport.HTTP2。这篇只看健康检查相关的两个字段：

因此，SendPingTimeout 不是“PING 要等多久”，也不是 HTTP 请求的读写超时；PingTimeout 也不是整个连接允许存在的最长时间。把它们混写，最常见的结果就是健康检查迟迟不触发，或者对短暂网络抖动过于敏感。

时间关系应该怎样设置

可以用一个简单的关系表达目标：

空闲探测阈值 = SendPingTimeout，PING 响应阈值 = PingTimeout。

前一个值应覆盖正常业务的空闲间隔，后一个值应覆盖网络和对端处理 PING 的合理抖动。比如一个允许几十秒无业务帧的长连接，可以让 SendPingTimeout 处在几十秒量级，再用数秒到十几秒量级的 PingTimeout 等待响应；具体数值要结合连接数量、网络质量和服务端负载决定，不要照搬固定数字。

如果把 SendPingTimeout 设得过短，会在本来正常的空闲连接上频繁发 PING；如果把 PingTimeout 设得过短，短暂排队、代理转发或调度抖动都可能被当成连接失活。两个值都不负责限制单个请求的业务耗时。

服务端和客户端分别挂在哪里

同一个 HTTP2Config 类型同时服务于 Server 和 Transport，但配置入口不同。服务端写入 http.Server.HTTP2，客户端则写入 http.Transport.HTTP2。不要把配置对象创建出来却没有挂到实际使用的 Server 或 Transport 上。

package main

import (
	"net/http"
	"time"
)

func newServer() *http.Server {
	return &http.Server{
		Addr: ":8443",
		HTTP2: &http.HTTP2Config{
			// 空闲无帧达到该时长后，才进入 PING 健康检查。
			SendPingTimeout: 45 * time.Second,
			// PING 发出后，在该窗口内等不到响应就关闭连接。
			PingTimeout: 8 * time.Second,
		},
	}
}

func newClient() *http.Client {
	transport := http.DefaultTransport.(*http.Transport).Clone()
	transport.HTTP2 = &http.HTTP2Config{
		// 客户端连接同样按“无帧等待 + PING 响应等待”配置。
		SendPingTimeout: 45 * time.Second,
		PingTimeout:     8 * time.Second,
	}
	return &http.Client{Transport: transport}
}

上面的数字只是配置示例，不表示任何线上环境的验证结果。服务端模板返回 *http.Server，客户端模板克隆默认 Transport 后再挂载 HTTP/2 配置，避免修改共享的默认 Transport。

三个容易误判的边界

零值不是“马上检查”

SendPingTimeout: 0 的语义是不执行这项健康检查；它不会让连接一建立就发 PING。PingTimeout: 0 则不同，它会采用 15 秒默认响应等待。若团队需要显式表达策略，可以把两个字段都写出来，避免读代码的人把两个零值当成同一种行为。

它不是请求级超时

请求的上下文取消、http.Client.Timeout、Server 的读写超时，解决的是请求或 I/O 的时间边界；SendPingTimeout 和 PingTimeout 解决的是 HTTP/2 连接健康检查。请求已经卡住时，不能只调大健康检查字段来替代请求级取消。

它不等于连接生命周期

健康检查通过时，连接可以继续复用；健康检查失败时，连接会被关闭，但这不等于“到点轮换连接”。如果目标是连接池轮换、最大空闲时间或单请求截止时间，应使用对应的 Transport、Server 或 Context 配置。

最后保留一份可维护的配置清单

落地时可以按下面的顺序记录：

• 先确认实际启用的是 HTTP/2，并找到生效的 Server 或 Transport 实例。
• 写清业务允许的最长无帧空闲时间，再设置 SendPingTimeout。
• 按网络环境给 PING 响应留出窗口，再设置 PingTimeout；若依赖默认值，备注 15 秒语义。
• 把请求级超时、连接池策略和健康检查策略分开记录。
• 连接被关闭时，结合错误日志与连接指标判断是健康检查失败还是请求自身超时。

一句话总结：SendPingTimeout 决定“空闲多久开始问”，PingTimeout 决定“问了多久没回应就断开”。先分清这两个边界，再把同一策略挂到真正工作的 Server 或 Transport 上，配置就不容易失真。

相关问题

SendPingTimeout 设为零会发生什么？

不会进行这项 PING 健康检查；它不代表立即探测，也不代表请求被取消。

PingTimeout 设为零会立即关闭连接吗？

不会。官方语义是使用 15 秒默认响应等待。

HTTP2Config 应该配置在 Server 还是 Transport？

看连接由谁发起：服务端配置 http.Server.HTTP2，客户端配置 http.Transport.HTTP2。