Шесть ограничений и что каждое даёт

Stateless - что это значит на практике

Это не значит «состояния нет вообще»: данные в базе никуда не деваются. Речь про состояние сессии клиента на конкретном инстансе. Всё нужное запрос обязан нести сам: токен вместо «сервер помнит, что ты залогинен», курсор пагинации вместо «сервер помнит, где ты остановился». Взамен любой инстанс обрабатывает любой запрос, sticky session не нужен, падение узла не рвёт работу пользователя, ретрай безопасен, а автоскейл честный.

Ресурс, представление, URI

• Ресурс - сущность с идентичностью: «заказ 42». Представлением называют то, как её сериализовали сейчас: JSON, XML, CSV, PDF. Один URI отдаёт много представлений, нужное клиент выбирает через Accept.
• URI именует существительное, а не действие. /orders/42 годится, а /getOrder?id=42 уже RPC в URL-костюме.
• Коллекция и элемент: /orders и /orders/42. Множественное число никто не требует, это соглашение, но полезное.
• Вкладывай не глубже одного уровня: /orders/42/items. Дальше (/users/7/orders/42/items/3/comments) начинается ад: элемент всё равно адресуется своим id, а длинные пути ломают кэш и роутинг.

RESTful vs REST-like

RESTful соблюдает все ограничения, включая гипермедиа: уровень 3. У REST-like есть ресурсные URI, корректные методы и статус-коды, но переходы клиент знает из документации, а не из ответов: уровень 2. Индустрия живёт на уровне 2, потому что там всё окупается: кэш, идемпотентность, ретраи и понятность для прокси уже есть, а гипермедиа машинному клиенту обходится дорого.

Одна и та же задача в двух моделях

# REST: состояние ресурса
GET    /orders/42            -> 200 Order
POST   /orders               -> 201 + Location
PATCH  /orders/42            -> 200
DELETE /orders/42            -> 204

# «отменить» тоже состояние:
PATCH  /orders/42
{"status": "cancelled"}
# или ресурс-действие:
POST   /orders/42/cancellation

# RPC: список процедур
POST /OrderService/GetOrder
POST /OrderService/CreateOrder
POST /OrderService/UpdateOrder
POST /OrderService/DeleteOrder
POST /OrderService/CancelOrder
POST /OrderService/RecalculateTotals
POST /OrderService/SendReceiptEmail
# в gRPC то же самое, но с контрактом
# и бинарным телом

Посмотри на нижние строки правой колонки: RecalculateTotals и SendReceiptEmail в RPC ложатся естественно, а в REST их приходится придумывать как ресурсы. Это честная слабость REST, и, признав её, ты только выиграешь. Обратный пример: «отдай мне заказ, и пусть CDN его закэширует на 5 минут». В REST хватит одной строки заголовка, в RPC нужна отдельная инфраструктура.

Разница в том, где живёт семантика

• REST: семантика в протоколе. Посредник (прокси, CDN, WAF, балансировщик) видит GET /orders/42 и знает: это чтение, безопасно, идемпотентно, кэшируемо, можно ретраить. Ему не нужен твой контракт.
• RPC: семантика в контракте. Для посредника любой вызов выглядит как POST с непрозрачным телом. Не зная твоего .proto, он не может ни ретраить, ни кэшировать, ни маршрутизировать по смыслу.
• Отсюда и практическое правило: наружу - REST (открываемость, кэш, любой клиент), внутрь - RPC/gRPC (контракт, скорость, стриминг).

Может ли REST жить не поверх HTTP

Может: в диссертации HTTP ни разу не назван обязательным. Требуются идентификаторы ресурсов, единообразный набор операций с описанной семантикой, самоописывающиеся сообщения, statelessness, явная кэшируемость, слоистость.

• CoAP (RFC 7252) даёт самый чистый пример: GET/POST/PUT/DELETE, URI вида coap://device/sensors/temp, коды ответов «2.05 Content», «4.04 Not Found», кэширование по Max-Age, подписки через Observe. Работает поверх UDP, потому что рассчитан на устройства с батарейкой и каналом в килобиты.
• Поверх брокера (AMQP, MQTT, NATS): метод и путь кладут в свойства сообщения, а ответ шлют в reply-to. Формально похоже на REST, по сути это уже самодельный протокол.

