Цели главы
- Поднять 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: разобравшись в нём, любой фреймворк выучишь за день — отличаться будет лишь синтаксис.
Первый сервер
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))
// сервер: только сборка
}go run .
curl localhost:8080/helloHandleFunc(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 — отчасти поэтому и были популярны фреймворки.
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()))
}
}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 — и второй может не появиться никогда, но префикс закладывают сразу.
Слои приложения
Код растёт — его делят на части с узкой зоной ответственности.
- Handler (handle — глагол, handler — существительное) — сущность, которая обрабатывает запросы: читает и проверяет данные, преобразует их, вызывает следующий слой и формирует ответ.
- Service — бизнес-логика: то, что хочет бизнес. Например, выдать пользователю Premium — это не работа хендлера.
- Repository — работа с базой данных: сохранить, найти, удалить.
Зачем делить? Чтобы одну часть можно было заменить, не задевая остальные: перейти с PostgreSQL на другую базу или принимать данные не по HTTP, а из очереди. Если бизнес-логики почти нет — данные пришли, и их надо просто сохранить, — сервисный слой опускают, и хендлер работает с репозиторием напрямую. Так дальше и сделаем.
Хендлер как структура
Хендлер оформляют структурой с зависимостями. Репозиторий передают через конструктор и описывают интерфейсом: хендлеру всё равно, что за ним — PostgreSQL, память или заглушка в тесте (16 — Интерфейсы → Дженерики, идиома «принимай интерфейсы»). Метод Routes регистрирует ручки в мультиплексоре.
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", "")
}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:
w.Header().Set("Content-Type", "application/json")— говорим, что отдаём JSON, а не форму или картинку.w.WriteHeader(status)— код ответа: 200 OK, 201 Created, 400 Bad Request, 404 Not Found, 500 Internal Server Error.- Тело —
json.NewEncoder(w).Encode(data).
Чтобы не дублировать эти три строки в каждом хендлере, их выносят в writeJSON и writeError, как в примере выше. Заодно формат ответов становится единым: ошибка всегда приходит как {"error": "…"}.
Валидация
Полученные данные проверяют: имя — от 3 до 100 символов, почта — в формате почты, возраст — в разумных пределах. Удобно описывать правила тегами validate и проверять библиотекой go-playground/validator. Чтобы не повторять вызов в каждом хендлере, на проектах пишут небольшую обёртку.
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"}))
}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: ручки, параметры, их типы и форматы, схемы объектов.
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 — сервер разрешает запросы браузера только с определённых адресов, методов и заголовков.
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())
}
}→ 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. А раз хендлер зависит от интерфейса репозитория, в тесте вместо базы подставляют заглушку (мок) с заранее заданными данными.
// 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)
}
})
}
}go test -race -v ./...=== 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 (элегантное завершение) решает это: получив сигнал остановки, сервер перестаёт принимать новые запросы, но даёт текущим доработать.
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 с хранилищем в памяти:
POST /api/v1/movies— создать фильм из JSON{"title": "…", "year": …}; пустое название — 400.GET /api/v1/movies?limit=&offset=— список с пагинацией; пустой список —[], а неnull.DELETE /api/v1/movies/{id}— удалить; нет такого — 404, успех — 204.- Хранилище потокобезопасное:
sync.RWMutex. - Оберни мультиплексор в middleware-цепочку и запусти сервер с graceful shutdown и таймаутами из примеров выше; проверь через
curl.
решениеЭталонное решение (обработчики и хранилище)
Проверка сделана через httptest, а запуск настоящего сервера — как в разделе «Graceful shutdown».
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", "")
}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 и таймауты — обязательная часть любого сервера.
