json.Unmarshal vs NewDecoder.Decode: что быстрее в Go?

Два брата-акробата: Unmarshal и Decode

Если вы пишете на Go и работаете с JSON, то рано или поздно встаёте перед выбором: использовать json.Unmarshal или json.NewDecoder.Decode? Вопрос настолько популярен, что на Stack Overflow он собрал тысячи просмотров и десятки голосов. Но ответ, который вы найдёте там, часто сводится к "зависит от задачи".

Сегодня мы не просто дадим абстрактный ответ. Мы проведём собственное расследование: разберём внутреннюю кухню обоих методов, напишем бенчмарки, покажем реальные примеры кода и выведем чёткие правила, когда что применять. Пристегнитесь — будет жарко!

Коротко о главном: что такое Unmarshal и Decode?

Оба инструмента делают одно и то же — превращают JSON в структуру Go. Но делают это по-разному.

• json.Unmarshal — принимает на вход []byte и указатель на структуру. Всё сразу: байты есть, структура готова, поехали. Работает "в лоб" — десериализует весь массив данных в памяти.
• json.NewDecoder.Decode — работает с потоком (io.Reader). Вы создаёте декодер, передаёте ему ридер (например, os.File или http.Response.Body) и вызываете Decode. Декодер читает данные порциями, не загружая всё в память сразу.

Казалось бы, разница очевидна: для больших данных — Decoder, для маленьких — Unmarshal. Но дьявол, как всегда, в деталях.

Внутренняя кухня: как они работают под капотом

json.Unmarshal — снайперский выстрел

Unmarshal — это функция, которая:

1. Принимает слайс байтов.
2. Выделяет память под результирующую структуру.
3. За один проход парсит весь JSON и заполняет структуру.

Всё просто и элегантно. Но есть нюанс: если вы передаёте в Unmarshal большой JSON (например, 100 МБ), то сначала вы должны прочитать эти 100 МБ в память. А потом Unmarshal выделит ещё память под структуру. Итог — двойное потребление RAM.

json.NewDecoder.Decode — водопроводчик

Decoder работает иначе:

1. Создаётся новый декодер, который оборачивает io.Reader.
2. Декодер читает данные буферами (по умолчанию 4 КБ).
3. По мере чтения он парсит JSON токен за токеном и заполняет структуру.

Преимущество — вы не храните весь JSON в памяти. Недостаток — чуть больше накладных расходов на управление буфером и потоковое чтение.

Эксперимент: бенчмарки не врут

Давайте проверим теорию на практике. Напишем простой бенчмарк для трёх сценариев:

• Маленький JSON (1 КБ)
• Средний JSON (100 КБ)
• Большой JSON (10 МБ)

package main

import (
    "bytes"
    "encoding/json"
    "testing"
)

type Data struct {
    ID    int    `json:"id"`
    Name  string `json:"name"`
    Items []int  `json:"items"`
}

func generateJSON(size int) []byte {
    data := Data{
        ID:    1,
        Name:  "test",
        Items: make([]int, size),
    }
    for i := 0; i < size; i++ {
        data.Items[i] = i
    }
    b, _ := json.Marshal(data)
    return b
}

func BenchmarkUnmarshal(b *testing.B) {
    jsonData := generateJSON(1000) // 1 KB
    var result Data
    for i := 0; i < b.N; i++ {
        json.Unmarshal(jsonData, &result)
    }
}

func BenchmarkDecoder(b *testing.B) {
    jsonData := generateJSON(1000) // 1 KB
    var result Data
    for i := 0; i < b.N; i++ {
        reader := bytes.NewReader(jsonData)
        json.NewDecoder(reader).Decode(&result)
    }
}

Результаты (на моём ноутбуке, Go 1.22):

Вывод: на маленьких данных Unmarshal быстрее. На больших — разница стирается, но Decoder выигрывает по памяти.

Когда что использовать: практические сценарии

Сценарий 1: API-запрос (маленький JSON)

Вы получаете JSON от стороннего API. Размер ответа — редко больше 10 КБ.

// Плохо: лишние телодвижения с Decoder
resp, _ := http.Get("https://api.example.com/user/1")
var user User
json.NewDecoder(resp.Body).Decode(&user)
resp.Body.Close()

// Хорошо: Unmarshal проще и быстрее
resp, _ := http.Get("https://api.example.com/user/1")
body, _ := io.ReadAll(resp.Body)
resp.Body.Close()
json.Unmarshal(body, &user)

Сценарий 2: Потоковые данные (большой JSON)

Вы читаете файл логов размером 500 МБ. Каждая строка — отдельный JSON-объект.

// Плохо: прочитаем всё в память (500 МБ + структура)
data, _ := os.ReadFile("logs.jsonl")
var logs []LogEntry
json.Unmarshal(data, &logs)

// Хорошо: читаем построчно через Decoder
file, _ := os.Open("logs.jsonl")
defer file.Close()
decoder := json.NewDecoder(file)
var log LogEntry
for decoder.More() {
    decoder.Decode(&log)
    // обрабатываем log
}

Сценарий 3: Множественная десериализация из одного источника

У вас есть массив JSON-объектов, и вы хотите обрабатывать их по одному.

// Unmarshal не подходит — нужно разбивать массив вручную
// Decoder справляется идеально
data := `[{"id":1},{"id":2},{"id":3}]`
decoder := json