Веб-сервисы на Go

10.1Дизайн API

Что такое REST, здесь не спрашивают. Просят спроектировать API вслух: назвать ручки, коды, формат ошибки, пагинацию. Смотрят, есть ли у тебя в голове система или ты придумываешь на ходу.

Базовое правило: ресурс — существительное, действие — метод

URL именует ресурс (сущность или коллекцию), а действие над ним задаёт HTTP-метод. Стоит в пути появиться глаголу (/getPost, /createPost, /updatePostById), и получается RPC поверх HTTP: все механизмы протокола (кэширование, идемпотентные ретраи прокси, понятные коды) перестают работать.

# так делать не надо
POST /api/getPosts
POST /api/createPost
POST /api/deletePostById?id=7
GET  /api/posts/get_by_author_and_tag

# ресурсно
GET    /v1/posts
POST   /v1/posts
DELETE /v1/posts/7
GET    /v1/posts?author=3&tag=go

Коллекции пишут во множественном числе и в нижнем регистре (/posts, а не /Post). Вкладывают не глубже одного уровня: /posts/{id}/comments читается нормально, /authors/{a}/posts/{p}/comments/{c}/likes уже нет. Вложенный ресурс со своим идентификатором выносят на верхний уровень (/comments/{c}/likes). Слова в сегменте пути разделяют дефисом (/blog-posts), поля JSON называют в snake_case или camelCase, но одинаково по всему API.

CRUD API блога: полная таблица ручек

Эту таблицу и просят написать на доске. Метода и пути мало: проговаривай ещё код успеха, коды ошибок и что в теле. Как раз этого кандидату обычно не хватает.

Коды ответа: минимальный набор, который надо знать наизусть

Версионирование

Версия нужна ровно тогда, когда предстоит ломающее изменение. Всё, что можно добавить совместимо, версии не требует. Способов три, и у каждого своя цена.

Пагинация, фильтрация, сортировка

У любой ручки-коллекции должны быть лимит по умолчанию и жёсткий максимум. Без них первый же клиент напишет ?limit=1000000 и уронит сервис, причём по памяти, а не по сети: миллион строк надо сначала собрать в слайс, потом сериализовать.

const (
    defaultLimit = 20
    maxLimit     = 100
)

func parseLimit(q url.Values) (int, error) {
    raw := q.Get("limit")
    if raw == "" {
        return defaultLimit, nil
    }
    n, err := strconv.Atoi(raw)
    if err != nil || n < 1 {
        return 0, fmt.Errorf("limit: ожидается целое >= 1")
    }
    if n > maxLimit {
        n = maxLimit // молча зажимаем вместо 400, клиенту так удобнее
    }
    return n, nil
}

# фильтры и сортировка в плоских query-параметрах
GET /v1/posts?status=published&author_id=3&tag=go&created_after=2026-01-01
GET /v1/posts?sort=-created_at,title&limit=20&cursor=eyJ0IjoiMjAyNi0wOC0wMSIsImlkIjo0Mn0

# ответ с курсором
{
  "items": [ ... 20 постов ... ],
  "next_cursor": "eyJ0IjoiMjAyNi0wNy0zMSIsImlkIjozMX0",
  "has_more": true
}

Ссылку на следующую страницу почти всегда собирают из URL текущего запроса: скопировать всё, что прислал клиент, и заменить один параметр. И тут же ловят классическую ошибку: поле r.URL объявлено как указатель, а url.Values как map. Присвоишь такую переменную другой, и копия будет смотреть на те же данные, поэтому «поправил копию» на деле значит «поправил запрос, который сейчас обрабатывают остальные слои». Раньше глубокую копию писали руками, поле за полем, а в Go 1.27 появились готовые URL.Clone() и Values.Clone().

// Go 1.27
func nextPageURL(r *http.Request, cursor string) string {
    u := r.URL.Clone()          // глубокая копия: оригинальный r.URL не трогаем
    q := u.Query()              // Query() и так парсит заново, копия не нужна
    q.Set("cursor", cursor)
    u.RawQuery = q.Encode()
    return u.String()
}

// Values.Clone() нужен, когда параметры лежат в поле или в общей переменной
var base = url.Values{"status": {"published"}, "limit": {"20"}}

page := base.Clone()            // без Clone() строка ниже испортила бы сам base
page.Set("cursor", cursor)

Сортировку задают одним параметром sort со списком полей, минус означает DESC (?sort=-created_at,title). По безопасности правило жёсткое: имя поля никогда не подставляется в SQL напрямую, только через белый список. Иначе получишь SQL-инъекцию в ORDER BY, а плейсхолдеры туда не подставить.

var sortable = map[string]string{
    "created_at": "p.created_at",
    "title":      "p.title",
    "likes":      "p.likes_count",
}

func orderBy(sort string) (string, error) {
    if sort == "" {
        return "p.created_at DESC, p.id DESC", nil // всегда добиваем уникальным полем
    }
    var parts []string
    for _, f := range strings.Split(sort, ",") {
        dir := "ASC"
        if strings.HasPrefix(f, "-") {
            dir, f = "DESC", f[1:]
        }
        col, ok := sortable[f] // ORDER BY защищает только белый список
        if !ok {
            return "", fmt.Errorf("sort: неизвестное поле %q", f)
        }
        parts = append(parts, col+" "+dir)
    }
    return strings.Join(parts, ", ") + ", p.id DESC", nil
}

Идемпотентность и Idempotency-Key

Идемпотентная операция при повторе даёт тот же результат, что и при однократном вызове. Речь об эффекте на сервере, тело ответа тут ни при чём: у DELETE второй вызов может вернуть 404 вместо 204, и метод всё равно идемпотентен, потому что состояние системы не изменилось.

Клиент не может отличить «запрос не дошёл» от «дошёл, но ответ потерялся». Платёж мог пройти и при таймауте на стороне клиента, и при разрыве TCP, и при перезапуске пода. Ретрай без защиты спишет деньги второй раз. Поэтому клиент генерирует уникальный ключ (UUIDv4) на бизнес-операцию, а не на HTTP-запрос, и посылает его в заголовке Idempotency-Key. Сервер хранит ключ вместе с ответом.

CREATE TABLE idempotency_keys (
    key           text        NOT NULL,
    user_id       bigint      NOT NULL,
    endpoint      text        NOT NULL,
    request_hash  bytea       NOT NULL,   -- sha256 от тела: защита от «тот же ключ, другой запрос»
    state         text        NOT NULL,   -- in_progress | done
    status_code   int,
    response_body jsonb,
    created_at    timestamptz NOT NULL DEFAULT now(),
    expires_at    timestamptz NOT NULL,   -- TTL 24 часа, чистим фоновым джобом
    PRIMARY KEY (user_id, key)            -- ключ уникален в пределах клиента
);
CREATE INDEX ON idempotency_keys (expires_at);

func (h *Handler) CreatePayment(w http.ResponseWriter, r *http.Request) {
    key := r.Header.Get("Idempotency-Key")
    if key == "" {
        writeProblem(w, http.StatusBadRequest, "missing-idempotency-key",
            "Заголовок Idempotency-Key обязателен для этой операции")
        return
    }
    body, err := io.ReadAll(http.MaxBytesReader(w, r.Body, 1<<20))
    if err != nil { // MaxBytesReader сам 413 не пишет
        writeProblem(w, http.StatusRequestEntityTooLarge, "body-too-large", "Тело больше 1 МБ")
        return
    }
    sum := sha256.Sum256(body)

    // 1. Пытаемся занять ключ. Уникальный индекс делает это атомарным.
    rec, fresh, err := h.keys.Acquire(r.Context(), key, userID(r), r.URL.Path, sum[:])
    switch {
    case err != nil:
        writeProblem(w, 500, "internal", "")
        return
    case !fresh && !bytes.Equal(rec.RequestHash, sum[:]):
        // ключ тот же, а тело другое: клиент ошибся, это не ретрай
        writeProblem(w, http.StatusUnprocessableEntity, "idempotency-key-reuse",
            "Idempotency-Key уже использован с другим телом запроса")
        return
    case !fresh && rec.State == "done":
        // честный ретрай: отдаём сохранённый ответ, ничего не выполняя
        w.Header().Set("Idempotent-Replay", "true")
        w.WriteHeader(rec.StatusCode)
        w.Write(rec.ResponseBody)
        return
    case !fresh: // state == in_progress: параллельный дубль
        w.Header().Set("Retry-After", "1")
        writeProblem(w, http.StatusConflict, "request-in-progress",
            "Запрос с этим ключом ещё выполняется")
        return
    }

    // 2. Ключ наш, выполняем операцию.
    resp, code, err := h.charge(r.Context(), body)
    if err != nil {
        h.keys.Release(r.Context(), key) // освобождаем, чтобы ретрай мог попробовать снова
        writeProblem(w, 502, "psp-unavailable", "")
        return
    }

    // 3. Сохраняем ответ до отправки клиенту.
    _ = h.keys.Complete(r.Context(), key, code, resp)
    w.WriteHeader(code)
    w.Write(resp)
}

Единый формат ошибок: RFC 7807

RFC 7807 (обновлён как RFC 9457) описывает media type application/problem+json, то есть стандартное тело ошибки. В ядре пять полей: type (URI класса проблемы), title (человекочитаемое короткое название, стабильное для типа), status (дублирует HTTP-код), detail (подробности этого случая), instance (URI конкретного вхождения). Свои поля добавлять можно, стандарт это разрешает.

// HTTP/1.1 422 Unprocessable Content
// Content-Type: application/problem+json
{
  "type":     "https://api.blog.ru/errors/validation-failed",
  "title":    "Validation failed",
  "status":   422,
  "detail":   "Поле title обязательно и не длиннее 200 символов",
  "instance": "/v1/posts",
  "trace_id": "01J8Z9K2R3Q4",
  "errors": [
    {"field": "title", "code": "required"},
    {"field": "tags",  "code": "too_many", "max": 10}
  ]
}

// Так нельзя: утечка внутренностей
func handle(w http.ResponseWriter, r *http.Request) {
    if err := svc.Do(r.Context()); err != nil {
        http.Error(w, err.Error(), 500)
        // pq: duplicate key value violates
        // unique constraint "users_email_key"
        // ...в ответе клиенту
    }
}

// Так надо: наружу код, внутрь детали
func handle(w http.ResponseWriter, r *http.Request) {
    if err := svc.Do(r.Context()); err != nil {
        tid := middleware.TraceID(r.Context())
        slog.ErrorContext(r.Context(), "create user",
            "err", err, "trace_id", tid)
        writeProblem(w, 500, "internal",
            "Внутренняя ошибка", tid)
    }
}

Обратная совместимость: что ломает клиентов

GET    /v1/posts                    200                 список + пагинация
POST   /v1/posts                    201 + Location      создать
GET    /v1/posts/{id}               200 / 404 / 304     получить
PUT    /v1/posts/{id}               200 / 404 / 409     заменить целиком
PATCH  /v1/posts/{id}               200 / 404 / 422     частично изменить
DELETE /v1/posts/{id}               204 / 404           удалить
POST   /v1/posts/{id}/publish       200 / 409           смена состояния
GET    /v1/posts/{id}/comments      200 / 404           комментарии поста
POST   /v1/posts/{id}/comments      201 + Location      добавить комментарий
DELETE /v1/comments/{id}            204 / 403 / 404     удалить комментарий
PUT    /v1/posts/{id}/likes/me      204                 лайк (идемпотентно)
DELETE /v1/posts/{id}/likes/me      204                 снять лайк

GET /v1/posts/42

Accept: application/vnd.blog.v2+json
X-API-Version: 2
Stripe-Version: 2024-06-20

GET /posts?version=2&tag=go

type Cursor struct {
    CreatedAt time.Time `json:"t"`
    ID        int64     `json:"i"`
}

func encodeCursor(c Cursor) string {
    b, _ := json.Marshal(c)
    return base64.RawURLEncoding.EncodeToString(b)
}

// составной ключ сравниваем именно кортежем, чтобы работал индекс:
// WHERE (created_at, id) < ($1, $2) ORDER BY created_at DESC, id DESC LIMIT $3

-- занимаем ключ атомарно одним запросом
INSERT INTO idempotency_keys (key, user_id, endpoint, request_hash, state, expires_at)
VALUES ($1, $2, $3, $4, 'in_progress', now() + interval '24 hours')
ON CONFLICT (user_id, key) DO NOTHING
RETURNING key;
-- пусто в ответе => ключ уже занят, читаем существующую строку и смотрим state

type Problem struct {
    Type     string       `json:"type"`
    Title    string       `json:"title"`
    Status   int          `json:"status"`
    Detail   string       `json:"detail,omitempty"`
    Instance string       `json:"instance,omitempty"`
    TraceID  string       `json:"trace_id,omitempty"`
    Errors   []FieldError `json:"errors,omitempty"`
}

func writeProblem(w http.ResponseWriter, p Problem) {
    w.Header().Set("Content-Type", "application/problem+json; charset=utf-8")
    w.Header().Set("X-Content-Type-Options", "nosniff")
    w.WriteHeader(p.Status)
    _ = json.NewEncoder(w).Encode(p)
}

// доменные ошибки маппятся в HTTP в одном месте, а не по хендлерам
func toProblem(ctx context.Context, err error) Problem {
    tid := trace.SpanContextFromContext(ctx).TraceID().String()
    switch {
    case errors.Is(err, domain.ErrNotFound):
        return Problem{Type: "/errors/not-found", Title: "Not found", Status: 404, TraceID: tid}
    case errors.Is(err, domain.ErrConflict):
        return Problem{Type: "/errors/conflict", Title: "Conflict", Status: 409, TraceID: tid}
    case errors.As(err, new(*domain.ValidationError)):
        // ... 422 + разбивка по полям
    }
    slog.ErrorContext(ctx, "unhandled", "err", err, "trace_id", tid) // детали только в лог
    return Problem{Type: "/errors/internal", Title: "Internal error", Status: 500, TraceID: tid}
}

10.2HTTP-сервер в Go

Самая «инженерная» глава темы. Здесь спрашивают, как net/http устроен изнутри: кто создаёт горутину, какой таймаут что именно режет, почему дефолтный http.Client однажды уронит прод и как выкатиться, не оборвав запросы на полуслове.

Путь запроса: от Listener до твоего хендлера

Внутри http.ListenAndServe(addr, handler) всего три строчки: создать &http.Server{Addr: addr, Handler: handler}, открыть слушающий сокет через net.Listen("tcp", addr) и уйти в srv.Serve(l). Дальше начинается цикл, который стоит уметь рассказать пошагово.

1. l.Accept() в бесконечном цикле в горутине, вызвавшей Serve. Если Accept вернул временную ошибку (например, кончились файловые дескрипторы), сервер не падает, а спит по нарастающей (5 мс, 10, 20… до 1 с) и пробует снова.
2. На принятое соединение создаётся c := srv.newConn(rw) и сразу запускается go c.serve(connCtx). Пула воркеров нет: одна горутина на одно TCP-соединение. В HTTP/1.x не на запрос, а именно на соединение; HTTP/2 внутри соединения запускает ещё по горутине на каждый поток.
3. Внутри c.serve для HTTPS сначала идёт TLS-handshake (там же согласуется ALPN: h2 или http/1.1), потом цикл чтения запросов.
4. c.readRequest(ctx) парсит стартовую строку и заголовки в *http.Request. Тело не читается: в r.Body кладётся обёртка над буферизованным ридером соединения, и байты потекут, только когда хендлер сам вызовет Read.
5. serverHandler{srv}.ServeHTTP(w, req) при srv.Handler == nil подставляет http.DefaultServeMux. Затем роутер выбирает нужный Handler и вызывает его ServeHTTP. Это уже твой код.
6. Когда хендлер вернулся, w.finishRequest() сбрасывает буфер ответа в сокет, дочитывает и выбрасывает остаток тела запроса (иначе соединение нельзя переиспользовать) и закрывает chunked-поток.
7. Если клиент и сервер согласны на keep-alive и ошибок не было, цикл делает continue, и та же горутина ждёт следующий запрос на том же соединении. Иначе вызывается c.close(), и горутина завершается.

