Go语言 sql.Null 类型详解：处理数据库 NULL 值的正确姿势

1. 引言：数据库 NULL 值处理的痛点

在 Go 语言中操作数据库时，一个常见且棘手的问题是如何处理 SQL 中的 NULL 值。Go 的基本数据类型（如 int、string、bool）无法直接表示 SQL 的 NULL 状态。如果数据库某字段为 NULL，而 Go 代码尝试将其扫描（Scan）到一个 int 变量中，将会导致错误。

例如，假设有一个用户表，其中的 age 字段允许为 NULL：

CREATE TABLE users (
    id INT PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    age INT NULL -- 允许为 NULL
);

使用标准库 database/sql 查询时，如果直接将结果扫描到 int 类型的变量，当 age 为 NULL 时会报错：

var age int
err := row.Scan(&age) // 如果 age 为 NULL，这里会报错！

为了解决这个问题，Go 的 database/sql 包提供了一系列 sql.Null 类型，它们是处理可空字段的"标准答案"。

2. sql.Null 类型家族

database/sql 包为常见的 SQL 数据类型提供了对应的可空包装类型。它们都遵循相似的结构：包含一个基础类型的 Val 字段和一个表示有效性的 Valid 布尔字段。

类型	对应 Go 基础类型	说明
sql.NullString	string	可空字符串
sql.NullInt32	int32	可空 32 位整数
sql.NullInt64	int64	可空 64 位整数
sql.NullFloat64	float64	可空双精度浮点数
sql.NullBool	bool	可空布尔值
sql.NullTime	time.Time	可空时间
sql.NullByte	byte	可空字节（Go 1.17+）
sql.NullInt16	int16	可空 16 位整数

它们的内部结构大同小异，以 sql.NullString 为例：

// 源码节选
type NullString struct {
    String string
    Valid  bool // Valid 为 true 时，String 才包含有效数据
}

当 Valid 为 false 时，表示数据库中的值是 NULL，此时 String 字段的值是零值（空字符串），不应被使用。

3. 基础用法：查询与扫描

3.1 声明与扫描

在查询时，你需要声明对应字段的变量为 sql.Null 类型。

package main

import (
    "database/sql"
    "fmt"
    "log"
    _ "github.com/go-sql-driver/mysql"
)

func main() {
    db, err := sql.Open("mysql", "user:password@/dbname")
    if err != nil {
        log.Fatal(err)
    }
    defer db.Close()

    var (
        id   int
        name string
        age  sql.NullInt64 // 使用 NullInt64 接收可能为 NULL 的 age
    )

    row := db.QueryRow("SELECT id, name, age FROM users WHERE id = ?", 1)
    err = row.Scan(&id, &name, &age)
    if err != nil {
        log.Fatal(err)
    }

    // 使用前必须检查 Valid
    if age.Valid {
        fmt.Printf("用户年龄: %d\n", age.Int64)
    } else {
        fmt.Println("用户年龄: (未设置)")
    }
}

3.2 插入与更新

当需要向数据库插入或更新一个可能为 NULL 的值时，也需要使用 sql.Null 类型。

// 插入一个年龄未知（NULL）的用户
newAge := sql.NullInt64{Valid: false} // Valid 为 false 表示 NULL
// 或者使用 Int64 的零值，但 Valid 为 false
// newAge := sql.NullInt64{}

result, err := db.Exec(
    "INSERT INTO users (name, age) VALUES (?, ?)",
    "张三",
    newAge, // 这里传递 sql.NullInt64
)
if err != nil {
    log.Fatal(err)
}

// 更新，将某个用户的年龄设置为 NULL
_, err = db.Exec(
    "UPDATE users SET age = ? WHERE id = ?",
    sql.NullInt64{}, // 等价于 sql.NullInt64{Valid: false}
    2,
)

关键点 ：驱动（如 mysql、pq）会检查传入参数的类型。当它发现是一个 sql.NullInt64 且 Valid 为 false 时，会在生成的 SQL 中放入 NULL 字面量。

4. 进阶技巧与最佳实践

4.1 便捷构造函数

为每个 sql.Null 类型编写一个便捷的构造函数或使用字面量初始化，可以让代码更清晰。

func NewNullString(s string) sql.NullString {
    return sql.NullString{
        String: s,
        Valid:  s != "", // 根据业务逻辑定义"有效"条件
    }
}

