NullString序列化成空字符串怎么办

我在把数据库查询结果直接交给 JSON 接口时，最容易误判的一类字段就是 sql.NullString：数据库里的 NULL 到了 Go 里并不是一个“特殊字符串”，而是由 String 和 Valid 两个字段共同表达。若直接调用 json.Marshal，客户端看到的可能是空字符串，或者一个带有 String、Valid 字段的对象。

解决办法不是把空字符串强行替换掉，而是先确定 API 契约：如果缺失值应该是 JSON null，就用自定义序列化或 DTO 指针；如果调用方需要知道“是否来自 NULL”，就保留状态字段。

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

JSON 编码规则：https://pkg.go.dev/encoding/json#Marshal

先把 NULL 和空字符串分开

sql.NullString 的核心是下面两个字段：

• String 保存字符串内容，SQL NULL 时通常是它的零值 ""。
• Valid 表示这次扫描到的值是否不是 SQL NULL。

因此，String == "" 不能单独证明数据库值是 NULL。Valid=true, String="" 可以表示数据库里明确存了空字符串；Valid=false 才表示数据库值是 NULL。两种情况的业务意义可能完全不同。

为什么直接 Marshal 看起来像空字符串

encoding/json 默认按 Go 类型编码。NullString 是一个导出的结构体，标准库不会根据 Valid 自动猜测“这个结构体应该变成 null”。直接编码时，结构体的导出字段会参与结果。

package main

import (
    "database/sql"
    "encoding/json"
    "fmt"
)

func main() {
    // Valid=false 表示数据库列是 NULL；String 只是零值空字符串。
    missing := sql.NullString{String: "", Valid: false}

    // 标准库按结构体字段编码，不会自动把 Valid=false 改写成 JSON null。
    b, err := json.Marshal(missing)
    if err != nil {
        panic(err)
    }
    fmt.Println(string(b))
}

这里最重要的不是某一段输出文本，而是数据模型和接口模型没有对齐。数据库模型需要表达扫描和写回，接口模型则需要表达客户端能理解的 JSON 值。

小范围复用时，给 NullString 加 MarshalJSON

如果多个响应都希望保持同一规则，可以包一层类型：Valid=false 输出 null，Valid=true 输出字符串。这样数据库查询仍然可以使用 Scan，对外编码时才转换语义。

package api

import (
    "database/sql"
    "encoding/json"
)

// JSONNullString 把数据库可空字符串映射成 API 的 null 或字符串。
type JSONNullString struct {
    sql.NullString
}

// MarshalJSON 保留“NULL”和“空字符串”的差别，避免只看 String 的零值。
func (n JSONNullString) MarshalJSON() ([]byte, error) {
    if !n.Valid {
        // 数据库是 NULL 时，API 明确输出 JSON null。
        return []byte("null"), nil
    }

    // Valid=true 时，即使 String 是空串，也要输出合法 JSON 字符串。
    return json.Marshal(n.String)
}

// FromSQL 只负责把查询结果转成对外类型，避免调用方手动改 Valid。
func FromSQL(v sql.NullString) JSONNullString {
    return JSONNullString{NullString: v}
}

这种写法适合已经大量使用 NullString、又希望统一输出规则的项目。需要注意，API 一旦把 NULL 输出为 null，前端或其他调用方就应按可空字段处理，不能继续假设它永远是字符串。

更清晰的做法是把数据库模型转换成 DTO

对外接口字段不一定要复用数据库模型。用 *string 做 DTO 字段时，指针为 nil 就会编码成 JSON null；非空指针则编码成字符串。这样接口契约一眼可见，也不会把 Valid 暴露给客户端。

package api

import "database/sql"

type UserRow struct {
    Nickname sql.NullString
}

type UserDTO struct {
    // nil 输出 null；非 nil 输出字符串，包括明确的空字符串。
    Nickname *string `json:"nickname"`
}

func toStringPtr(v sql.NullString) *string {
    if !v.Valid {
        // SQL NULL 不伪造默认文案，交给 JSON 编码器输出 null。
        return nil
    }

    value := v.String
    return &value
}

func toUserDTO(row UserRow) UserDTO {
    // 转换层隔离数据库字段，避免把 String、Valid 原样暴露。
    return UserDTO{Nickname: toStringPtr(row.Nickname)}
}

当接口字段很多、需要做重命名或组合多个表时，我更倾向于 DTO 转换。它多了一层代码，但也把“数据库能存什么”和“接口允许什么”分开了。

Scan 时不要丢掉 Valid 的判断

查询阶段仍然要让 NullString 作为扫描目标，而不是先扫描到普通 string。普通字符串无法接住 SQL NULL，容易把数据库的缺失语义提前抹掉。

var nickname sql.NullString

// QueryRow 只负责定位一行，真正的查询和扫描错误由 Scan 返回。
err := db.QueryRowContext(ctx,
    "SELECT nickname FROM users WHERE id = ?", userID,
).Scan(&nickname)
if err != nil {
    // 生产代码应区分 sql.ErrNoRows 与数据库连接、语句等错误。
    return err
}

// 先在业务层决定 NULL 的含义，再转换成 API DTO。
dto := UserDTO{Nickname: toStringPtr(nickname)}

如果业务确实需要默认昵称，可以在这里根据 Valid 选择文案；如果业务需要保留缺失状态，就不要在查询层直接写成空字符串。

三个容易踩到的边界

omitempty 还会改变客户端看到的字段集合。比如 *string 为 nil 时，如果标签含有 omitempty，字段可能被省略，而不是输出 null。如果前端依赖字段始终存在，就不要只为了“看起来更短”而添加它。

最后怎么选

• 只想让所有可空字符串统一输出 null 或字符串：使用包装类型和 MarshalJSON。
• 接口需要隐藏数据库字段、重命名或拼接结果：转换成 DTO，使用 *string。
• 调用方确实需要知道是否来自 NULL：保留 Valid，或者在 DTO 中显式设计状态字段。

排查“NullString 序列化成空字符串”时，先检查 Valid，再检查 JSON 契约。不要用 String == "" 代替空值判断，也不要把数据库模型直接当成接口模型。

相关问题

NullString 的 Valid=true 但 String 为空，应该输出什么？

如果数据库确实存的是空字符串，通常输出 JSON 空字符串 ""；只有 Valid=false 才应按 SQL NULL 处理。

为什么不直接把数据库字段改成 string？

因为普通 string 无法表达 SQL NULL。提前改成 string 会丢掉缺失值与空字符串之间的差异。

DTO 用 *string 后还要保留 NullString 吗？

如果数据来自可空数据库列，查询和存储层仍可保留 NullString；DTO 只负责对外契约，两者职责不同。