http.Handler и HandlerFunc: почему это одно и то же

Весь net/http стоит на интерфейсе из одного метода:

type Handler interface {
    ServeHTTP(ResponseWriter, *Request)
}

Писать структуру ради одного метода лень, а обычная функция интерфейс не реализует. Выручает адаптер на именованном функциональном типе:

type HandlerFunc func(ResponseWriter, *Request)

// метод на функциональном типе просто вызывает f
func (f HandlerFunc) ServeHTTP(w ResponseWriter, r *Request) {
    f(w, r)
}

Запись http.HandlerFunc(myFunc) ничего не вызывает и не заворачивает в структуру. Это конверсия типа: та же функция, но теперь у неё есть метод ServeHTTP, значит, она удовлетворяет Handler. Разница между mux.Handle и mux.HandleFunc ровно в этом — второй делает конверсию за тебя.

// три эквивалентные записи
mux.Handle("GET /ping", http.HandlerFunc(ping))
mux.HandleFunc("GET /ping", ping)
mux.Handle("GET /ping", pingHandler{}) // структура со своим ServeHTTP

Когда нужна структура, а не функция? Когда хендлеру нужны зависимости: репозиторий, логгер, конфиг. Подходов два, и оба в ходу:

// структура-хендлер
type PostsHandler struct {
    repo Repo
    log  *slog.Logger
}

func (h PostsHandler) ServeHTTP(
    w http.ResponseWriter, r *http.Request) {
    // h.repo, h.log доступны
}

// замыкание-конструктор (чаще)
func GetPost(repo Repo) http.HandlerFunc {
    return func(w http.ResponseWriter,
        r *http.Request) {
        // repo захвачен замыканием
    }
}
mux.Handle("GET /v1/posts/{id}", GetPost(repo))

Роутинг: ServeMux после Go 1.22 против chi/gin/echo

До Go 1.22 стандартный ServeMux умел стыдно мало: только префиксы и точные пути, никаких методов и параметров. Поэтому все тащили сторонний роутер. В Go 1.22 мукс переписали, и теперь паттерн выглядит так: [МЕТОД ][хост]/путь.

mux := http.NewServeMux()

mux.HandleFunc("GET /v1/posts",          listPosts)   // только GET (и HEAD автоматически)
mux.HandleFunc("POST /v1/posts",         createPosts)
mux.HandleFunc("GET /v1/posts/{id}",     getPost)     // сегмент-параметр
mux.HandleFunc("GET /v1/files/{path...}", serveFile)  // «остаток пути», строго последним
mux.HandleFunc("GET /v1/posts/{$}",      exactOnly)   // {$} = конец пути, без префиксного матча
mux.HandleFunc("api.example.com/", apiOnly)           // матч по хосту

func getPost(w http.ResponseWriter, r *http.Request) {
    id := r.PathValue("id")     // Go 1.22
    pattern := r.Pattern        // Go 1.23: "GET /v1/posts/{id}", годится как метка метрики
    _ = id
    _ = pattern
}

Что новый ServeMux умеет:

• Метод в паттерне; GET автоматически покрывает HEAD.
• Параметры пути {id} и хвост {rest...}, значения через r.PathValue / r.SetPathValue.
• Конфликты решаются по специфичности, а не по порядку регистрации: /v1/posts/{id} проигрывает более конкретному /v1/posts/latest. Если два паттерна пересекаются, а специфичнее ни один, мукс паникует при регистрации, а не затирает молча.
• Если путь совпал, а метод — нет, мукс отдаёт 405 с заголовком Allow. Раньше был 404, и это сбивало клиента с толку.
• {id} матчится по распаршенному сегменту: %2F внутри сегмента не «расклеит» путь, в отличие от наивных роутеров на strings.Split.

Чего не умеет и за чем всё ещё идут в chi/gin/echo:

• Группы роутов со своим набором middleware. В ServeMux middleware либо один на весь сервер, либо навешивается вручную на каждый хендлер. Можно завести отдельный mux под /admin/ плюс http.StripPrefix — работает, но громоздко.
• Ограничений на параметры ({id:[0-9]+}) нет, валидируй сам.
• Опциональные сегменты, необязательный завершающий слэш: мукс сам редиректит /x на зарегистрированный /x/ — и это бывает сюрпризом для клиентов, которые не следуют редиректам на POST. До Go 1.26 это был 301, и он был вдвойне опасен: браузер кэширует «навсегда», а на 301 POST исторически превращается в GET с потерей тела. С Go 1.26 код сменили на 307: такой ответ не кэшируется и обязан сохранять метод и тело (проверено на go1.27.0: POST /x → 307 Location: /x/). Тот же 307 теперь приходит и при чистке пути, вроде /a//b → /a/b.
• Кастомные 404/405-хендлеры, интроспекция списка роутов, генерация URL по имени роута.
• Биндинг и валидация тела, рендеринг, контекст фреймворка (*gin.Context).

Middleware: цепочка «луковицей»

Middleware — это функция func(http.Handler) http.Handler: берёт хендлер, возвращает хендлер, который что-то делает до, вызывает next.ServeHTTP и что-то делает после. Цепочка собирается вложенными вызовами, поэтому структура выходит концентрической.

type Middleware func(http.Handler) http.Handler

func Chain(mws ...Middleware) Middleware {
    return func(final http.Handler) http.Handler {
        // идём с конца, чтобы mws[0] оказался самым внешним
        for i := len(mws) - 1; i >= 0; i-- {
            final = mws[i](final)
        }
        return final
    }
}

stack := Chain(RequestID, Logging(log), Recover(log), Auth(keys), RateLimit(lim))
srv.Handler = stack(mux)
// эквивалентно: RequestID(Logging(Recover(Auth(RateLimit(mux)))))

Логирующий middleware: перехват статуса и латенси

Сложнее всего со статусом ответа. http.ResponseWriter его не отдаёт: узнать, что хендлер записал 404, можно только перехватив вызов WriteHeader. Значит, нужна обёртка со встроенным ResponseWriter.

type statusWriter struct {
    http.ResponseWriter       // встраивание: остальные методы наследуются
    status int
    bytes  int
}

func (w *statusWriter) WriteHeader(code int) {
    if w.status != 0 {
        return // защита от повторного WriteHeader (иначе superfluous WriteHeader в логах)
    }
    w.status = code
    w.ResponseWriter.WriteHeader(code)
}

func (w *statusWriter) Write(b []byte) (int, error) {
    if w.status == 0 {
        w.status = http.StatusOK // хендлер писал тело без явного WriteHeader
    }
    n, err := w.ResponseWriter.Write(b)
    w.bytes += n
    return n, err
}

// без него http.ResponseController не развернёт обёртку (Go 1.20+)
func (w *statusWriter) Unwrap() http.ResponseWriter { return w.ResponseWriter }

func Logging(log *slog.Logger) Middleware {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            start := time.Now()
            sw := &statusWriter{ResponseWriter: w}

            next.ServeHTTP(sw, r)

            if sw.status == 0 {
                sw.status = http.StatusOK // хендлер не написал вообще ничего
            }
            log.LogAttrs(r.Context(), slog.LevelInfo, "http_request",
                slog.String("method", r.Method),
                slog.String("path", r.URL.Path),
                slog.String("route", r.Pattern),          // Go 1.23: низкая кардинальность
                slog.Int("status", sw.status),
                slog.Int("bytes", sw.bytes),
                slog.Duration("latency", time.Since(start)),
                slog.String("request_id", RequestIDFrom(r.Context())),
                slog.String("ip", clientIP(r)),
            )
        })
    }
}

// вместо w.(http.Flusher) и w.(http.Hijacker):
rc := http.NewResponseController(w)
if err := rc.Flush(); err != nil { /* не поддерживается */ }
_ = rc.SetWriteDeadline(time.Now().Add(30 * time.Second)) // продлить WriteTimeout для SSE
conn, buf, err := rc.Hijack()

Recovery middleware

func Recover(log *slog.Logger) Middleware {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            sw := &statusWriter{ResponseWriter: w}
            defer func() {
                rec := recover()
                if rec == nil {
                    return
                }
                // штатный способ оборвать ответ: пробрасываем дальше, сервер его ждёт
                if rec == http.ErrAbortHandler {
                    panic(rec)
                }
                log.Error("panic in handler",
                    "err", rec,
                    "path", r.URL.Path,
                    "request_id", RequestIDFrom(r.Context()),
                    "stack", string(debug.Stack()))

                // заголовки уже ушли: 500 не написать, рвём соединение
                if sw.status != 0 {
                    panic(http.ErrAbortHandler)
                }
                w.Header().Set("Content-Type", "application/problem+json")
                w.WriteHeader(http.StatusInternalServerError)
                _, _ = io.WriteString(w,
                    `{"type":"about:blank","title":"internal error","status":500}`)
            }()
            next.ServeHTTP(sw, r)
        })
    }
}

Request ID через контекст

type ctxKey int                    // неэкспортируемый тип: чужой пакет не подменит
const requestIDKey ctxKey = iota

func RequestID(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        id := r.Header.Get("X-Request-Id")
        if id == "" || len(id) > 64 || !isSafeID(id) {
            id = uuid.New().String()  // не доверяем чужому значению вслепую
        }
        ctx := context.WithValue(r.Context(), requestIDKey, id)
        w.Header().Set("X-Request-Id", id)          // вернуть клиенту для саппорта
        next.ServeHTTP(w, r.WithContext(ctx))       // r.WithContext делает shallow copy
    })
}

func RequestIDFrom(ctx context.Context) string {
    id, _ := ctx.Value(requestIDKey).(string)       // type assertion с ok не паникует
    return id
}

import "uuid"

u := uuid.New()        // случайный, синоним uuid.NewV4()
u = uuid.NewV7()       // сортируемый по времени: первые 48 бит = миллисекунды Unix
s := u.String()        // "01a041dd-3cde-794b-a425-da2cd9f4379f"
v, err := uuid.Parse(s)
_ = uuid.MustParse(s)  // паникует вместо ошибки: только для констант в коде
_ = uuid.Nil()         // 00000000-…-000000000000
_ = uuid.Max()         // ffffffff-…-ffffffffffff

Таймауты сервера: четыре штуки плюс TimeoutHandler

Нулевые таймауты в http.Server{} означают «без ограничений». Это дефолт http.ListenAndServe, и он небезопасен: одно медленное или злонамеренное соединение может держаться вечно, занимая горутину, дескриптор и буферы. Каждый таймаут режет свою фазу.

srv := &http.Server{
    Addr:                ":8080",
    Handler:             stack(mux),
    ReadHeaderTimeout:   5 * time.Second,   // главный щит от slowloris
    ReadTimeout:         15 * time.Second,
    WriteTimeout:        20 * time.Second,  // > ReadTimeout, иначе долгое тело съест бюджет ответа
    IdleTimeout:         90 * time.Second,
    MaxHeaderBytes:      1 << 20,
    MaxHeaderValueCount: 500,               // Go 1.27: потолок числа значений; дефолт тот же 500
    ErrorLog:            slog.NewLogLogger(handler, slog.LevelError), // вместо дефолтного stderr
    BaseContext:         func(net.Listener) context.Context { return rootCtx },
}

Клиент: таймауты, транспорт и пул соединений

За http.Get(url) и http.DefaultClient стоит клиент с Timeout: 0, то есть без таймаута вообще. Если удалённый сервис принял соединение и замолчал, твоя горутина повиснет навсегда. Дальше сценарий известный: горутины копятся, каждая держит соединение и память, метрики показывают рост go_goroutines, через час — OOM. Это самый частый ответ на «падал ли у тебя прод?».

var transport = &http.Transport{
    Proxy: http.ProxyFromEnvironment,
    DialContext: (&net.Dialer{
        Timeout:   3 * time.Second,   // установка TCP-соединения
        KeepAlive: 30 * time.Second,  // TCP keepalive-пробы
    }).DialContext,
    TLSHandshakeTimeout:   3 * time.Second,
    ResponseHeaderTimeout: 5 * time.Second,  // от конца запроса до первого байта заголовков
    ExpectContinueTimeout: 1 * time.Second,
    MaxIdleConns:          256,   // всего idle-соединений в пуле
    MaxIdleConnsPerHost:   128,   // дефолт 2, почти всегда узкое место
    MaxConnsPerHost:       256,   // потолок активных, 0 = без лимита
    IdleConnTimeout:       90 * time.Second,
    ForceAttemptHTTP2:     true,
}

var client = &http.Client{
    Transport: transport,
    Timeout:   10 * time.Second, // общий потолок: dial + TLS + запрос + ответ + чтение тела
    CheckRedirect: func(r *http.Request, via []*http.Request) error {
        if len(via) >= 3 { return http.ErrUseLastResponse }
        return nil
    },
}

Пул соединений живёт в Transport, а не в Client. Отсюда правило: один Transport (и обычно один Client) на всё приложение, его создают один раз при старте. Новый http.Transport{} на каждый запрос даёт классическую утечку: у каждого свой пул (голый http.Client{} без Transport берёт общий DefaultTransport и не течёт), соединения не переиспользуются, порты уходят в TIME_WAIT, при высоком RPS кончаются эфемерные порты (cannot assign requested address).

MaxIdleConnsPerHost по умолчанию 2. Если сервис делает 500 RPS в один апстрим, то из пула переиспользуются два соединения, а остальные создаются и закрываются заново — на каждый запрос новый TCP-хендшейк и полный TLS-хендшейк. Симптом: латенси p99 выше, чем объясняет апстрим, и куча соединений в TIME_WAIT в ss -s. Лечится одной строкой.

// тело надо дочитать и закрыть, иначе соединение не вернётся в пул
resp, err := client.Do(req)
if err != nil {
    return err
}
defer func() {
    // дочитываем остаток (с лимитом, чтобы злой сервер не залил нас гигабайтом)
    _, _ = io.Copy(io.Discard, io.LimitReader(resp.Body, 64<<10))
    _ = resp.Body.Close()
}()

if resp.StatusCode != http.StatusOK {
    return fmt.Errorf("upstream: %s", resp.Status)  // тело всё равно дочитается в defer
}

// Go 1.27: сервер живёт на фейковой сети в памяти, сокета и порта нет вовсе
ts := httptest.NewTestServer(t, mux)     // t.Cleanup(ts.Close) регистрируется сам
client := ts.Client()                    // ходить надо именно этим клиентом
resp, err := client.Get(ts.URL + "/v1/orders/1")
// ts.URL == "http://example.com": имя синтетическое, DNS и порт не участвуют
// https://example.com/... тоже работает: TLS поднят на той же фейковой сети

Graceful shutdown

Задача: получив SIGTERM (его шлёт Kubernetes при выкатке), перестать принимать новые запросы, дать доработать текущим, закрыть внешние ресурсы и выйти с нулевым кодом. Успеть надо за terminationGracePeriodSeconds, иначе прилетит SIGKILL.

