Go database/sql把NULL时间扫描到sql.NullTime的方法

查询表里的可选时间字段时，直接把结果扫描到 time.Time 往往会在遇到 SQL NULL 时失败，或者让后续代码把“没有设置”误当成零时间。更稳妥的做法是使用 sql.NullTime：它同时保留 Time 和 Valid，业务层再决定展示什么。

把可空时间扫描到 sql.NullTime，使用 Valid 判断是否为 NULL，只有 Valid=true 时才读取并格式化 Time。这样 NULL、零时间和具体时间不会混成一个状态。

sql.NullTime 接住 NULL 并保留有效状态

官方 database/sql 文档把 NullTime 定义为可能为 NULL 的 time.Time。它包含 Time time.Time 和 Valid bool 两个字段，并实现了 Scanner 接口，所以可以直接作为 Scan 的目标。

查询结果不是 NULL 时，驱动交给扫描层的值会进入 Time，同时 Valid 为 true；结果为 NULL 时，Valid 为 false，代码不应再把 Time 当作业务时间使用。

package repository

import (
    "context"
    "database/sql"
    "fmt"
    "time"
)

type Event struct {
    ID        int64
    Name      string
    StartsAt  sql.NullTime
}

func loadEvent(ctx context.Context, db *sql.DB, id int64) (Event, error) {
    var event Event

    // 让Scan直接写入NullTime，保留数据库列是否为NULL的信息。
    err := db.QueryRowContext(ctx,
        "SELECT id, name, starts_at FROM events WHERE id = ?", id,
    ).Scan(&event.ID, &event.Name, &event.StartsAt)
    if err != nil {
        // 查询失败和时间为空是两种状态，不能用同一个默认值掩盖错误。
        return Event{}, fmt.Errorf("load event: %w", err)
    }
    return event, nil
}

func displayStartAt(t sql.NullTime, loc *time.Location) string {
    // Valid=false表示数据库是NULL，展示层给出明确的未设置文案。
    if !t.Valid {
        return "未设置"
    }
    // 时区和格式属于展示决策，不要在Scan阶段修改原始时间状态。
    return t.Time.In(loc).Format("2006-01-02 15:04")
}

这里没有把 NULL 转成 time.Time{}。零时间是一个真实的 Go 值，而 Valid=false 才表示数据库字段没有值。接口返回 JSON、列表筛选和排序时，都可以据此制定不同规则。

Rows 循环中按 Valid 决定展示结果

多行查询的处理方式相同，只是每行都要有自己的 sql.NullTime。建议把扫描错误、行迭代错误和空时间展示分开处理。下面的代码只展示结构关系，示例输出应以实际驱动和业务数据为准。

func listEvents(ctx context.Context, db *sql.DB) ([]string, error) {
    rows, err := db.QueryContext(ctx,
        "SELECT name, starts_at FROM events ORDER BY id",
    )
    if err != nil {
        return nil, fmt.Errorf("query events: %w", err)
    }
    defer rows.Close() // 提前返回时仍释放结果集占用的连接。

    loc, err := time.LoadLocation("Asia/Shanghai")
    if err != nil {
        return nil, fmt.Errorf("load display timezone: %w", err)
    }

    result := make([]string, 0)
    for rows.Next() {
        var name string
        var startsAt sql.NullTime
        // 每行重新接收可空时间，避免复用旧的Valid状态。
        if err := rows.Scan(&name, &startsAt); err != nil {
            return nil, fmt.Errorf("scan event: %w", err)
        }
        result = append(result, name+" / "+displayStartAt(startsAt, loc))
    }
    if err := rows.Err(); err != nil {
        // 驱动可能在Next之后才报告网络或解码错误。
        return nil, fmt.Errorf("iterate events: %w", err)
    }
    return result, nil
}

展示层可以把 Valid=false 渲染成“未设置”、留空或单独的筛选选项；不要无条件调用 t.Time.Format。如果产品要求统一默认时间，也应在这一层明确写出规则，避免数据库读取逻辑替业务做决定。

展示、回写与驱动边界要分开

NullTime 不负责替你选择时区，也不保证所有驱动把数据库时间列转换成完全相同的输入类型。写入前要确认驱动支持的时间值形式；读取时遇到类型转换错误，应记录原始错误并回到驱动、列类型和连接配置排查。

需要更新可空时间时，可以让 NullTime.Value() 参与参数绑定：

func updateStartAt(ctx context.Context, db *sql.DB, id int64, t sql.NullTime) error {
    // Value会把Valid=false表达为SQL NULL，Valid=true表达为具体时间。
    _, err := db.ExecContext(ctx,
        "UPDATE events SET starts_at = ? WHERE id = ?", t, id,
    )
    if err != nil {
        return fmt.Errorf("update event time: %w", err)
    }
    return nil
}

因此，“清除时间”不必伪造一个特殊日期；把 Valid 设为 false 就能表达清空。反过来，若业务确实要保存 Go 的零时间，应该设置 Valid=true，并在接口契约中说明它与 NULL 的区别。

上线前的四项检查

还要特别注意复用变量：如果同一个 NullTime 跨行复用，必须确保每次扫描都覆盖状态；更简单的方式是在循环体内声明。测试数据至少应同时包含 NULL、正常时间和业务允许的零时间三种情况。

常见问题

为什么不直接扫描到 *time.Time？

指针方案也可以表达缺失，但 sql.NullTime 与 database/sql 的 Scanner/Valuer 协作更直接，读取和回写都能显式保留 Valid。

Valid=false 时 Time 是什么值？

不要依赖它做业务判断。判断条件应是 Valid；Time 只是结构体中的时间字段，NULL 分支下通常不应被读取。

数据库列不允许 NULL，还需要 NullTime 吗？

如果数据库约束和业务契约都保证非 NULL，直接使用 time.Time 更简单；只有当字段确实可空或迁移期间存在空值时，才引入可空状态。