Почему всё равно HTTP? Он уже даёт URI, глаголы с зафиксированной семантикой, коды ответов, согласование содержимого, условные запросы, диапазоны, сжатие, а главное, планетарную кэш-инфраструктуру и инструменты, которые понимают всё это без твоего участия. Вне HTTP всё это пишут руками, и обычно хуже.

Кэш: почему у REST он бесплатный

• Ключом кэша служит URI плюс заголовки из Vary. У RPC ключа нет: у всех вызовов один путь и разные тела, а тело в ключ кэша не входит.
• GET объявлен безопасным и идемпотентным, поэтому кэшировать его можно по умолчанию. POST кэшируем только в теории и практически никем.
• Условные запросы (ETag + If-None-Match → 304) дают почти бесплатную ревалидацию: 150 байт вместо мегабайта.
• Уровни кэша складываются: браузер → Service Worker → CDN → реверс-прокси → кэш приложения. Каждый снимает часть нагрузки, и ни один не знает про твой код.

В RPC/gRPC всё это делают вручную: кэш в Redis по ключу из имени метода и полей запроса, своя логика инвалидации, TTL своими руками. Исключения есть: кэшируемые методы можно объявить через google.api.http и выставить наружу как GET через grpc-gateway. Но это уже трансляция в REST, а не кэш gRPC.

Балансировка: где именно ломается

1. Клиент открывает одно TCP-соединение. L4-балансировщик выбирает бэкенд по 5-кортежу (src IP, src port, dst IP, dst port, протокол) и делает это один раз.
2. gRPC мультиплексирует в этом соединении сотни потоков. Все они, естественно, идут на выбранный бэкенд.
3. Соединение живёт часами: gRPC его не рвёт, а keepalive-пинги не дают закрыться.
4. В итоге один под получает весь трафик клиента, остальные простаивают. Отскейлились с 3 подов до 30, а нагрузка не перераспределилась: никто не переподключался.

Решения и их цена

// 1. Сервер: не давать соединениям жить вечно + защита от «пинг-флуда»
srv := grpc.NewServer(
    grpc.KeepaliveParams(keepalive.ServerParameters{
        MaxConnectionAge:      30 * time.Minute, // потом GOAWAY
        MaxConnectionAgeGrace: 5 * time.Minute,  // доиграть текущие RPC
        Time:                  2 * time.Minute,  // пинг простаивающему клиенту
        Timeout:               20 * time.Second,
    }),
    grpc.KeepaliveEnforcementPolicy(keepalive.EnforcementPolicy{
        MinTime:             1 * time.Minute,
        PermitWithoutStream: true,
    }),
)

// 2. Клиент: сам балансирует через headless service.
// dns:/// отдаёт все A-записи; перечитывает их резолвер при обрыве, а не по таймеру.
conn, err := grpc.NewClient(
    "dns:///orders.default.svc.cluster.local:9000",
    grpc.WithDefaultServiceConfig(`{"loadBalancingConfig":[{"round_robin":{}}]}`),
    grpc.WithTransportCredentials(insecure.NewCredentials()),
)

Терминология, на которой путаются

Swagger - исторический бренд: в конце 2015 года спецификацию Swagger передали в Linux Foundation, а с 2016-го она называется OpenAPI (3.0, 3.1, 3.2). Сейчас «Swagger» зовут инструменты (Swagger UI, Swagger Editor, Swagger Codegen), а формат называется OpenAPI. Главное в 3.1: он стал полностью совместим с JSON Schema 2020-12, так что одна схема годится и для валидации, и для документации.

Что реально даёт спека

• Документация без ручной работы в Swagger UI, Redoc, Scalar. Уже одно это окупает спеку.
• Кодогенерация клиентов для всех потребителей: фронтенд, мобилки, соседние команды. В Go есть oapi-codegen (умеет и сервер: типы, роутинг, валидацию под chi/echo/gin/std).
• Валидация на входе из схемы, а не из руками написанных if-ов. Меньше кода, меньше расхождений документации с поведением.
• Моки для фронтенда (Prism, WireMock): фронт пишут, не дожидаясь бэкенда.
• Контрактные тесты и diff в CI: oasdiff breaking --fail-on ERR валит пайплайн, если удалили поле или сузили enum. Так спека из документа становится инструментом.
• Импорт в шлюзы: Kong, APIM, AWS API Gateway настраиваются прямо из OpenAPI.

