Часть 7. BackendУрок 18# go# backend# http# api

Backend — HTTP-сервер

net/http, роутинг, слои, JSON, middleware, тесты, graceful shutdown

Цели главы

  • Поднять HTTP-сервер и зарегистрировать эндпоинты с методами и параметрами пути.
  • Разделить приложение на слои и написать хендлер как структуру с зависимостью.
  • Читать из запроса путь, query, заголовки и JSON; отвечать JSON с правильным статусом.
  • Писать и упорядочивать middleware.
  • Тестировать хендлеры без сервера и корректно останавливать сервер.

Сеть без лишней теории

Гошный код написан, где-то есть фронтенд с кнопками и формами — как они общаются? Данные нужно передавать эффективно и надёжно, и об этом глава. Теории сетей, которую спрашивают на собеседованиях (модель OSI и прочее), здесь нет — только то, как работать с сетью именно в Go. Путь такой: простейший сервер → хендлеры и эндпоинты → структура сервиса, принятая в крупных компаниях.

net/http и роутеры

В Java для веб-сервиса нужен Spring, в Python — Django или Flask: отдельная большая библиотека поверх языка. В Go стандартная net/http настолько мощная, что сервисы иногда пишут только на ней. Фреймворки всё равно популярны:

Библиотека Что это
chi лёгкая обёртка над стандартной библиотекой; встречается в проектах чаще всего
gin самый популярный по звёздам на GitHub, полноценный фреймворк
echo, beego ещё два известных фреймворка
fiber один из самых быстрых по бенчмаркам, вдохновлён Express из мира JS

В Go даже говорят чаще не «фреймворк», а роутер (router): он направляет запросы по путям. Фреймворк — полный набор: роутер плюс работа с JSON, middleware и своя организация кода. Дальше — только net/http: разобравшись в нём, любой фреймворк выучишь за день — отличаться будет лишь синтаксис.

Первый сервер

go
package main

import (
    "fmt"
    "log"
    "net/http"
)

func main() {
    http.HandleFunc("/hello", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintln(w, "Hello, World!")
    })
    log.Println("сервер слушает :8080")
    log.Fatal(http.ListenAndServe(":8080", nil))
    // сервер: только сборка
}
bash
go run .
curl localhost:8080/hello
  • HandleFunc (handle — обрабатывать) связывает путь с функцией-обработчиком. Сигнатуру обработчика нужно запомнить: func(w http.ResponseWriter, r *http.Request).
  • Мнемоника: w — writer, сюда пишем ответ; r — запрос, его читаем.
  • ListenAndServe (serve — обслуживать) запускает сервер на порту 8080.

Эндпоинты, ServeMux и версии API

Эндпоинт (endpoint, на сленге — «ручка») — метод плюс путь: точка входа в сервер. Через одни ручки получают данные, через другие создают, меняют, удаляют. Ручки одной сущности группируют под общим путём:

Ручка Что делает
POST /api/v1/users создать пользователя
GET /api/v1/users список пользователей
GET /api/v1/users/{id} один пользователь
DELETE /api/v1/users/{id} удалить пользователя

ServeMux — мультиплексор: множество маршрутов сводится в один обработчик, который раздаёт запросы нужным функциям. Если в ListenAndServe передать nil, используется глобальный http.DefaultServeMux; в реальном коде создают свой через http.NewServeMux().

С Go 1.22 в шаблоне маршрута можно указать метод и параметры пути. Раньше приходилось делать один обработчик на все методы и внутри писать switch r.Method — отчасти поэтому и были популярны фреймворки.

go
package main

