Go database/sql用sql.NullString保留数据库NULL语义的写法

查询用户资料时，数据库里的 NULL 往往代表“尚未填写”，空字符串则可能代表“明确填写为空”。如果直接把列扫描到 Go 的 string，这两个状态就会被压成同一个零值。更稳妥的写法是让 sql.NullString 同时承载文本和有效标记：Valid=false 表示数据库值为 NULL，Valid=true 时再读取 String。

先把 NULL、空字符串和普通文本分开

假设 profiles.nickname 允许为空，三行数据可能分别是 NULL、'' 和 '林墨'。第一行是“没有值”，第二行是“有值但内容为空”，第三行是普通文本。业务层如果要展示占位符、统计填写率或判断是否允许二次补充，就必须保留这个区别。

直接扫描到 string 会在遇到 NULL 时产生转换错误或迫使调用方提前用 SQL 的 COALESCE 改写语义。查询层保留原状，通常更容易把数据库、领域模型和接口输出分别处理。

用 sql.NullString 接住查询结果

把扫描目标声明为 sql.NullString，Scan 会调用它的扫描逻辑。读取时先判断 Valid，不要把 String == "" 当作 NULL 判断：

package main

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

type Profile struct {
    ID       int64
    Nickname sql.NullString // String 保存文本，Valid 保存是否不是 NULL
}

func loadProfile(ctx context.Context, db *sql.DB, id int64) (Profile, error) {
    var p Profile
    // 参数化查询只读取目标列；Scan 的目标类型负责保留 NULL 状态。
    err := db.QueryRowContext(ctx,
        "SELECT id, nickname FROM profiles WHERE id = ?", id,
    ).Scan(&p.ID, &p.Nickname)
    if err != nil {
        // ErrNoRows 与数据库连接、扫描错误应交给上层分别处理。
        return Profile{}, fmt.Errorf("load profile %d: %w", id, err)
    }
    return p, nil
}

func displayName(p Profile) string {
    if !p.Nickname.Valid {
        return "未填写" // NULL 的展示策略由业务层决定。
    }
    return p.Nickname.String // 空字符串仍然保留为有值状态。
}

这里的关键不是把 NullString 当作最终领域对象，而是让查询层先拿到完整信息。实际项目还应检查 rows.Err()、及时关闭 Rows，并按驱动支持情况处理列类型。

在输出层决定是 null、空串还是省略

数据库语义保留后，API 是否返回 JSON null 要看接口约定。若前端需要知道“未填写”，可以把它转换为指针；若接口约定永远返回字符串，也可以在转换函数里把 NULL 映射为占位文本，但不要在查询阶段悄悄丢失状态。

type ProfileResponse struct {
    ID       int64   `json:"id"`
    Nickname *string `json:"nickname"` // nil 会编码为 JSON null
}

func toResponse(p Profile) ProfileResponse {
    out := ProfileResponse{ID: p.ID}
    if p.Nickname.Valid {
        value := p.Nickname.String
        out.Nickname = &value // 空字符串也会保留为 ""
    }
    return out
}

写回和排错时的四个边界

NullString.Value() 会根据 Valid 返回文本或 NULL，适合配合 ExecContext 更新。若业务只允许“有值/无值”而不允许空串，应在领域层额外校验，不能把数据库扫描类型当成业务校验器。

常见问题

为什么不能直接判断 Nickname.String == ""？

因为 NULL 和空字符串都可能得到空文本，只有 Valid 才能区分两者。

可以在 SQL 中统一用 COALESCE 吗？

可以，但这会把缺失值转换成默认值；需要统计 NULL、回显 JSON null 或执行不同业务分支时，应保留原始语义。

NullString 是否只能用于查询？

不是。它同时实现了扫描和参数值转换，写回时只要正确设置 Valid 即可。

最终判断很简单：需要保留数据库 NULL 语义，就把 sql.NullString 放在数据访问边界；进入领域或 API 层后，再依据业务契约选择占位文本、指针或 JSON null。