Contract-first против code-first

# contract-first в Go: генерируем типы + серверный интерфейс + валидацию
oapi-codegen -generate types,chi-server,spec -package api \
             -o internal/api/api.gen.go openapi.yaml

# CI проверяет обратную совместимость
oasdiff breaking origin/main:openapi.yaml openapi.yaml --fail-on ERR

Что происходит при вызове

1. Сгенерированный клиент сериализует запрос в protobuf.
2. Открывается новый поток в уже существующем HTTP/2-соединении. Летят HEADERS: :method: POST, :path: /order.v1.OrderService/GetOrder, content-type: application/grpc, te: trailers, дедлайн в grpc-timeout, метаданные пользователя.
3. DATA-фреймы несут «length-prefixed message»: 1 байт флага сжатия + 4 байта длины big-endian + сами байты сообщения. Если сообщений несколько, это и есть стриминг.
4. Ответ приходит так же, а результат вызова лежит в трейлерах после тела: grpc-status: 0, при ошибке ещё grpc-message и grpc-status-details-bin.

Откуда берётся скорость - по пунктам

Трезвая оценка: на межсервисном вызове «получить объект по id» gRPC выигрывает единицы миллисекунд, а по трафику в разы. Если ручка делает три запроса в базу на 20 мс, выигрыш утонет. Поэтому правильный ответ всегда уточняет: «быстрее в чём и при каких условиях».

Минимальный сервер и клиент в Go

// сервер
type server struct {
    orderv1.UnimplementedOrderServiceServer // обязательно: даёт forward-совместимость
    repo *Repo
}

func (s *server) GetOrder(ctx context.Context, req *orderv1.GetOrderRequest) (*orderv1.Order, error) {
    o, err := s.repo.Get(ctx, req.GetId())      // GetXxx() безопасен для nil-приёмника
    if errors.Is(err, ErrNotFound) {
        return nil, status.Errorf(codes.NotFound, "order %d not found", req.GetId())
    }
    if err != nil {
        return nil, status.Error(codes.Internal, "internal error") // без утечки деталей наружу
    }
    return toProto(o), nil
}

func main() {
    lis, _ := net.Listen("tcp", ":9000")
    s := grpc.NewServer(grpc.ChainUnaryInterceptor(logging, recovery, metrics))
    orderv1.RegisterOrderServiceServer(s, &server{repo: repo})
    reflection.Register(s) // чтобы grpcurl/Postman видели схему; в проде только внутри периметра
    _ = s.Serve(lis)
}

// клиент: NewClient не подключается сразу, соединение ленивое
conn, err := grpc.NewClient("orders:9000", grpc.WithTransportCredentials(insecure.NewCredentials()))
if err != nil { return err }
defer conn.Close()

cli := orderv1.NewOrderServiceClient(conn)

ctx, cancel := context.WithTimeout(ctx, 300*time.Millisecond)
defer cancel()

o, err := cli.GetOrder(ctx, &orderv1.GetOrderRequest{Id: 42})
if st, ok := status.FromError(err); ok && st.Code() == codes.NotFound {
    // здесь обрабатываем именно NotFound
}

Разбор конкретного сообщения

message User {
  int32  id   = 1;
  string name = 2;
}
// id = 300, name = "Go"   ->   08 AC 02 12 02 47 6F   (7 байт)

08 = 0000 1000 -> номер поля 1, wire type 0 (VARINT)
AC = 1010 1100 -> старший бит 1: читаем дальше; полезные 7 бит = 0101100
02 = 0000 0010 -> старший бит 0: конец числа;   полезные 7 бит = 0000010
     значение = (0000010 << 7) | 0101100 = 256 + 44 = 300
12 = 0001 0010 -> номер поля 2, wire type 2 (LEN)
02 -> длина 2
47 6F -> "Go"

// то же в JSON: {"id":300,"name":"Go"} = 22 байта, и это без пробелов

Из разбора видно: младшая группа varint идёт первой (little-endian по 7-битным группам), а числа 0–127 занимают ровно один байт. Ключ тоже varint: пока номер поля не больше 15, ключ влезает в один байт (15<<3|7 = 127), а с номера 16 занимает два. Поэтому в проектных гайдлайнах номера 1–15 берегут для полей, которые есть в каждом сообщении, а редкие поля нумеруют от 16.