import (
    "fmt"
    "net/http"
    "net/http/httptest"
    "strings"
)

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("GET /api/v1/movies/{id}", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintf(w, "фильм %s", r.PathValue("id")) // параметр пути
    })
    mux.HandleFunc("GET /api/v1/movies", func(w http.ResponseWriter, r *http.Request) {
        q := r.URL.Query() // параметры после ?
        fmt.Fprintf(w, "список: limit=%s offset=%s", q.Get("limit"), q.Get("offset"))
    })
    mux.HandleFunc("DELETE /api/v1/movies/{id}", func(w http.ResponseWriter, r *http.Request) {
        w.WriteHeader(http.StatusNoContent)
    })

    for _, req := range []*http.Request{
        httptest.NewRequest("GET", "/api/v1/movies/42", nil),
        httptest.NewRequest("GET", "/api/v1/movies?limit=10&offset=20", nil),
        httptest.NewRequest("DELETE", "/api/v1/movies/42", nil),
        httptest.NewRequest("POST", "/api/v1/movies/42", nil),
    } {
        rec := httptest.NewRecorder()
        mux.ServeHTTP(rec, req)
        fmt.Printf("%s %s → %d %s\n", req.Method, req.URL, rec.Code, strings.TrimSpace(rec.Body.String()))
    }
}
stdout // вывод программы
GET /api/v1/movies/42 → 200 фильм 42
GET /api/v1/movies?limit=10&offset=20 → 200 список: limit=10 offset=20
DELETE /api/v1/movies/42 → 204
POST /api/v1/movies/42 → 405 Method Not Allowed

Запросы здесь отправлены без настоящей сети, через httptest — подробнее в разделе о тестах ниже. На POST по пути, где есть только GET и DELETE, ServeMux сам ответил 405 Method Not Allowed.

Версия в пути (/api/v1) нужна, когда контракт API меняется. Одни клиенты продолжают работать с первой версией, другие переходят на /api/v2 с новыми ручками и параметрами. У многих продуктов есть только v1 — и второй может не появиться никогда, но префикс закладывают сразу.

Слои приложения

Код растёт — его делят на части с узкой зоной ответственности.

HTTP-запросhandlerразбор и проверка запроса, ответ клиентуserviceбизнес-логикаrepositoryработа с базой данныхPostgreSQL
  • Handler (handle — глагол, handler — существительное) — сущность, которая обрабатывает запросы: читает и проверяет данные, преобразует их, вызывает следующий слой и формирует ответ.
  • Service — бизнес-логика: то, что хочет бизнес. Например, выдать пользователю Premium — это не работа хендлера.
  • Repository — работа с базой данных: сохранить, найти, удалить.

Зачем делить? Чтобы одну часть можно было заменить, не задевая остальные: перейти с PostgreSQL на другую базу или принимать данные не по HTTP, а из очереди. Если бизнес-логики почти нет — данные пришли, и их надо просто сохранить, — сервисный слой опускают, и хендлер работает с репозиторием напрямую. Так дальше и сделаем.

Хендлер как структура

Хендлер оформляют структурой с зависимостями. Репозиторий передают через конструктор и описывают интерфейсом: хендлеру всё равно, что за ним — PostgreSQL, память или заглушка в тесте (16 — Интерфейсы → Дженерики, идиома «принимай интерфейсы»). Метод Routes регистрирует ручки в мультиплексоре.

go
package main

import (
    "encoding/json"
    "errors"
    "fmt"
    "net/http"
    "net/http/httptest"
    "strconv"
    "strings"
    "sync"
)

var ErrNotFound = errors.New("not found")

type User struct {
    ID    int64  `json:"id"`
    Name  string `json:"name"`
    Email string `json:"email"`
}

// UserRepository — то, что хендлеру нужно от хранилища.
type UserRepository interface {
    Create(name, email string) (User, error)
    GetByID(id int64) (User, error)
}

// MemoryRepo — хранилище в памяти; в главе 19 его заменит PostgreSQL.
type MemoryRepo struct {
    mu     sync.Mutex
    nextID int64
    users  map[int64]User
}

func NewMemoryRepo() *MemoryRepo {
    return &MemoryRepo{users: make(map[int64]User)}
}

func (r *MemoryRepo) Create(name, email string) (User, error) {
    r.mu.Lock()
    defer r.mu.Unlock()
    r.nextID++
    u := User{ID: r.nextID, Name: name, Email: email}
    r.users[u.ID] = u
    return u, nil
}

func (r *MemoryRepo) GetByID(id int64) (User, error) {
    r.mu.Lock()
    defer r.mu.Unlock()
    u, ok := r.users[id]
    if !ok {
        return User{}, ErrNotFound
    }
    return u, nil
}

type UserHandler struct {
    repo UserRepository
}

func NewUserHandler(repo UserRepository) *UserHandler {
    return &UserHandler{repo: repo}
}

