Jak kodować/dekodować JSON w Go?

Question

Accepted Answer

Pakiet **`encoding/json`** z biblioteki standardowej Go obsługuje serializację JSON (marshaling) i deserializację (unmarshaling), mapując między strukturami Go a JSON. **Tagi struktur** kontrolują nazewnictwo pól i stanowią fundament większości interfejsów API Go.

## Marshaling: struktura Go → JSON

```go
type User struct {
    Name    string `json:"name"`              // tag maps the field to a JSON key
    Email   string `json:"email"`
    Age     int    `json:"age,omitempty"`     // omitempty → skip if zero/empty
    private string                             // unexported → NOT serialized (lowercase)
}

u := User{Name: "Ann", Email: "ann@x.com", Age: 30}
data, err := json.Marshal(u)
fmt.Println(string(data))   // {"name":"Ann","email":"ann@x.com","age":30}
```

`json.Marshal` konwertuje strukturę na bajty JSON. **Serializowane są tylko pola eksportowane (zaczynające się z wielkiej litery)** — pola nieeksportowane są pomijane.

## Rola tagów struktur

```go
type Product struct {
    ID    int    `json:"id"`                  // → "id"
    Name  string `json:"product_name"`        // → "product_name" (rename)
    Price float64 `json:"price,omitempty"`     // omit if 0
    Notes string `json:"-"`                    // "-" → NEVER serialize this field
}
```

Bez tagów, klucze JSON domyślnie przyjmują dokładną (kapitalizowaną) nazwę pola. Tagi pozwalają kontrolować nazwę klucza JSON, pomijać puste wartości (`omitempty`) i całkowicie wykluczać pola (`-`) — niezbędne do dopasowania konwencji API (np. snake_case w JSON).

## Unmarshaling: JSON → struktura Go

```go
jsonData := []byte(`{"name":"Bob","email":"bob@x.com","age":25}`)

var user User
err := json.Unmarshal(jsonData, &user)   // pass a POINTER to populate it
if err != nil { log.Fatal(err) }
fmt.Println(user.Name)   // "Bob"
```

`json.Unmarshal` parsuje JSON do struktury — musisz przekazać **wskaźnik**, aby mógł wypełnić strukturę. Pola są dopasowywane przez tag/nazwę (bez rozróżniania wielkości liter).

## Praca z nieznanym/dynamicznym JSON

```go
// when the structure is unknown, unmarshal into a map or interface{}
var result map[string]interface{}
json.Unmarshal(data, &result)
name := result["name"].(string)        // type-assert the value (JSON numbers → float64!)
```

## Streaming z Encoder/Decoder (dla I/O)

```go
// encode directly to an io.Writer (e.g. an HTTP response) — efficient, no intermediate buffer
json.NewEncoder(w).Encode(user)

// decode directly from an io.Reader (e.g. an HTTP request body)
json.NewDecoder(r.Body).Decode(&user)
```

Dla serwerów sieciowych `Encoder`/`Decoder` pracują bezpośrednio ze strumieniami (treściami żądań/odpowiedzi) — to powszechny wzorzec w handlerach.

## Dlaczego to ważne

Kodowanie/dekodowanie JSON jest fundamentalne dla praktycznie całego tworzenia stron internetowych w Go — interfejsy API REST, mikrousługi i konfiguracje wszystkie polegają na konwersji między strukturami Go a JSON.

Pakiet `encoding/json` (biblioteka standardowa, bez zależności) jest standardowym narzędziem, a jego dobra znajomość jest niezbędna jako wiedza codziennna: jak działają marshaling/unmarshaling, krytyczna reguła, że **serializowane są tylko pola eksportowane**, i szczególnie **tagi struktur** (kontrolowanie nazw kluczy JSON za pomocą `json:"..."`, `omitempty` do pomijania pustych wartości, `-` do wykluczania) które są potrzebne do dopasowania konwencji API z realnego świata, takich jak snake_case.

Wiedzenie, aby przekazać wskaźnik do `Unmarshal`, obsługiwać dynamiczny JSON poprzez mapy/`interface{}` (z gotcham, że liczby JSON dekodują się do `float64`), i używać streaming `Encoder`/`Decoder` do treści HTTP pokrywa praktyczne potrzeby budowania interfejsów API.

To stała, praktyczna część pracy nad backendem w Go.