func main() {
    // 1. ловим сигналы: ctx закроется по SIGINT/SIGTERM
    ctx, stop := signal.NotifyContext(context.Background(),
        syscall.SIGINT, syscall.SIGTERM)
    defer stop()

    srv := &http.Server{ /* ... таймауты ... */ }

    errCh := make(chan error, 1)
    go func() {
        // ErrServerClosed: штатный возврат после Shutdown, не ошибка
        if err := srv.ListenAndServe(); err != nil &&
            !errors.Is(err, http.ErrServerClosed) {
            errCh <- err
        }
    }()

    select {
    case err := <-errCh:
        log.Error("сервер не поднялся", "err", err)
        os.Exit(1)
    case <-ctx.Done():
        // Go 1.26: NotifyContext отменяет контекст через CancelCauseFunc,
        // поэтому причина отмены прямо называет пришедший сигнал.
        //   SIGTERM -> "terminated signal received"
        //   SIGINT  -> "interrupt signal received"
        //   stop()  -> context.Canceled
        log.Info("начинаем graceful shutdown", "cause", context.Cause(ctx))
    }
    stop() // вернуть дефолтное поведение: второй Ctrl+C убьёт процесс немедленно

    // 2. readiness начинает отдавать 503, но запросы ещё принимаем
    ready.Store(false)
    time.Sleep(5 * time.Second) // дать балансировщику убрать нас из пула

    // 3. перестать принимать новые, дождаться активных
    shCtx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
    defer cancel()
    if err := srv.Shutdown(shCtx); err != nil {
        log.Error("не успели за отведённое время, рвём соединения", "err", err)
        _ = srv.Close() // жёстко
    }

    // 4. только теперь закрываем ресурсы: до этого ими пользуются хендлеры
    consumer.Stop()          // остановить читателей Kafka, закоммитить оффсеты
    _ = db.Close()           // закрыть пул соединений с БД
    _ = tracerProvider.Shutdown(context.Background()) // выплюнуть накопленные спаны
    if f, ok := log.Handler().(interface{ Flush() error }); ok {
        _ = f.Flush() // у JSONHandler и TextHandler Flush нет
    }
}

ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
<-ctx.Done()

ctx.Err()              // context.Canceled, как раньше, ничего не говорит
context.Cause(ctx)     // "terminated signal received", а вот это уже SIGTERM

errors.Is(context.Cause(ctx), context.Canceled) // true: старые проверки не ломаются

Тело запроса: Decoder против Unmarshal, лимиты, стриминг

// json.Unmarshal
b, err := io.ReadAll(r.Body)   // всё в память
if err != nil { ... }
err = json.Unmarshal(b, &in)

// + можно перечитать/залогировать сырое тело
// + понятные ошибки с позицией
// - память = размер тела
// - без MaxBytesReader это DoS

// json.Decoder
dec := json.NewDecoder(r.Body)  // стрим
dec.DisallowUnknownFields()
err := dec.Decode(&in)

// + не держит тело в памяти целиком
// + умеет поток JSON-объектов (dec.More)
// + UseNumber(), Token() для больших данных
// - сырое тело уже не залогируешь

В обычной API-ручке Decoder ставят поверх MaxBytesReader. Потоковую загрузку (NDJSON, батчи) тот же Decoder читает в цикле по dec.More(), и память не растёт с размером входа.

func createPost(w http.ResponseWriter, r *http.Request) {
    // 1. жёсткий потолок на тело; w нужен, чтобы сервер закрыл соединение корректно
    r.Body = http.MaxBytesReader(w, r.Body, 1<<20) // 1 МиБ

    // 2. на публичных API стоит проверить и Content-Type
    if ct := r.Header.Get("Content-Type"); !strings.HasPrefix(ct, "application/json") {
        writeProblem(w, http.StatusUnsupportedMediaType, "нужен application/json")
        return
    }

    dec := json.NewDecoder(r.Body)
    dec.DisallowUnknownFields() // поле с опечаткой даст 400, а не пропадёт молча

    var in createPostReq
    if err := dec.Decode(&in); err != nil {
        var maxErr *http.MaxBytesError      // Go 1.19+
        var synErr *json.SyntaxError
        var typErr *json.UnmarshalTypeError
        switch {
        case errors.As(err, &maxErr):
            writeProblem(w, http.StatusRequestEntityTooLarge, "тело больше 1 МиБ")
        case errors.As(err, &synErr):
            writeProblem(w, http.StatusBadRequest,
                fmt.Sprintf("битый JSON на позиции %d", synErr.Offset))
        case errors.As(err, &typErr):
            writeProblem(w, http.StatusBadRequest,
                fmt.Sprintf("поле %q ожидает тип %s", typErr.Field, typErr.Type))
        case errors.Is(err, io.EOF):
            writeProblem(w, http.StatusBadRequest, "пустое тело")
        default:
            writeProblem(w, http.StatusBadRequest, "не удалось разобрать тело")
        }
        return
    }

    // 3. в теле ровно один объект, иначе {"a":1}{"b":2} проедет молча
    if err := dec.Decode(&struct{}{}); !errors.Is(err, io.EOF) {
        writeProblem(w, http.StatusBadRequest, "ожидается ровно один JSON-объект")
        return
    }

    if err := in.Validate(); err != nil { /* 422 */ }
}

// Go 1.26: тип в параметре, переменная прямо в условии
if _, ok := errors.AsType[*http.MaxBytesError](err); ok {
    writeProblem(w, http.StatusRequestEntityTooLarge, "тело больше 1 МиБ")
} else if se, ok := errors.AsType[*json.SyntaxError](err); ok {
    writeProblem(w, http.StatusBadRequest, fmt.Sprintf("битый JSON на позиции %d", se.Offset))
} else if te, ok := errors.AsType[*json.UnmarshalTypeError](err); ok {
    writeProblem(w, http.StatusBadRequest, fmt.Sprintf("поле %q ожидает тип %s", te.Field, te.Type))
}

Загрузка файлов и multipart

Браузерная форма с файлом шлёт Content-Type: multipart/form-data; boundary=.... Тело состоит из частей, разделённых boundary, и у каждой свои заголовки (Content-Disposition, Content-Type). В Go его разбирают двумя способами.

// Вариант A: ParseMultipartForm — просто, для небольших файлов
func upload(w http.ResponseWriter, r *http.Request) {
    r.Body = http.MaxBytesReader(w, r.Body, 32<<20) // общий потолок 32 МиБ

    // аргумент задаёт порог памяти; остальное уйдёт во временные файлы в os.TempDir
    if err := r.ParseMultipartForm(8 << 20); err != nil {
        writeProblem(w, http.StatusBadRequest, "битая форма")
        return
    }
    defer func() { _ = r.MultipartForm.RemoveAll() }() // сервер чистит только форму исходного r, не копии

    file, hdr, err := r.FormFile("avatar")
    if err != nil { /* 400 */ }
    defer file.Close()

    // hdr.Filename и hdr.Header.Get("Content-Type") прислал клиент, им не доверяем
    name := filepath.Base(hdr.Filename)               // с Go 1.17 путь отрезан и так, это страховка
    if hdr.Size > 5<<20 { /* 413 */ }

    // определяем реальный тип по содержимому, а не по расширению
    head := make([]byte, 512)
    n, _ := io.ReadFull(file, head)
    mime := http.DetectContentType(head[:n])
    if mime != "image/jpeg" && mime != "image/png" { /* 415 */ }
    if _, err := file.Seek(0, io.SeekStart); err != nil { /* 500 */ }

    dst, err := os.CreateTemp(uploadDir, "up-*")      // имя генерируем сами
    if err != nil { /* 500 */ }
    defer dst.Close()
    if _, err := io.Copy(dst, file); err != nil { /* 500 */ }
    _ = name
}

// Вариант B: MultipartReader — потоково, без буферизации, годится для гигабайтов
func uploadStream(w http.ResponseWriter, r *http.Request) {
    r.Body = http.MaxBytesReader(w, r.Body, 256<<20)
    mr, err := r.MultipartReader() // до этого нельзя вызывать r.FormValue/r.FormFile: съедят тело
    if err != nil {
        writeProblem(w, http.StatusUnsupportedMediaType, "ожидается multipart/form-data")
        return
    }
    for {
        part, err := mr.NextPart()
        if errors.Is(err, io.EOF) {
            break
        }
        if err != nil { /* 400 */ return }

        switch part.FormName() {
        case "meta":
            var meta Meta
            if err := json.NewDecoder(io.LimitReader(part, 64<<10)).Decode(&meta); err != nil {
                /* 400 */ return
            }
        case "file":
            // сразу в S3/minio, минуя диск и память
            // не LimitReader: тот молча обрежет файл, и в хранилище уйдёт обрубок
            _, err = uploader.Upload(r.Context(), key, http.MaxBytesReader(w, part, 200<<20))
            if err != nil { /* 500 */ return }
        }
        _ = part.Close()
    }
}

type Handler interface { ServeHTTP(ResponseWriter, *Request) }

type HandlerFunc func(ResponseWriter, *Request)
func (f HandlerFunc) ServeHTTP(w ResponseWriter, r *Request) { f(w, r) }

mux.HandleFunc("GET /v1/posts/{id}", getPost)
mux.HandleFunc("GET /v1/files/{path...}", files)   // хвост пути
mux.HandleFunc("GET /v1/posts/{$}", exact)         // без префиксного матча
id := r.PathValue("id")
route := r.Pattern    // Go 1.23: готовая метка для метрик

type Middleware func(http.Handler) http.Handler

func Chain(mws ...Middleware) Middleware {
    return func(final http.Handler) http.Handler {
        for i := len(mws) - 1; i >= 0; i-- { // с конца: mws[0] станет внешним
            final = mws[i](final)
        }
        return final
    }
}
srv.Handler = Chain(RequestID, Logging(log), Recover(log), Auth)(mux)

type statusWriter struct {
    http.ResponseWriter
    status, bytes int
}
func (w *statusWriter) WriteHeader(code int) {
    if w.status != 0 { return }             // гасим повторный WriteHeader
    w.status = code
    w.ResponseWriter.WriteHeader(code)
}
func (w *statusWriter) Write(b []byte) (int, error) {
    if w.status == 0 { w.status = http.StatusOK }
    n, err := w.ResponseWriter.Write(b)
    w.bytes += n
    return n, err
}
func (w *statusWriter) Unwrap() http.ResponseWriter { return w.ResponseWriter }

func Logging(log *slog.Logger) Middleware {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            start := time.Now()
            sw := &statusWriter{ResponseWriter: w}
            next.ServeHTTP(sw, r)
            if sw.status == 0 { sw.status = http.StatusOK }
            log.Info("http",
                "method", r.Method, "path", r.URL.Path, "route", r.Pattern,
                "status", sw.status, "bytes", sw.bytes,
                "latency_ms", time.Since(start).Milliseconds(),
                "request_id", RequestIDFrom(r.Context()))
        })
    }
}

func Recover(log *slog.Logger) Middleware {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            defer func() {
                rec := recover()
                if rec == nil { return }
                if rec == http.ErrAbortHandler { panic(rec) } // штатный обрыв, не глотаем
                log.Error("panic", "err", rec, "stack", string(debug.Stack()),
                    "request_id", RequestIDFrom(r.Context()))
                w.WriteHeader(http.StatusInternalServerError)
                _, _ = io.WriteString(w, `{"title":"internal error","status":500}`)
            }()
            next.ServeHTTP(w, r)
        })
    }
}

type ctxKey int
const requestIDKey ctxKey = iota   // неэкспортируемый тип: чужой пакет не подменит ключ

func RequestID(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        id := r.Header.Get("X-Request-Id")
        if id == "" || len(id) > 64 { id = uuid.New().String() }  // Go 1.27: uuid уже в stdlib
        w.Header().Set("X-Request-Id", id)
        next.ServeHTTP(w, r.WithContext(context.WithValue(r.Context(), requestIDKey, id)))
    })
}
func RequestIDFrom(ctx context.Context) string { s, _ := ctx.Value(requestIDKey).(string); return s }

var transport = &http.Transport{
    DialContext:           (&net.Dialer{Timeout: 3 * time.Second, KeepAlive: 30 * time.Second}).DialContext,
    TLSHandshakeTimeout:   3 * time.Second,
    ResponseHeaderTimeout: 5 * time.Second,
    MaxIdleConns:          256,
    MaxIdleConnsPerHost:   128,  // дефолт 2
    MaxConnsPerHost:       256,
    IdleConnTimeout:       90 * time.Second,
    ForceAttemptHTTP2:     true,
}
var client = &http.Client{Transport: transport, Timeout: 10 * time.Second}

resp, err := client.Do(req)
if err != nil { return err }          // сначала err: при ошибке resp == nil
defer func() {
    _, _ = io.Copy(io.Discard, io.LimitReader(resp.Body, 64<<10)) // дочитать
    _ = resp.Body.Close()
}()

ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
defer stop()

srv := &http.Server{Addr: ":8080", Handler: h, ReadHeaderTimeout: 5 * time.Second}

errCh := make(chan error, 1)
go func() {
    if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
        errCh <- err
    }
}()

select {
case err := <-errCh:
    log.Error("не поднялись", "err", err); os.Exit(1)
case <-ctx.Done():
    // Go 1.26: причина отмены называет сигнал — "terminated signal received" и т. п.
    log.Info("получен сигнал", "cause", context.Cause(ctx))
}
stop()                        // второй Ctrl+C убьёт процесс сразу

ready.Store(false)            // /readyz отдаёт 503
time.Sleep(5 * time.Second)   // ждём, пока нас выведут из балансировки

shCtx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
defer cancel()
if err := srv.Shutdown(shCtx); err != nil {
    log.Error("не успели", "err", err)
    _ = srv.Close()           // рвём остатки
}

consumer.Stop()               // и только теперь ресурсы
_ = db.Close()
_ = tracer.Shutdown(context.Background())

r.Body = http.MaxBytesReader(w, r.Body, 1<<20)   // 1 МиБ, w нужен для корректного закрытия
dec := json.NewDecoder(r.Body)
dec.DisallowUnknownFields()

var in createReq
if err := dec.Decode(&in); err != nil {
    var maxErr *http.MaxBytesError                // Go 1.19+
    var typErr *json.UnmarshalTypeError
    switch {
    case errors.As(err, &maxErr): // 413
    case errors.As(err, &typErr): // 400 с именем поля и ожидаемым типом
    case errors.Is(err, io.EOF):  // 400 «пустое тело»
    }
    return
}
if err := dec.Decode(&struct{}{}); !errors.Is(err, io.EOF) {
    // в теле было {"a":1}{"b":2} — второй объект молча проехал бы
    return
}

// A: ParseMultipartForm
r.Body = http.MaxBytesReader(w, r.Body, 32<<20)
if err := r.ParseMultipartForm(8 << 20); err != nil {
    return // 400
}
defer r.MultipartForm.RemoveAll() // /tmp!

f, hdr, err := r.FormFile("avatar")
if err != nil {
    return // 400
}
defer f.Close()
// hdr.Filename, hdr.Size, hdr.Header

// B: MultipartReader — стриминг
mr, err := r.MultipartReader()
if err != nil { return } // 415
for {
    p, err := mr.NextPart()
    if errors.Is(err, io.EOF) { break }
    if err != nil { return } // 400
    if p.FormName() == "file" {
        uploader.Upload(ctx, key,
            http.MaxBytesReader(w, p, 200<<20))
    }
    p.Close()
}