func (h *UserHandler) Routes(mux *http.ServeMux) {
    mux.HandleFunc("POST /api/v1/users", h.CreateUser)
    mux.HandleFunc("GET /api/v1/users/{id}", h.GetUser)
}

type CreateUserRequest struct {
    Name  string `json:"name"`
    Email string `json:"email"`
}

func (h *UserHandler) CreateUser(w http.ResponseWriter, r *http.Request) {
    var req CreateUserRequest
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
        writeError(w, http.StatusBadRequest, "invalid request body")
        return
    }
    if req.Name == "" || !strings.Contains(req.Email, "@") {
        writeError(w, http.StatusBadRequest, "name and valid email are required")
        return
    }
    user, err := h.repo.Create(req.Name, req.Email)
    if err != nil {
        writeError(w, http.StatusInternalServerError, "internal error")
        return
    }
    writeJSON(w, http.StatusCreated, user)
}

func (h *UserHandler) GetUser(w http.ResponseWriter, r *http.Request) {
    id, err := strconv.ParseInt(r.PathValue("id"), 10, 64)
    if err != nil {
        writeError(w, http.StatusBadRequest, "id must be a number")
        return
    }
    user, err := h.repo.GetByID(id)
    if errors.Is(err, ErrNotFound) {
        writeError(w, http.StatusNotFound, "user not found")
        return
    }
    if err != nil {
        writeError(w, http.StatusInternalServerError, "internal error")
        return
    }
    writeJSON(w, http.StatusOK, user)
}

func writeJSON(w http.ResponseWriter, status int, data any) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(status)           // сначала статус...
    json.NewEncoder(w).Encode(data) // ...потом тело
}

func writeError(w http.ResponseWriter, status int, message string) {
    writeJSON(w, status, map[string]string{"error": message})
}

func main() {
    mux := http.NewServeMux()
    NewUserHandler(NewMemoryRepo()).Routes(mux)

    send := func(method, target, body string) {
        req := httptest.NewRequest(method, target, strings.NewReader(body))
        rec := httptest.NewRecorder()
        mux.ServeHTTP(rec, req)
        fmt.Printf("%s %s → %d %s", method, target, rec.Code, rec.Body.String())
    }
    send("POST", "/api/v1/users", `{"name":"Алексей","email":"alex@goflix.ru"}`)
    send("POST", "/api/v1/users", `{"name":`)
    send("GET", "/api/v1/users/1", "")
    send("GET", "/api/v1/users/99", "")
    send("GET", "/api/v1/users/abc", "")
}
stdout // вывод программы
POST /api/v1/users → 201 {"id":1,"name":"Алексей","email":"alex@goflix.ru"}
POST /api/v1/users → 400 {"error":"invalid request body"}
GET /api/v1/users/1 → 200 {"id":1,"name":"Алексей","email":"alex@goflix.ru"}
GET /api/v1/users/99 → 404 {"error":"user not found"}
GET /api/v1/users/abc → 400 {"error":"id must be a number"}

Что можно прочитать из запроса

Откуда Как прочитать Пример
Параметр пути r.PathValue("id") /api/v1/users/{id}
Query-параметры r.URL.Query().Get("limit") ?limit=10&offset=20 — сколько записей отдать и с какой начать
Заголовок r.Header.Get("Authorization") токен, чтобы понять, что пользователю можно
Тело (JSON) json.NewDecoder(r.Body).Decode(&req) {"name": "…", "email": "…"}

Тело читают в структуру-запрос (CreateUserRequest) с JSON-тегами (15 — Структуры → Теги), а дальше передают поля в репозиторий.

Ответ: статус до тела

Ответ формирует ResponseWriter:

  1. w.Header().Set("Content-Type", "application/json") — говорим, что отдаём JSON, а не форму или картинку.
  2. w.WriteHeader(status) — код ответа: 200 OK, 201 Created, 400 Bad Request, 404 Not Found, 500 Internal Server Error.
  3. Тело — json.NewEncoder(w).Encode(data).

Чтобы не дублировать эти три строки в каждом хендлере, их выносят в writeJSON и writeError, как в примере выше. Заодно формат ответов становится единым: ошибка всегда приходит как {"error": "…"}.

