Go 长连接怎么设置 TCP KeepAlive 探测参数

Go 长连接要发现“对端已经断开但本地还没读到 EOF”的情况，可以在 TCP 层打开 KeepAlive。最小写法是先把连接断言为 *net.TCPConn，调用 SetKeepAlive(true)，再用 SetKeepAlivePeriod 设置空闲多久后开始探测。Go 1.23 及以上还可以用 KeepAliveConfig 分开控制首次空闲时间、探测间隔和失败次数。

为什么连接还在，业务却已经收不到消息

TCP 连接在本地保持 ESTABLISHED，并不等于对端进程、网卡链路和中间设备都正常。对端突然断电时，内核可能没有收到 FIN 或 RST；如果连接长时间没有数据交换，本地应用也就没有读取动作可以触发错误。

KeepAlive 的作用是让操作系统在连接空闲后发送探测，等待对端确认。它适合做“连接是否还活着”的底层兜底；如果业务需要判断用户是否在线、订阅是否有效，仍然要设计带超时和序号的应用层 ping/pong。

旧写法：用 TCPConn 设置首次探测前的空闲时间

如果连接已经通过 net.Dial 建立，可以直接断言为 *net.TCPConn。下面把空闲 2 分钟后开始探测写成一个独立函数；错误必须返回，避免把不支持该选项误当成配置成功。

package main

import (
    "fmt"
    "net"
    "time"
)

func configureTCPKeepAlive(conn net.Conn) error {
    tcpConn, ok := conn.(*net.TCPConn)
    if !ok {
        return fmt.Errorf("连接不是 TCPConn: %T", conn)
    }

    // 先打开操作系统级 KeepAlive，再设置首次探测前的空闲时间。
    if err := tcpConn.SetKeepAlive(true); err != nil {
        return fmt.Errorf("开启 keepalive: %w", err)
    }
    if err := tcpConn.SetKeepAlivePeriod(2 * time.Minute); err != nil {
        return fmt.Errorf("设置 keepalive 空闲时间: %w", err)
    }
    return nil
}

这里的 2*time.Minute 表示连接在没有数据交换 2 分钟后，允许 TCP 开始发送探测。它不是“每 2 分钟发送一次”的完整承诺，具体间隔和失败次数仍由操作系统默认值决定；想分别控制这些值，应使用下一节的配置。

新写法：用 KeepAliveConfig 拆开 Idle、Interval 和 Count

Go 1.23 新增 net.KeepAliveConfig 和 TCPConn.SetKeepAliveConfig。参数含义可以按连接生命周期理解：Idle 是第一次探测前要空闲多久，Interval 是探测之间等待多久，Count 是连续无响应多少次后放弃连接。

func configureWithConfig(conn net.Conn) error {
    tcpConn, ok := conn.(*net.TCPConn)
    if !ok {
        return fmt.Errorf("连接不是 TCPConn: %T", conn)
    }

    config := net.KeepAliveConfig{
        Enable:  true,              // 开启内核探测。
        Idle:    2 * time.Minute,   // 首次探测前的空闲时间。
        Interval: 15 * time.Second, // 未收到确认时的探测间隔。
        Count:   4,                 // 连续失败 4 次后断开。
    }
    if err := tcpConn.SetKeepAliveConfig(config); err != nil {
        return fmt.Errorf("设置 keepalive 配置: %w", err)
    }
    return nil
}

零值不是“完全不设置”：官方实现会为 Idle 和 Interval 选择默认值，Count 也会选择默认次数；负值则表示保留对应的 socket 选项。生产环境不要只凭经验填一个很小的值，先估算负载均衡器、NAT 和服务端允许的空闲时间。

把策略放到 Dialer 和 Listener 的连接入口

只给某条已建立连接调用方法，容易漏掉后续连接。客户端可以在 net.Dialer 中设置 KeepAliveConfig；服务端则在 net.ListenConfig 中设置，接受到的 TCP 连接会沿用入口策略。若项目需要兼容 Go 1.22 及更早版本，可保留 SetKeepAlive 与 SetKeepAlivePeriod 的小范围封装，并在升级到 Go 1.23 后切换到新配置。

还要注意平台差异。Go 官方文档特别提示，Windows 10 1709 之前不能独立设置 Idle、Interval，旧系统上的 SetKeepAlivePeriod 还可能把间隔重置为系统默认值。部署到 Linux、Windows 或 Solaris 时，应把“设置成功”与“实际网络路径可达”分开验证。

常见问题

KeepAlive 能替代 WebSocket 心跳吗？

不能。它只能说明 TCP 层探测是否得到确认，不知道业务连接是否还能处理消息。WebSocket、RPC 或自定义协议仍应保留自己的心跳和响应超时。

设置了 KeepAlive，为什么断网后仍要很久才发现？

检查 Idle、Interval、Count 的组合，以及中间 NAT、代理和防火墙是否丢弃探测。KeepAlive 是操作系统策略，不是立即中断的网络监控器。

SetKeepAlivePeriod 的时间单位是什么？

类型是 time.Duration，直接使用 time.Second、time.Minute 等常量表达，避免传入裸整数造成单位误读。