Golang JSON：Marshal、Unmarshal 与结构体标签

Marshal 与 Unmarshal

json.Marshal 把 Go 值转换成 JSON 字节。json.Unmarshal 用 JSON 字节填充一个 Go 值。结构体标签决定 JSON 中的字段名。

package main

import (
	"encoding/json"
	"fmt"
)

type User struct {
	ID    int      `json:"id"`
	Name  string   `json:"name"`
	Email string   `json:"email,omitempty"`
	Tags  []string `json:"tags"`
}

func main() {
	u := User{ID: 1, Name: "Ada", Tags: []string{"admin"}}

	data, err := json.Marshal(u)
	if err != nil {
		fmt.Println("marshal:", err)
		return
	}
	fmt.Println(string(data))

	var back User
	input := []byte(`{"id": 2, "name": "Linus", "email": "l@example.com", "tags": ["kernel", "git"]}`)
	if err := json.Unmarshal(input, &back); err != nil {
		fmt.Println("unmarshal:", err)
		return
	}
	fmt.Printf("%+v\n", back)
}

第一次输出中没有 Email，因为它带有 omitempty，而值是空字符串。Unmarshal 需要一个指针（&back）；直接传入值本身会返回 InvalidUnmarshalError。

结构体标签

标签的语法是 json:"name,option,option"。

package main

import (
	"encoding/json"
	"fmt"
	"time"
)

type Account struct {
	ID        int       `json:"id"`
	Password  string    `json:"-"`
	Nickname  string    `json:"nickname,omitempty"`
	Balance   int64     `json:"balance,string"`
	CreatedAt time.Time `json:"created_at,omitempty"` // omitempty never omits a struct
	DeletedAt time.Time `json:"deleted_at,omitzero"`  // Go 1.24: omitted when zero
	internal  string    // unexported: always ignored
}

func main() {
	a := Account{ID: 7, Password: "hunter2", Balance: 1500, internal: "x"}
	out, err := json.MarshalIndent(a, "", "  ")
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(out))
}

密码永远不会离开结构体，余额带上了引号，deleted_at 消失了，而 created_at 打印出零值时间 0001-01-01T00:00:00Z。这个差别正是新增 omitzero 的原因：omitempty 从来都对结构体无效，在 time.Time 上更是长期让人意外。在 Go 1.23 及更早的版本中，可以用带 omitempty 的 *time.Time 达到同样的效果。

MarshalIndent(v, prefix, indent) 生成易读的输出。它适合用于配置文件和调试；API 通常发送紧凑的 JSON。

只处理导出字段

encoding/json 通过反射工作，只能看到导出的字段。这是 Go 中最常见的 JSON bug：

type point struct {
	x, y int // lowercase: json.Marshal(point{1, 2}) gives {}
}

没有错误，也没有警告，编码时只得到 {}，解码时字段保持零值。把字段名首字母大写，再为小写键名加上标签。

解码时如何匹配字段

解码到结构体时：

• 键会与标签名或字段名进行不区分大小写的匹配。{"NAME": "x"} 会填充标签为 json:"name" 的字段。
• 没有对应字段的键会被悄悄忽略。
• 没有对应键的字段会保留原来的值。Unmarshal 不会重置它们，所以解码到一个已有数据的结构体时，结果是合并进去的。
• 类型不匹配（结构体中是 int，JSON 里却是字符串）会返回 *json.UnmarshalTypeError，但其他字段仍然会被填充。

如果要拒绝意料之外的键，比如在严格的 API 中，或者在可能有拼写错误的配置文件中，就使用带 DisallowUnknownFields 的 Decoder：

package main

import (
	"encoding/json"
	"fmt"
	"strings"
)

type Config struct {
	Port  int  `json:"port"`
	Debug bool `json:"debug"`
}

func main() {
	input := `{"port": 8080, "debgu": true}` // typo in "debug"

	var lenient Config
	err := json.Unmarshal([]byte(input), &lenient)
	fmt.Printf("Unmarshal: %+v, err=%v\n", lenient, err)

	var strict Config
	dec := json.NewDecoder(strings.NewReader(input))
	dec.DisallowUnknownFields()
	err = dec.Decode(&strict)
	fmt.Println("Decoder:", err)

	var typed Config
	err = json.Unmarshal([]byte(`{"port": "8080"}`), &typed)
	fmt.Println("type mismatch:", err)
}

结构未知：map[string]any

如果事先不知道数据的结构，就解码到 map[string]any 或 any 中。对应关系是固定的：

package main

import (
	"encoding/json"
	"fmt"
	"strings"
)

func main() {
	input := `{"name": "widget", "price": 9.5, "stock": 3, "tags": ["a", "b"], "meta": {"id": 9007199254740993}}`

	var m map[string]any
	if err := json.Unmarshal([]byte(input), &m); err != nil {
		fmt.Println(err)
		return
	}

	name, _ := m["name"].(string)
	stock, _ := m["stock"].(float64) // numbers are float64, even 3
	tags, _ := m["tags"].([]any)
	fmt.Println(name, int(stock), len(tags))

	meta := m["meta"].(map[string]any)
	fmt.Printf("id as float64: %.0f\n", meta["id"]) // precision lost

	// UseNumber keeps numbers as json.Number (a string) for exact handling.
	dec := json.NewDecoder(strings.NewReader(input))
	dec.UseNumber()
	var exact map[string]any
	if err := dec.Decode(&exact); err != nil {
		fmt.Println(err)
		return
	}
	id, err := exact["meta"].(map[string]any)["id"].(json.Number).Int64()
	fmt.Println("id with UseNumber:", id, err)
}

