如何为 Go 中的 sql.Null* 类型自定义 JSON 序列化行为

本文详解如何通过实现 encoding.TextMarshaler 接口，让 sql.NullFloat64 等类型在 JSON 编码时仅输出原始值（如 141.0）或 null，而非默认的 { "Float64": ..., "Valid": ... } 结构。

本文详解如何通过实现 `encoding.TextMarshaler` 接口，让 `sql.NullFloat64` 等类型在 JSON 编码时仅输出原始值（如 `141.0`）或 `null`，而非默认的 `{ "Float64": ..., "Valid": ... }` 结构。

在 Go 语言中，database/sql 提供的 sql.Null* 类型（如 sql.NullFloat64、sql.NullString）虽能安全表示数据库中的可空字段，但其默认 JSON 序列化行为并不符合 API 设计惯例：它会将整个结构体字段暴露为 JSON 对象，例如：

{ "Float64": 141, "Valid": true }

而我们通常期望的是更简洁、语义更清晰的输出：

141.0

或当值为空时：

null

要达成这一目标，不能依赖 json.Marshaler（因为 sql.Null* 类型本身未实现该接口），而应利用 Go 的 encoding/json 包对 encoding.TextMarshaler 接口的特殊支持——当类型实现了 MarshalText() ([]byte, error)，json.Marshal 会自动将其返回的字节切片作为字符串字面量编码（即等效于 "..."），但前提是该值被嵌入在字符串上下文中（如 map[string]interface{} 或 []interface{} 中）；然而，更可靠且通用的方式是：*直接为 `sql.Null衍生自定义类型，并正确实现json.Marshaler`**。

⚠️ 注意：原问题中尝试实现 MarshalText() 是一个常见误区。MarshalText() 属于 encoding.TextMarshaler，它影响的是 fmt.String()、strconv 转换及某些文本序列化场景（如 CSV、YAML），但 json.Marshal 默认并不调用 MarshalText() ——除非你显式使用 json.RawMessage 或通过 text.Marshaler 间接桥接。真正的 JSON 控制权在 json.Marshaler 接口。

✅ 正确做法：为自定义 NullFloat64 实现 json.Marshaler：

package main

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

// NullFloat64 是 sql.NullFloat64 的封装，支持自定义 JSON 序列化
type NullFloat64 struct {
    sql.NullFloat64
}

// MarshalJSON 实现 json.Marshaler 接口
func (nf NullFloat64) MarshalJSON() ([]byte, error) {
    if !nf.Valid {
        return []byte("null"), nil
    }
    // 将 float64 格式化为无尾随零的 JSON 数字（避免引号）
    return []byte(strconv.FormatFloat(nf.Float64, 'f', -1, 64)), nil
}

// UnmarshalJSON 可选：保持反序列化兼容性
func (nf *NullFloat64) UnmarshalJSON(data []byte) error {
    if len(data) == 0 || string(data) == "null" {
        nf.Valid = false
        return nil
    }
    var f float64
    if err := json.Unmarshal(data, &f); err != nil {
        return err
    }
    nf.Float64 = f
    nf.Valid = true
    return nil
}

使用示例：

func main() {
    data := []NullFloat64{
        {sql.NullFloat64{Float64: 141.0, Valid: true}},
        {sql.NullFloat64{Float64: 0.0, Valid: false}},
        {sql.NullFloat64{Float64: 3.1415926, Valid: true}},
    }

    b, _ := json.Marshal(data)
    println(string(b)) // 输出：[141,null,3.1415926]
}

? 关键要点总结：

• MarshalText() ≠ json.Marshaler：前者用于文本格式（如日志、CSV），后者专用于 JSON；
• sql.Null* 原生不实现 json.Marshaler，必须封装并重写；
• MarshalJSON() 返回 []byte 时，若内容为合法 JSON 字面量（如 "141"、"null"、"true"），json 包会直接嵌入，不会额外加引号；
• 若需支持 nil 指针语义（如 *NullFloat64），应在 MarshalJSON 中增加 nil 判定；
• 生产环境建议同时实现 UnmarshalJSON，确保序列化/反序列化对称。

通过以上方式，你就能彻底摆脱冗余 JSON 结构，让 API 响应更专业、前端解析更简单。