Go database/sql NullTime 扫描 NULL 后 Valid 状态不对怎么办

如果 sql.NullTime 扫描数据库字段后发现 Valid 和预期不一致，先不要只看 Time 的零值。这个类型把“有没有可用时间”单独放在 Valid 中：扫描到 SQL NULL 时，Time 会被重置为零值并且 Valid=false；扫描到非空值时，只有时间转换成功，Valid 才会是 true。扫描本身返回错误时，业务代码也不能继续读取 Time。

正确判断顺序是：先处理 Scan 返回的错误，再根据 Valid 区分 NULL 和有效时间。不要用 Time.IsZero() 代替 Valid，也不要在扫描错误后继续使用对象里的旧时间。

NullTime 的变化重点是状态契约

database/sql 的 NullTime 在 Go 1.13 加入，用来表示可能为 NULL 的 time.Time。它包含两个公开字段：

• Time：扫描成功且输入不是 NULL 时保存时间值。
• Valid：当前值是否可按非 NULL 时间使用。

这两个字段不是两个独立答案。Time 的零值可能是合法业务时间，也可能只是 NULL 后的清空结果；因此业务含义必须由 Valid 表达。

为什么扫描 NULL 后看起来像“状态错了”

NullTime.Scan 的实现可以概括为两条分支：

// Scan 把驱动返回的值写入 NullTime，并同步更新 Valid。
func (n *sql.NullTime) Scan(value any) error {
    if value == nil {
        // SQL NULL 要清掉旧时间，避免复用对象时残留上一次结果。
        n.Time, n.Valid = time.Time{}, false
        return nil
    }

    // 非 NULL 值交给 database/sql 做类型转换。
    err := convertAssign(&n.Time, value)
    // 只有转换没有错误，当前时间才可被业务使用。
    n.Valid = err == nil
    return err
}

所以，扫描 NULL 后得到 Valid=false 是正常结果，不是异常。真正容易出错的是下面三种写法：

1. 把 Time.IsZero() 当成 NULL 判断，导致合法的零时间也被当成缺失值。
2. 忽略 Scan 错误，只检查 Valid，把转换失败当成普通 NULL。
3. 复用同一个 NullTime，发生错误后仍然读取里面可能残留的 Time。

先把 NULL、有效时间和扫描错误分开

下面的辅助函数只负责把三种状态转换成业务可读的结果。它没有把数据库 NULL 偷换成某个默认日期，也没有在错误时返回对象中的时间。

package main

import (
    "database/sql"
    "fmt"
)

// describeTime 先区分扫描错误，再判断当前值是否为 NULL。
func describeTime(value sql.NullTime, scanErr error) string {
    if scanErr != nil {
        // 转换失败时不能读取 value.Time，避免把旧值当成新值。
        return fmt.Sprintf("扫描失败：%v", scanErr)
    }
    if !value.Valid {
        // Scan(nil) 会走到这里，表示数据库字段是 NULL。
        return "数据库时间为空"
    }
    // 只有 Valid=true 时，Time 才进入业务格式化或计算。
    return value.Time.Format("2006-01-02 15:04:05")
}

这里的关键不是把判断写成一个固定函数，而是保留顺序：err != nil、!Valid、最后才使用 Time。

在 QueryRow 中不要跳过 Scan 错误

QueryRowContext 把查询错误延迟到 Scan，所以最小写法应该同时接收错误，并把 NULL 当作业务分支处理：

func loadPublishedAt(ctx context.Context, db *sql.DB, id int64) (string, error) {
    var publishedAt sql.NullTime

    // 查询字段允许为 NULL，因此不用 time.Time 直接接收。
    err := db.QueryRowContext(ctx,
        "SELECT published_at FROM posts WHERE id = ?", id,
    ).Scan(&publishedAt)
    if err != nil {
        // 先返回查询、无记录或类型转换错误。
        return "", err
    }
    if !publishedAt.Valid {
        // NULL 是可预期状态，由调用方决定展示“未发布”等文案。
        return "", nil
    }
    // Valid=true 后才读取时间并格式化。
    return publishedAt.Time.Format("2006-01-02 15:04:05"), nil
}

如果查询没有返回记录，Scan 可能返回 sql.ErrNoRows；这和“返回了一行但时间列是 NULL”是两件事，不能都压成 Valid=false。

Rows.Scan 复用对象时要防止旧值误导

循环扫描时，可以复用一个 sql.NullTime，但每次都必须检查 Scan 的错误，并且不要在错误分支继续使用字段：

var publishedAt sql.NullTime
for rows.Next() {
    // 每一行都会重新更新 publishedAt 的状态。
    if err := rows.Scan(&publishedAt); err != nil {
        // 记录错误并结束当前处理，不能继续使用可能残留的 Time。
        return err
    }
    if !publishedAt.Valid {
        // 这一行的列值是 NULL，不代表下一行也是 NULL。
        continue
    }
    // 只有这一行 Valid=true 时才使用时间。
    fmt.Println(publishedAt.Time)
}
if err := rows.Err(); err != nil {
    // 迭代过程中出现的驱动错误要在循环结束后检查。
    return err
}

如果你的代码把扫描失败吞掉，再用 Valid=false 统一处理，就会丢失“数据库 NULL”和“驱动无法转换”之间的差异。前者通常可以展示为空，后者应记录并修复数据或驱动映射。

写回数据库时由 Valid 决定 NULL 还是时间

NullTime 还实现了 driver.Valuer。当 Valid=false 时，Value 返回 nil，交给驱动写成 SQL NULL；当 Valid=true 时，返回 Time。

func savePublishedAt(ctx context.Context, db *sql.DB, id int64, at sql.NullTime) error {
    // Value 会按 Valid 选择 SQL NULL 或具体时间值。
    _, err := db.ExecContext(ctx,
        "UPDATE posts SET published_at = ? WHERE id = ?", at, id,
    )
    return err
}

// 调用方明确表达“清空发布日期”。
var clearTime sql.NullTime

// 调用方表达“写入一个具体发布日期”。
setTime := sql.NullTime{Time: time.Now(), Valid: true}

不要只设置 Time 而忘记设置 Valid=true；这种写法会按无效值写回 NULL。相反，如果希望清空字段，使用默认的 Valid=false 状态即可。

用这张表快速定位 Valid 不对

排查时可以依次问四个问题：这个查询是否真的返回了一行？Scan 的错误是什么？驱动返回的是 nil 还是可转换的 time.Time？业务代码是否只在 Valid=true 后使用 Time？通常不需要改动 NullTime 本身，只要把状态判断顺序修正即可。

相关问题

Valid=false 一定表示数据库列是 NULL 吗？

不一定。扫描错误时实现也会把 Valid 设为 false，所以必须先检查 Scan 返回值。

可以用 Time.IsZero() 代替 Valid 吗？

不建议。零时间是一个时间值，而 Valid 表达的是数据库 NULL 语义；两者不是同一层信息。

为什么复用 NullTime 后会看到上一行的时间？

最常见原因是扫描错误被忽略，或者业务先读取了字段再处理错误。错误分支不能使用对象字段；扫描 NULL 本身会清零，但也仍要用 Valid 判断。