Wire types и типы данных

Эволюция схемы

message Order {
  int64  id       = 1;
  string customer = 2;
  int64  amount   = 3;

  reserved 4, 7 to 9;          // номера, которые больше нельзя занимать
  reserved "discount", "promo"; // и имена, чтобы не сломать JSON-представление

  optional string coupon = 10;  // explicit presence: отличаем "" от «не задано»
}

Ещё две тонкости proto3, которые любят спрашивать. Первая: нет различия «ноль» и «не задано» у скаляров, нулевые значения на провод вообще не пишутся. Отсюда проблема с частичным обновлением («сбросить скидку в 0» неотличимо от «не трогать»), её решают через optional, обёртки (google.protobuf.Int32Value) или FieldMask. Вторая: protobuf не детерминирован. Порядок полей и кодирование map не гарантированы между реализациями и версиями, поэтому байты protobuf не годятся ни в ключ кэша, ни во вход хэша, ни в основу цифровой подписи.

Где применяется, кроме gRPC

• События в Kafka/Pulsar вместе со Schema Registry: компактно и с контролем совместимости схем (как альтернативу берут Avro, у которого схема эволюционирует по именам, а не по номерам).
• В Prometheus remote write метрики едут в protobuf поверх HTTP, сжатые snappy.
• Envoy xDS - вся динамическая конфигурация service mesh описана в protobuf.
• Кэши и хранилища, где важен размер значения; в Redis это заметно на десятках миллионов ключей.
• Мобильные и IoT-протоколы, где трафик стоит денег и батарейки.
• Форматы файлов: например, OSM PBF для карт, tfrecord-подобные форматы в ML.

Как объявляются и когда какой

Server streaming в Go

// сервер: шлём заказы потоком, пока клиент не отменил
func (s *server) ListOrders(req *orderv1.ListOrdersRequest, stream orderv1.OrderService_ListOrdersServer) error {
    rows, err := s.repo.Cursor(stream.Context(), req.GetFilter())
    if err != nil { return status.Error(codes.Internal, "query failed") }
    defer rows.Close()

    for rows.Next() {
        select {
        case <-stream.Context().Done(): // клиент ушёл или сработал дедлайн
            return status.FromContextError(stream.Context().Err()).Err()
        default:
        }
        if err := stream.Send(toProto(rows.Order())); err != nil {
            return err // соединение оборвалось, отдаём наверх без обёртки
        }
    }
    return rows.Err()
}

// клиент: поток заканчивается io.EOF, и это не ошибка
st, err := cli.ListOrders(ctx, &orderv1.ListOrdersRequest{})
if err != nil { return err }
for {
    o, err := st.Recv()
    if errors.Is(err, io.EOF) { break }   // нормальное завершение
    if err != nil { return err }          // всё остальное - ошибка
    handle(o)
}

Client streaming и bidirectional

// client streaming: клиент шлёт N, получает 1 итог
up, _ := cli.ImportOrders(ctx)
for _, o := range batch {
    if err := up.Send(o); err != nil { break } // при ошибке Send настоящую причину даст CloseAndRecv
}
summary, err := up.CloseAndRecv()

// bidirectional: запись и чтение в разных горутинах, не вперемешку
stream, _ := cli.Watch(ctx)
go func() {
    for ev := range outbox {
        if err := stream.Send(ev); err != nil { return }
    }
    _ = stream.CloseSend() // «я больше не пишу», но продолжаю читать
}()
for {
    ev, err := stream.Recv()
    if errors.Is(err, io.EOF) { break }
    if err != nil { return err }
    apply(ev)
}

Дедлайн, а не таймаут - и почему это важно

Клиент передаёт не «дай мне 300 мс», а «истекает через 300 мс от сейчас». Сервер получает grpc-timeout: 300m, кладёт дедлайн в ctx, а вызывая следующий сервис, передаёт тот же ctx, то есть оставшееся время. Если A дал 300 мс, B потратил 250 на базу, то C получит 50 мс и, скорее всего, сразу вернёт DeadlineExceeded, не тратя ресурсы впустую. Так цепочка обрывается вся разом, а не каскадом наложенных друг на друга таймаутов.

