Go net 包的 TCP 编程：从 Dial 到 Listen 的完整 TCP 服务实现

Dial：别让连接迟迟不返回

很多 Go 开发者第一次写网络程序，都是从 net 包的 Dial 和 Listen 这两个函数开始的。它们看起来一个负责连出去，一个负责收进来，用法也足够简单，几分钟就能跑通一个 echo 服务。但一旦把这样的代码放到生产环境，连接超时、粘包、半包、连接泄漏、优雅关闭，这些问题会一个接一个冒出来。这篇文章不打算停留在 API 层面，而是沿着 Dial 到 Listen 的路径，把 TCP 服务实现中最容易踩坑、也最值得想清楚的部分拆开讲一遍。

Go net 包的 TCP 编程：从 Dial 到 Listen 的完整 TCP 服务实现

客户端发起连接时，大家最先接触到的往往是 net.Dial。它的签名很友好，传入协议和地址，返回一个 net.Conn。可问题就藏在“友好”后面：net.Dial 内部没有内置超时，当目标 IP 不可达或者端口被防火墙丢弃时，connect 调用可能阻塞很长一段时间。在实际排查中，我们经常看到上游服务超时，往下追才发现，是客户端在建立连接这一步就卡住了。

所以更稳妥的做法是使用 net.DialTimeout，或者直接通过 net.Dialer 来配置连接参数。下面的代码是实践中很常见的一段：

conn, err := net.DialTimeout("tcp", "127.0.0.1:8080", 3*time.Second)
if err != nil {
    log.Fatal(err)
}
defer conn.Close()

net.DialTimeout 本质上就是创建了一个带 Timeout 字段的 net.Dialer。而直接使用 net.Dialer 的好处是，后续还能额外设置 KeepAlive、LocalAddr、Control 等字段。比如把 TCP KeepAlive 时间打开，对长连接场景很有帮助。

这里容易忽视一个点：DialTimeout 的 Timeout 覆盖的是建立连接的总耗时，包含 DNS 解析和 TCP 握手。如果你的客户端需要频繁创建短连接，最好在连接池里复用连接，而不是每次请求都重新 Dial。net.Conn 本身不是并发安全的，所以要自己管理连接池的锁和空闲回收。很多团队一开始忽略这个，等并发上来后，握手的开销和端口资源占用会很快成为瓶颈。

Listen 与 Accept：循环背后的边界情况

服务端这边，net.Listen 返回的是一个 net.Listener，接口很简单，但真正需要关注的其实是 Accept 循环。最常见的写法是 for 循环里不断 Accept，每来一个连接就交给一个 goroutine 处理：

ln, err := net.Listen("tcp", ":8080")
if err != nil {
    log.Fatal(err)
}
defer ln.Close()

for {
    conn, err := ln.Accept()
    if err != nil {
        log.Printf("accept error: %v", err)
        continue
    }
    go handleConn(conn)
}

这个循环看着简单，但有两个边界情况很容易被忽略。第一，Accept 返回的错误不一定都是致命错误。比如在 Linux 上，当进程收到信号或遇到 EAGAIN 时，Accept 会返回错误，但这种错误通常可以通过继续循环重试来恢复。如果直接把 log.Fatal 写在里面，整个服务就会在短暂的资源抖动下退出。第二，每个连接都直接开一个 goroutine，在连接数很少的时候没有问题，但连接数达到数万甚至更高时，goroutine 的数量和每个连接上缓冲区的内存占用会迅速上涨。虽然 goroutine 很轻，但轻不代表无代价。

监听地址也值得多说一句。net.Listen 里的“:8080”表示监听本机所有网络接口上的 8080 端口，而“127.0.0.1:8080”则只监听回环地址。如果服务需要内网访问，但只监听回环，会造成翻遍网络也连不上的问题；反过来，如果不小心监听了所有接口，服务也会暴露在外。部署时最好根据实际网络边界明确指定 IP 和端口。

连接处理：TCP 是流，不是消息边界

处理好 Accept 之后，真正麻烦的事情才开始。TCP 协议面向字节流，它不保证上层消息的边界。应用层发送的两次 Write，可能被对端一次 Read 全部收走，也可能只收到一部分。如果不处理边界，直接按 Read 返回的数据去解析业务内容，在压力测试下几乎必然出错。

常见的解决办法是在应用层自定义协议，用固定长度的头部表示消息长度，后面跟上消息体。这样在读取时就通过 io.ReadFull 确保读到一个完整的消息：

func handleConn(conn net.Conn) {
    defer conn.Close()
    for {
        header := make([]byte, 4)
        if _, err := io.ReadFull(conn, header); err != nil {
            return
        }
        length := binary.BigEndian.Uint32(header)
        body := make([]byte, length)
        if _, err := io.ReadFull(conn, body); err != nil {
            return
        }
        // 处理完整消息
    }
}

这里使用 io.ReadFull 而不是直接 conn.Read，就是为了处理半包。conn.Read 可能会在数据不足时返回一个较小的 n，而 io.ReadFull 会持续读取，直到填满给定长度的缓冲区或出现错误。