Валидация

Полученные данные проверяют: имя — от 3 до 100 символов, почта — в формате почты, возраст — в разумных пределах. Удобно описывать правила тегами validate и проверять библиотекой go-playground/validator. Чтобы не повторять вызов в каждом хендлере, на проектах пишут небольшую обёртку.

go
package main

import (
    "fmt"

    "github.com/go-playground/validator/v10"
)

type CreateUserRequest struct {
    Name  string `json:"name" validate:"required,min=3,max=100"`
    Email string `json:"email" validate:"required,email"`
    Age   int    `json:"age,omitempty" validate:"omitempty,min=0,max=150"`
}

func main() {
    validate := validator.New()
    fmt.Println(validate.Struct(CreateUserRequest{Name: "Al", Email: "не-почта"}))
    fmt.Println(validate.Struct(CreateUserRequest{Name: "Алексей", Email: "alex@goflix.ru"}))
}
stdout // вывод программы
Key: 'CreateUserRequest.Name' Error:Field validation for 'Name' failed on the 'min' tag
Key: 'CreateUserRequest.Email' Error:Field validation for 'Email' failed on the 'email' tag
<nil>

Контракт API: OpenAPI и API-first

Структура User с тремя полями — простой случай. В реальности проектировать контракт — какими данными обмениваются клиент и сервер — бывает очень сложно. Контракт описывают OpenAPI-спецификацией в формате YAML: ручки, параметры, их типы и форматы, схемы объектов.

yaml
openapi: 3.0.3
info:
  title: GoFlix API
  version: 1.0.0
paths:
  /api/v1/users/{id}:
    get:
      summary: Получить пользователя
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Пользователь найден
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "404":
          description: Пользователь не найден
components:
  schemas:
    User:
      type: object
      required: [id, name, email]
      properties:
        id: { type: integer }
        name: { type: string }
        email: { type: string, format: email }

Подход API-first: сначала пишут спецификацию, а Go-код хендлеров и моделей генерируют из неё инструментами. Код гарантированно соответствует контракту, а разработчик не пишет boilerplate — повторяющийся шаблонный код — и занимается бизнес-логикой.

Middleware

Некоторые действия нужны в каждом хендлере: залогировать запрос и его длительность, проставить request ID для трейсинга, перехватить панику, проверить CORS. Их выносят в middleware — промежуточные слои. Ограничение одно: middleware принимает обработчик и возвращает обработчик — func(http.Handler) http.Handler. Слои вкладываются друг в друга, и при вызове хендлера запрос проходит через все.

  • Logging — метод, путь и сколько заняла обработка.
  • Request ID — берёт ID запроса из заголовка X-Request-Id или создаёт новый, возвращает его в ответе и кладёт в context. Трейсинг — когда запрос проходит через много сервисов, по ID его путь можно проследить при отладке.
  • Recovery — самый важный: одна паника в хендлере не должна ронять сервис. Да, в Kubernetes под перезапустится за пару секунд, но зачем, если можно перехватить панику (14 — defer, panic, recover) и ответить 500.
  • CORS — сервер разрешает запросы браузера только с определённых адресов, методов и заголовков.
go
package main

import (
    "context"
    "fmt"
    "log"
    "net/http"
    "net/http/httptest"
    "os"
    "time"
)

type Middleware func(http.Handler) http.Handler

type ctxKey string // свой тип ключа: не пересечётся с ключами других пакетов

const requestIDKey ctxKey = "request_id"

var logger = log.New(os.Stdout, "", 0) // без даты — чтобы вывод был стабильным

func LoggingMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        start := time.Now()
        id, _ := r.Context().Value(requestIDKey).(string)
        logger.Printf("→ %s %s [%s]", r.Method, r.URL.Path, id)
        next.ServeHTTP(w, r)
        logger.Printf("← %s %s за %v", r.Method, r.URL.Path, time.Since(start).Round(time.Second))
    })
}

func RequestIDMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        id := r.Header.Get("X-Request-Id")
        if id == "" {
            id = "req-generated" // в реальности — UUID
        }
        w.Header().Set("X-Request-Id", id)
        ctx := context.WithValue(r.Context(), requestIDKey, id)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

func RecoveryMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        defer func() {
            if rec := recover(); rec != nil {
                logger.Printf("panic recovered: %v", rec)
                w.Header().Set("Content-Type", "application/json")
                w.WriteHeader(http.StatusInternalServerError)
                fmt.Fprintln(w, `{"error":"internal server error"}`)
            }
        }()
        next.ServeHTTP(w, r)
    })
}

func CORSMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        w.Header().Set("Access-Control-Allow-Origin", "https://goflix.ru")
        w.Header().Set("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS")
        w.Header().Set("Access-Control-Allow-Headers", "Content-Type, Authorization, X-Request-Id")
        if r.Method == http.MethodOptions {
            w.WriteHeader(http.StatusNoContent) // preflight-запрос браузера
            return
        }
        next.ServeHTTP(w, r)
    })
}

// Chain оборачивает h так, что первый middleware в списке — самый внешний.
func Chain(h http.Handler, middlewares ...Middleware) http.Handler {
    for i := len(middlewares) - 1; i >= 0; i-- {
        h = middlewares[i](h)
    }
    return h
}

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("GET /movies", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintln(w, "Дюна, Матрица")
    })
    mux.HandleFunc("GET /panic", func(w http.ResponseWriter, r *http.Request) {
        panic("внутренний баг")
    })

    handler := Chain(mux, RecoveryMiddleware, CORSMiddleware, RequestIDMiddleware, LoggingMiddleware)

    for _, path := range []string{"/movies", "/panic"} {
        req := httptest.NewRequest("GET", path, nil)
        req.Header.Set("X-Request-Id", "abc-123")
        rec := httptest.NewRecorder()
        handler.ServeHTTP(rec, req)
        fmt.Printf("%s → %d %s", path, rec.Code, rec.Body.String())
    }
}
stdout // вывод программы
→ GET /movies [abc-123]
← GET /movies за 0s
/movies → 200 Дюна, Матрица
→ GET /panic [abc-123]
panic recovered: внутренний баг
/panic → 500 {"error":"internal server error"}

Порядок слоёв важен. Chain вызывает middleware от последнего к первому, поэтому первый в списке оказывается самым внешним: запрос проходит Recovery → CORS → RequestID → Logging → хендлер. Logging стоит после RequestID, чтобы в логе уже был ID запроса.

Часто пишут и свои middleware: авторизацию через SSO, проверку прав для всех ручек с префиксом /admin и так далее. Главное — понимать механизм, реализаций много.

Тестирование хендлеров

Чтобы протестировать хендлер, сервер поднимать не нужно. Пакет net/http/httptest даёт:

  • httptest.NewRequest(method, url, body) — конструктор тестового *http.Request;
  • httptest.NewRecorder() — подменный ResponseWriter, который просто запоминает статус, заголовки и тело.

Хендлер вызывается как обычная функция — без портов и Listen. А раз хендлер зависит от интерфейса репозитория, в тесте вместо базы подставляют заглушку (мок) с заранее заданными данными.

go
// user_handler_test.go — лежит рядом с кодом UserHandler из примера выше
package main

import (
    "net/http"
    "net/http/httptest"
    "strings"
    "testing"
)

type stubRepo struct {
    users map[int64]User
}

func (s stubRepo) Create(name, email string) (User, error) { return User{}, nil }

func (s stubRepo) GetByID(id int64) (User, error) {
    u, ok := s.users[id]
    if !ok {
        return User{}, ErrNotFound
    }
    return u, nil
}

func TestGetUser(t *testing.T) {
    mux := http.NewServeMux()
    NewUserHandler(stubRepo{users: map[int64]User{1: {ID: 1, Name: "Алексей"}}}).Routes(mux)

    tests := []struct {
        name     string
        path     string
        wantCode int
        wantBody string
    }{
        {"существующий", "/api/v1/users/1", http.StatusOK, `"name":"Алексей"`},
        {"нет такого", "/api/v1/users/2", http.StatusNotFound, "user not found"},
        {"кривой id", "/api/v1/users/abc", http.StatusBadRequest, "id must be a number"},
    }
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            rec := httptest.NewRecorder()
            mux.ServeHTTP(rec, httptest.NewRequest("GET", tt.path, nil))
            if rec.Code != tt.wantCode {
                t.Fatalf("код %d, ждали %d", rec.Code, tt.wantCode)
            }
            if !strings.Contains(rec.Body.String(), tt.wantBody) {
                t.Fatalf("тело %q не содержит %q", rec.Body.String(), tt.wantBody)
            }
        })
    }
}
bash
go test -race -v ./...
text
=== RUN   TestGetUser
=== RUN   TestGetUser/существующий
=== RUN   TestGetUser/нет_такого
=== RUN   TestGetUser/кривой_id
--- PASS: TestGetUser (0.00s)
    --- PASS: TestGetUser/существующий (0.00s)
    --- PASS: TestGetUser/нет_такого (0.00s)
    --- PASS: TestGetUser/кривой_id (0.00s)
