Go database/sql Scan 到自定义类型为什么报错怎样构造最小复现

在 Go 中把查询结果写入自定义结构体时，Rows.Scan 报出“unsupported Scan”并不一定是数据库列类型错了。更常见的原因是：驱动返回的是 int64、[]byte、string 或 nil，而目标字段是一个没有实现转换规则的业务类型。

官方文档：https://pkg.go.dev/database/sql

排查这类问题可以固定成两步：先把源值和目标类型缩小到一个最小复现，再决定是改成基础类型后转换，还是让自定义类型实现 sql.Scanner。如果这个类型要长期复用，通常第二种方式更清晰。

Scan 为什么会在自定义结构体处失败

database/sql 的扫描入口不是把数据库结果反序列化成任意 Go 类型。文档列出了常见目标，例如 *string、*[]byte、整数指针、浮点数、*bool、*time.Time、*any，以及实现 Scanner 的类型。

因此，数据库返回一个整数时，写入 *int64 没问题；但写入 *Price 时，Price 如果只是普通结构体，标准库不知道应该把整数放到哪个字段，也不知道是否需要单位换算。此时错误发生在 Scan 阶段，而不是查询阶段。

先用一个单字段复现真实错误

下面的示例使用一个内存中的驱动值模拟一次扫描。它不连接具体数据库，目的只是把“源值是 int64，目标是 *Price”这一边界固定下来，便于确认报错来自类型转换。

package main

import (
    "database/sql"
    "fmt"
)

// Price 是业务层的金额结构，不是 database/sql 的内置目标类型。
type Price struct {
    Cents int64
}

func main() {
    var price Price

    // ConvertAssign 模拟 Rows.Scan 内部的赋值路径，不需要启动数据库。
    err := sql.ConvertAssign(&price, int64(1299))
    if err != nil {
        fmt.Printf("scan failed: %v\n", err)
        return
    }
    fmt.Printf("price=%+v\n", price)
}

这里的关键不是记住某一段固定错误文本，而是看错误中的两端：左侧是驱动源值类型，右侧是目标指针类型。若目标是结构体或其他业务对象，先确认它有没有实现 Scan(any) error。

两种修复路线：基础类型转换或 Scanner

一次性使用的字段，可以先扫描到基础类型，再在业务代码中构造对象。例如把金额扫描到 int64，随后创建 Price{Cents: cents}。这种写法简单，但每个查询都要重复转换和错误处理。

更适合复用的做法是让 Price 实现 sql.Scanner。Scanner 的 Scan 方法接收数据库驱动可能提供的值，文档列出的常见源值包括 int64、float64、bool、[]byte、string、time.Time 和 nil。

package main

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

type Price struct {
    Cents int64
    Valid bool
}

// Scan 把驱动值集中转换成金额，调用方就不必在每个查询中重复判断类型。
func (p *Price) Scan(src any) error {
    if p == nil {
        return errors.New("price: nil receiver")
    }

    // NULL 不等于 0，用 Valid 区分数据库 NULL 和真实的零金额。
    if src == nil {
        p.Cents = 0
        p.Valid = false
        return nil
    }

    switch value := src.(type) {
    case int64:
        p.Cents = value
    case []byte:
        // []byte 只在当前 Scan 生命周期内可靠，解析后只保留数值。
        cents, err := strconv.ParseInt(string(value), 10, 64)
        if err != nil {
            return fmt.Errorf("price: parse bytes: %w", err)
        }
        p.Cents = cents
    case string:
        cents, err := strconv.ParseInt(value, 10, 64)
        if err != nil {
            return fmt.Errorf("price: parse string: %w", err)
        }
        p.Cents = cents
    default:
        return fmt.Errorf("price: unsupported source %T", src)
    }

    p.Valid = true
    return nil
}

// Value 让同一个类型也能作为写入参数，避免发送不受支持的结构体值。
func (p Price) Value() (driver.Value, error) {
    if !p.Valid {
        return nil, nil
    }
    return p.Cents, nil
}

这个实现把边界集中在一个地方：int64 直接接收，文本值显式解析，nil 记录为无效值，其他类型返回带有实际类型的错误。业务类型越复杂，集中处理越能避免不同查询出现不同的转换规则。

把 Scanner 放进真实 Rows.Scan

实现完成后，真实查询只需要把字段地址传给 Scan。遍历时仍要先调用 Next，扫描结束后检查 Rows.Err，并在不再使用时关闭 rows。

rows, err := db.QueryContext(ctx, `SELECT amount FROM invoices`)
if err != nil {
    return err
}
defer rows.Close() // 及时释放结果集和关联连接资源。

for rows.Next() {
    var price Price
    // Price 实现 Scanner 后，Scan 会调用 price.Scan，而不是猜结构体字段。
    if err := rows.Scan(&price); err != nil {
        return fmt.Errorf("scan invoice amount: %w", err)
    }
    if !price.Valid {
        continue // 按业务规则跳过 NULL 金额。
    }
    fmt.Println(price.Cents)
}

// Next 返回 false 既可能是读完，也可能是迭代错误，必须检查 Err。
if err := rows.Err(); err != nil {
    return fmt.Errorf("iterate invoices: %w", err)
}

如果 Scanner.Scan 返回错误，database/sql 会把它包装到 Rows.Scan 的错误中。因此，错误里保留“字段名 + 源值类型 + 解析原因”，比在调用方只打印“scan failed”更容易定位。

几个容易误判的边界

结论

Scan 报自定义类型错误的根因，通常是目标类型没有落在 database/sql 的常见转换范围内。最小复现只需要固定一个驱动源值和一个目标指针；确认边界后，再选择“扫描基础类型后转换”或“实现 sql.Scanner”。对于需要处理 NULL、文本格式和多处复用的业务字段，Scanner 更适合集中表达规则。

相关问题

• 为什么 Scan(&stringValue) 能接收数字，而自定义结构体不行？
• 自定义 Scanner 中的 []byte 为什么不能直接长期保存？
• 数据库字段允许 NULL 时，应该使用 Valid 标志还是 sql.Null？
• Rows.Scan 失败后还需要继续调用 Rows.Err 吗？