如果你用的是 JSON 行协议，也可以使用 bufio.Reader 的 ReadBytes 按换行符切分。这种方案实现起来很直接，但有两个隐患：一是消息体不能出现换行符，否则切分会出错；二是遇到超大数据包时，按行读取需要依赖缓冲区不断扩容，可能带来额外的内存压力。所以长度前缀协议在大多数工程场景下是更稳妥的选择。

还有一点需要特别注意：从网络读取的 length 字段是不可信的。如果对端发送一个很大的数值，比如 4GB，你的程序会尝试分配一个巨大的缓冲区，轻则消耗内存，重则直接 OOM。因此，在分配消息体缓冲区前，一定要对 length 做上限校验，超过约定的最大值就拒绝处理并关闭连接。

读写超时与连接保活

另一个经常被忽略的问题是读写超时。默认情况下，从一个 TCP 连接上 Read 是会一直阻塞的。服务端如果只负责 Accept 然后交给 goroutine 读取，而客户端发完握手包后就不再发数据，这个 goroutine 就会一直挂在 Read 上，连接也不会被回收。时间一长，文件描述符和 goroutine 都会被耗尽。

net.Conn 提供了 SetReadDeadline、SetWriteDeadline 和 SetDeadline 方法，用于设置绝对时间的截止点。这里有一个比较常见的误解：这些 deadline 是绝对时间，不是相对时间。如果每次读取前设置 30 秒后的时间，那么无论这个连接后续怎么复用，一旦到了时间，Read 就会返回超时错误。所以对于长连接，通常需要在每次读写之前重新设置 deadline。

为了避免死连接，应用层一般还会配合心跳机制。典型做法是服务端每隔一段时间向客户端发送一个 ping 包，客户端在收到后必须回复 pong。如果在若干周期内没有收到任何数据，服务端就主动 Close 连接。管理这种超时，可以在 goroutine 里使用 time.Ticker 扫描连接的最后活动时间，也可以用 context.WithTimeout 控制单次读取。

内核层面也有 TCP KeepAlive 这个选项，但要注意它默认是关闭的，即使打开，探测周期也比较长，通常在小时级别。对于需要快速发现死连接的场景，应用层心跳仍然不可替代。通过 net.Dialer 的 KeepAlive 字段可以设置 TCP 层保活间隔，但不要把业务存活判断完全寄托在它上面。

优雅关闭：先停止接收，再等待存量连接

当你要上线新版本或者重启服务时，直接 kill 进程会粗暴地切断所有连接。更稳妥的做法是：先关闭 Listener，停止接收新的连接，然后等待正在处理中的连接完成，再退出进程。Go 标准库并没有直接提供一个 http.Server 那样的 Shutdown 方法给 net.Listener，所以我们需要自己组织这个过程。

这里有一个常用的实现思路：监听系统退出信号，触发 ctx 的 cancel，主 goroutine 在收到取消信号后不再 Accept，最后用 WaitGroup 等待所有 handler 返回。

ctx, cancel := context.WithCancel(context.Background())
var wg sync.WaitGroup

ln, _ := net.Listen("tcp", ":8080")

go func() {
    <-ctx.Done()
    ln.Close()
}()

for {
    conn, err := ln.Accept()
    if err != nil {
        if ctx.Err() != nil {
            break
        }
        continue
    }
    wg.Add(1)
    go func(c net.Conn) {
        defer wg.Done()
        handleConn(c)
    }(conn)
}

wg.Wait()

这个例子中，一旦收到退出信号，Listener 会被 Close，Accept 立即返回错误，我们在检查到 ctx 已被取消后退出循环。随后 wg.Wait 等待所有 connection handler 完成。要注意的是，如果 handler 内部没有使用可取消的读取，等待时间可能过长，所以最好在 handler 中同样关注 ctx 的取消，并且为连接设置一个最大生存时间。

实际部署时，我们还经常遇到一个问题：有些连接虽然还在，但业务上已经不再活跃，如果一直等待，进程无法退出。这种情况下，可以在 WaitGroup 等待外层加一个超时，超过一定时间后强制关闭所有剩余连接。这不是最优雅的方案，但总比无限期挂起好。

常见误区与方案选型

在实际项目中，我还看到过一些反复出现的错误，在这里一起列出来。第一个是给所有连接设置同一个全局 deadline，这会导致在某些空闲连接被超时杀掉后，活跃连接也受影响。第二个是在 Accept 循环里遇到错误就直接 return，忽略了可恢复的临时错误。第三个是以为调用 Close 就能立刻回收资源，其实如果还有 goroutine 阻塞在 Read 上，连接对象并不会立刻释放。

把 SetDeadline 当作每次读写的闲置超时，而不是绝对时间。
在 accept 循环中对所有错误一视同仁，直接让进程退出。
忽略半包，直接按一次 Read 的结果解析消息。
没有应用层心跳，靠 TCP KeepAlive 兜底，导致连接泄漏。

对于服务端模型，不同场景下并没有万能的方案。下面的表格对比了短连接同步处理和长连接 goroutine 处理的差异，可以帮助你在规划架构时做个判断。

维度	短连接 + 同步处理	长连接 + Goroutine
连接管理	用完即关，状态简单	需要维护状态和超时
并发能力	受限于连接建立频率	可承载大量并发连接
资源占用	每次握手有额外开销	每个连接常驻一个 Goroutine
典型场景	内部 API、一次性 RPC	消息推送、实时网关、IoT