Go database/sql/driver.Validator 返回 ErrBadConn 后连接池会怎样处理

如果数据库服务端重启过，连接池里可能还留着一条“对象存在、会话已经失效”的连接。此时最容易混淆的两个词是 Validator 和 ErrBadConn：前者的 IsValid 只返回 bool，并不会返回错误；后者才是驱动用来告诉 database/sql“这条连接不能安全继续使用”的错误契约。

直接结论是：连接准备归还连接池时，如果实现了 driver.Validator，database/sql 会调用 IsValid()。返回 true 才允许进入空闲池，返回 false 就丢弃该连接。ErrBadConn 不应塞进 IsValid，它应该只在驱动已经确认连接失效、且把当前操作交给新连接重试不会造成重复执行时返回。

官方地址：https://pkg.go.dev/database/sql/driver#Validator

问题：Validator 为什么不能直接返回 ErrBadConn

driver.Validator 的接口非常小：

type Validator interface {
    // IsValid 在连接准备放回连接池前被调用。
    // true 表示可以复用，false 表示应该丢弃。
    IsValid() bool
}

所以标题里的“Validator 返回 ErrBadConn”需要先纠正为两个相邻但不同的判断：

这一区分很重要：IsValid 是“归还前的状态门槛”，不负责描述一次 SQL 调用发生了什么；ErrBadConn 是错误传播机制，不是连接池接口的返回类型。

最小配方：连接归还池时到底发生什么

一条连接从业务代码回到连接池，大致会经历“仍在使用 → 准备归还 → 校验 → 进入空闲池或丢弃”四个阶段。只有第三步真正涉及 Validator.IsValid。

1. 业务操作完成，database/sql 收回这条底层连接的使用权。
2. 驱动连接实现了 driver.Validator 时，连接放入池前调用 IsValid()。
3. 返回 true，连接才可能成为下一次借用的候选；返回 false，连接从池中淘汰。
4. 后续需要连接时，连接池可以建立或获取另一条连接；这不是 IsValid 自己负责的重连策略。

因此，IsValid 的实现不应该发起一个没有边界的长时间网络探测，也不应该把“这次 SQL 的业务错误”一律当成连接已经损坏。它只需要根据驱动已经维护的连接状态，给出能否复用的布尔结论。

关键实现：用连接状态实现 Validator

下面的示例用一个最小状态字段模拟驱动连接。真实驱动通常会在读写失败、服务端主动关闭或协议状态异常时更新该字段；示例重点是接口契约和并发读取边界，而不是某个数据库协议。

package demo

import (
    "database/sql/driver"
    "sync/atomic"
)

type conn struct {
    // 1 表示连接仍可复用，0 表示驱动已经确认连接失效。
    valid atomic.Uint32
}

// IsValid 只做快速状态判断，不在归还路径上无限等待网络。
func (c *conn) IsValid() bool {
    return c.valid.Load() == 1
}

// markBroken 在协议层确认连接不可用后调用。
func (c *conn) markBroken() {
    // 原子写让归还连接池的判断能看到最新状态。
    c.valid.Store(0)
}

// 编译期断言：conn 必须实现 driver.Validator。
var _ driver.Validator = (*conn)(nil)

如果驱动没有足够可靠的本地状态，也可以在自己的协议层维护“已关闭”“读写失败”“认证会话失效”等状态，但要把探测动作的超时和并发语义设计清楚。Validator 返回 false 只表达“不要把它放回池中”，不需要返回错误文本。

变体：ErrBadConn 什么时候才适合返回

driver.ErrBadConn 的语义比“这次请求失败”更强：它是在告诉 database/sql，当前驱动连接处于坏状态，可以考虑在新连接上重试。官方契约同时强调，为了避免重复操作，如果数据库服务端可能已经执行过这条语句，就不应该返回 ErrBadConn。

func classifyWriteResult(sent bool, transportErr error) error {
    if transportErr == nil {
        return nil
    }
    if !sent {
        // 请求尚未发到服务端，当前连接已确定不能继续使用。
        return driver.ErrBadConn
    }
    // 请求可能已经执行，不能用 ErrBadConn 诱发重复写入。
    return transportErr
}

这段代码只展示决策边界，具体驱动需要根据协议确认“已发送”“服务端已确认”“响应是否完整”等状态。不要把所有超时都映射成 ErrBadConn：网络超时发生在请求发出之后时，重试可能再次执行写操作。

兼容坑：不要把一次失效连接扩大成整个连接池故障

第一，IsValid() == false 只针对当前这条连接。它说明这条连接不应复用，不等于数据库服务整体不可用，更不等于所有空闲连接都已经失效。

第二，ErrBadConn 的目标是让 database/sql 知道连接坏了，并在安全条件满足时尝试新连接。它不是业务层“自动重试任何 SQL”的开关，尤其不能绕过写操作的幂等性判断。

第三，Validator 和 SessionResetter 关注的时机不同。前者决定连接能否进入池，后者负责连接再次复用前的会话重置；不要因为实现了一个接口，就假定另一个接口会自动补齐。

第四，连接状态字段应由驱动协议层更新。业务代码不应通过类型断言强行调用某个驱动私有的 IsValid，应用侧只使用 database/sql 暴露的连接池 API。

完整片段：用决策表复查驱动行为

func shouldDiscard(valid bool, opErr error, requestSent bool) bool {
    // 归还前的 Validator 结果优先决定当前连接能否进入池。
    if !valid {
        return true
    }
    if opErr == driver.ErrBadConn {
        // ErrBadConn 代表连接不可安全复用，交给上层处理新连接尝试。
        return true
    }
    if opErr != nil && requestSent {
        // 普通错误不自动等价为坏连接，避免重复执行已经发出的操作。
        return false
    }
    return false
}

相关问题

Validator.IsValid 返回 false 后会立即重连吗？

不会。它只阻止当前连接回到可复用池；后续是否建立新连接、何时建立，由 database/sql 的连接需求和连接池状态决定。

普通 SQL 错误都应该换成 ErrBadConn 吗？

不应该。只有明确知道当前连接已经坏掉，并且重新执行不会造成重复操作时，才适合返回 ErrBadConn。

IsValid 里可以主动 Ping 数据库吗？

可以由驱动设计探测，但要有明确的超时、并发和资源边界。更常见的做法是利用协议层已知的失效状态，避免每次归还连接都增加一次网络往返。

排查这类问题时，先记住一句话：Validator.IsValid 决定“这条连接能否回池”，ErrBadConn 表达“这条连接坏到可以考虑换新连接”，而“是否安全重试当前操作”仍然需要结合请求是否已经到达服务端来判断。