// дедлайн задаёт вызывающий, а не сервер
ctx, cancel := context.WithTimeout(ctx, 300*time.Millisecond)
defer cancel()
resp, err := cli.GetOrder(ctx, req)
if status.Code(err) == codes.DeadlineExceeded { /* сюда попадём ровно через 300 мс */ }

// сервер проверяет остаток и передаёт контекст дальше
func (s *server) GetOrder(ctx context.Context, req *orderv1.GetOrderRequest) (*orderv1.Order, error) {
    if dl, ok := ctx.Deadline(); ok && time.Until(dl) < 20*time.Millisecond {
        return nil, status.Error(codes.DeadlineExceeded, "not enough time left") // fail fast
    }
    o, err := s.repo.Get(ctx, req.GetId()) // ctx уходит в database/sql, запрос отменится сам
    ...
}

Отмена работает симметрично: если клиент вызвал cancel() или ушёл, gRPC шлёт RST_STREAM, а сервер видит ctx.Done() и context.Canceled. Отсюда разница в кодах: Canceled - отменил клиент, DeadlineExceeded - вышло время. Первое обычно не считают ошибкой сервиса и не алертят по нему, а второе считают.

Метаданные

// клиент кладёт метаданные в исходящий контекст
ctx = metadata.AppendToOutgoingContext(ctx,
    "authorization", "Bearer "+token,
    "x-request-id", reqID,
    "x-trace-bin", string(traceBytes)) // суффикс -bin => значение бинарное, поедет в base64

// сервер читает входящие
md, ok := metadata.FromIncomingContext(ctx)
vals := md.Get("x-request-id")

// заголовки (до тела) и трейлеры (после тела)
var header, trailer metadata.MD
resp, err := cli.GetOrder(ctx, req, grpc.Header(&header), grpc.Trailer(&trailer))

Имена ключей приводятся к нижнему регистру, ключи с суффиксом -bin несут бинарь и кодируются base64, а префикс grpc- зарезервирован. Через метаданные передают аутентификацию, трассировку, идемпотентность, версию клиента и локаль, то есть всё сквозное, чему не место в теле сообщения.

Коды ошибок и их маппинг на HTTP

Интерцепторы

Это middleware gRPC, и их два независимых семейства: unary и stream. Одну и ту же функцию на оба не навесишь. Об этом регулярно забывают, и стриминговые методы остаются без логов, метрик и recovery.

// unary-интерцептор: логи + метрики + recovery
func unaryObs(l *slog.Logger) grpc.UnaryServerInterceptor {
    return func(ctx context.Context, req any, info *grpc.UnaryServerInfo,
                handler grpc.UnaryHandler) (resp any, err error) {
        start := time.Now()
        defer func() {
            if r := recover(); r != nil {          // паника не должна ронять весь сервер
                l.Error("panic", "method", info.FullMethod, "panic", r)
                err = status.Error(codes.Internal, "internal error")
            }
            code := status.Code(err)
            rpcDuration.WithLabelValues(info.FullMethod, code.String()).Observe(time.Since(start).Seconds())
            l.Info("rpc", "method", info.FullMethod, "code", code, "dur", time.Since(start))
        }()
        return handler(ctx, req)
    }
}

// stream-интерцептор: чтобы подменить ctx, оборачивают ServerStream
type wrappedStream struct {
    grpc.ServerStream
    ctx context.Context
}
func (w *wrappedStream) Context() context.Context { return w.ctx }

func streamAuth(srv any, ss grpc.ServerStream, info *grpc.StreamServerInfo, h grpc.StreamHandler) error {
    ctx, err := authorize(ss.Context())
    if err != nil { return err }
    return h(srv, &wrappedStream{ServerStream: ss, ctx: ctx})
}

s := grpc.NewServer(
    grpc.ChainUnaryInterceptor(unaryObs(log), auth, validate, ratelimit),  // порядок = порядок выполнения
    grpc.ChainStreamInterceptor(streamObs(log), streamAuth),
)

Типовой набор в проде: recovery (самый внешний), логирование и трассировка, метрики, аутентификация и авторизация, валидация запроса (protoc-gen-validate), rate limiting, проброс request-id. На клиенте интерцепторами вешают дефолтный дедлайн, ретраи, circuit breaker и подстановку токена. ChainUnaryInterceptor вызывает их по порядку, снаружи внутрь, поэтому recovery и логирование идут первыми, а бизнес-валидация последней.