10.3Аутентификация и авторизация

В этой теме половина кандидатов путает термины, а другая знает про JWT ровно то, что написано на jwt.io. Определений тут не спрашивают, спрашивают компромиссы: почему токен так трудно отозвать, где хранить его в браузере и что будет, если об этом не подумать.

Аутентификация, авторизация и всё, что рядом

Вся глава крутится вокруг одного слова. Токен — строка, которую сервер один раз выдал клиенту после проверки пароля, а клиент потом прикладывает к каждому запросу вместо пароля. Всё. После логина пароль больше никуда не летит, летит токен. Схемы различаются ответами на два вопроса. Что внутри строки: случайный идентификатор («непрозрачный» токен, его смысл знает только сервер) или подписанные данные, которые сервер проверит, ни у кого не спрашивая (это JWT)? И кто прикладывает токен к запросу: браузер сам (кука) или наш JavaScript руками (заголовок Authorization)? Из второго вопроса вырастает вся тема CSRF в главе 10.4.

Порядок жёсткий: сначала аутентификация, потом авторизация. Нельзя решить, что человеку можно, пока не знаешь, кто он. Названия кодов в HTTP исторически перепутаны: 401 Unauthorized на деле означает «не аутентифицирован» и обязан идти с заголовком WWW-Authenticate, а 403 Forbidden значит «аутентифицирован, но прав не хватает».

Сессии против JWT: где живёт состояние

Разница одна, и всё остальное следует из неё. У сессии состояние лежит на сервере: клиент носит непрозрачный идентификатор, сервер по нему достаёт данные. У JWT состояние у клиента: все данные внутри токена, сервер только проверяет подпись.

Устройство JWT

JWT (RFC 7519) состоит из трёх частей через точку: header.payload.signature. Каждая закодирована base64url (алфавит без + и /, без паддинга, чтобы спокойно жить в URL). Но кодирование ещё не шифрование: payload прочитает кто угодно.

Стандартные claims, которые обязан назвать кандидат:

HS256 против RS256

Главный аргумент за RS256: принцип наименьших привилегий. С HS256 любой сервис, который проверяет токен, технически может его и подделать. Достаточно взломать один второстепенный сервис, чтобы выписать себе админский токен. С RS256 приватный ключ есть только у auth-сервиса, остальные тянут публичные ключи с /.well-known/jwks.json и кэшируют их по kid.

// Правильная проверка на golang-jwt/jwt/v5
type Claims struct {
    Roles []string `json:"roles"`
    jwt.RegisteredClaims
}

var claims Claims
token, err := jwt.ParseWithClaims(raw, &claims,
    func(t *jwt.Token) (any, error) {
        // 1. семейство алгоритмов фиксируем сами
        if _, ok := t.Method.(*jwt.SigningMethodHMAC); !ok {
            return nil, fmt.Errorf("неожиданный alg: %v", t.Header["alg"])
        }
        // 2. kid ищем только по whitelist, никаких путей и SQL
        kid, _ := t.Header["kid"].(string)
        key, ok := keyring[kid]
        if !ok {
            return nil, errors.New("неизвестный kid")
        }
        return key, nil
    },
    jwt.WithValidMethods([]string{"HS256"}), // 3. дублируем whitelist явно
    jwt.WithIssuer("auth.example.com"),      // 4. iss
    jwt.WithAudience("api.example.com"),     // 5. aud
    jwt.WithExpirationRequired(),            // 6. exp обязателен
    jwt.WithLeeway(30*time.Second),          // допуск на расхождение часов
)
if err != nil || !token.Valid {
    problem(w, http.StatusUnauthorized, "невалидный токен")
    return
}

Где хранить токен на клиенте

Вопрос-ловушка: «правильного» варианта нет, ты выбираешь, от какой атаки страдать.

http.SetCookie(w, &http.Cookie{
    Name:     "session",
    Value:    token,
    Path:     "/",
    HttpOnly: true,                    // недоступна из JS
    Secure:   true,                    // только по HTTPS
    SameSite: http.SameSiteLaxMode,    // база защиты от CSRF
    MaxAge:   int((15 * time.Minute).Seconds()),
    // Domain намеренно не задаём: без него кука привязана к конкретному хосту
    // и не утечёт на поддомены (__Host- префикс дал бы то же самое жёстче)
})

Refresh-токены: зачем, ротация, обнаружение кражи

Дилемма такая: с длинным TTL access-токена удобно, но украденный токен долго живёт; короткий TTL безопасен, но заставляет логиниться каждые 10 минут. Поэтому выдают пару токенов:

• Access — JWT, 5–15 минут, живёт в памяти клиента, летит в каждый запрос, проверяется без похода в БД.
• Refresh — непрозрачная случайная строка (не JWT), 7–30 дней, хранится в БД в хешированном виде, летит только на /auth/refresh, привязан к устройству и сессии.

Refresh специально делают непрозрачным: его всё равно сверяют с БД, так что подпись не нужна, а отозвать его можно одной строкой UPDATE. В БД кладут хеш (хватит SHA-256: энтропии 256 бит, словарём не подберёшь), чтобы дамп базы не давал готовых сессий.

Ротация и обнаружение переиспользования

Ротация — плановая замена секрета: новый вводят, старый тут же выводят из обращения. Это рутина, а не «поменяли пароль, потому что испугались», и идёт она по расписанию (ключи подписи, сертификаты, API-ключи) или по событию. У refresh-токена событие одно: каждое обновление.

При каждом обновлении старый refresh инвалидируется, а клиент получает новый. Заодно выходит бесплатный детектор кражи: если кто-то предъявил уже использованный refresh, значит, токен ходит по рукам. Кто из двоих вор, не понять, поэтому убивают всё семейство токенов и заставляют залогиниться заново.

CREATE TABLE refresh_tokens (
    id          uuid PRIMARY KEY,
    family_id   uuid NOT NULL,          -- цепочка ротаций одной сессии
    user_id     bigint NOT NULL,
    token_hash  bytea NOT NULL UNIQUE,  -- sha256(секрет), не сам секрет
    used_at     timestamptz,            -- NOT NULL => уже потрачен
    revoked_at  timestamptz,
    expires_at  timestamptz NOT NULL,
    user_agent  text,
    ip          inet
);
CREATE INDEX ON refresh_tokens (family_id) WHERE revoked_at IS NULL;

func (s *Auth) Refresh(ctx context.Context, raw string) (Pair, error) {
    h := sha256.Sum256([]byte(raw))

    tx, _ := s.db.BeginTx(ctx, &sql.TxOptions{Isolation: sql.LevelReadCommitted})
    defer tx.Rollback()

    var t token
    // FOR UPDATE: параллельный refresh ждёт блокировку и потом видит used_at.
    // Без неё оба выпустят по живой паре, и кражу никто не заметит
    err := tx.QueryRowContext(ctx,
        `SELECT id, family_id, user_id, used_at, revoked_at, expires_at
           FROM refresh_tokens WHERE token_hash = $1 FOR UPDATE`, h[:]).Scan(...)
    if errors.Is(err, sql.ErrNoRows) {
        return Pair{}, ErrUnauthorized
    }

    switch {
    case t.RevokedAt.Valid || t.ExpiresAt.Before(time.Now()):
        return Pair{}, ErrUnauthorized
    case t.UsedAt.Valid:
        // переиспользование: токен уже меняли, значит, утёк. Рубим всё семейство
        _, _ = tx.ExecContext(ctx,
            `UPDATE refresh_tokens SET revoked_at = now()
              WHERE family_id = $1 AND revoked_at IS NULL`, t.FamilyID)
        _ = tx.Commit()
        s.alert(ctx, "refresh token reuse", t.UserID, t.FamilyID)
        return Pair{}, ErrUnauthorized
    }

    tx.ExecContext(ctx, `UPDATE refresh_tokens SET used_at = now() WHERE id = $1`, t.ID)
    newRaw, newHash := generateToken()  // 32 байта из crypto/rand
    tx.ExecContext(ctx, `INSERT INTO refresh_tokens
        (id, family_id, user_id, token_hash, expires_at) VALUES ($1,$2,$3,$4,$5)`,
        uuid.NewV7(), t.FamilyID, t.UserID, newHash, time.Now().Add(30*24*time.Hour))
        // v7 сортируется по времени: вставки ложатся в хвост индекса, а не разбрасываются

    if err := tx.Commit(); err != nil { return Pair{}, err }
    return Pair{Access: s.issueJWT(t.UserID), Refresh: newRaw}, nil
}

Как разлогинить пользователя с JWT

Если коротко, по-настоящему никак. Подписанный токен валиден, пока не истёк exp, и проверяющий сервер не обязан ни с кем сверяться. Остаётся выбрать компромисс.

OAuth 2.0 и OIDC

OAuth 2.0 придуман для делегирования доступа, а не для логина: «дай этому приложению читать мои репозитории, не отдавая ему пароль от GitHub». OIDC надстраивается над OAuth тонким слоем и добавляет к нему аутентификацию: новый скоуп openid, дополнительный id_token (JWT с данными о пользователе), эндпоинт /userinfo и дискавери /.well-known/openid-configuration. Фраза «OAuth — авторизация, OIDC — аутентификация поверх неё» закрывает половину вопроса.

Клиенты делятся на confidential (серверные, умеют хранить client_secret) и public (SPA и мобильные: секрет там спрятать негде, любой выковыряет его из бандла или apk). Для public-клиентов PKCE и придумали.

API-ключи и Basic auth — где уместны

RBAC, ABAC и middleware авторизации

RBAC (role-based): у пользователя роли, у ролей — права, а проверка звучит как «есть ли у роли право posts:delete». Просто, понятно, легко аудируется, но плохо выражает «можно, если это твой пост, рабочее время и сумма меньше 10 000». В ABAC (attribute-based) решение считается функцией от атрибутов субъекта, объекта, действия и среды. Гибко, но отлаживать труднее, и понять, «почему отказали», тоже.

В жизни почти всегда встречается гибрид: RBAC грубо фильтрует на входе (middleware), а владение и условия точечно проверяют в сервисном слое.

// Middleware: только грубая проверка «есть ли вообще такое право»
func RequirePerm(perm string) Middleware {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            u, ok := UserFrom(r.Context())
            if !ok {
                w.Header().Set("WWW-Authenticate", `Bearer realm="api"`)
                problem(w, http.StatusUnauthorized, "нужна аутентификация")
                return
            }
            if !u.Can(perm) {
                problem(w, http.StatusForbidden, "недостаточно прав")
                return
            }
            next.ServeHTTP(w, r)
        })
    }
}

mux.Handle("DELETE /v1/posts/{id}", RequirePerm("posts:delete")(deletePost))

Хранение паролей

Пароль нельзя ни хранить в открытом виде, ни шифровать (расшифровать сможет и атакующий с ключом), ни хешировать быстрым алгоритмом. Нужна намеренно медленная функция с солью.

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

// bcrypt: соль внутри самого хеша
hash, err := bcrypt.GenerateFromPassword(
    []byte(pass), 12)         // cost 12 ≈ 250 мс

err = bcrypt.CompareHashAndPassword(
    hash, []byte(pass))       // сравнение constant-time
// bcrypt учитывает только 72 байта пароля,
// а GenerateFromPassword на более длинном
// вернёт ErrPasswordTooLong. Длинную фразу
// заранее сворачивают в SHA-256 (или берут argon2)

// argon2id
salt := make([]byte, 16)
rand.Read(salt) // с Go 1.24 ошибки не бывает
key := argon2.IDKey([]byte(pass), salt,
    3,          // time: число проходов
    64*1024,    // memory: 64 МиБ
    4,          // threads
    32)         // длина ключа

ok := subtle.ConstantTimeCompare(key, stored) == 1
// в БД: соль + все параметры + хеш,
// иначе не сможешь их поднять при ротации

Секреты приложения

Под секретом понимают пароль БД, ключ подписи JWT, токен платёжного провайдера. Требований к ним три: не попасть в git, не светиться в логах и уметь меняться без релиза.

Vault AppRole — стандартный способ аутентифицировать сервис без участия человека. У приложения есть role_id (не секрет, лежит в конфиге) и secret_id (одноразовый, короткоживущий, приходит отдельным каналом: от оркестратора или через response wrapping). Приложение меняет пару на токен с TTL, регулярно продлевает его (renew) и по этому токену читает секреты. role_id и secret_id разделены, чтобы утечка одного артефакта не давала доступа. Есть и отдельный джокер, динамические секреты: Vault сам создаёт временного пользователя в PostgreSQL с TTL 1 час, и «украсть пароль от БД» становится почти бессмысленно.

// eyJhbGciOi… . eyJzdWIiOi… . 4pcPyMD0…   (три части base64url через точку)
// header:    {"alg":"HS256","typ":"JWT","kid":"2024-06"}
// payload:   {"sub":"123","exp":1700000000,"iat":...,"iss":"api","aud":"web","jti":"..."}
// signature: HMAC-SHA256(base64url(header) + "." + base64url(payload), secret)

// обмен уже потраченного refresh = сигнал кражи
row, err := repo.GetRefresh(ctx, hash(presented))
switch {
case err != nil:
    return ErrInvalid
case row.UsedAt != nil:                 // токен уже обменивали
    repo.RevokeFamily(ctx, row.FamilyID) // рвём всю цепочку: и вора, и жертву
    audit.Warn("refresh reuse", "user", row.UserID)
    return ErrInvalid
case time.Now().After(row.ExpiresAt):
    return ErrExpired
}
newRT := random256()
repo.MarkUsedAndIssue(ctx, row.ID, hash(newRT), row.FamilyID)

// вариант 3: одна цифра решает 90% задач отзыва
type Claims struct {
    jwt.RegisteredClaims
    Ver int `json:"ver"`
}
// при логауте-везде / смене пароля / бане:
//   UPDATE users SET token_version = token_version + 1 WHERE id = $1
func (a *Auth) check(ctx context.Context, c Claims) error {
    cur, err := a.verCache.Get(ctx, c.Subject) // локальный кэш на 30 секунд
    if err != nil { return err }
    if c.Ver != cur { return ErrRevoked }
    return nil
}

// ключ отдаём один раз при создании, в БД только хеш и префикс
key := "sk_live_" + base64url(random(24))          // 192 бита энтропии
row := APIKey{
    Prefix:    key[:14],                            // для поиска и показа в UI
    Hash:      sha256.Sum256([]byte(key)),          // быстрый хеш ок: секрет высокоэнтропийный
    Scopes:    []string{"orders:read"},
    ExpiresAt: time.Now().AddDate(1, 0, 0),
}
// проверка: находим по префиксу, сравниваем хеши constant-time

func RequirePerm(p string) func(http.Handler) http.Handler {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            u, ok := auth.From(r.Context())     // положил middleware аутентификации
            if !ok { fail(w, 401); return }
            if !u.Can(p) { fail(w, 403); return }
            next.ServeHTTP(w, r)
        })
    }
}
r.With(RequirePerm("order:cancel")).Post("/orders/{id}/cancel", h.Cancel)

// а это middleware сделать не может, он не знает, чей это заказ:
func (s *Service) Cancel(ctx context.Context, orderID, userID int64) error {
    o, err := s.repo.Get(ctx, orderID)
    if err != nil { return err }
    if u, _ := auth.From(ctx); o.UserID != userID && !u.Can("order:cancel:any") {
        return ErrForbidden           // отдать наружу как 404, если факт существования секретен
    }
    ...
}

