Golang JSON: Marshal, Unmarshal ve Struct Tag'leri

Marshal ve Unmarshal

json.Marshal bir Go değerini JSON baytlarına çevirir. json.Unmarshal bir Go değerini JSON baytlarından doldurur. Struct tag'leri JSON alan adlarını seçer.

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 ilk çıktıda omitempty ve boş bir string nedeniyle eksik. Unmarshal bir pointer ister (&back); değerin kendisini aktarmak bir InvalidUnmarshalError döndürür.

Struct tag'leri

Tag söz dizimi json:"name,option,option" şeklindedir.

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

Parola struct'tan hiç çıkmaz, bakiye tırnak içine alınır ve deleted_at kaybolurken created_at sıfır zamanı 0001-01-01T00:00:00Z yazdırır. omitzero'nun eklenmesinin nedeni bu farktır: omitempty struct'lar için hiç çalışmadı ve time.Time ile uzun süredir bilinen bir sürprizdir. Go 1.23 ve öncesinde aynı etkiyi elde etmek için omitempty ile bir *time.Time kullanın.

MarshalIndent(v, prefix, indent) okunabilir çıktı üretir. Onu yapılandırma dosyaları ve hata ayıklama için kullanın; API'ler genellikle sıkıştırılmış JSON gönderir.

Yalnızca dışa açık alanlar

encoding/json reflection kullanır ve yalnızca dışa açık alanları görebilir. Go'daki en yaygın JSON hatası budur:

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

Hata yok, uyarı yok; çıkışta yalnızca {}, girişte sıfırda bırakılan alanlar. Alanları büyük harfle başlatın ve küçük harfli anahtarlar için tag ekleyin.

Çözme alanları nasıl eşleştirir

Bir struct'a unmarshal ederken:

• Anahtarlar tag adıyla ya da alan adıyla büyük/küçük harf duyarsız eşleştirilir. {"NAME": "x"}, json:"name" tag'li bir alanı doldurur.
• Eşleşen alanı olmayan anahtarlar sessizce yok sayılır.
• Eşleşen anahtarı olmayan alanlar mevcut değerlerini korur. Unmarshal onları sıfırlamaz, bu yüzden zaten verisi olan bir struct'a çözmek onunla birleştirir.
• Bir tip uyuşmazlığı (struct'ta int olan yerde bir string) bir *json.UnmarshalTypeError döndürür, ama diğer alanlar yine doldurulur.

Beklenmeyen anahtarları reddetmek için, örneğin katı bir API'de ya da yazım hatalı bir yapılandırma dosyasında, DisallowUnknownFields ile bir Decoder kullanın:

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

Bilinmeyen yapı: map[string]any

Biçimi önceden bilmediğinizde map[string]any'ye ya da any'ye çözün. Eşleme sabittir:

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

Çıktıda iki tuzak görünüyor. Her sayı float64'tür, bu yüzden m["stock"].(int) başarısız olurdu. Ve 2^53'ün üzerindeki tam sayılar float64 olarak hassasiyet kaybeder: 9007199254740993 id'si ...992 olarak geri gelir. UseNumber ikisinden de kaçınır.

Yapının bir kısmını biliyorsanız o kısmı bir struct'a çözün ve geri kalanı için json.RawMessage kullanın. Bir alanın ham baytlarını tutar, böylece tipini öğrendiğinizde onu daha sonra çözebilirsiniz.

Slice'lar, map'ler, pointer'lar ve nil

nil ile boş slice arasındaki fark bir dizi bekleyen API istemcileri için önemlidir. Alanın [] olması gerektiğinde []T{} ya da make([]T, 0) ile başlatın.

Girdide "yok" ile "sıfır"ı ayırt etmeniz gerektiğinde bir pointer alan (*int, *bool) kullanın. Unmarshal'dan sonra nil bir pointer anahtarın eksik ya da null olduğu anlamına gelir; 0'a işaret eden bir pointer ise istemcinin 0 gönderdiği anlamına gelir.

Akışlar: Encoder ve Decoder

json.Marshal ve Unmarshal bütün byte slice'ları üzerinde çalışır. Bir io.Reader ya da io.Writer için (bir HTTP gövdesi, bir dosya, stdin) json.NewDecoder ve json.NewEncoder kullanın. Bir Decoder ayrıca bir JSON değerleri dizisini tek tek okuyabilir:

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 her değerden sonra bir yeni satır yazar. Varsayılan olarak hem Marshal hem Encoder, JSON'un HTML'e gömülmesi güvenli olsun diye <, > ve & karakterlerini \u003c, \u003e ve \u0026 olarak kaçışlar. SetEscapeHTML(false) bunu kapatır. HTTP handler'larında olağan çift json.NewDecoder(r.Body).Decode(&v) ve json.NewEncoder(w).Encode(v)'dir.

Özel kodlama

Bir tip json.Marshaler ve json.Unmarshaler'ı gerçekleştirerek kendi JSON'unu kontrol edebilir. Yaygın bir durum, bir sayı olarak değil bir ad olarak görünmesi gereken bir iota enum'udur:

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'un hem değerler hem de pointer'lar için çalışsın diye değer alıcısı vardır; UnmarshalJSON değeri değiştirdiği için pointer alıcıya ihtiyaç duyar. Yalnızca bir string biçimine ihtiyaç duyan tipler bunun yerine encoding.TextMarshaler'ı (MarshalText) gerçekleştirebilir; bu da onları map anahtarı olarak da kullanılabilir yapar.

Sık yapılan hatalar

• Küçük harfli alan adları. Sessizce atlanırlar.
• Unmarshal'a bir değer aktarmak. Bir pointer ister.
• Hatayı yok saymak. Hatalı biçimli JSON ve tip uyuşmazlıkları yalnızca onun üzerinden bildirilir.
• map[string]any içindeki sayıların int olduğunu varsaymak. Onlar float64'tür.
• omitempty'nin boş bir struct'ı ya da sıfır bir time.Time'ı atmasını beklemek. Go 1.24'te omitzero ya da bir pointer kullanın.
• Map'lerde alan sırasına güvenmek. Map anahtarları çıktıda sıralanır; struct alanları tanım sıralarını korur.