Гибрид, который встречается чаще всего

Внутри ходит gRPC, а на границе стоит шлюз, который выставляет наружу REST/JSON: grpc-gateway генерирует обратный прокси прямо из .proto с аннотациями google.api.http, так что и REST-контракт, и OpenAPI-спека берутся из того же источника истины. Браузеру отдают gRPC-Web через Envoy. Схема одна, интерфейсов два, и руками их синхронизировать не надо.

service OrderService {
  rpc GetOrder(GetOrderRequest) returns (Order) {
    option (google.api.http) = { get: "/v1/orders/{id}" };   // и REST, и gRPC из одного описания
  }
  rpc CreateOrder(CreateOrderRequest) returns (Order) {
    option (google.api.http) = { post: "/v1/orders", body: "*" };
  }
}

Рукопожатие

GET /ws HTTP/1.1
Host: api.example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==     <- случайные 16 байт в base64
Sec-WebSocket-Version: 13
Sec-WebSocket-Protocol: chat.v1                 <- согласование субпротокола
Origin: https://app.example.com                 <- проверять обязательно!

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
Sec-WebSocket-Protocol: chat.v1

Sec-WebSocket-Accept вычисляется как base64(SHA1(key + "258EAFA5-E914-47DA-95CA-C5AB0DC85B11")). Это не безопасность, а защита от дурака: так клиент проверяет, что на том конце WebSocket-сервер, а не кэширующий прокси, который решил, что понял запрос.

Кадры

• Заголовок кадра: FIN-бит (последний фрагмент), 4 бита opcode (0x1 текст, 0x2 бинарь, 0x8 close, 0x9 ping, 0xA pong), MASK-бит, длина (7, 7+16 или 7+64 бита). Итого 2–14 байт вместо сотен байт HTTP-заголовков.
• Клиент обязан маскировать данные 4-байтовым ключом (сервер - нет). Это тоже не про шифрование: маскирование ломает атаки на промежуточные прокси, которые могли бы принять содержимое кадра за начало нового HTTP-запроса (cache poisoning).
• Ping/pong - служебные кадры для keepalive, и они обязательны: без трафика NAT и балансировщики рвут «мёртвые» соединения через 30–120 секунд, а клиент узнаёт об этом только при попытке записи. Пингуют обычно раз в 20–30 секунд.
• Сообщение можно фрагментировать на несколько кадров: так стримят большие полезные нагрузки.

Чем отличается от HTTP

Когда что брать

• WebSocket нужен для обмена в обе стороны с низкой задержкой: чат, совместное редактирование, игры, торговый терминал, интерактивные дашборды с командами.
• Для потока только вниз хватает SSE: лента событий, уведомления, прогресс длинной задачи, потоковая выдача текста LLM, живые метрики. Он дешевле, работает через любой прокси, а переподключение и Last-Event-ID встроены в браузерный EventSource. Историческое ограничение в 6 соединений на домен в HTTP/1.1 снимает мультиплексирование HTTP/2.
• Long polling остался ради совместимости с древними клиентами и сетями, где ничего другого не проходит.
• gRPC-стриминг - то же самое между сервисами, но с контрактом, дедлайнами, кодами ошибок и flow control.
• Обычный polling раз в 5–30 секунд подойдёт, если событий мало и задержка терпима. Дешевле в эксплуатации ничего нет, и вспомнить о нём - признак опыта.

// SSE в Go делается обычным долгим обработчиком, без библиотек
func stream(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "text/event-stream")
    w.Header().Set("Cache-Control", "no-cache")
    w.Header().Set("Connection", "keep-alive")
    w.Header().Set("X-Accel-Buffering", "no") // иначе nginx буферизует и «реалтайма» не будет

    rc := http.NewResponseController(w) // Go 1.20+: доступ к Flush и дедлайнам записи
    events := subscribe(r.Context(), r.Header.Get("Last-Event-ID"))
    heartbeat := time.NewTicker(20 * time.Second)
    defer heartbeat.Stop()

    for {
        select {
        case <-r.Context().Done(): // клиент отвалился
            return
        case <-heartbeat.C:
            fmt.Fprint(w, ": ping\n\n") // комментарий-пульс, чтобы прокси не закрыл соединение
            _ = rc.Flush()
        case ev := <-events:
            fmt.Fprintf(w, "id: %s\nevent: %s\ndata: %s\n\n", ev.ID, ev.Type, ev.JSON)
            _ = rc.Flush() // без Flush данные осядут в буфере и никуда не поедут
        }
    }
}