10.4Безопасность и защита сервиса

Секция, которую многие готовят по списку «OWASP Top 10» и на собеседовании пересказывают заголовки. Спрашивают другое: покажи уязвимый код, объясни, почему он уязвим, и почини — а потом расскажи, что из этого вообще может сделать бэкенд, а что решается на клиенте или на периметре. Половина вопросов здесь упирается в границу ответственности.

Одна мысль, из которой выводится вся глава

Почти каждая уязвимость из этого списка сводится к стёртой границе между данными и кодом или к доверию к тому, что контролирует не сервер. В SQL-инъекции пользовательская строка стала куском SQL, в XSS стала куском HTML, в SSRF превратилась в адрес, куда сервер сам пошёл. Остальное про доверие. При CSRF сервер поверил, что раз кука пришла, значит запрос осознанный. При IDOR он поверил идентификатору из URL, при mass assignment поверил набору полей во входном JSON. Если держать в голове эту рамку, ответы перестают быть списком заклинаний.

SQL-инъекция

Классика, которую всё ещё находят в проде — обычно не в основном CRUD, а в отчётах, поиске, админке и там, где «плейсхолдер не подставляется»: сортировка, имя таблицы, IN (...) с динамическим числом элементов. Механика всегда одна: строка пользователя попадает в текст запроса, СУБД разбирает этот текст целиком и не может отличить, какая часть была задумана как данные.

// Уязвимо. Такое и находят на пентестах.
func (r *Repo) UserByID(ctx context.Context, raw string) (*User, error) {
    q := "SELECT id, email, is_admin FROM users WHERE id = " + raw
    row := r.db.QueryRowContext(ctx, q)
    ...
}

При raw = "1" всё работает, тесты зелёные. При raw = "1 OR 1=1 --" получается WHERE id = 1 OR 1=1 --: условие тождественно истинно, а -- отрезает всё, что шло следом. Дальше атака развивается по накатанной:

• Расширение выборки. С OR 1=1 вываливается вся таблица.
• UNION-инъекция подставляет в ту же форму ответа чужие колонки: 1 UNION SELECT id, password_hash, NULL FROM users (типы колонок должны сойтись, отсюда NULL на месте is_admin).
• Blind / boolean-based. Ответа не видно, зато видно, изменился ли он: 1 AND (SELECT substr(password_hash,1,1) FROM users WHERE id=1)='a', и хеш вытаскивается посимвольно.
• Time-based обходится без ответа вовсе, ему хватает времени: 1 AND (SELECT 1 FROM pg_sleep(5)) = 1. Работает даже там, где ответ всегда 200 и пустой.
• Stacked queries проходят, если драйвер разрешает несколько операторов в одном сообщении: 1; DROP TABLE users; --. В PostgreSQL расширенный протокол такое запрещает, а Exec с простым протоколом или MySQL с multiStatements=true пропустят спокойно.

Почему параметризация работает, а экранирование — нет

Плейсхолдер не «умный escape». В расширенном протоколе PostgreSQL клиент шлёт два разных сообщения: Parse с текстом запроса и Bind со значениями. Когда сервер видит значение, синтаксическое дерево уже построено, и оно ляжет в конкретный лист этого дерева. Никакая строка не «дорастёт» до нового предиката: грамматика уже разобрана. Поэтому параметризация риск не смягчает, а устраняет.

Ручное экранирование решает ту же задачу с другого конца — пытается угадать, что именно опасно. И проигрывает сразу по нескольким причинам:

• Правила зависят от диалекта и настроек. В MySQL при NO_BACKSLASH_ESCAPES обратный слеш перестаёт экранировать; в PostgreSQL поведение E'...' и standard_conforming_strings различается. Функция, написанная под одну конфигурацию, дырявая в другой.
• Кодировки. Классическая атака на GBK/SJIS: байт 0x5C оказывается второй половиной многобайтового символа, и добавленный слеш «съедается», освобождая кавычку. Экранирование, не знающее charset соединения, ломается.
• Числовой контекст. Экранируют кавычки, но если значение подставляется без них (WHERE id = 1 OR 1=1), атакующему кавычки и не нужны.
• Это ручная работа. Хватит одного забытого места — и всё остальное экранирование теряет смысл. Параметризация ошибается «в безопасную сторону»: забыл плейсхолдер, и запрос обычно просто не компилируется или падает на несовпадении числа аргументов.

ORDER BY и имена таблиц — куда плейсхолдер не ставится

Плейсхолдер подставляет значение. А имя колонки, направление сортировки, имя таблицы или схемы относятся к идентификаторам, к грамматике запроса, и параметр на их месте не сработает: имя таблицы СУБД не примет, а ORDER BY $1 молча отсортирует по константе, то есть никак. LIMIT $1 и OFFSET $2, наоборот, обычные значения. В зрелых проектах реальные инъекции чаще всего находят именно тут: везде параметризовано, а сортировка склеена. Рабочее решение одно: маппинг из белого списка. Клиент присылает ключ, а сервер превращает его в заранее написанный фрагмент SQL.

// Клиент присылает sort=created_at&order=desc, но в SQL уезжает только то,
// что мы написали сами. Строки пользователя в тексте запроса нет.
var sortable = map[string]string{
    "created_at": "p.created_at",
    "title":      "p.title",
    "views":      "p.views_count",
}

func orderClause(q url.Values) (string, error) {
    col, ok := sortable[q.Get("sort")]
    if !ok {
        if q.Get("sort") == "" {
            return "p.created_at DESC, p.id DESC", nil // детерминированный дефолт
        }
        return "", fmt.Errorf("%w: неизвестное поле сортировки", ErrValidation)
    }
    dir := "ASC"
    if strings.EqualFold(q.Get("order"), "desc") {
        dir = "DESC"
    }
    // tie-breaker по id обязателен, иначе keyset-пагинация «дребезжит»
    return col + " " + dir + ", p.id " + dir, nil
}

Бывает, что без динамического имени таблицы или схемы не обойтись (мультитенантность «схема на клиента», админский конструктор отчётов). Тогда идентификатор не склеивают, а цитируют библиотечной функцией и всё равно проверяют по списку: pgx.Identifier{schema, table}.Sanitize() в pgx или quote_ident() на стороне PostgreSQL. Список существующих тенантов проверяй заранее — цитирование спасает от синтаксической инъекции, но не от «покажи мне схему чужого клиента».

Что ещё говорят про инъекции на собеседовании

• ORM сама по себе не защищает. Склеить строку можно и в GORM: Where("name = '" + s + "'"), Raw, Exec, любой конструктор «сырых» фрагментов. Защищает плейсхолдер, а не ORM.
• Least privilege у роли БД. Приложение ходит под ролью без DROP, без CREATE, без доступа к чужим схемам и без суперправ. Тогда даже успешная инъекция прочитает только то, что и так доступно сервису. Для миграций заводят отдельную роль.
• Ошибки наружу не отдавать. Текст ошибки СУБД подсказывает атакующему имя таблицы, тип колонки, версию сервера. Клиент получает обезличенный 500/400 и trace_id, детали уходят в лог.
• Инъекции бывают и помимо SQL. Тот же класс: NoSQL (оператор $ne в JSON-фильтре Mongo), LDAP, command injection через exec.Command("sh", "-c", user), шаблонизаторы, XPath, заголовки писем. Ответ везде один: не собирать команду строкой. В Go с процессами это особенно просто: exec.Command(name, args...) вообще не запускает shell, если явно не позвать sh -c.
• Обнаружение: линтеры (gosec, правила G201/G202 про конкатенацию в SQL; сам go vet такого не ловит), запрет fmt.Sprintf рядом с db.Query на ревью, WAF как второй эшелон, а не как первый.

XSS: что из этого реально может сделать бэкенд

XSS тоже инъекция, только в HTML: строка пользователя оказывается в разметке, и браузер исполняет её как код. Исполняет у другого пользователя и в контексте нашего origin, то есть с доступом ко всему, что там есть: DOM, localStorage, куки без httpOnly. И, что хуже всего, скрипт может слать запросы к нашему же API от имени жертвы, уже с её сессией.

Отсюда и ответ на вопрос «что тут делает бэкенд». Если фронт написан как SPA, а бэкенд отдаёт только JSON, классический XSS чинится на фронте: React/Vue экранируют по умолчанию, и дыра появляется через dangerouslySetInnerHTML/v-html. Но у бэкенда остаётся четыре рычага, и их надо назвать.

1. Экранирование при рендере — если рендерим мы

В Go разница между двумя пакетами стоит инцидента. text/template подставляет строку как есть. html/template учитывает контекст: парсит шаблон, понимает, куда попадает значение (в текст, в атрибут, в href, внутрь <script>, в CSS), и в каждом месте экранирует по-своему. Контекст нужен потому, что экранировать < и > мало, если значение попадает в атрибут без кавычек или в URL со схемой javascript:.

import "html/template"   // не text/template

var page = template.Must(template.New("p").Parse(`
  <p>Привет, {{.Name}}</p>                     <!-- HTML-контекст -->
  <a href="{{.Site}}">сайт</a>                 <!-- URL-контекст -->
  <script>var u = {{.Name}};</script>          <!-- JS-контекст -->
`))

// Name = `<img src=x onerror=alert(1)>` → в HTML станет &lt;img …&gt;,
//   а в <script> станет корректным JS-литералом "\u003cimg src=x …\u003e".
// Site = `javascript:alert(1)`          → html/template подставит #ZgotmplZ.

Обратная сторона: тип template.HTML отключает экранирование. Нужен он в одном случае: когда вставляем HTML, которому доверяем. Пользовательскому HTML доверять нельзя никогда. Если продукту нужно форматирование (комментарии с разметкой), такой HTML пропускают через санитайзер с белым списком тегов и атрибутов — bluemonday в Go. Чёрный список (вырезать <script>) не работает, обходов десятки: <img onerror>, <svg onload>, <iframe srcdoc>, экзотические кодировки, <scr<script>ipt> для наивной однопроходной замены.

2. Content-Type и X-Content-Type-Options

Браузер решает, исполнять ли содержимое как HTML, по заголовку Content-Type. Если его нет или он неправильный, срабатывает MIME-sniffing: браузер угадывает по первым байтам. Загруженный «аватар», который на самом деле начинается с <html><script> и отдаётся без Content-Type, вполне может исполниться как страница на нашем домене. Отсюда два обязательных пункта:

• всегда выставлять точный Content-Type — application/json; charset=utf-8 для API, реальный тип для файлов, а для скачиваемого пользовательского контента ещё и Content-Disposition: attachment;
• X-Content-Type-Options: nosniff, который запрещает угадывание. Один заголовок закрывает целый класс атак.

Мера посерьёзнее: отдавать пользовательские файлы с другого домена (usercontent.example.net, не поддомен основного). Тогда даже скрипт, который там исполнился, окажется в чужом origin и до сессии на основном домене не дотянется.

3. JSON-эндпоинт как вектор — почему это не паранойя

На фразе «У нас только JSON, XSS невозможен» любят ловить. Превратить JSON-ручку в XSS можно несколькими способами:

• Неверный Content-Type. Тот же JSON, отданный как text/html (или вообще без типа, с включённым sniffing), исполняется. Хватит того, что в теле есть отражённое значение из запроса: {"error":"неизвестный параметр <script>…</script>"}. Классический сценарий: обработчик ошибок отражает err.Error() в ответ. В Go http.Error тут безопасен: он ставит text/plain и X-Content-Type-Options: nosniff. Опасен самописный хелпер без Content-Type: тип тогда угадывает net/http по первым байтам, и <script> в начале тела сделает ответ text/html.
• Отражение в ответе плюс скачивание. Если ручка отдаёт файл с именем, взятым из запроса, и браузер открывает его как документ, контекст снова становится HTML.
• JSONP, легаси-механизм обхода SOP: ответ оборачивается в вызов функции, имя которой пришло в query. Выходит сразу XSS (имя коллбэка попадает в исполняемый код) и полный обход CORS, потому что <script src> уходит куда угодно и с куками. Ответ простой: JSONP не использовать, для кросс-домена есть CORS.
• Ответ, который потом кладут в DOM. Даже идеальный JSON становится XSS, если фронт вставит поле через innerHTML. Формально виноват фронт, но проектная вина общая: не хранить в БД то, что не прошло валидацию, и не отдавать HTML там, где по контракту текст.

// Ответ API: тип выставляем явно и до записи тела, sniffing запрещаем.
func writeJSON(w http.ResponseWriter, status int, v any) {
    w.Header().Set("Content-Type", "application/json; charset=utf-8")
    w.Header().Set("X-Content-Type-Options", "nosniff")
    w.WriteHeader(status)                       // строго после Header().Set

    enc := json.NewEncoder(w)
    enc.SetEscapeHTML(true)                     // дефолт: < > & → \u003c \u003e \u0026
    if err := enc.Encode(v); err != nil {
        // статус и заголовки уже ушли, поменять их нельзя: только логируем
        slog.Error("encode response", "err", err)
    }
}

Про SetEscapeHTML: по умолчанию encoding/json экранирует <, > и & в юникод-последовательности, чтобы JSON можно было безопасно встроить в HTML. Иногда это отключают ради читаемости — и заодно убирают одну из подстраховок.

4. CSP — второй эшелон

Заголовком Content-Security-Policy сервер сообщает браузеру, откуда странице можно грузить скрипты, стили и картинки и разрешён ли инлайн. Экранирование CSP не заменяет, а страхует: если XSS всё-таки просочился, полезная нагрузка не исполнится или не сможет утечь наружу.

# Строгая политика для отрендеренной сервером страницы: nonce на каждый запрос,
# никакого 'unsafe-inline', запрет фреймов и base-тега.
Content-Security-Policy:
  default-src 'self';
  script-src 'self' 'nonce-r4nd0m' 'strict-dynamic';
  style-src 'self';
  img-src 'self' data:;
  connect-src 'self' https://api.example.com;
  object-src 'none'; base-uri 'none'; frame-ancestors 'none';
  form-action 'self'

# Чистому JSON-API хватит жёсткого минимума, страниц там нет:
Content-Security-Policy: default-src 'none'; frame-ancestors 'none'; sandbox

• 'unsafe-inline' в script-src почти полностью обесценивает CSP — XSS как раз и исполняется инлайном. Вместо него ставят nonce (случайное значение на каждый ответ, оно проставляется в теге и в заголовке) или хеш скрипта.
• Внедрять политику разумно через Content-Security-Policy-Report-Only плюс report-to: собрать нарушения на проде, вычистить, потом включить в блокирующем режиме.
• frame-ancestors 'none' пришёл на смену X-Frame-Options: DENY и защищает от clickjacking. Старый заголовок оставляют для совместимости.

CSRF: браузер отправляет запрос за пользователя

Cross-Site Request Forgery держится на автоматическом прикреплении учётных данных. Браузер прикладывает куки к запросу, глядя на адрес назначения, а не на того, кто этот запрос инициировал. Значит, чужая страница может заставить браузер жертвы сходить на наш домен — и запрос придёт полностью аутентифицированным.

Прочитать ответ злоумышленник при этом не может. Same-Origin Policy не даст чужому скрипту увидеть тело, статус или заголовки нашего ответа. Поэтому CSRF бьёт по изменяющим операциям: перевод денег, смена email, смена пароля, удаление, выдача прав. Это «слепой» вызов, результат которого атакующему не нужен.

