sql.NullString 区分 NULL 与空字符串的处理方案

在 Go 的数据库代码里，string 只能表达“有一个字符串值”，不能表达 SQL 的 NULL。如果一列允许为空，直接把它扫描到 string，就会把数据库的缺失值和业务上的空文本混在一起。

解决办法是使用 sql.NullString：String 保存文本，Valid 表示这个值是否不是 NULL。因此，判断结果时要看 Valid，不能只看 String。

官方文档：https://pkg.go.dev/database/sql#NullString

一、先看清 String 与 Valid 的分工

生产系统里常见一个“资料卡片”场景：用户没有填写备注时，数据库可能保存 NULL；用户主动清空备注时，业务又可能保存空字符串。这两个状态在审计、PATCH 更新和接口返回中不一定等价。

sql.NullString 的零值就是 String == "" 且 Valid == false。它的设计重点是把“字符串内容”和“是否存在”拆成两个字段。只要 Valid 为 false，就应该把它当作 NULL，而不是把 String 的空值当作最终判断。

换句话说，下面两个值的 String 完全相同，但业务含义不同：

package main

import "database/sql"

func exampleStates() (sql.NullString, sql.NullString) {
	// Valid=false 表示数据库值为 NULL；String 的零值只是伴随状态。
	missing := sql.NullString{}

	// Valid=true 表示这是一个真实字符串，即使字符串内容为空。
	empty := sql.NullString{String: "", Valid: true}
	return missing, empty
}

二、在 Scan 中接住可空列

读取可空字段时，把 sql.NullString 的地址传给 Scan。标准库在接收到数据库 NULL 时会把 Valid 设为 false；接收到可转换的字符串时会写入 String 并把 Valid 设为 true。

package repository

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

type UserNote struct {
	ID   int64
	Note sql.NullString
}

func loadUserNote(ctx context.Context, db *sql.DB, id int64) (UserNote, error) {
	var item UserNote
	const query = `SELECT id, note FROM user_profile WHERE id = ?`

	// QueryRowContext 把“查不到行”的错误延迟到 Scan，统一在这里处理。
	err := db.QueryRowContext(ctx, query, id).Scan(&item.ID, &item.Note)
	if err != nil {
		// ErrNoRows 与数据库连接、扫描类型错误是不同的分支，调用方可分别处理。
		return UserNote{}, fmt.Errorf("load user note: %w", err)
	}
	return item, nil
}

func noteForLog(note sql.NullString) string {
	if !note.Valid {
		// 不把 NULL 伪装成空文本，日志可以明确表达“未设置”。
		return ""
	}
	return note.String
}

如果使用多行查询，原则相同：每一轮 Scan 都应覆盖目标对象的字段，并在循环结束后检查 rows.Err()。如果复用同一个 sql.NullString 变量，不能假设旧值会自动代表当前行的业务语义，应以当前次扫描后的 Valid 为准。

三、把数据库状态映射到接口模型

数据库层保留三态，不代表接口层必须原样暴露结构体。关键是先决定接口契约：如果客户端需要区分“未设置”和“已设置为空”，可以转换成 *string；如果接口约定两者都显示为空，则可以在边界层显式归一化。

package api

import "database/sql"

type UserResponse struct {
	// 指针让 JSON 编码器能够区分 null 和 ""。
	Note *string `json:"note"`
}

func toUserResponse(note sql.NullString) UserResponse {
	if !note.Valid {
		// 数据库 NULL 映射为 JSON null；不要返回指向临时空字符串的指针。
		return UserResponse{Note: nil}
	}

	value := note.String
	// 有效的空字符串仍然返回非 nil 指针，JSON 结果是 ""。
	return UserResponse{Note: &value}
}

func toDisplayText(note sql.NullString) string {
	if !note.Valid {
		// 只有展示层明确允许合并语义时，才把 NULL 转成占位文本。
		return ""
	}
	return note.String
}

这个转换最好放在 repository 与 handler 的边界，不要在数据库扫描阶段就把 NULL 改成空字符串。这样同一份读取结果既能支持严格的 PATCH 语义，也能支持只需要展示文本的页面。

四、写回数据库并保留语义

sql.NullString 同时实现了 Scanner 和 driver.Valuer。写回时，Valid=false 会让 Value 返回 SQL NULL；Valid=true 会返回 String，即使该字符串为空。

package repository

import (
	"context"
	"database/sql"
)

func updateNote(ctx context.Context, db *sql.DB, id int64, note sql.NullString) error {
	const query = `UPDATE user_profile SET note = ? WHERE id = ?`

	// NullString 作为参数会调用 Value：Valid=false 写入 NULL，Valid=true 写入 String。
	_, err := db.ExecContext(ctx, query, note, id)
	return err
}

func clearNote() sql.NullString {
	// 业务明确要清除字段时返回 NULL，而不是把它误写成有效的空字符串。
	return sql.NullString{Valid: false}
}

func setNote(value string) sql.NullString {
	// value 即使是 "" 也代表“有效地设置为空”，与 clearNote 不同。
	return sql.NullString{String: value, Valid: true}
}

如果更新接口支持“保持原值、清空字段、设置文本”三种操作，单独使用一个普通 string 参数往往不够。可以在业务层先把操作解析成是否更新，再把真正要写入的值表示为 sql.NullString；不要用字符串内容猜测用户意图。

五、处理零值和常见误区

• 只判断 String：String == "" 同时可能对应 NULL 和有效空字符串，必须同时读取 Valid。
• 把 NullString 当成 string：扫描目标要传 &value，读取结果则使用 value.String 和 value.Valid。
• 忽略 Scan 错误：非字符串数据库值的转换可能失败，Valid 不能替代错误处理。
• 复用对象不重置：在手写转换或自定义扫描逻辑中，要让每次读取都覆盖当前状态；不要沿用上一条记录的 Valid。
• 把接口契约藏在 repository：数据库语义和 JSON 展示语义不同，建议在边界层做一次明确映射。

结语：先保留三态，再按边界归一化

sql.NullString 的核心并不复杂：String 表示内容，Valid 表示是否存在。读取时用它接住 SQL 的 NULL，接口层按契约转换，写回时让 Valid 决定 NULL 还是字符串。只要不把空字符串当作存在性判断，这个类型就能稳定地承接数据库和 Go 之间的可空文本。

常见问题

sql.NullString 的零值是空字符串吗？

它的 String 字段是空字符串，但 Valid 为 false，整体语义是 NULL，不是有效空字符串。

可以用 *string 替代 sql.NullString 吗？

在业务对象或 JSON 响应中可以，但直接作为 database/sql 的扫描目标时，sql.NullString 明确表达了 Scanner/Valuer 行为，通常更适合数据库边界。

Valid=true 且 String="" 会写入什么？

会写入有效的空字符串，不会写成 SQL NULL。只有 Valid=false 才表示 NULL。

扫描 NULL 到普通 string 会怎样？

普通 string 没有表示 NULL 的位置，扫描可能返回转换错误。因此可空列应在扫描目标处使用 sql.NullString 或其他可空类型。