Go net.Conn 写入超时为何仍会卡住：SetWriteDeadline、部分写入与连接复用检查

日志里出现 write: i/o timeout，并不等于这条连接已经被安全处理完。Go 的 net.Conn 把写入截止时间交给 SetWriteDeadline，但调用方仍要检查 n 和 err，处理部分写入，并决定这条连接还能不能复用。

先分清 deadline 和单次写入的关系

SetWriteDeadline 设置的是连接的写入截止时间。下面的 writeFrame 在发送前设置绝对时间，并把返回的 n、err 原样交给上层判断。

func writeFrame(conn net.Conn, payload []byte) error {
    if err := conn.SetWriteDeadline(time.Now().Add(2 * time.Second)); err != nil {
        return fmt.Errorf("set write deadline: %w", err)
    }
    n, err := conn.Write(payload)
    if err != nil {
        return fmt.Errorf("write %d/%d bytes: %w", n, len(payload), err)
    }
    if n != len(payload) {
        return io.ErrShortWrite
    }
    return nil
}

这里的调用链是 SetWriteDeadline → conn.Write → n, err。若返回超时，日志中的 n 可能大于零；上层不能只依据错误字符串决定是否重发。

为什么写入超时后不能无条件重试

TCP 连接是字节流，不知道对端已经消费了多少完整业务帧。假设发送 4096 字节只成功写出 1500 字节，这就是一次 partial write；直接再次发送完整 payload，对端可能收到重复前缀。只有协议具备明确的帧边界和续传语义时，才可以从 payload[n:] 继续。

func writeAll(conn net.Conn, payload []byte) error {
    for len(payload) > 0 {
        if err := conn.SetWriteDeadline(time.Now().Add(2 * time.Second)); err != nil {
            return err
        }
        n, err := conn.Write(payload)
        if n > 0 {
            payload = payload[n:]
        }
        if err != nil {
            return err
        }
        if n == 0 {
            return io.ErrUnexpectedEOF
        }
    }
    return nil
}

循环每次都把剩余数据作为新的 payload，因此不会重复已经写出的前缀。若业务协议不能接受半帧，应该把连接标记为不可复用并进入 close 路径，而不是调用这个续写函数。

连接复用时要处理三个状态

成功写完后清理旧 deadline

如果连接会进入池或交给下一次请求，成功完成后可调用 SetWriteDeadline(time.Time{}) 清除旧截止时间，避免下一位使用者继承一个已经临近的绝对时间。

超时连接不要直接放回池

写入超时意味着对端消费进度不确定。除非协议层有可验证的恢复握手，否则把这条连接放回池会把半帧风险传给下一个请求。

关闭动作要和日志一致

日志建议包含 phase=write、written、total 和错误类型。这样能区分“尚未写出”和“已写出部分内容后超时”，后续复盘才不会误判。

用最小测试复现并验收

测试时不要只断言返回了 timeout。还要核对服务端收到的字节数、客户端返回的 n，以及连接是否被关闭。一个可靠的验收标准是：完整帧成功写完才复用；部分帧或超时连接进入关闭路径。

n, err := conn.Write(payload)
switch {
case err == nil && n == len(payload):
    // 完整写入，可进入后续复用流程
case n > 0:
    // 已写出部分内容，按协议决定续写或关闭
default:
    // 未写出有效字节，记录错误并关闭
}

相关问题

SetWriteDeadline 是相对超时吗？

不是。它接收绝对时间；要表达“从现在起两秒”，需要传入 time.Now().Add(2 * time.Second)。

Write 返回错误时 n 一定是零吗？

不一定。网络写入可能已经完成部分字节，所以必须同时记录 n 与 err。

部分写入后什么时候能重试？

只有协议明确支持按剩余字节续写，并且连接状态仍可验证时才重试；否则关闭连接比盲目重发完整帧安全。

小结

排查 Go 写入超时，先看 SetWriteDeadline 的绝对时间，再看 conn.Write 返回的 n 与 err，最后检查连接是否仍被复用。把这三个层次写进日志和测试，才能把偶发卡住变成可定位、可收口的状态机。