PASS

Это табличный тест из 15 — Структуры → Анонимные структуры: каждый случай — строка в слайсе, t.Run запускает его как отдельный подтест. Проверяем статус и что тело содержит нужные поля.

Graceful shutdown и таймауты

Представь: сервер обрабатывает долгие запросы — 5, 20 секунд, а то и минуты. Если в этот момент процесс убить — деплой, падение, что угодно, — клиенты получат обрыв соединения: Postman покажет socket hang up, curl — Empty reply from server. Graceful shutdown (элегантное завершение) решает это: получив сигнал остановки, сервер перестаёт принимать новые запросы, но даёт текущим доработать.

go
package main

import (
    "context"
    "errors"
    "log"
    "net/http"
    "os/signal"
    "syscall"
    "time"
)

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("GET /slow", func(w http.ResponseWriter, r *http.Request) {
        time.Sleep(5 * time.Second) // долгий запрос
        w.Write([]byte("готово\n"))
    })

    srv := &http.Server{
        Addr:              ":8080",
        Handler:           mux,
        ReadHeaderTimeout: 5 * time.Second,  // сколько ждать заголовки запроса
        ReadTimeout:       10 * time.Second, // сколько читать весь запрос
        WriteTimeout:      15 * time.Second, // сколько писать ответ
        IdleTimeout:       60 * time.Second, // сколько держать keep-alive соединение
    }

    go func() {
        log.Println("сервер запущен на :8080")
        if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
            log.Fatalf("ListenAndServe: %v", err)
        }
    }()

    ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
    defer stop()
    <-ctx.Done() // ждём Ctrl+C или SIGTERM от оркестратора

    log.Println("останавливаем сервер...")
    shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()
    if err := srv.Shutdown(shutdownCtx); err != nil { // новые не принимаем, текущие дорабатывают
        log.Printf("Shutdown: %v", err)
    }
    log.Println("сервер остановлен корректно")
    // сервер: только сборка
}

Как проверить: запусти сервер, отправь curl localhost:8080/slow и сразу нажми Ctrl+C в окне сервера. Сервер напишет «останавливаем сервер...», дождётся окончания запроса, и curl получит «готово».

  • Сервер запускается в отдельной горутине, а main ждёт сигнала через signal.NotifyContext.
  • srv.Shutdown(ctx) даёт текущим запросам до 10 секунд. Большинство запросов идёт сотни миллисекунд, за 10 секунд почти все успеют; если какой-то висит 100 минут — сервер не обязан его ждать.
  • После Shutdown метод ListenAndServe возвращает http.ErrServerClosed — это не ошибка, поэтому её отфильтровывают.

Таймауты нужно ставить почти всегда: http.ListenAndServe удобен, но без таймаутов медленный клиент может держать горутину бесконечно.

Таймаут Что ограничивает
ReadHeaderTimeout ожидание заголовков запроса
ReadTimeout чтение всего запроса вместе с телом
WriteTimeout запись ответа
IdleTimeout простой keep-alive соединения между запросами

Итоги

  • Как устроена net/http: ServeMux, ResponseWriter и Request, маршруты с методами и параметрами.
  • Структура реального проекта: handler → service → repository, зависимости через интерфейсы и конструкторы.
  • Разбор запроса и единый формат JSON-ответов, валидация, контракт OpenAPI.
  • Middleware: логирование, request ID, recovery, CORS; порядок цепочки важен.
  • Тесты через httptest без сервера.
  • Graceful shutdown и таймауты — обязательная часть любого сервера.

