Go database/sql/driver 怎样实现 RowsColumnScanner 接口

我第一次看到 Go 1.27 的 database/sql/driver.RowsColumnScanner 时，最容易误判的一点是：它不是给业务层 rows.Scan 增加一个新用法，而是给数据库驱动增加一条“由驱动直接完成列扫描”的实现路径。实现后，database/sql 会在每一列调用驱动的 ScanColumn，而不是再把整行先装进 []driver.Value。

本文只讨论驱动作者如何实现这一接口。相关官方文档：https://pkg.go.dev/database/sql/driver@go1.27.3、https://pkg.go.dev/database/sql@go1.27.3。

最小规则可以记成一句话：NextRow 只负责把游标推进到当前行，ScanColumn 只负责读取当前行的一个列并写入目标；如果要兼容旧版 Go，仍然保留 Rows.Next，但不要让两套游标逻辑互相推进。

先抓住 Go 1.27 改变的调用边界

RowsColumnScanner 嵌入了 driver.Rows，新增 NextRow() error 和 ScanColumn(scanCtx driver.ScanContext, index int, dest any) error。官方定义明确说明：从 Go 1.27 开始，只要一个 Rows 实现了这个接口，database/sql 就不会调用它的 Next 来完成常规扫描；旧的 Next 仍可保留，用于旧版本兼容。

这项变化的价值不在于把接口写得更复杂，而在于驱动可以避免先把每列统一塞入中间切片，再由上层重新转换。驱动已经知道底层字段的真实表示时，可以在 ScanColumn 中直接处理目标类型，同时仍把标准转换交给 database/sql.ConvertAssign。

把 Rows 与 RowsColumnScanner 的状态拆开

一个可靠的实现至少要分清五类状态：列名集合、底层行数据、下一行位置、当前行位置和关闭状态。NextRow 成功后才会有“当前行”；在没有当前行时调用 ScanColumn，应该返回驱动自己的状态错误，而不是默默读取上一行。

下面的代码是一个实现骨架。它用内存中的二维值模拟底层结果集，重点是状态边界，不代表任何具体数据库协议。真实驱动可以把 values 换成网络缓冲区或协议解码器，但方法职责应保持不变。

package driverrows

import (
	"database/sql"
	"database/sql/driver"
	"errors"
	"fmt"
	"io"
)

var errNoCurrentRow = errors.New("driverrows: no current row")

type rows struct {
	columns []string
	values  [][]driver.Value
	next    int  // 下一次 NextRow 要定位的行下标。
	current int  // 当前行下标；-1 表示还没有定位到行。
	closed  bool // 关闭后所有读取操作都应停止访问底层资源。
}

// Columns 返回结果集的列名；长度决定 database/sql 期望的列数。
func (r *rows) Columns() []string { return r.columns }

// Close 释放协议游标、网络缓冲区等资源；重复关闭保持幂等。
func (r *rows) Close() error {
	r.closed = true
	return nil
}

// Next 保留给旧版 Go；它与 NextRow 共享同一个行游标。
func (r *rows) Next(dest []driver.Value) error {
	if err := r.NextRow(); err != nil {
		return err
	}
	copy(dest, r.values[r.current])
	return nil
}

// NextRow 只推进行，不负责把列写入用户目标。
func (r *rows) NextRow() error {
	if r.closed {
		return errors.New("driverrows: rows closed")
	}
	if r.next >= len(r.values) {
		return io.EOF
	}
	r.current = r.next
	r.next++
	return nil
}

// ScanColumn 读取当前行的单列，并保留 database/sql 的标准转换规则。
func (r *rows) ScanColumn(scanCtx driver.ScanContext, index int, dest any) error {
	if r.closed {
		return errors.New("driverrows: rows closed")
	}
	if r.current = len(r.values[r.current]) {
		return fmt.Errorf("driverrows: column index %d out of range", index)
	}
	// 透传 scanCtx，避免游标类值丢失 database/sql 的父 Rows 关系。
	return sql.ConvertAssign(scanCtx, dest, r.values[r.current][index])
}

var _ driver.RowsColumnScanner = (*rows)(nil)

这里有一个容易忽视的细节：Next 和 NextRow 不能各自维护一套独立的行位置，否则旧版调用路径和 Go 1.27 调用路径会出现不同步。代码中的接口断言只用于编译期确认方法集合；它不会替代运行时的资源、协议和错误处理。

在 ScanColumn 中正确使用 ScanContext

Go 1.27 同时公开了给驱动使用的 database/sql.ConvertAssign。它接收 driver.ScanContext、目标指针和一个 driver.Value。实现 ScanColumn 时，应把收到的 scanCtx 原样传入，而不是随手创建一个空上下文。

这样做有两层好处。第一，字符串、数字、[]byte、time.Time、sql.Scanner 等标准扫描转换仍由 database/sql 统一处理；第二，如果某个值代表数据库游标，转换过程可以保留它与父结果集的关系。驱动只需要在确实掌握更高效的底层表示时，先做自己的安全处理，再把剩余转换交给 ConvertAssign。

不要把 ScanColumn 写成“无论目标类型是什么都强制断言”。目标可能是指针、实现了 sql.Scanner 的类型，甚至是用户自己的别名类型。让标准转换函数返回错误，通常比驱动吞掉不兼容信息更容易排查。

兼顾旧版 Go、关闭和错误传播

如果驱动需要兼容 Go 1.26 或更早版本，保留 Next 是必要的，但兼容方式不是复制另一套转换逻辑。可以让旧版 Next 读取协议行并填充 []driver.Value，让新路径的 NextRow 只定位行、ScanColumn 再按列读取；两条路径共享底层游标和关闭状态即可。

错误边界也要保持稳定：

• 没有更多行时，NextRow 和旧版 Next 返回 io.EOF。
• 当前行尚未定位、列下标越界或结果集已经关闭时，返回带上下文的驱动错误。
• 协议读取失败、类型转换失败和关闭失败不要互相伪装；让上层能区分可重试的连接问题与数据问题。
• Close 要释放真实底层资源，并保证重复调用不会再次关闭网络连接或重复归还缓冲区。

如果驱动还实现了 RowsColumnTypeScanType、RowsColumnTypeDatabaseTypeName 等可选接口，返回值应与 ScanColumn 能接受的列表示一致。元数据说列是整数，而扫描时只接受字符串，会让上层的 ColumnTypes 判断失去意义。

什么时候值得采用这条路径

从趋势角度看，RowsColumnScanner 更像驱动维护者的精细化能力，而不是普通 Go 业务代码应该主动依赖的 API。可以用下面的清单做决定：

我的判断是：先把 NextRow、ScanColumn、Close 的状态契约写清，再考虑协议层优化。只要旧版 Next 与新路径共用游标、错误和资源生命周期，RowsColumnScanner 就能作为渐进式增强，而不是一次性重写结果集。

常见问题

实现 RowsColumnScanner 后还必须实现 Next 吗？

接口本身嵌入了 driver.Rows，所以方法集合上仍然必须有 Next。Go 1.27 的 database/sql 不会用它完成这条新扫描路径，但为了旧版本兼容，驱动仍应提供一个与新游标状态一致的实现。

ScanColumn 可以直接把值断言成目标类型吗？

不建议。目标可能实现 sql.Scanner，也可能需要标准的数字、字符串或时间转换。除非驱动确实掌握一条不改变语义的专用快路径，否则应把 scanCtx 传给 sql.ConvertAssign。