JSON trong Golang: Marshal, Unmarshal và struct tag

Marshal và Unmarshal

json.Marshal biến một giá trị Go thành các byte JSON. json.Unmarshal điền dữ liệu từ các byte JSON vào một giá trị Go. Struct tag quyết định tên các trường trong 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 không có trong đầu ra đầu tiên vì có omitempty và chuỗi rỗng. Unmarshal cần một con trỏ (&back); truyền chính giá trị vào sẽ trả về một InvalidUnmarshalError.

Struct tag

Cú pháp tag là 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))
}

Mật khẩu không bao giờ rời khỏi struct, số dư được đặt trong dấu ngoặc kép, và deleted_at biến mất trong khi created_at in ra thời điểm zero 0001-01-01T00:00:00Z. Sự khác biệt đó là lý do omitzero ra đời: omitempty chưa bao giờ hoạt động với struct, và từ lâu đã là điều gây bất ngờ với time.Time. Trên Go 1.23 trở về trước, dùng *time.Time với omitempty để có cùng hiệu quả.

MarshalIndent(v, prefix, indent) tạo đầu ra dễ đọc. Hãy dùng nó cho tệp cấu hình và khi gỡ lỗi; API thường gửi JSON gọn.

Chỉ các trường được export

encoding/json dùng reflection và chỉ thấy được các trường được export. Đây là bug JSON phổ biến nhất trong Go:

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

Không lỗi, không cảnh báo, chỉ ra {} khi mã hóa và các trường vẫn là zero khi giải mã. Hãy viết hoa tên trường và thêm tag cho các khóa chữ thường.

Cách giải mã khớp các trường

Khi unmarshal vào một struct:

• Các khóa được khớp với tên trong tag, hoặc với tên trường, không phân biệt hoa thường. {"NAME": "x"} điền vào trường có tag json:"name".
• Các khóa không có trường tương ứng bị bỏ qua mà không báo gì.
• Các trường không có khóa tương ứng giữ nguyên giá trị hiện tại. Unmarshal không đặt lại chúng, nên giải mã vào một struct đã có dữ liệu sẽ trộn dữ liệu mới vào.
• Sai kiểu (một chuỗi ở chỗ struct có int) trả về một *json.UnmarshalTypeError, nhưng các trường khác vẫn được điền.

Để từ chối các khóa không mong đợi, ví dụ trong một API nghiêm ngặt hoặc một tệp cấu hình có lỗi gõ, dùng một Decoder với DisallowUnknownFields:

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)
}

Cấu trúc không biết trước: map[string]any

Khi không biết trước cấu trúc, hãy giải mã vào map[string]any hoặc any. Cách ánh xạ là cố định:

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)
}

Đầu ra cho thấy hai cái bẫy. Mọi số đều là float64, nên m["stock"].(int) sẽ thất bại. Và số nguyên lớn hơn 2^53 mất độ chính xác khi là float64: id 9007199254740993 quay về thành ...992. UseNumber tránh được cả hai.

Nếu bạn biết một phần cấu trúc, hãy giải mã phần đó vào struct và dùng json.RawMessage cho phần còn lại. Nó giữ các byte thô của một trường để bạn giải mã sau, khi đã biết kiểu của nó.

Slice, map, con trỏ và nil

Sự khác biệt giữa slice nil và slice rỗng quan trọng với các client API mong đợi một mảng. Hãy khởi tạo bằng []T{} hoặc make([]T, 0) khi trường phải là [].

Dùng trường con trỏ (*int, *bool) khi bạn cần phân biệt "không có" với "bằng zero" ở đầu vào. Sau khi unmarshal, một con trỏ nil nghĩa là khóa bị thiếu hoặc là null; một con trỏ tới 0 nghĩa là client đã gửi 0.

Luồng dữ liệu: Encoder và Decoder

json.Marshal và Unmarshal làm việc trên toàn bộ một slice byte. Với một io.Reader hoặc io.Writer (body HTTP, một tệp, stdin), dùng json.NewDecoder và json.NewEncoder. Decoder cũng có thể đọc lần lượt từng giá trị trong một chuỗi giá trị 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 ghi thêm một ký tự xuống dòng sau mỗi giá trị. Mặc định cả Marshal lẫn Encoder đều escape <, > và & thành \u003c, \u003e và \u0026, để JSON nhúng vào HTML một cách an toàn. SetEscapeHTML(false) tắt việc đó. Trong HTTP handler, json.NewDecoder(r.Body).Decode(&v) và json.NewEncoder(w).Encode(v) là cặp quen thuộc.

Tự định nghĩa cách mã hóa

Một kiểu có thể tự quyết định JSON của nó bằng cách triển khai json.Marshaler và json.Unmarshaler. Một trường hợp phổ biến là một enum dùng iota nên hiện ra dưới dạng tên chứ không phải số:

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 có value receiver nên dùng được cho cả giá trị lẫn con trỏ; UnmarshalJSON cần pointer receiver vì nó sửa đổi giá trị. Những kiểu chỉ cần dạng chuỗi có thể triển khai encoding.TextMarshaler (MarshalText) thay thế, việc này cũng giúp chúng dùng được làm khóa của map.

Lỗi thường gặp

• Tên trường viết thường. Chúng bị bỏ qua mà không báo gì.
• Truyền giá trị vào Unmarshal. Hàm này cần một con trỏ.
• Bỏ qua lỗi. JSON sai định dạng và sai kiểu chỉ được báo qua lỗi đó.
• Cho rằng các số trong map[string]any là int. Chúng là float64.
• Mong omitempty bỏ đi struct rỗng hoặc time.Time zero. Hãy dùng omitzero trên Go 1.24, hoặc dùng con trỏ.
• Dựa vào thứ tự trường trong map. Các khóa của map được sắp xếp khi xuất ra; các trường struct giữ thứ tự khai báo.