Почему кука уязвима, а Authorization: Bearer — нет

Всё решает то, кто прикрепляет учётные данные. Куку прикрепляет браузер по правилу «домен совпал — приложил», и инициатор запроса ему при этом не важен (без SameSite). Заголовок Authorization проставляет наш JavaScript, который живёт на нашем origin. Чужая страница до него не дотянется — не прочитает токен из localStorage нашего домена и не заставит браузер добавить заголовок. К тому же любой запрос с кастомным заголовком перестаёт быть «простым» и требует CORS-preflight. Это предварительный запрос OPTIONS: им браузер сам, ещё до отправки настоящего запроса, спрашивает у сервера разрешение («можно этому origin такой метод и такие заголовки?»). Чужому Origin мы разрешения не дадим, и настоящий запрос просто не уйдёт. Подробно preflight разобран в разделе про CORS ниже.

SameSite в деталях

• «Same-site» ≠ «same-origin». Сравнивается registrable domain (eTLD+1), а не полный origin: app.example.com и api.example.com считаются одним site, схема тоже учитывается. Поэтому SameSite не спасает от атаки с соседнего поддомена, который кто-то захватил (subdomain takeover).
• Lax защищает не полностью. Форму и fetch он закрывает, а изменяющую операцию, повешенную на GET, нет. Если у нас есть GET /account/delete, атака сводится к простой ссылке или редиректу: top-level навигацию GET-ом Lax пропускает. А где кука без SameSite и браузер не ставит Lax сам, хватит и <img src=…>. Отсюда прямая связь: семантика методов тоже защищает от CSRF.
• Старые браузеры атрибут игнорируют, поэтому для по-настоящему критичных операций SameSite остаётся первым эшелоном, но не единственным.

CSRF-токены: два рабочих паттерна

Идея у обоих одна: потребовать от запроса значение, которое чужой сайт узнать не может. Читать наш ответ он не умеет (SOP), так что любой секрет, выданный на странице, ему недоступен.

• Synchronizer token. Сервер генерирует случайный токен, кладёт его в состояние сессии и отдаёт в HTML (скрытое поле формы или мета-тег), а на изменяющем запросе сверяет пришедшее значение с сохранённым. Надёжнее некуда, но нужно состояние на сервере.
• Double submit cookie обходится без состояния: сервер кладёт случайное значение в отдельную не-httpOnly куку, фронт читает её из JS и дублирует в заголовок X-CSRF-Token, а сервер сравнивает куку и заголовок. Схема работает, потому что чужой сайт не может прочитать куку и тем более проставить заголовок. Слабое место: захваченный поддомен может записать куку на родительский домен. Поэтому в проде берут signed double submit — значение куки привязано к идентификатору сессии через HMAC, и подставить произвольную пару не выйдет.

// Middleware: пропускаем безопасные методы, для остальных сверяем токен.
var safe = map[string]bool{http.MethodGet: true, http.MethodHead: true, http.MethodOptions: true}

func CSRF(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        if safe[r.Method] {
            next.ServeHTTP(w, r)
            return
        }
        // CSRF грозит только сессии в куке. Bearer-запросы пропускаем.
        if strings.HasPrefix(r.Header.Get("Authorization"), "Bearer ") {
            next.ServeHTTP(w, r)
            return
        }
        c, err := r.Cookie("csrf_token")
        hdr := r.Header.Get("X-CSRF-Token")
        // Сравниваем за постоянное время, иначе токен подберут побайтово.
        if err != nil || hdr == "" ||
            subtle.ConstantTimeCompare([]byte(c.Value), []byte(hdr)) != 1 {
            problem(w, http.StatusForbidden, "csrf_failed", "CSRF-токен не совпал")
            return
        }
        next.ServeHTTP(w, r)
    })
}

// Кука с токеном: httpOnly=false, иначе наш же JS её не прочитает.
http.SetCookie(w, &http.Cookie{
    Name: "csrf_token", Value: randomToken(32),
    Path: "/", Secure: true, HttpOnly: false, SameSite: http.SameSiteLaxMode,
})

Go 1.25: http.CrossOriginProtection — защита без токенов и кук

Выше была классика: своё состояние, своя кука, свой заголовок, свой код на фронте. В Go 1.25 в net/http появился CrossOriginProtection, готовый middleware из стандартной библиотеки, который решает ту же задачу вообще без токенов. Из-за него сдвинулась рекомендация по умолчанию, и на собесе это хороший свежий ответ: «для современных браузеров хватает штатного middleware, токены остаются страховкой».

Механика держится на Fetch metadata — служебных заголовках, которые к каждому запросу на HTTPS (и на localhost) добавляет сам браузер. Страница-инициатор не может их ни подделать, ни убрать (в отличие от Referer, который вырезается политикой, и от кастомных заголовков, которые ставит JS). Главный из них, Sec-Fetch-Site, отвечает как раз на тот вопрос, которого не хватало серверу: откуда запрос инициирован. Значения: same-origin, same-site, cross-site и none (пользователь сам ввёл адрес или открыл закладку). Само правило умещается в строку: небезопасный метод при Sec-Fetch-Site, не равном same-origin или none, получает 403. Если заголовка нет вовсе, в ход идёт запасной вариант: хост из Origin сверяется с Host, и при несовпадении запрос тоже отклоняется.

cop := http.NewCrossOriginProtection()

// Свой фронт на другом origin добавляем в белый список.
_ = cop.AddTrustedOrigin("https://admin.example.com")

// Ручки, куда браузер не ходит (вебхуки платёжки, колбэки), пускаем в обход.
cop.AddInsecureBypassPattern("/webhooks/")

// Дефолтный отказ: 403 с текстом. Приводим к своему формату ошибок.
cop.SetDenyHandler(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    problem(w, http.StatusForbidden, "cross_origin_denied", "межсайтовый запрос отклонён")
}))

srv := &http.Server{Addr: ":8080", Handler: cop.Handler(mux)}

// Если решение нужно принимать самому (например, логировать, но пропускать на канарейке):
if err := cop.Check(r); err != nil { /* это межсайтовый небезопасный запрос */ }

Полная таблица решений (проверено запуском на go1.27.0, POST на bank.example):

Sec-Fetch-Site: cross-site                      -> 403  "cross-origin request detected from Sec-Fetch-Site header"
Sec-Fetch-Site: same-site  (соседний поддомен)   -> 403  тоже отказ: проверка по ORIGIN, а не по site
Sec-Fetch-Site: same-origin                     -> 200
Sec-Fetch-Site: none       (адрес ввели руками)  -> 200
нет Sec-Fetch-Site и нет Origin                 -> 200  считаем, что это не браузер: curl, мобилка, сервис
нет Sec-Fetch-Site, Origin != Host              -> 403  "...and/or browser is out of date"
cross-site, но Origin в AddTrustedOrigin        -> 200
cross-site, но путь в AddInsecureBypassPattern  -> 200
GET / HEAD / OPTIONS при любом Sec-Fetch-Site   -> 200  безопасные методы не проверяются вообще

SSRF: сервер идёт туда, куда ему сказал клиент

При Server-Side Request Forgery злоумышленник управляет адресом, по которому наш сервис делает исходящий запрос. Атакующему это ценно, потому что наш сервер стоит внутри периметра: он видит приватную сеть, служебные порты и облачные метаданные, недоступные снаружи. Типовые точки входа: «загрузить картинку по URL», вебхуки, импорт из внешнего источника, генерация PDF/превью по ссылке, прокси-ручка, парсинг og:-разметки для красивого превью ссылки.

// Уязвимо: адрес полностью контролирует клиент.
func fetchAvatar(ctx context.Context, rawURL string) ([]byte, error) {
    resp, err := http.Get(rawURL)     // http://169.254.169.254/latest/meta-data/…
    ...                               // http://localhost:6379/  → Redis по HTTP
}                                     // file:///etc/passwd      → зависит от клиента

• Облачные метаданные. По адресу 169.254.169.254 в AWS/GCP/Azure лежат временные учётные данные роли инстанса. Хватит одного удачного SSRF, и у атакующего ключи от облака. IMDSv2 (обязательный PUT-токен и X-aws-ec2-metadata-token) появился как раз поэтому.
• Внутренние сервисы — админки без аутентификации «потому что они не торчат наружу», Kubernetes API, Consul, Elasticsearch, Prometheus, панель самого приложения.
• Сканирование сети. По времени ответа и коду ошибки атакующий картирует внутренние адреса и открытые порты, даже если тело ответа ему не возвращают (blind SSRF).
• Смена протокола через file://, gopher://, dict://. Если библиотека поддерживает эти схемы, из HTTP-запроса можно собрать произвольный TCP-пакет и, например, отдать команду Redis.

Как защищаться — по убыванию надёжности

1. Allowlist. В идеале сервис вообще не ходит по произвольным URL: есть список разрешённых хостов или заранее зарегистрированные интеграции, всё остальное отвергается. Только эта защита не проигрывает гонку с обходами.
2. Отдельный egress-прокси. Весь исходящий трафик сервиса идёт через прокси, у которого своя политика; сам под сидит в сетевой политике, запрещающей прямые соединения во внутренние подсети. Тогда даже ошибка в коде не даёт доступа.
3. Запрет приватных диапазонов на этапе соединения. Проверять надо не строку URL, а IP, к которому реально подключается сокет. Проверка «распарсили URL → отрезолвили → сравнили» уязвима к DNS rebinding: между проверкой и соединением DNS отдаёт другой адрес (TOCTOU). В Go это решает хук Control у диалера — его вызывают уже с готовым адресом, прямо перед connect.

// Диалер, который отказывается соединяться с приватными и служебными адресами.
// Control зовут после резолва и до connect: DNS rebinding не пройдёт.
var blocked = []netip.Prefix{
    netip.MustParsePrefix("0.0.0.0/8"),      netip.MustParsePrefix("10.0.0.0/8"),
    netip.MustParsePrefix("100.64.0.0/10"),  netip.MustParsePrefix("127.0.0.0/8"),
    netip.MustParsePrefix("169.254.0.0/16"), netip.MustParsePrefix("172.16.0.0/12"),
    netip.MustParsePrefix("192.168.0.0/16"), netip.MustParsePrefix("::1/128"),
    netip.MustParsePrefix("fc00::/7"),       netip.MustParsePrefix("fe80::/10"),
    netip.MustParsePrefix("::/128"),         // [::] ядро соединит с loopback
}

func safeControl(network, address string, _ syscall.RawConn) error {
    if network != "tcp4" && network != "tcp6" {
        return fmt.Errorf("ssrf: сеть %s запрещена", network)
    }
    host, _, err := net.SplitHostPort(address)
    if err != nil {
        return err
    }
    ip, err := netip.ParseAddr(host)
    if err != nil {
        return err
    }
    ip = ip.Unmap()                       // ::ffff:169.254.169.254 → 169.254.169.254
    ip = ip.WithZone("")                  // для fe80::1%lo0 Contains всегда false
    for _, p := range blocked {
        if p.Contains(ip) {
            return fmt.Errorf("ssrf: адрес %s запрещён", ip)
        }
    }
    return nil
}

var safeClient = &http.Client{
    Timeout: 5 * time.Second,
    Transport: &http.Transport{
        DialContext: (&net.Dialer{Timeout: 3 * time.Second, Control: safeControl}).DialContext,
    },
    // Редирект даёт новый URL, выбранный не нами: проверяем каждый прыжок.
    CheckRedirect: func(req *http.Request, via []*http.Request) error {
        if len(via) >= 3 {
            return errors.New("ssrf: слишком много редиректов")
        }
        return checkScheme(req.URL)       // только http/https, порт из разрешённых
    },
}

IDOR и broken access control — самая частая реальная дыра

В OWASP Top 10 первое место (A01) занимает не инъекция, а сломанный контроль доступа. Причина простая: инъекцию ловит линтер, и выглядит она везде одинаково, а «этот заказ принадлежит этому пользователю» остаётся бизнес-правилом. Его пишут руками в каждом обработчике, и достаточно один раз забыть.

Самый узнаваемый частный случай называется IDOR (Insecure Direct Object Reference): идентификатор объекта приходит из запроса и используется без проверки прав на этот конкретный объект.

// Уязвимо: middleware проверил, что пользователь аутентифицирован,
// но никто не проверил, что заказ принадлежит именно ему.
func (h *Handler) GetOrder(w http.ResponseWriter, r *http.Request) {
    id, _ := strconv.ParseInt(r.PathValue("id"), 10, 64)
    order, err := h.repo.GetByID(r.Context(), id)   // ← /v1/orders/1235 вместо 1234
    ...
}

// Правильно: владение проверяется в самом запросе, отдельную проверку
// легко забыть. Условие уезжает в WHERE.
func (h *Handler) GetOrder(w http.ResponseWriter, r *http.Request) {
    id, _ := strconv.ParseInt(r.PathValue("id"), 10, 64)
    uid := auth.UserID(r.Context())
    order, err := h.repo.GetForUser(r.Context(), id, uid)  // WHERE id=$1 AND user_id=$2
    if errors.Is(err, sql.ErrNoRows) {
        problem(w, http.StatusNotFound, "not_found", "Заказ не найден")
        return
    }
    ...
}

