10.2HTTP-сервер в Go

Проследи, как net/http принимает соединение, вызывает handler и удерживает ресурсы на время запроса. Настрой таймауты по фазам, размер тела и shutdown так, чтобы медленный клиент или SIGTERM не оставляли процесс без контроля.

Путь запроса: от 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()
}

Что стоит запомнить

• ReadHeaderTimeout защищает приём заголовков; ReadTimeout, WriteTimeout и IdleTimeout относятся к другим фазам соединения.
• Response body клиента нужно закрыть, чтобы transport мог вернуть соединение в пул; для reuse его обычно дочитывают в ограниченном объёме.
• Shutdown прекращает принимать новые соединения и ждёт активные handlers до заданного контекста.

Частые ошибки

• Не полагайся на дефолты http.Client/http.Server для production latency и защиты ресурсов.
• Не пиши 500 после того, как заголовки уже ушли клиенту; в этот момент остаётся логирование/закрытие.
• Не делай shutdown timeout неограниченным: он должен укладываться в termination grace period.

srv := &http.Server{
    ReadHeaderTimeout: 5 * time.Second,
    ReadTimeout: 15 * time.Second,
    WriteTimeout: 20 * time.Second,
    IdleTimeout: 90 * time.Second,
    MaxHeaderBytes: 1 << 20,
}

resp, err := client.Do(req)
if err != nil { return err }
if resp.StatusCode != http.StatusOK { return fmt.Errorf("upstream: %s", resp.Status) }
return json.NewDecoder(resp.Body).Decode(&out)