Go database/sql 怎么用 NullString 保存可空文本

如果数据库中的备注、昵称或扩展说明允许为 NULL，不要直接把查询结果扫描到 Go 的 string。database/sql 提供的 sql.NullString 会同时保留文本和“是否有值”的状态：Valid=true 表示不是 NULL，Valid=false 表示数据库返回了 NULL。这样可以把 SQL 的三态语义稳定地带回业务层。

读取时使用 var note sql.NullString 并 Scan(¬e)，展示或拼装响应前先判断 note.Valid；写回时让 Valid=false 表示真正的 SQL NULL，不要把空字符串当成替代品。

一、先区分 NULL 与空字符串

表中的可空文本至少有三种业务状态：字段为 NULL，字段为长度为零的空字符串，以及字段含有实际文字。第一种通常表示“没有提供”或“未知”，第二种可能表示“明确清空”。如果 Go 端只接收一个 string，这两个状态就会被压到同一个类型里。

sql.NullString 的核心结构只有两个公开字段：

因此，空字符串会得到 String == "" 且 Valid == true；SQL NULL 通常会得到 String == "" 且 Valid == false。真正有意义的判断是 Valid，而不是只看 String 是否为空。

二、用 NullString 扫描单行可空文本

读取单行记录时，把 NullString 的地址传给 Scan。下面的示例只展示查询与分支，驱动名和 DSN 由具体项目配置；代码中的 displayNote 明确把“没有备注”和“备注为空”留给业务规则决定。

package main

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

// readNote 读取一条用户记录，并保留 note 的 NULL 状态。
func readNote(ctx context.Context, db *sql.DB, userID int64) (string, bool, error) {
    var note sql.NullString
    err := db.QueryRowContext(ctx, `
        SELECT note
        FROM user_profile
        WHERE user_id = ?`, userID).Scan(¬e)
    if err != nil {
        // ErrNoRows 表示没有这条用户记录，不等同于 note 为 NULL。
        return "", false, fmt.Errorf("读取用户备注: %w", err)
    }

    if !note.Valid {
        // 数据库字段为 NULL，交给调用方决定展示文案。
        return "", false, nil
    }
    return note.String, true, nil
}

这里的 bool 表示“是否存在文本”，不是“查询是否成功”。调用方应该先处理 error，再根据布尔值选择默认文案。若直接 Scan(&plainString)，驱动把 NULL 传入时可能出现类似“converting NULL to string is unsupported”的错误。

三、在多行查询中保持状态判断

使用 Rows 时，每次循环都要让当前行的 NullString 接收新的扫描结果。不要把上一行的 Valid 当作下一行的默认值，也不要只在循环结束后检查错误。

rows, err := db.QueryContext(ctx, `
    SELECT user_id, note
    FROM user_profile
    ORDER BY user_id`)
if err != nil {
    return err
}
defer rows.Close() // 即使中途 Scan 失败，也要释放结果集资源。

for rows.Next() {
    var (
        userID int64
        note   sql.NullString
    )
    if err := rows.Scan(&userID, ¬e); err != nil {
        return fmt.Errorf("扫描用户 %d 的备注: %w", userID, err)
    }

    if note.Valid {
        fmt.Printf("%d: %s\\n", userID, note.String)
    } else {
        fmt.Printf("%d: \\n", userID)
    }
}
if err := rows.Err(); err != nil {
    return fmt.Errorf("遍历用户备注: %w", err)
}

这段代码把“查询失败”“单行扫描失败”和“迭代过程中出现的错误”分开处理。若接口响应要区分三态，可以把 Valid 原样转换成指针或带状态的响应字段，而不是无条件输出一个空字符串。

四、写回数据库时保留可空语义

NullString 不只是扫描目标，也实现了 driver.Valuer。当 Valid=true 时，它可以作为文本参数；当 Valid=false 时，驱动会得到代表 SQL NULL 的值。更新前先把业务输入转换成明确的状态：

func updateNote(ctx context.Context, db *sql.DB, userID int64, text *string) error {
    var note sql.NullString
    if text != nil {
        // 非 nil 表示调用方明确提供了文本；空字符串仍是有效值。
        note.String = *text
        note.Valid = true
    }

    _, err := db.ExecContext(ctx, `
        UPDATE user_profile
        SET note = ?
        WHERE user_id = ?`, note, userID)
    if err != nil {
        return fmt.Errorf("更新用户备注: %w", err)
    }
    return nil
}

示例中 text == nil 才会写入 SQL NULL；text 指向空字符串则写入空字符串。若接口还需要表达“保持原值不变”，应额外设计更新命令的字段存在性，而不能把 nil 同时解释成“清空”和“不修改”。

常见问题

NullString.Valid 为 false 时还能读取 String 吗？

可以读取，但此时的空字符串只是结构体的零值，不应把它当成数据库真实保存的文本。业务判断应优先看 Valid。

空字符串和 NULL 应该统一吗？

只有在业务明确不需要区分“未提供”和“明确清空”时才统一。否则保留两种状态，后续筛选、统计和接口回显会更准确。

只查询一行时要不要关闭 Rows？

使用 QueryRowContext 不需要手动关闭 Rows；使用 QueryContext 得到的结果集则应关闭，并在循环后检查 rows.Err()。

参考：Go database/sql NullString 文档；Go 数据库查询指南。