Сравнение по осям

Голосом стоит добавить, что у XML есть то, чего нет у JSON: атрибуты, пространства имён, XSD-валидация, XSLT и, главное, XML Signature, подпись части документа. Поэтому он и жив в банках и госсистемах, а вовсе не «потому что не переписали». У YAML же есть «норвежская проблема» (country: NO → false в YAML 1.1) и якоря, из которых собирают YAML-бомбу. Это ещё один довод не брать его форматом обмена.

encoding/json: теги и правила

type Order struct {
    ID        int64      `json:"id"`
    Customer  string     `json:"customer,omitempty"`
    Amount    int64      `json:"amount"`                 // копейки: float для денег не годится
    Note      *string    `json:"note,omitempty"`         // указатель: отличаем "" от отсутствия
    CreatedAt time.Time  `json:"created_at"`
    DeletedAt *time.Time `json:"deleted_at,omitempty"`   // только указатель даёт настоящий omitempty
    Internal  string     `json:"-"`                      // никогда не сериализуется
    Weird     string     `json:"-,"`                     // а это поле с именем "-"
    BigID     int64      `json:"big_id,string"`          // число как строка: спасает JS от потери точности
    Tags      []string   `json:"tags,omitempty"`         // nil и пустой срез оба исчезнут
    Meta      map[string]any `json:"meta,omitempty"`
}

• Сериализуются только экспортируемые поля. Поле с маленькой буквы молча исчезнет, отсюда классическое «почему у меня в JSON пусто».
• При разборе имена сопоставляются без учёта регистра, если точного совпадения нет: {"ID":1} попадёт в поле с тегом json:"id".
• Встроенная (embedded) структура «разворачивается» в родителя, если у неё нет своего имени в теге.
• []byte кодируется в base64. time.Time - в RFC 3339. Ключи map сортируются, поэтому вывод детерминирован (в отличие от protobuf).
• json.Marshal экранирует <, >, & в \u003c, \u003e, \u0026. Отключается только через Encoder.SetEscapeHTML(false).

// Go 1.24: omitzero, каким omitempty должен был быть с самого начала
type Event struct {
    At      time.Time `json:"at,omitzero"`     // нулевое время исчезнет, этого ждали годами
    Retries int       `json:"retries,omitzero"`// а вот значимый 0 придётся оставить без тега
    Addr    Address   `json:"addr,omitzero"`   // пустая структура тоже исчезнет
}
// omitzero проверяет «нулевое значение типа» (и уважает метод IsZero() bool),
// omitempty проверяет «пустое» по своему списку. Их можно комбинировать в одном теге.

json.RawMessage и отложенный разбор

// когда часть документа надо разобрать позже или пробросить как есть
type Envelope struct {
    Type    string          `json:"type"`
    Payload json.RawMessage `json:"payload"` // не разбираем, пока не знаем тип
}

var e Envelope
if err := json.Unmarshal(data, &e); err != nil { return err }
switch e.Type {
case "order.created":
    var o OrderCreated
    if err := json.Unmarshal(e.Payload, &o); err != nil { return err }
    handle(o)
}

Тот же приём используют, чтобы не потерять неизвестные поля при проксировании: разобрал что нужно, остальное протащил байтами. json.RawMessage всего лишь []byte с методами MarshalJSON/UnmarshalJSON. При разборе байты копируются как есть, а при Marshal содержимое уплотняется и экранируется (< станет \u003c), так что байт в байт он данные не протащит.

Кастомные MarshalJSON и UnmarshalJSON

// Задача: наружу отдавать длительность как "1500ms", а не как 1500000000 наносекунд
type Duration struct {
    time.Duration
}

func (d Duration) MarshalJSON() ([]byte, error) {          // приёмник-значение
    return json.Marshal(d.String())
}

func (d *Duration) UnmarshalJSON(b []byte) error {          // обязательно указатель
    var s string
    if err := json.Unmarshal(b, &s); err != nil { return err }
    v, err := time.ParseDuration(s)
    if err != nil { return fmt.Errorf("duration %q: %w", s, err) }
    d.Duration = v
    return nil
}