• Проверять владение в том же запросе к БД, а не отдельным if после чтения. Так забыть проверку структурно труднее, и гонок нет. Для сложных правил пишут явную функцию can(ctx, subject, action, object) и вызывают её в сервисном слое, где объект уже известен.
• Отдавать 404, а не 403, если даже факт существования объекта выдаёт информацию. 403 подтверждает, что заказ с таким id есть.
• Непредсказуемые идентификаторы смягчают риск, но не защищают. UUIDv4 вместо автоинкремента убирает тривиальный перебор, но id утекают в логи, в реферер, в шаринг ссылок. «Секретный URL» работает как контроль доступа только там, где так задумано (одноразовые ссылки с TTL).
• Массовые операции и вложенные ресурсы. PATCH /v1/orders со списком id, GET /v1/users/{uid}/orders/{oid}, экспорт в CSV, GraphQL-резолвер вложенного поля: здесь проверку владения забывают чаще всего, потому что она нужна для каждого элемента.
• Fail closed. По умолчанию роутер требует авторизацию, а публичные маршруты помечаются явно. Полезный тест: пройтись по всем зарегистрированным маршрутам и убедиться, что у каждого есть политика, иначе новый эндпоинт однажды приедет голым.
• Функциональный уровень. Во втором частом случае защищать надо не объект, а действие: /admin/* открыт без роли, потому что «ссылки на него нет в интерфейсе». Скрытая кнопка доступ не контролирует.

Mass assignment: почему входной JSON не биндят в доменную модель

Соблазн понятен: структура уже есть, теги json тоже, зачем писать вторую. Но json.NewDecoder(r.Body).Decode заполняет те поля, которые прислали, а прислать могут любые — включая те, о которых клиент знать не должен.

// Доменная модель, она же модель БД, она же тело запроса. Так делать нельзя.
type User struct {
    ID        int64  `json:"id"`
    Email     string `json:"email"`
    IsAdmin   bool   `json:"is_admin"`      // ← {"is_admin": true}
    Balance   int64  `json:"balance"`       // ← {"balance": 999999}
    CreatedAt time.Time `json:"created_at"`
}

func (h *Handler) UpdateProfile(w http.ResponseWriter, r *http.Request) {
    var u User
    json.NewDecoder(r.Body).Decode(&u)      // клиент задаёт любое поле
    h.repo.Update(r.Context(), &u)          // и оно уезжает в UPDATE
}

Правильно заводить отдельный тип на каждое направление: DTO запроса, доменная модель, DTO ответа. Это явное описание контракта, а не «лишний слой ради слоя»: какие поля клиент может задать и какие мы готовы показать.

// Клиенту разрешено прислать ровно два поля.
type updateProfileReq struct {
    DisplayName string `json:"display_name" validate:"required,min=1,max=64"`
    Bio         string `json:"bio"          validate:"max=500"`
}

func (h *Handler) UpdateProfile(w http.ResponseWriter, r *http.Request) {
    var req updateProfileReq
    dec := json.NewDecoder(http.MaxBytesReader(w, r.Body, 32<<10))
    dec.DisallowUnknownFields()                   // "is_admin" → явная ошибка 400
    if err := dec.Decode(&req); err != nil {
        problem(w, http.StatusBadRequest, "malformed_json", "Тело запроса неразборчиво")
        return
    }
    if err := h.validate.Struct(req); err != nil { ... }

    // Из DTO в домен поля переносим явно. Про забытое новое поле компилятор
    // не напомнит: это ловят тест или линтер exhaustruct.
    err := h.svc.UpdateProfile(r.Context(), auth.UserID(r.Context()),
        service.ProfilePatch{DisplayName: req.DisplayName, Bio: req.Bio})
    ...
}

CORS: что это на самом деле

Из всей секции CORS понимают хуже всего. Первым делом стоит сказать: CORS ослабляет Same-Origin Policy в браузере и сервер ни от чего не защищает. По умолчанию скрипт со страницы app.example.com не может прочитать ответ от api.example.com. Через CORS сервер говорит браузеру: «этому origin читать мой ответ можно». Запрещать CORS не умеет, только разрешать.

Simple request против preflight

Браузер сначала решает, «простой» ли запрос. Простой уходит сразу, а отдавать ли ответ скрипту, браузер решает уже потом. Перед непростым он шлёт отдельный запрос OPTIONS (preflight), и, если политика не подошла, настоящий запрос не уходит вовсе. На практике разница такая: preflight предотвращает побочный эффект, а simple его не останавливает.

Выходит, что почти любой современный JSON-API всегда идёт с preflight — Content-Type: application/json и заголовок Authorization выводят запрос из «простых». Поэтому HTML-форма не подделает JSON-запрос, если сервер строго проверяет Content-Type: форма с text/plain умеет прислать тело, похожее на JSON. А токен в заголовке не подвержен CSRF по другой причине: браузер не прикладывает его сам, как куку.

Заголовки: кто за что отвечает

Типичные ошибки настройки

• Allow-Origin: * вместе с Allow-Credentials: true. Спецификация это прямо запрещает, и браузер отклонит ответ. Логика простая: «любой сайт» плюс «с куками пользователя» дают произвольной странице право читать личные данные жертвы. Выход один: отдавать конкретный origin.
• Отражение Origin без проверки. Классическая «починка» предыдущего пункта: w.Header().Set("Access-Control-Allow-Origin", r.Header.Get("Origin")) плюс Allow-Credentials: true. По сути это тот же * с куками, только спецификацию удалось обмануть: любой сайт получает право читать ответы с сессией жертвы. Одна из самых частых находок на пентесте.
• Слабое сравнение origin. strings.HasPrefix(o, "https://example.com") пропускает https://example.com.evil.net, а strings.Contains(o, "example.com") пропустит ещё и https://evil-example.com. Сравнивать нужно полный origin, на точное совпадение с заранее заданным множеством.
• Забытый Vary: Origin. Если ответ кэшируется (CDN, обратный прокси, кэш браузера), без Vary ответ с Allow-Origin: https://a.example.com уйдёт клиенту с origin b.example.com — и наоборот. Смотря в какую сторону промахнулся кэш, получится либо неработающий фронт, либо утечка разрешения. Ставить его надо на всех ответах, где Allow-Origin вычисляется динамически.
• null в белом списке. Origin null присылают песочницы iframe sandbox, локальные файлы и некоторые редиректы, так что разрешить его значит впустить кого угодно.
• Preflight не доходит до обработчика. На OPTIONS нужно отвечать до аутентификации: браузер не прикладывает к нему ни кук, ни Authorization, поэтому auth-middleware вернёт 401, и весь запрос упадёт. Выглядит это как «CORS-ошибка, хотя всё настроено».
• CORS вместо авторизации. Для публичного API разрешить всё (* без credentials) совершенно нормально. Ошибка в другом: считать API «закрытым», раз в CORS перечислены только свои домены. См. первый пункт про curl.

// Аккуратный CORS-middleware: точное сравнение, Vary всегда, OPTIONS до auth.
func CORS(allowed map[string]bool) func(http.Handler) http.Handler {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            origin := r.Header.Get("Origin")
            // Vary ставим всегда, даже когда origin не разрешён и заголовков не будет:
            // иначе кэш смешает ответы для разных origin.
            w.Header().Add("Vary", "Origin")

            if origin != "" && allowed[origin] {
                w.Header().Set("Access-Control-Allow-Origin", origin) // конкретный, не *
                w.Header().Set("Access-Control-Allow-Credentials", "true")
                w.Header().Set("Access-Control-Expose-Headers",
                    "X-Request-Id, X-RateLimit-Remaining, Retry-After")
            }

            if r.Method == http.MethodOptions &&
                r.Header.Get("Access-Control-Request-Method") != "" {
                w.Header().Add("Vary", "Access-Control-Request-Method")
                w.Header().Add("Vary", "Access-Control-Request-Headers")
                if origin != "" && allowed[origin] {
                    w.Header().Set("Access-Control-Allow-Methods",
                        "GET, POST, PUT, PATCH, DELETE")
                    w.Header().Set("Access-Control-Allow-Headers",
                        "Authorization, Content-Type, X-Request-Id, Idempotency-Key")
                    w.Header().Set("Access-Control-Max-Age", "600")
                }
                w.WriteHeader(http.StatusNoContent) // отвечаем до auth-middleware
                return
            }
            next.ServeHTTP(w, r)
        })
    }
}

Rate limiting

У ограничения частоты несколько задач, и на собеседовании их полезно развести. Оно не даёт перебирать пароли и токены, мешает скрейпить и выкачивать базу, спасает от случайного DoS собственным клиентом с ретраями, честно делит ёмкость между тенантами и, наконец, бережёт деньги, если за нами платный внешний API. От «настоящего» DDoS на канал приложение не защитит — это уровень CDN и провайдера.

Все алгоритмы решают одно: пропустить запрос или отклонить. Различаются они на всплеске, и проще всего это увидеть, если прогнать через все четыре один и тот же трафик.

В двух из четырёх названий стоит слово bucket — «ведро». Это метафора счётчика, и она честная ровно до дна. Token bucket: в ведро фиксированной ёмкости с постоянной скоростью капают разрешения (их и называют «токенами», к токенам аутентификации из главы 10.3 они отношения не имеют). Каждый запрос забирает одно разрешение; ведро пусто — отказ. Пока клиент молчал, ведро наполнялось — отсюда и право на всплеск размером ровно в ёмкость ведра. Leaky bucket: тут ведро наполняют сами запросы, а вытекает оно с постоянной скоростью, поэтому на выходе трафик всегда идеально ровный; переполнилось ведро — отказ. Физически «ведро» хранится в Redis как два числа: сколько в нём сейчас и когда его трогали в прошлый раз.

Локальный лимитер: golang.org/x/time/rate

Готовый token bucket лежит в стандартном расширении. Конструктор rate.NewLimiter(r, b) принимает скорость долива и ёмкость, те самые две ручки из таблицы выше. Спросить его о решении можно тремя способами, и путать их не стоит:

// r — токенов в секунду, b — ёмкость ведра (максимальный всплеск).
lim := rate.NewLimiter(rate.Every(time.Second/10), 20)  // 10 rps, burst 20

lim.Allow()          // не ждать: true/false сразу, для HTTP-хендлера
lim.Wait(ctx)        // ждать токен до дедлайна ctx, для фонового воркера
lim.Reserve()        // забронировать и узнать, сколько ждать: r.Delay()

В HTTP почти всегда нужен Allow. Wait внутри хендлера копит ждущие горутины, а за ними и таймауты: вместо быстрого 429 клиент получает зависший запрос. Wait хорош там, где мы сами исходящая сторона, например когда обходим сторонний API с лимитом 100 rps.

// Лимитер на ключ с вытеснением: без уборки map растёт бесконечно, это утечка.
type Limiters struct {
    mu   sync.Mutex
    m    map[string]*entry
    r    rate.Limit
    b    int
}
type entry struct {
    lim  *rate.Limiter
    seen time.Time
}

func (l *Limiters) Get(key string) *rate.Limiter {
    l.mu.Lock()
    defer l.mu.Unlock()
    e, ok := l.m[key]
    if !ok {
        e = &entry{lim: rate.NewLimiter(l.r, l.b)}
        l.m[key] = e
    }
    e.seen = time.Now()
    return e.lim
}

// Отдельная горутина раз в минуту выкидывает ключи, не встречавшиеся 10 минут.
// Или LRU фиксированного размера: память под нагрузкой предсказуема.

func RateLimit(l *Limiters, keyOf func(*http.Request) string) func(http.Handler) http.Handler {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            if !l.Get(keyOf(r)).Allow() {
                w.Header().Set("Retry-After", "1")
                problem(w, http.StatusTooManyRequests, "rate_limited",
                    "Слишком много запросов, повторите позже")
                return
            }
            next.ServeHTTP(w, r)
        })
    }
}

Распределённый лимитер на Redis

Когда лимит должен быть общим для всех инстансов, состояние переезжает в общее хранилище. Redis тут хорош по двум причинам. Он быстрый, а лимитер стоит на горячем пути каждого запроса. И он однопоточный, поэтому Lua-скрипт выполняется атомарно — между чтением счётчика и его записью никакой другой под не вклинится.

// Token bucket в Redis: одно ведро на ключ, весь read-modify-write внутри Lua.
// KEYS[1] — ключ ведра.  ARGV: now_ms, rate (токенов в секунду), burst, cost.
var tokenBucket = redis.NewScript(`
local key   = KEYS[1]
local now   = tonumber(ARGV[1])
local rate  = tonumber(ARGV[2])
local burst = tonumber(ARGV[3])
local cost  = tonumber(ARGV[4])

local st     = redis.call('HMGET', key, 'tokens', 'ts')
local tokens = tonumber(st[1])
local ts     = tonumber(st[2])

if tokens == nil then          -- первое обращение: ведро полное
  tokens = burst
  ts     = now
end

-- долив за прошедшее время, с потолком в ёмкость ведра
local delta = math.max(0, now - ts) / 1000.0
tokens = math.min(burst, tokens + delta * rate)
ts     = now

local allowed = 0
local retry   = 0
if tokens >= cost then
  tokens  = tokens - cost
  allowed = 1
else
  -- сколько миллисекунд ждать, пока накапает недостающее
  retry = math.ceil(((cost - tokens) / rate) * 1000)
end

redis.call('HSET', key, 'tokens', tokens, 'ts', ts)
-- TTL с запасом на полное восстановление ведра: без него ключи копятся вечно
redis.call('PEXPIRE', key, math.ceil((burst / rate) * 1000) + 1000)

return { allowed, math.floor(tokens), retry }
`)

type Decision struct {
    Allowed   bool
    Remaining int
    RetryIn   time.Duration
}

func (l *RedisLimiter) Allow(ctx context.Context, key string, cost int) (Decision, error) {
    // Жёсткий таймаут: из-за лимитера запрос не должен упасть по таймауту.
    ctx, cancel := context.WithTimeout(ctx, 50*time.Millisecond)
    defer cancel()

    res, err := tokenBucket.Run(ctx, l.rdb, []string{"rl:tb:" + key},
        time.Now().UnixMilli(), l.rate, l.burst, cost).Int64Slice()
    if err != nil {
        // fail-open: лимитер сломался, а сервис продолжает работать.
        // Нужны метрика и алерт, иначе поломку никто не заметит.
        l.failures.Inc()
        return Decision{Allowed: true}, err
    }
    return Decision{
        Allowed:   res[0] == 1,
        Remaining: int(res[1]),
        RetryIn:   time.Duration(res[2]) * time.Millisecond,
    }, nil
}

Что отдавать клиенту

Отказ должен быть машиночитаемым, чтобы клиент понял, что делать дальше, не разбирая текст.

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 5                          # секунды либо HTTP-дата
RateLimit-Policy: "default";q=100;w=60  # черновик IETF: квота 100 на 60 секунд
RateLimit: "default";r=0;t=5            # осталось 0, окно освободится через 5 с
X-RateLimit-Limit: 100                  # де-факто стандарт, его понимают все SDK
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1756192846           # unix-время сброса

{"type":"https://api.example.com/errors/rate-limited",
 "title":"Слишком много запросов","status":429,
 "detail":"Лимит 100 запросов в минуту исчерпан","retry_after":5}

• Retry-After обязателен. Без него клиент начнёт ретраить сразу и сделает только хуже. Тот же заголовок уместен на 503 при перегрузке.
• Заголовки лимита отдавать и на успешных ответах, чтобы вежливый клиент притормозил до того, как упрётся. Не забыть добавить их в Access-Control-Expose-Headers, иначе браузерный SPA их не увидит.
• 429 против 503. 429 значит «конкретно ты превысил свою квоту», а 503 (в идеале с Retry-After) значит «плохо всему сервису». Смешивать их вредно: алерты на них настраивают по-разному, и клиенты реагируют по-разному.
• Лишнего о лимитах не раскрывать. Для анонимных запросов и для эндпоинта логина точные цифры «осталось 0 из 5» подсказывают перебиральщику ритм. Там достаточно 429 и Retry-After.
• Ответ 429 должен быть дешёвым. Ходить в БД, писать подробный лог на каждый отказ и рендерить тяжёлое тело незачем — иначе лимитер сам становится вектором DoS. Логировать лучше агрегатами, а метрику вести счётчиком с меткой причины.
• Со стороны клиента на 429 отвечают экспоненциальным backoff с джиттером, соблюдают Retry-After и ставят circuit breaker. Если вся армия клиентов ретраит без джиттера, получается синхронный «стук» ровно через N секунд.

Где ставить и по какому ключу считать

Правильный ответ: оба уровня. И это не компромисс, у уровней просто разные задачи: периметр отсекает объём и мусор, приложение следит за бизнес-квотами. На собеседовании хорошо звучит так: «грубый лимит — как можно раньше и как можно дешевле; точный лимит — там, где есть контекст».

// trustedProxies — сколько НАШИХ прокси стоит перед сервисом (обычно 1–2).
func clientIP(r *http.Request, trustedProxies int) netip.Addr {
    peer, _ := netip.ParseAddrPort(r.RemoteAddr)   // это подделать нельзя
    if trustedProxies == 0 {
        return peer.Addr()
    }
    // все строки заголовка: прокси может дописать свою отдельной строкой
    parts := strings.Split(strings.Join(r.Header.Values("X-Forwarded-For"), ","), ",")
    idx := len(parts) - trustedProxies             // отсчёт СПРАВА
    if idx < 0 || idx >= len(parts) {
        return peer.Addr()                         // список короче ожидаемого — не верим
    }
    ip, err := netip.ParseAddr(strings.TrimSpace(parts[idx]))
    if err != nil {
        return peer.Addr()
    }
    return ip.Unmap()
}
// Альтернатива, если инфраструктура позволяет: заголовок, который наш edge
// ПЕРЕЗАПИСЫВАЕТ (не дополняет) — CF-Connecting-IP, True-Client-IP,
// либо стандартный Forwarded из RFC 7239. Всё, что пришло снаружи, стирается.

Ретраи-дубли: идемпотентность и дедупликация

Эту задачу часто путают с rate limiting, хотя она отдельная. Rate limiting защищает от слишком многих запросов, идемпотентность — от повторов одного и того же. За повторами почти никогда не стоит злой умысел: оборвался ответ, клиент словил таймаут, сработал автоматический ретрай библиотеки, пользователь дважды нажал кнопку, брокер доставил сообщение at-least-once. Сам запрос при этом выполнился — потерялся только ответ.

Механику Idempotency-Key разбирали в главе 10.1, здесь посмотрим на неё со стороны безопасности и надёжности. Хватит трёх пунктов.

• Ключ занимают до внешнего эффекта. Строку в idempotency_keys с UNIQUE и статусом in_progress вставляют раньше, чем идут в платёжный шлюз. Тогда параллельный дубль упрётся в конфликт уникальности и вторую оплату не запустит. Порядок «сходили в банк → записали ключ» не спасает вообще: проблема живёт как раз между этими двумя шагами.
• Ключ привязан к субъекту и к телу. Уникальна пара (user_id, key), иначе через чужой ключ можно прочитать чужой сохранённый ответ. Плюс хеш тела: тот же ключ с другим телом означает ошибку клиента (422), старый ответ на него не отдают.
• Сохраняют сам ответ, одного факта мало. Повтор должен получить тот же статус и то же тело, что и оригинал, иначе клиент, потерявший первый ответ, так и не узнает результата.

Есть и второй, независимый механизм: дедупликация по естественному ключу. Она нужна там, где ключ идемпотентности прислать некому: входящие вебхуки, сообщения из брокера, импорт файлов. Логика та же, только идентификатор берут из полезной нагрузки.

// Вебхук от платёжной системы: доставка at-least-once, дубли неизбежны.
// Уникальный индекс делает вторую вставку конфликтом, а не вторым эффектом.
func (s *Service) HandleWebhook(ctx context.Context, ev Event) error {
    tx, err := s.db.BeginTx(ctx, nil)
    if err != nil { return err }
    defer tx.Rollback()

    // UNIQUE (provider, event_id)
    res, err := tx.ExecContext(ctx, `
        INSERT INTO processed_events (provider, event_id, received_at)
        VALUES ($1, $2, now())
        ON CONFLICT (provider, event_id) DO NOTHING`, ev.Provider, ev.ID)
    if err != nil { return err }

    if n, _ := res.RowsAffected(); n == 0 {
        return nil          // уже обработано: тихо отвечаем 200, иначе провайдер будет ретраить вечно
    }
    if err := s.apply(ctx, tx, ev); err != nil { return err }
    return tx.Commit()      // отметка и эффект коммитятся одной транзакцией
}

• Дедупликация и эффект живут в одной транзакции. Если отметить «обработано» в Redis, а потом упасть на записи в БД, событие потеряется навсегда. Проще всего сделать это корректно одной транзакцией БД; Redis годится как быстрый фильтр перед ней, но источником истины его делать нельзя.
• Проверять подпись вебхука (HMAC от тела с общим секретом, constant-time сравнение) и метку времени — иначе перехваченный когда-то запрос можно проиграть заново (replay). Подпись считают по сырому телу, до парсинга JSON: пересериализация меняет байты.
• TTL у таблицы дедупликации. Хранить ключи вечно нельзя, но окно должно с запасом перекрывать политику ретраев провайдера (Stripe, например, ретраит до трёх суток).
• Отвечать быстро. Обработку вебхука лучше свести к «проверил подпись → положил в очередь → 200». Если обрабатывать долго и синхронно, провайдер отвалится по таймауту и пришлёт ретрай, то есть медленный обработчик сам плодит дубли.

Валидация входных данных

Валидация не сводится к «проверить, что поле не пустое». Она явно описывает множество допустимых входов и стоит на границе системы. Всё, что не описано, отвергается, поэтому валидация, помимо удобства, ещё и защищает.

Где валидировать

• На границе, сразу после разбора запроса, проверяют синтаксис и формат: типы, диапазоны, длины, обязательность, регулярки. На ошибку отвечают 400 (тело неразборчиво) или 422 (разобрано, но не проходит правила).
• В домене живут бизнес-инварианты, которым нужен контекст: «дата окончания позже даты начала», «сумма не превышает остаток», «этот статус недостижим из текущего». Их место в сервисном слое, потому что они нужны любому вызывающему: HTTP, gRPC, CLI-команде, консьюмеру из брокера.
• В базе — последняя линия: NOT NULL, CHECK, UNIQUE, внешние ключи. Это единственный уровень, который переживёт баг в коде и ручной UPDATE из psql.
• На фронте проверяют только ради UX: это дублирование, защиты оно не даёт.

go-playground/validator и кастомные правила

type createOrderReq struct {
    Email    string    `json:"email"     validate:"required,email,max=254"`
    Currency string    `json:"currency"  validate:"required,iso4217"`
    Amount   int64     `json:"amount"    validate:"required,gt=0,lte=100000000"`
    Comment  string    `json:"comment"   validate:"max=500"`
    DeliverAt time.Time `json:"deliver_at" validate:"required,gt"`   // gt без числа у времени: позже now
    Items    []item    `json:"items"     validate:"required,min=1,max=100,dive"`
    Phone    string    `json:"phone"     validate:"omitempty,e164"`
}

// Валидатор создаётся один раз: он кэширует разбор тегов через reflect,
// а пересоздание на каждый запрос заметно бьёт по производительности.
var validate = func() *validator.Validate {
    v := validator.New(validator.WithRequiredStructEnabled())

    // Имена полей в ошибках берём из json-тегов, чтобы наружу уезжал
    // контракт API, а не имена полей Go.
    v.RegisterTagNameFunc(func(f reflect.StructField) string {
        name := strings.SplitN(f.Tag.Get("json"), ",", 2)[0]
        if name == "-" { return "" }
        return name
    })

    // Кастомное правило: слаг статьи.
    var slugRe = regexp.MustCompile(`^[a-z0-9]+(?:-[a-z0-9]+)*$`)
    v.RegisterValidation("slug", func(fl validator.FieldLevel) bool {
        s := fl.Field().String()
        return len(s) <= 80 && slugRe.MatchString(s)
    })

    // Правило уровня структуры: когда одно поле зависит от другого.
    v.RegisterStructValidation(func(sl validator.StructLevel) {
        r := sl.Current().Interface().(createOrderReq)
        if r.Currency == "RUB" && r.Amount < 100 {
            sl.ReportError(r.Amount, "amount", "Amount", "min_rub", "")
        }
    }, createOrderReq{})
    return v
}()

Ошибки валидатора нельзя отдавать наружу как есть: текст Key: 'createOrderReq.amount' Error:Field validation for 'amount' failed on the 'gt' tag раскрывает внутренние имена и нечитаем для клиента. Их превращают в структуру «поле → код ошибки», совместимую с общим форматом ошибок из главы 10.1.

func validationProblem(err error) *Problem {
    var ve validator.ValidationErrors
    if !errors.As(err, &ve) {
        return &Problem{Status: 400, Code: "bad_request", Title: "Некорректный запрос"}
    }
    p := &Problem{Status: 422, Code: "validation_failed", Title: "Проверьте поля формы"}
    for _, fe := range ve {
        p.Errors = append(p.Errors, FieldError{
            Field: fe.Field(),   // "amount" благодаря RegisterTagNameFunc
            Code:  fe.Tag(),     // "gt", "required", "email" — машиночитаемо
            // Текст для человека собираем сами; сообщение библиотеки наружу не отдаём.
            Message: humanize(fe),
        })
    }
    return p
}

HTTPS everywhere и security-заголовки

Базовая гигиена, про неё спрашивают под конец секции. TLS обязателен везде, включая внутренние вызовы: сеть внутри периметра прослушивается ровно так же, а модель «мягкая внутри, твёрдая снаружи» разваливается от одной скомпрометированной машины. Минимум на практике: TLS 1.2+ (лучше 1.3), автоматические сертификаты, редирект 80 → 443. Межсервисный трафик закрывают mTLS, обычно через service mesh, чтобы не ротировать сертификаты руками.

func SecurityHeaders(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        h := w.Header()
        // HSTS имеет смысл только на HTTPS-ответе: по http браузер его игнорирует,
        // а на localhost он ещё и мешает разработке.
        if r.TLS != nil {
            h.Set("Strict-Transport-Security", "max-age=31536000; includeSubDomains")
        }
        h.Set("X-Content-Type-Options", "nosniff")
        h.Set("X-Frame-Options", "DENY")
        h.Set("Referrer-Policy", "strict-origin-when-cross-origin")
        h.Set("Content-Security-Policy", "default-src 'none'; frame-ancestors 'none'")
        h.Set("Cache-Control", "no-store")
        // Server и X-Powered-By net/http сам не ставит. А Del тут не помог бы:
        // он выполняется раньше хендлера, который мог их выставить.
        next.ServeHTTP(w, r)
    })
}

q := "SELECT id, email FROM users WHERE id = " + raw   // raw = "1 OR 1=1 --"
row := db.QueryRowContext(ctx, q)

row := db.QueryRowContext(ctx, "SELECT id, email FROM users WHERE id = $1", raw)

var sortable = map[string]string{"created_at": "p.created_at", "views": "p.views_count"}
col, ok := sortable[q.Get("sort")]      // неизвестный ключ → 400, а не склейка
dir := "ASC"; if strings.EqualFold(q.Get("order"), "desc") { dir = "DESC" }

cop := http.NewCrossOriginProtection()
_ = cop.AddTrustedOrigin("https://admin.example.com") // честный фронт на другом origin
cop.AddInsecureBypassPattern("/webhooks/")            // ручки, куда браузер не ходит
srv := &http.Server{Handler: cop.Handler(mux)}        // всё, защита включена

var safeClient = &http.Client{
    Timeout: 5 * time.Second,
    Transport: &http.Transport{
        DialContext: (&net.Dialer{Control: safeControl}).DialContext, // блокирует 10/8, 127/8, 169.254/16, fc00::/7 …
    },
    CheckRedirect: func(r *http.Request, via []*http.Request) error {
        if len(via) >= 3 { return errors.New("too many redirects") }
        return checkScheme(r.URL)   // за редиректом новый адрес, проверяем каждый прыжок
    },
}

// Middleware проверил, что пользователь аутентифицирован.
// Что заказ его, не проверил никто. /v1/orders/1235 вместо 1234.
order, err := repo.GetByID(ctx, id)

// Правильно: владение уезжает в WHERE и его нельзя «забыть проверить».
order, err := repo.GetForUser(ctx, id, auth.UserID(ctx))   // WHERE id=$1 AND user_id=$2

type User struct {
    ID int64 `json:"id"`; Email string `json:"email"`
    IsAdmin bool `json:"is_admin"`; Balance int64 `json:"balance"`
}
var u User
json.NewDecoder(r.Body).Decode(&u)   // {"is_admin": true, "balance": 999999}
repo.Update(ctx, &u)                 // и это уезжает в UPDATE

type updateProfileReq struct {          // ровно то, что клиенту разрешено прислать
    DisplayName string `json:"display_name" validate:"required,max=64"`
    Bio         string `json:"bio"          validate:"max=500"`
}
dec := json.NewDecoder(http.MaxBytesReader(w, r.Body, 32<<10))
dec.DisallowUnknownFields()
// … и перенос в домен поле за полем (забытое новое поле ловят тест или exhaustruct)

→ OPTIONS /v1/orders/42
  Origin: https://app.example.com
  Access-Control-Request-Method: DELETE
  Access-Control-Request-Headers: authorization, content-type

← 204 No Content
  Access-Control-Allow-Origin: https://app.example.com
  Access-Control-Allow-Methods: GET, POST, DELETE
  Access-Control-Allow-Headers: authorization, content-type
  Access-Control-Allow-Credentials: true
  Access-Control-Max-Age: 600
  Vary: Origin

→ DELETE /v1/orders/42          # только теперь уходит боевой запрос
← 200 OK + Access-Control-Allow-Origin  # заголовок обязателен и здесь

lim := rate.NewLimiter(rate.Every(time.Second/10), 20) // 10 rps, burst 20 — это token bucket
lim.Allow()     // не ждать: для HTTP-хендлера
lim.Wait(ctx)   // ждать токен: для исходящих вызовов и фоновых воркеров
lim.Reserve()   // забронировать и узнать задержку

// Token bucket целиком внутри одного атомарного вызова.
var tokenBucket = redis.NewScript(`
local st     = redis.call('HMGET', KEYS[1], 'tokens', 'ts')
local tokens = tonumber(st[1]); local ts = tonumber(st[2])
local now, rate, burst, cost = tonumber(ARGV[1]), tonumber(ARGV[2]), tonumber(ARGV[3]), tonumber(ARGV[4])
if tokens == nil then tokens = burst; ts = now end
tokens = math.min(burst, tokens + math.max(0, now - ts) / 1000.0 * rate)
local allowed, retry = 0, 0
if tokens >= cost then tokens = tokens - cost; allowed = 1
else retry = math.ceil(((cost - tokens) / rate) * 1000) end
redis.call('HSET', KEYS[1], 'tokens', tokens, 'ts', now)
redis.call('PEXPIRE', KEYS[1], math.ceil((burst / rate) * 1000) + 1000)
return { allowed, math.floor(tokens), retry }
`)

// Доверяем ровно тому числу своих прокси, которое реально стоит перед сервисом,
// и отсчитываем справа налево. r.RemoteAddr подделать нельзя.
idx := len(parts) - trustedProxies
if idx < 0 || idx >= len(parts) { return peerAddr }   // список короче ожидаемого, не верим

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 5                      # желателен: секунды или HTTP-дата
X-RateLimit-Limit: 100              # де-факто стандарт, понимают все SDK
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1756192846       # unix-время сброса
RateLimit-Policy: "default";q=100;w=60   # черновик IETF, постепенно вытесняет X-
RateLimit: "default";r=0;t=5

{"type":"…/errors/rate-limited","title":"Слишком много запросов",
 "status":429,"detail":"Лимит 100 запросов в минуту исчерпан","retry_after":5}

// UNIQUE (provider, event_id): вторая вставка становится конфликтом, а не вторым эффектом.
res, err := tx.ExecContext(ctx, `INSERT INTO processed_events (provider, event_id)
    VALUES ($1,$2) ON CONFLICT DO NOTHING`, ev.Provider, ev.ID)
if err != nil {
    return err            // без проверки res == nil, и RowsAffected ниже упадёт
}
if n, _ := res.RowsAffected(); n == 0 {
    return nil            // уже обработано → тихий 200, иначе провайдер будет ретраить вечно
}
if err := apply(ctx, tx, ev); err != nil { return err }
return tx.Commit()        // отметка и эффект коммитятся одной транзакцией

Amount int64 `json:"amount" validate:"required,gt=0,lte=100000000"`
Items  []item `json:"items"  validate:"required,min=1,max=100,dive"`

v.RegisterTagNameFunc(...)        // имена полей в ошибках — из json-тегов, а не из Go
v.RegisterValidation("slug", ...) // своё правило на поле
v.RegisterStructValidation(...)   // правило, где одно поле зависит от другого