如何在 Go HTTP 客户端中实现连接空闲超时（Idle Timeout）

go 标准库的 `http.client` 不直接支持连接级空闲超时（即对底层 `net.conn` 的每次 `read`/`write` 设置动态 deadline），需通过自定义 `net.dialer` 和包装 `net.conn` 实现。

在 Go 的 HTTP 客户端中，“空闲超时（Idle Timeout）”并非指连接建立后的整体存活时间（那是 KeepAlive 或 IdleConnTimeout 的职责），而是特指：在已建立的 TCP 连接上，每次调用 Read() 或 Write() 时，若操作在指定时间内未完成（例如因网络卡顿、服务端响应缓慢或中断），则立即返回超时错误。这一机制对大文件下载、流式响应处理等长耗时场景至关重要——它能避免客户端无限期阻塞在某一次读取上。

标准 http.Client 提供的 Timeout、Transport.IdleConnTimeout 等字段均无法满足该需求。正确做法是：自定义 net.Dialer，使其返回一个包装过的 net.Conn，并在每次 Read/Write 前动态设置读/写截止时间（deadline）。

以下是一个生产就绪的实现示例：

type DeadlineConn struct {
    net.Conn
    ReadTimeout  time.Duration
    WriteTimeout time.Duration
}

func (c *DeadlineConn) Read(b []byte) (int, error) {
    if c.ReadTimeout > 0 {
        if err := c.Conn.SetReadDeadline(time.Now().Add(c.ReadTimeout)); err != nil {
            return 0, err
        }
    }
    return c.Conn.Read(b)
}

func (c *DeadlineConn) Write(b []byte) (int, error) {
    if c.WriteTimeout > 0 {
        if err := c.Conn.SetWriteDeadline(time.Now().Add(c.WriteTimeout)); err != nil {
            return 0, err
        }
    }
    return c.Conn.Write(b)
}

// 自定义 Dialer，返回带 deadline 控制的连接
dialer := &net.Dialer{
    Timeout:   30 * time.Second,
    KeepAlive: 30 * time.Second,
}
transport := &http.Transport{
    DialContext: func(ctx context.Context, network, addr string) (net.Conn, error) {
        conn, err := dialer.DialContext(ctx, network, addr)
        if err != nil {
            return nil, err
        }
        return &DeadlineConn{
            Conn:         conn,
            ReadTimeout:  60 * time.Second,  // 每次读操作最多等待 60 秒
            WriteTimeout: 30 * time.Second,  // 每次写操作最多等待 30 秒
        }, nil
    },
    // 其他 Transport 配置（如 TLS、IdleConnTimeout 等）按需设置
}

client := &http.Client{Transport: transport}

✅ 关键说明与注意事项：

• SetReadDeadline/SetWriteDeadline 是 per-operation 生效的，每次 Read/Write 前必须重新设置，因此包装器中必须在方法入口处调用；
• 若使用 io.Copy 或 resp.Body.Read() 等方式读取响应体，请确保底层 Body 使用的是上述包装连接，否则 deadline 不生效；
• ReadTimeout 应显著大于预期单次数据块传输耗时（如 HTTP 分块传输、TLS 握手后数据帧），避免误判超时；
• 对于 HTTPS 请求，该方案同样适用，因为 tls.Conn 也实现了 net.Conn 接口，且 SetReadDeadline 在 TLS 层会被正确传递到底层 TCP 连接；
• 不建议在 Close() 中重置 deadline —— 正确做法是仅在 I/O 方法中设置，关闭连接本身不受 deadline 影响。

通过此方式，你便拥有了真正可控的“空闲超时”能力：既保障了长连接复用效率，又杜绝了因单次 I/O 卡死导致整个客户端不可用的风险。