Как выполняется кодирование/декодирование JSON в Go?

Question

Accepted Answer

Пакет **`encoding/json`** из стандартной библиотеки Go обрабатывает сериализацию JSON (маршалинг) и десериализацию (анмаршалинг), отображая связь между структурами Go и JSON. **Struct tags** управляют именованием полей и являются основой большинства веб-API на Go.

## Маршалинг: структура 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` преобразует структуру в байты JSON. **Сериализуются только экспортированные (с заглавной буквы) поля** — неэкспортированные поля пропускаются.

## Роль struct tags

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

Без тегов ключи JSON по умолчанию соответствуют точному имени поля (с заглавной буквы). Теги позволяют контролировать имя ключа JSON, опускать пустые значения (`omitempty`) и полностью исключать поля (`-`) — это необходимо для соответствия соглашениям API (например, snake_case в JSON).

## Анмаршалинг: JSON → структура 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` разбирает JSON в структуру — необходимо передать **указатель**, чтобы он мог заполнить структуру. Поля сопоставляются по тегу/имени (без учета регистра).

## Работа с неизвестным/динамическим 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!)
```

## Потоковая обработка с Encoder/Decoder (для ввода-вывода)

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

Для веб-серверов `Encoder`/`Decoder` работают непосредственно с потоками (телами запросов/ответов) — это типичный паттерн в обработчиках.

## Почему это важно

Кодирование/декодирование JSON является основой практически всей веб-разработки на Go — REST API, микросервисы и конфигурация полагаются на преобразование между структурами Go и JSON.

Пакет `encoding/json` (из стандартной библиотеки, без зависимостей) является стандартным инструментом, и его хорошее понимание крайне важно в повседневной работе: как работают маршалинг/анмаршалинг, критическое правило о том, что **сериализуются только экспортированные поля**, и особенно **struct tags** (управление именами ключей JSON с помощью `json:"..."`, `omitempty` для пропуска пустых значений, `-` для исключения), которые необходимы для соответствия реальным соглашениям API, таким как snake_case.

Знание того, что нужно передавать указатель в `Unmarshal`, обработка динамического JSON через maps/`interface{}` (с учётом того, что числа JSON декодируются в `float64`), и использование потокового `Encoder`/`Decoder` для тел HTTP охватывают практические потребности создания API.

Это постоянная, практическая часть работы с Go backend.