Практика

Задание: API фильмов в памяти

По образцу UserHandler сделай API фильмов GoFlix с хранилищем в памяти:

  1. POST /api/v1/movies — создать фильм из JSON {"title": "…", "year": …}; пустое название — 400.
  2. GET /api/v1/movies?limit=&offset= — список с пагинацией; пустой список — [], а не null.
  3. DELETE /api/v1/movies/{id} — удалить; нет такого — 404, успех — 204.
  4. Хранилище потокобезопасное: sync.RWMutex.
  5. Оберни мультиплексор в middleware-цепочку и запусти сервер с graceful shutdown и таймаутами из примеров выше; проверь через curl.
решениеЭталонное решение (обработчики и хранилище)

Проверка сделана через httptest, а запуск настоящего сервера — как в разделе «Graceful shutdown».

go
package main

import (
    "encoding/json"
    "fmt"
    "net/http"
    "net/http/httptest"
    "slices"
    "strconv"
    "strings"
    "sync"
)

type Movie struct {
    ID    int    `json:"id"`
    Title string `json:"title"`
    Year  int    `json:"year"`
}

type MovieStore struct {
    mu     sync.RWMutex
    nextID int
    movies map[int]Movie
}

func NewMovieStore() *MovieStore { return &MovieStore{movies: make(map[int]Movie)} }

func (s *MovieStore) Add(title string, year int) Movie {
    s.mu.Lock()
    defer s.mu.Unlock()
    s.nextID++
    m := Movie{ID: s.nextID, Title: title, Year: year}
    s.movies[m.ID] = m
    return m
}

func (s *MovieStore) List(limit, offset int) []Movie {
    s.mu.RLock()
    defer s.mu.RUnlock()
    all := make([]Movie, 0, len(s.movies))
    for _, m := range s.movies {
        all = append(all, m)
    }
    slices.SortFunc(all, func(a, b Movie) int { return a.ID - b.ID })
    if offset >= len(all) {
        return []Movie{} // пустой слайс → [] в JSON
    }
    return all[offset:min(offset+limit, len(all))]
}

func (s *MovieStore) Delete(id int) bool {
    s.mu.Lock()
    defer s.mu.Unlock()
    if _, ok := s.movies[id]; !ok {
        return false
    }
    delete(s.movies, id)
    return true
}

type MovieHandler struct{ store *MovieStore }

func (h *MovieHandler) Routes(mux *http.ServeMux) {
    mux.HandleFunc("GET /api/v1/movies", h.List)
    mux.HandleFunc("POST /api/v1/movies", h.Create)
    mux.HandleFunc("DELETE /api/v1/movies/{id}", h.Delete)
}

func (h *MovieHandler) List(w http.ResponseWriter, r *http.Request) {
    limit := queryInt(r, "limit", 10)
    offset := queryInt(r, "offset", 0)
    writeJSON(w, http.StatusOK, h.store.List(limit, offset))
}

func (h *MovieHandler) Create(w http.ResponseWriter, r *http.Request) {
    var req struct {
        Title string `json:"title"`
        Year  int    `json:"year"`
    }
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil || req.Title == "" {
        writeJSON(w, http.StatusBadRequest, map[string]string{"error": "нужны title и year"})
        return
    }
    writeJSON(w, http.StatusCreated, h.store.Add(req.Title, req.Year))
}

func (h *MovieHandler) Delete(w http.ResponseWriter, r *http.Request) {
    id, err := strconv.Atoi(r.PathValue("id"))
    if err != nil || !h.store.Delete(id) {
        writeJSON(w, http.StatusNotFound, map[string]string{"error": "фильм не найден"})
        return
    }
    w.WriteHeader(http.StatusNoContent)
}

func queryInt(r *http.Request, key string, def int) int {
    v, err := strconv.Atoi(r.URL.Query().Get(key))
    if err != nil || v < 0 {
        return def
    }
    return v
}

func writeJSON(w http.ResponseWriter, status int, data any) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(status)
    json.NewEncoder(w).Encode(data)
}