输出中可以看到两个陷阱。所有数字都是 float64，所以 m["stock"].(int) 会失败。而且大于 2^53 的整数存成 float64 时会丢失精度：id 9007199254740993 读回来变成了 ...992。UseNumber 可以同时避免这两个问题。

如果你知道部分结构，就把这部分解码到结构体中，其余部分使用 json.RawMessage。它保存字段的原始字节，等你知道它的类型后再解码。

切片、map、指针与 nil

对于期望得到数组的 API 客户端来说，nil 切片和空切片的区别很重要。当字段必须是 [] 时，用 []T{} 或 make([]T, 0) 初始化。

如果需要在输入中区分“缺失”和“零值”，就使用指针字段（*int、*bool）。解码后，nil 指针表示这个键不存在或为 null；指向 0 的指针表示客户端发送的就是 0。

数据流：Encoder 与 Decoder

json.Marshal 和 Unmarshal 处理的是完整的字节切片。对于 io.Reader 或 io.Writer（HTTP 请求体、文件、标准输入），使用 json.NewDecoder 和 json.NewEncoder。Decoder 还可以逐个读取一连串 JSON 值：

package main

import (
	"encoding/json"
	"errors"
	"fmt"
	"io"
	"os"
	"strings"
)

type Event struct {
	Type string `json:"type"`
	N    int    `json:"n"`
}

func main() {
	// Newline-delimited JSON, as in log files and many streaming APIs.
	stream := `{"type":"click","n":1}
{"type":"view","n":2}
{"type":"click","n":3}`

	dec := json.NewDecoder(strings.NewReader(stream))
	clicks := 0
	for {
		var e Event
		err := dec.Decode(&e)
		if errors.Is(err, io.EOF) {
			break
		}
		if err != nil {
			fmt.Println("decode:", err)
			return
		}
		if e.Type == "click" {
			clicks++
		}
	}
	fmt.Println("clicks:", clicks)

	enc := json.NewEncoder(os.Stdout)
	enc.SetEscapeHTML(false) // keep <, > and & readable
	enc.SetIndent("", "  ")
	if err := enc.Encode(map[string]any{"clicks": clicks, "note": "a < b & c"}); err != nil {
		fmt.Println("encode:", err)
	}
}

Encoder.Encode 在每个值后面写一个换行符。默认情况下，Marshal 和 Encoder 都会把 \u003c、\u003e 和 \u0026 转义成 \u003c、\u003e 和 \u0026，这样 JSON 可以安全地嵌入 HTML。SetEscapeHTML(false) 可以关闭这一行为。在 HTTP 处理器中，json.NewDecoder(r.Body).Decode(&v) 和 json.NewEncoder(w).Encode(v) 是常用的一对。

自定义编码

一个类型可以通过实现 json.Marshaler 和 json.Unmarshaler 来控制自己的 JSON 形式。常见的例子是一个 iota 枚举，它应该显示为名字，而不是数字：

package main

import (
	"encoding/json"
	"fmt"
	"strings"
)

type Level int

const (
	Low Level = iota
	High
)

var levelNames = []string{"low", "high"}

func (l Level) MarshalJSON() ([]byte, error) {
	return json.Marshal(levelNames[l])
}

func (l *Level) UnmarshalJSON(b []byte) error {
	var s string
	if err := json.Unmarshal(b, &s); err != nil {
		return err
	}
	for i, name := range levelNames {
		if strings.EqualFold(s, name) {
			*l = Level(i)
			return nil
		}
	}
	return fmt.Errorf("unknown level %q", s)
}

type Alert struct {
	Msg   string `json:"msg"`
	Level Level  `json:"level"`
}

func main() {
	out, _ := json.Marshal(Alert{Msg: "disk full", Level: High})
	fmt.Println(string(out))

	var a Alert
	err := json.Unmarshal([]byte(`{"msg":"cpu","level":"LOW"}`), &a)
	fmt.Printf("%+v %v\n", a, err)

	err = json.Unmarshal([]byte(`{"msg":"cpu","level":"urgent"}`), &a)
	fmt.Println(err)
}

MarshalJSON 使用值接收者，所以对值和指针都有效；UnmarshalJSON 需要指针接收者，因为它要修改值。如果类型只需要字符串形式，可以改为实现 encoding.TextMarshaler（MarshalText），这样它还能用作 map 的键。

常见错误

• 字段名小写。 它们会被悄悄跳过。
• 把值传给 Unmarshal。 它需要指针。
• 忽略错误。 格式错误的 JSON 和类型不匹配只会通过错误报告出来。
• 以为 map[string]any 中的数字是 int。 它们是 float64。
• 指望 omitempty 省略空结构体或零值 time.Time。 在 Go 1.24 上使用 omitzero，或者使用指针。
• 依赖 map 中的字段顺序。 map 的键在输出时会排序；结构体字段则保持声明时的顺序。