Go database/sql Rows把 SQL NULL 映射到可空类型的读取方法

在 Go 中遍历 database/sql.Rows 时，SQL 的 NULL 不能直接当成普通的 string 或 int64 读取。最稳妥的做法是让 Scan 目标实现 sql.Scanner：字符串使用 sql.NullString，整数使用 sql.NullInt64；使用 Go 1.22 及以上时，也可以使用泛型 sql.Null[T]。读取后先判断 Valid，再访问值字段，这样 NULL、空字符串和数字 0 不会混在一起。

官方依据：https://pkg.go.dev/database/sql

可空列的关键不是“给普通变量一个默认值”，而是先把数据库的 NULL 语义接住，再由业务层决定展示为空、隐藏还是继续传递。

为什么普通 string 和 int64 接不住 SQL NULL

Rows.Scan 会把驱动返回的列值转换到目标指针。官方 Scanner 约定中，数据库 NULL 会以 nil 表示；而 string、int64 本身没有“未设置”的状态，所以直接扫描可为空列时，通常会得到类似“converting NULL to string is unsupported”的错误。这里不要用 SQL 的 COALESCE 随手抹平差异，除非业务确实规定 NULL 必须变成某个默认值。

尤其要区分三种结果：NULL 表示没有值，空字符串表示有值但内容为空，整数 0 也可能是有意义的真实值。读取层如果把它们都改成零值，后面的 PATCH 更新、筛选条件和页面展示就很难恢复原意。

用 NullString 和 NullInt64 保留 Valid 状态

标准库已经提供了常见可空类型。它们都实现了 Scanner，扫描 NULL 时会把 Valid 置为 false；扫描到真实值时，Valid 为 true，同时写入对应字段。

package main

import (
    "database/sql"
    "fmt"
)

type RowView struct {
    Name  string
    Score int64
}

func readNullable(name sql.NullString, score sql.NullInt64) RowView {
    // 只有 Valid 为 true 时才把列值交给业务对象，避免 NULL 伪装成零值。
    view := RowView{}
    if name.Valid {
        view.Name = name.String
    }
    if score.Valid {
        view.Score = score.Int64
    }
    return view
}

func describe(name sql.NullString, score sql.NullInt64) {
    // 展示层可以单独处理“没有值”和“值为零”这两种情况。
    if !name.Valid {
        fmt.Println("name: NULL")
    } else {
        fmt.Println("name:", name.String)
    }
    if !score.Valid {
        fmt.Println("score: NULL")
    } else {
        fmt.Println("score:", score.Int64)
    }
}

如果业务对象也需要保留“有没有值”，不要直接返回上面这种只含普通字段的结构，可以使用 *string、*int64 或带 Value/Valid 的领域类型。转换的时机应在数据库读取之后，避免让 SQL 适配细节扩散到查询代码之外。

把可空目标放进 Rows 遍历闭环

多行查询时，先检查查询错误，再在每次 Next 后调用 Scan。循环结束后还要检查 Rows.Err；如果中途返回，使用 defer 关闭 rows。下面的查询只演示读取边界，驱动名称和连接配置应由项目实际环境提供。

func loadViews(ctx context.Context, db *sql.DB) ([]RowView, error) {
    // QueryContext 失败时没有可关闭的 rows，先返回查询错误。
    rows, err := db.QueryContext(ctx, `
        SELECT display_name, score
        FROM member_profile
        ORDER BY id`)
    if err != nil {
        return nil, err
    }
    defer rows.Close() // 及时释放结果集及其可能占用的连接。

    result := make([]RowView, 0)
    for rows.Next() {
        var name sql.NullString
        var score sql.NullInt64
        // Scan 目标必须与 SELECT 列顺序对应，Null* 负责接住 nil。
        if err := rows.Scan(&name, &score); err != nil {
            return nil, err
        }
        result = append(result, readNullable(name, score))
    }
    // Next 返回 false 既可能是读完，也可能是迭代期间发生错误。
    if err := rows.Err(); err != nil {
        return nil, err
    }
    return result, nil
}

这里的 Rows.Scan 目标数量必须和查询列数相同。若只想处理前几行，也不要忘记 rows 的关闭；Close 是幂等的，在正常读完且没有更多结果集时通常会自动关闭，但显式 defer 更容易覆盖提前返回的路径。

泛型 Null、业务转换和边界排查

Go 1.22 起可以使用 sql.Null[T]，其结构是 V T 与 Valid bool，T 必须属于驱动支持的值类型。它适合减少重复的 Null 类型声明：

var (
    // 泛型 Null 保留同样的 Valid 语义，T 应选择驱动可接收的类型。
    name  sql.Null[string]
    score sql.Null[int64]
)
if err := rows.Scan(&name, &score); err != nil {
    // Scan 错误要原样返回，不能用空值掩盖类型不匹配。
    return err
}
if name.Valid {
    fmt.Println(name.V)
}

若项目需要兼容更早的 Go 版本，优先使用 NullString、NullInt64 等专用类型。排查时可按这张速查表判断：

最终检查四点：列顺序是否一致、可空列是否用了 Scanner、循环后是否检查 Rows.Err、业务层是否明确 NULL 的展示和更新语义。只要这四点完整，Go database/sql Rows 读取 SQL NULL 就不会再靠默认值猜测。

相关问题

SQL NULL 能不能直接扫描到 *any？

可以接收到驱动提供的原始值，NULL 通常表现为 nil，但类型判断和业务转换都要自己承担。固定列结构更推荐使用 Null* 类型。

NullString 的 String 为空时代表 NULL 吗？

不一定。必须先看 Valid：Valid=false 才是 NULL；Valid=true 且 String 为空，表示数据库存的是空字符串。