func main() {
    mux := http.NewServeMux()
    (&MovieHandler{store: NewMovieStore()}).Routes(mux)

    call := func(method, target, body string) {
        rec := httptest.NewRecorder()
        mux.ServeHTTP(rec, httptest.NewRequest(method, target, strings.NewReader(body)))
        fmt.Printf("%s %s → %d %s\n", method, target, rec.Code, strings.TrimSpace(rec.Body.String()))
    }
    call("POST", "/api/v1/movies", `{"title":"Дюна","year":2021}`)
    call("POST", "/api/v1/movies", `{"title":"Матрица","year":1999}`)
    call("POST", "/api/v1/movies", `{"title":"Начало","year":2010}`)
    call("POST", "/api/v1/movies", `{"year":2010}`)
    call("GET", "/api/v1/movies?limit=2&offset=1", "")
    call("DELETE", "/api/v1/movies/2", "")
    call("DELETE", "/api/v1/movies/2", "")
    call("GET", "/api/v1/movies", "")
}
stdout // вывод программы
POST /api/v1/movies → 201 {"id":1,"title":"Дюна","year":2021}
POST /api/v1/movies → 201 {"id":2,"title":"Матрица","year":1999}
POST /api/v1/movies → 201 {"id":3,"title":"Начало","year":2010}
POST /api/v1/movies → 400 {"error":"нужны title и year"}
GET /api/v1/movies?limit=2&offset=1 → 200 [{"id":2,"title":"Матрица","year":1999},{"id":3,"title":"Начало","year":2010}]
DELETE /api/v1/movies/2 → 204
DELETE /api/v1/movies/2 → 404 {"error":"фильм не найден"}
GET /api/v1/movies → 200 [{"id":1,"title":"Дюна","year":2021},{"id":3,"title":"Начало","year":2010}]

Проверь себя

вопросКакая сигнатура у HTTP-обработчика в Go и что означают параметры?

func(w http.ResponseWriter, r *http.Request): в w пишем ответ, из r читаем запрос.

вопросЧто такое ServeMux и что изменилось в Go 1.22?

Мультиплексор: сопоставляет запросы маршрутам и вызывает нужный обработчик. С Go 1.22 в шаблоне можно указать метод и параметры пути — "GET /users/{id}" и r.PathValue("id"); на неподходящий метод мультиплексор сам отвечает 405.

вопросЗачем делить приложение на handler, service и repository?

У каждого слоя своя ответственность: транспорт, бизнес-логика, хранение. Один слой можно заменить — другую базу, другой транспорт, заглушку в тесте, — не трогая остальные.

вопросПочему WriteHeader вызывают до записи тела?

Первая запись тела неявно отправляет статус 200. Поздний WriteHeader уже ничего не изменит.

вопросЧто такое middleware и какой у него тип?

Промежуточный слой вокруг обработчика для общих задач: логи, request ID, recovery, CORS, авторизация. Тип — func(http.Handler) http.Handler.

вопросКак протестировать хендлер без запуска сервера?

Создать запрос через httptest.NewRequest, ответ записать в httptest.NewRecorder, вызвать ServeHTTP, проверить код и тело. Зависимости подменить заглушками через интерфейсы.

вопросЧто такое graceful shutdown?

Корректная остановка: получив SIGINT или SIGTERM, сервер перестаёт принимать новые запросы и даёт текущим доработать в пределах таймаута — srv.Shutdown(ctx).

вопросКакие таймауты стоит задать у http.Server?

ReadHeaderTimeout, ReadTimeout, WriteTimeout, IdleTimeout.


Ключевые выводы

  • 🌐 net/http хватает для продакшена; роутеры вроде chi лишь добавляют удобства.
  • 🛣️ С Go 1.22 маршрут — это метод и путь с параметрами: "GET /api/v1/users/{id}".
  • 🧅 Handler → service → repository; зависимости — через интерфейсы и конструкторы.
  • 📤 Ответ: заголовок Content-Type, затем статус, затем тело — единый JSON-формат ошибок.
  • 🧩 Middleware func(http.Handler) http.Handler — для логов, request ID, recovery и CORS; первый в цепочке — внешний.
  • 🧪 httptest тестирует хендлеры без сервера; моки подставляются через интерфейсы.
  • 🛑 Graceful shutdown и таймауты — обязательная часть любого сервера.
// связанные темы и шпаргалки