// Приём «alias»: добавить поле без бесконечной рекурсии
type Order struct {
    ID     int64     `json:"id"`
    Status Status    `json:"status"`
}

func (o Order) MarshalJSON() ([]byte, error) {
    type alias Order          // новый тип без методов: рекурсии не будет
    return json.Marshal(struct {
        alias
        StatusText string `json:"status_text"`
    }{alias(o), o.Status.String()})
}

Decoder против Unmarshal и неизвестные поля

// Unmarshal: весь документ уже в памяти
var o Order
err := json.Unmarshal(body, &o)

// Decoder читает из io.Reader: тело целиком не держим, умеем поток
dec := json.NewDecoder(io.LimitReader(r.Body, 1<<20)) // лимит от «бомбы» на 2 ГБ
dec.DisallowUnknownFields()                            // строгий разбор: лишнее поле = ошибка
dec.UseNumber()                                        // числа как json.Number, а не float64

if err := dec.Decode(&o); err != nil {
    var syn *json.SyntaxError
    var typ *json.UnmarshalTypeError
    switch {
    case errors.As(err, &syn):  // битый JSON
    case errors.As(err, &typ):  // "amount": "abc" при int64 - можно назвать поле в ответе
    }
    return err
}
// поток JSON-объектов подряд (ndjson): Decode в цикле до io.EOF
for dec.More() { ... }

encoding/json/v2 - с Go 1.27 это уже не эксперимент

В Go 1.25 encoding/json/v2 был экспериментом и включался переменной окружения GOEXPERIMENT=jsonv2. В Go 1.27 он включён по умолчанию безо всяких настроек, а выключает его обратная переменная GOEXPERIMENT=nojsonv2. Пакетов теперь два, и граница между ними чёткая:

• encoding/json/v2 отвечает за семантику: как Go-значение соответствует JSON. Теги, omitzero, кастомные маршалеры, опции разбора.
• encoding/json/jsontext - синтаксис: как JSON выглядит текстом. Токены (Token), «сырое» значение (Value), потоковые Encoder/Decoder, отступы. Раньше всё это было слеплено в одном пакете, и половину настроек нельзя было выразить.

Паниковать не надо: старый encoding/json никуда не делся и поведения не поменял. Его переписали поверх v2, но наблюдаемую семантику намеренно сохранили, иначе сломался бы весь существующий код в мире. Строгость v2 приезжает ровно тогда, когда ты сам меняешь импорт. Зато Unmarshal стал заметно быстрее, а API - по-настоящему потоковым: MarshalWrite/UnmarshalRead работают с io.Writer/io.Reader, MarshalEncode/UnmarshalDecode - с jsontext.Encoder/Decoder.

import (
    "encoding/json/v2"        // пакет называется json, импортируется без переименования
    "encoding/json/jsontext"
)

// синтаксическую опцию (отступ) и семантическую передают одинаково, списком Options
b, err := json.Marshal(v, jsontext.WithIndent("  "))

// строгий разбор конфига: неизвестное поле = ошибка (замена DisallowUnknownFields)
err = json.Unmarshal(data, &cfg, json.RejectUnknownMembers(true))

// поток без промежуточного буфера
err = json.MarshalWrite(w, v)
err = json.UnmarshalRead(io.LimitReader(r.Body, 1<<20), &req)

// 1. Дублирующиеся ключи объекта
json.Unmarshal([]byte(`{"a":1,"a":2}`), &v)
// v2 -> ошибка: jsontext: duplicate object member name "a"
// v1 -> nil, молча побеждало последнее значение

// 2. Невалидный UTF-8 (и на чтении, и на записи)
json.Unmarshal([]byte("{\"b\":\"\xff\xfe\"}"), &v)
// v2 -> ошибка: jsontext: invalid UTF-8 within "/b" after offset 6
// v1 -> nil, битые байты тихо заменялись на U+FFFD

// 3. Регистр имён: v2 по умолчанию строгий
json.Unmarshal([]byte(`{"ID":7}`), &v)   // при теге `json:"id"`
// v2 -> поле осталось нулевым, ошибки нет
// v1 -> поле заполнено: при промахе он пробовал сопоставить без учёта регистра