func NewNullInt64(i int64) sql.NullInt64 {
    return sql.NullInt64{
        Int64: i,
        Valid: true,
    }
}

// 使用
age := NewNullInt64(25)
nullableName := NewNullString("") // Valid 将为 false

4.2 与 JSON 序列化的配合

sql.Null 类型默认的 JSON 序列化行为可能不符合预期。它们会被序列化为一个包含 Val 和 Valid 字段的对象。通常我们希望在 Valid 为 false 时序列化为 JSON 的 null。

你需要为它们实现自定义的 MarshalJSON 和 UnmarshalJSON 方法，或者使用指针。

type User struct {
    ID   int             `json:"id"`
    Name string          `json:"name"`
    Age  *int64          `json:"age,omitempty"` // 使用指针，nil 对应 JSON null
}

// 从数据库扫描到结构体
row := db.QueryRow("SELECT id, name, age FROM users WHERE id = ?", 1)
var (
    id   int
    name string
    age  sql.NullInt64
)
row.Scan(&id, &name, &age)

user := User{
    ID:   id,
    Name: name,
}
if age.Valid {
    user.Age = &age.Int64 // 只有有效时才赋值指针
}
// user.Age 为 nil 时，JSON 输出中 age 字段会被忽略（omitempty）或为 null

4.3 在模板或业务逻辑中使用

在模板渲染或业务逻辑中，始终先检查 Valid。

// 业务逻辑
func formatAge(age sql.NullInt64) string {
    if !age.Valid {
        return "保密"
    }
    return fmt.Sprintf("%d岁", age.Int64)
}

// 模板中使用 (例如 html/template)
// {{if .Age.Valid}}{{.Age.Int64}}{{else}}未设置{{end}}

5. 常见陷阱与替代方案

5.1 陷阱：忘记检查 Valid

这是最常见的错误。直接使用 NullXXX.Val 而不检查 Valid，当值为 NULL 时，你使用的是该类型的零值，这可能导致逻辑错误。

// 错误示例
avgAge := totalAge / userCount // 如果 totalAge 来自某个 SUM(age)，而 age 有 NULL，结果可能不对

5.2 替代方案：使用指针

除了 sql.Null 类型，你也可以直接使用指针（如 *string, *int64）来接收可能为 NULL 的值。database/sql 的 Scan 方法支持将 NULL 扫描到 nil 指针。

var age *int64
err := row.Scan(&age)
if err != nil {
    log.Fatal(err)
}
if age != nil {
    fmt.Println(*age)
} else {
    fmt.Println("NULL")
}

指针 vs sql.Null：

• 指针 ：更符合 Go 语言习惯（nil 表示空），与 JSON 序列化配合更好。但指针可能带来额外的内存分配和 nil 检查。
• sql.Null ：值类型，无额外内存分配，语义明确（Valid 字段）。但 JSON 序列化需要额外处理。

选择哪种取决于你的项目约定和主要使用场景。

5.3 使用第三方库

一些第三方库提供了更丰富的可空类型支持，例如：

• gopkg.in/guregu/null.v4 ：功能强大，支持更多类型（如 null.UUID），且 JSON 序列化行为更直观。
• github.com/volatiletech/null/v9：通常与 SQLBoiler 等 ORM 搭配使用。

6. 总结

sql.Null 类型是 Go 标准库为处理数据库 NULL 值提供的标准、安全的解决方案。其核心在于 Valid 字段，在使用值之前必须检查它。

使用要点总结：

1. 声明 ：查询可能为 NULL 的字段时，使用对应的 sql.NullXXX 类型。
2. 扫描 ：Scan 方法会自动根据数据库值设置 Valid 字段。
3. 使用前检查 ：任何使用 .Val 字段前，务必检查 Valid 是否为 true。
4. 插入/更新 ：要设置 NULL，就传递一个 Valid: false 的 sql.Null 实例。
5. 序列化：考虑 JSON 序列化需求，可能需要配合指针或自定义序列化。
6. 选择 ：在标准 sql.Null、指针和第三方库之间，根据团队规范和项目复杂度做出选择。

掌握 sql.Null 的正确用法，能让你在 Go 中与数据库交互时更加得心应手，避免因 NULL 值导致的运行时错误和数据不一致问题。