🌍 HTTP-сервер на net/http
HTTP-сервер — первое, что пишет почти любой бэкендер на Go, и стандартной библиотеки для него хватает. С Go 1.22 net/http сам разбирает методы и параметры пути, поэтому сторонний роутер больше не обязателен. На собеседовании здесь проверяют три вещи: понимаешь ли ты, как запрос доходит до хендлера, умеешь ли писать middleware и знаешь ли, почему сервер без таймаутов нельзя выпускать в прод
🧠 Как это устроено
Handler — один метод
Всё в net/http держится на интерфейсе из одного метода:
type Handler interface {
ServeHTTP(ResponseWriter, *Request)
}http.HandlerFunc превращает обычную функцию с такой сигнатурой в Handler. Роутер http.ServeMux тоже Handler: он смотрит на запрос и передаёт его дальше нужному хендлеру. Middleware тоже Handler, который оборачивает другой. Из-за этого всё собирается как матрёшка, и любая библиотека, которая принимает и возвращает http.Handler, встаёт в цепочку без переходников
Сервер принимает соединение и запускает отдельную горутину на каждое соединение. Внутри неё он читает запросы по очереди и вызывает ServeHTTP. Поэтому хендлер может спокойно блокироваться на запросе в базу, а общие данные между запросами нужно защищать, как в любом конкурентном коде
Шаблоны маршрутов с Go 1.22
Шаблон в ServeMux состоит из необязательного метода, необязательного хоста и пути. В пути бывают параметры:
| Шаблон | Что совпадает |
|---|---|
GET /items/{id} | /items/7, значение берут через r.PathValue("id") |
GET /files/{path...} | всё после /files/: a/b/c.txt целиком |
GET /docs/ | /docs/ и всё, что под ним, а /docs получит редирект на /docs/ |
GET /{$} | только корень /, без {$} шаблон / ловит вообще всё |
POST /items | только POST, на другие методы — 405 |
Порядок регистрации не важен. Если два шаблона подходят к одному запросу, побеждает более конкретный: GET /items/new выигрывает у GET /items/{id}. Если ни один не конкретнее, это конфликт, и ServeMux паникует прямо при регистрации, а не в проде под нагрузкой. Вот что он пишет на GET /a/{x}/b и GET /a/b/{y}:
GET /a/b/{y} and GET /a/{x}/b both match some paths, like "/a/b/b".
But neither is more specific than the other.Три поведения видно прямо по ответам. Шаблон с GET автоматически отвечает и на HEAD. На метод, для которого маршрута нет, сервер отвечает 405 и сам ставит заголовок Allow: GET, HEAD. Редирект на путь со слешем на конце с Go 1.26 идёт кодом 307 вместо 301. Старое поведение роутера целиком возвращает GODEBUG=httpmuxgo121=1
Таймауты сервера
http.ListenAndServe(addr, h) создаёт http.Server с нулевыми полями, а ноль значит «без таймаута». Клиент, который открыл соединение и шлёт заголовки по байту в минуту, держит горутину и файловый дескриптор сколько угодно. Это атака slowloris, и её устраивает не только злоумышленник, но и сломанный клиент с плохой сетью
| Поле | Что ограничивает | Если ноль |
|---|---|---|
ReadHeaderTimeout | чтение заголовков запроса | берётся ReadTimeout |
ReadTimeout | чтение всего запроса вместе с телом | без ограничения |
WriteTimeout | от конца чтения заголовков до конца записи ответа | без ограничения |
IdleTimeout | ожидание следующего запроса в keep-alive соединении | берётся ReadTimeout |
MaxHeaderBytes | размер заголовков | 1 МБ |
С Go 1.27 есть ещё MaxHeaderValueCount — сколько значений заголовков сервер согласен принять
WriteTimeout не останавливает хендлер. Он ставит дедлайн на запись в соединение. Хендлер продолжит работать, запишет ответ в никуда, а клиент получит обрыв соединения. В проверке хендлер спал 1,5 секунды при WriteTimeout: time.Second: в логе сервера стоит статус 200, а клиент получил EOF. Чтобы работа прервалась, хендлер должен слушать r.Context(), об этом подробно на странице про context
🛠️ На практике
Сервер, с которого можно начинать
func main() {
mux := http.NewServeMux()
mux.HandleFunc("GET /items/{id}", getItem)
mux.HandleFunc("POST /items", createItem)
srv := &http.Server{
Addr: ":8080",
Handler: logging(recoverer(mux)),
ReadHeaderTimeout: 5 * time.Second,
ReadTimeout: 15 * time.Second,
WriteTimeout: 30 * time.Second,
IdleTimeout: 90 * time.Second,
}
log.Fatal(srv.ListenAndServe())
}Цифры зависят от сервиса. ReadHeaderTimeout в несколько секунд подходит почти всем: нормальный клиент присылает заголовки за миллисекунды. WriteTimeout должен быть больше самого долгого нормального ответа, иначе отчёт на 40 секунд будет обрываться на тридцатой. Как правильно останавливать такой сервер при деплое, разобрано на странице про graceful shutdown в этом же модуле
Middleware
Middleware в Go — функция func(http.Handler) http.Handler. Она получает следующий хендлер и возвращает новый, который делает что-то до и после вызова. Чтобы залогировать статус ответа, ResponseWriter оборачивают, потому что узнать статус у него самого нельзя:
type statusRecorder struct {
http.ResponseWriter
status int
}
func (r *statusRecorder) WriteHeader(code int) {
r.status = code
r.ResponseWriter.WriteHeader(code)
}
// Unwrap нужен, чтобы http.NewResponseController видел исходный writer
func (r *statusRecorder) Unwrap() http.ResponseWriter { return r.ResponseWriter }
func logging(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
start := time.Now()
rec := &statusRecorder{ResponseWriter: w, status: http.StatusOK}
next.ServeHTTP(rec, r)
slog.Info("request", "method", r.Method, "path", r.URL.Path,
"status", rec.status, "dur", time.Since(start))
})
}Начальное значение http.StatusOK нужно потому, что хендлер часто пишет тело без WriteHeader. Тогда сервер отправляет 200 сам, и обёртка об этом не узнает
Go · recover-middleware
func recoverer(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
defer func() {
if v := recover(); v != nil {
if v == http.ErrAbortHandler {
panic(v) // штатный способ оборвать ответ, его не глотаем
}
slog.Error("panic", "err", v, "path", r.URL.Path)
http.Error(w, "internal error", http.StatusInternalServerError)
}
}()
next.ServeHTTP(w, r)
})
}Без такой обёртки сервер не падает: он сам ловит панику в горутине соединения, пишет в лог http: panic serving со стеком и закрывает соединение. Но клиент вместо ответа получает EOF, а не понятный 500, и в access-логе этого запроса не будет
JSON на входе и выходе
func createItem(w http.ResponseWriter, r *http.Request) {
r.Body = http.MaxBytesReader(w, r.Body, 1<<20) // не больше 1 МБ
dec := json.NewDecoder(r.Body)
dec.DisallowUnknownFields()
var in createItemRequest
if err := dec.Decode(&in); err != nil {
var tooBig *http.MaxBytesError
if errors.As(err, &tooBig) {
http.Error(w, "body too large", http.StatusRequestEntityTooLarge)
return
}
http.Error(w, "bad json", http.StatusBadRequest)
return
}
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(http.StatusCreated)
json.NewEncoder(w).Encode(itemResponse{ID: 42, Name: in.Name})
}MaxBytesReader защищает от тела на гигабайт, DisallowUnknownFields превращает опечатку клиента в понятную ошибку json: unknown field "cost" вместо молча потерянного поля. Порядок в конце важен: заголовки ставят до WriteHeader, после него они уже ушли клиенту
С Go 1.27 пакет encoding/json работает поверх новой реализации encoding/json/v2. Поведение старого API сохранили, поменяться может только текст ошибок, а разбор стал заметно быстрее. Новый API encoding/json/v2 строже по умолчанию, и разницу легко проверить:
| Вход | encoding/json | encoding/json/v2 |
|---|---|---|
{"name":"pen","name":"cup"} | берёт последнее, cup | ошибка duplicate object member name "name" |
{"NAME":"pen"} в поле с тегом name | заполняет без учёта регистра | поле остаётся пустым |
| невалидный UTF-8 в строке | заменяет символ | ошибка |
Если обновление до 1.27 что-то сломало, старую реализацию возвращает GOEXPERIMENT=nojsonv2 при сборке. Этот флаг обещают убрать в одном из следующих релизов
Когда брать chi или gin
net/http | chi | gin | |
|---|---|---|---|
| Сигнатура хендлера | http.Handler | http.Handler | func(*gin.Context) |
| Middleware | func(http.Handler) http.Handler | те же, стандартные | свои, через gin.Context |
| Группы маршрутов | нет, собираются вручную | r.Route, r.Group | r.Group |
| Привязка и валидация JSON | вручную | вручную | встроены |
chi — тонкий роутер поверх net/http, без внешних зависимостей. Берут его ради групп маршрутов с общими middleware и готового набора middleware. Код хендлеров остаётся стандартным, и в chi v5.5.0 даже r.PathValue("id") работает наравне с chi.URLParam, это проверено запуском. gin живёт в своей экосистеме: хендлер получает *gin.Context, и стандартный middleware в него не вставишь без обёртки. Зато из коробки привязка JSON к структуре с валидацией. Gin 1.12 требует Go 1.26 и выше
Для нового сервиса обычно хватает net/http. Chi добавляют, когда маршрутов много и нужны группы, gin берут, если он уже в проекте или команда его знает. Fiber стоит особняком: он построен на fasthttp, а не на net/http, и у него свои типы запроса и контекста
⚠️ Где ошибаются
- Запускают
http.ListenAndServeв прод. У такого сервера нет ни одного таймаута, и сотня медленных клиентов съедает горутины и дескрипторы. В примере сReadHeaderTimeout: 500msсоединение, которое не дописало заголовки, закрылось ровно через полсекунды. На сервере без таймаутов такое соединение через 5 секунд всё ещё было открыто и ждало - Ставят
recovererснаружи логирования. При панике стек раскручивается черезlogging, и строка access-лога не пишется. В демо наGET /boomклиент получил 500, а в логе запросов этого запроса не было. Правильный порядок —logging(recoverer(mux)), тогда логирование увидит 500 - Оборачивают
ResponseWriterбезUnwrap. Обёртка прячет методы исходного writer, иhttp.NewResponseController(w).Flush()илиSetWriteDeadlineперестают работать. Первыми ломаются стриминг и SSE - Думают, что
WriteTimeoutотменяет работу. Хендлер продолжает ходить в базу после того, как клиент получил обрыв. Вдобавок клиент на Go сам повторяет идемпотентныйGET, если переиспользованное соединение оборвалось до ответа. В демо медленный хендлер из-за этого отработал дважды на один вызовclient.Do - Ставят статус после тела. Первый
w.Writeуже отправил клиенту 200 и заголовки.WriteHeader(500)после него статус не меняет: клиент получает 200, а в логе сервера появляетсяsuperfluous response.WriteHeader call.w.Header().Setв этот момент тоже молча ничего не делает
🎯 Вопросы с собеседований
Что такое http.Handler и как устроен middleware в Go?
http.Handler — интерфейс с одним методом ServeHTTP(ResponseWriter, *Request). Роутер, хендлер и middleware реализуют его, поэтому складываются в цепочку. Middleware — функция, которая принимает http.Handler и возвращает новый: внутри она делает что-то до и после вызова next.ServeHTTP. Так пишут логирование, recover, аутентификацию, трейсинг. Порядок оборачивания важен: внешний middleware видит результат всех внутренних
Что умеет стандартный ServeMux с Go 1.22?
Методы в шаблоне (POST /items), параметры пути (/items/{id}, значение через r.PathValue), хвост пути ({path...}) и точное совпадение со слешем через {$}. На неподходящий метод он сам отвечает 405 с заголовком Allow, GET заодно обслуживает HEAD. Порядок регистрации не важен, побеждает более конкретный шаблон, а неразрешимый конфликт вызывает панику при регистрации. Для большинства сервисов сторонний роутер теперь не нужен
Какие таймауты есть у http.Server и что будет без них?
ReadHeaderTimeout, ReadTimeout, WriteTimeout, IdleTimeout. Нулевое значение значит «без ограничения», а http.ListenAndServe создаёт сервер именно с нулями. Медленный клиент держит соединение и горутину сколько угодно, это slowloris. Минимум для прода — ReadHeaderTimeout в несколько секунд и IdleTimeout, а WriteTimeout подбирают больше самого долгого нормального ответа
Если сработал WriteTimeout, хендлер остановится?
Нет. WriteTimeout ставит дедлайн на запись в соединение: хендлер дорабатывает до конца, его запись уходит в никуда, клиент видит обрыв. Чтобы остановить работу, хендлер передаёт r.Context() во все вызовы базы и внешних сервисов, а время ограничивают через context.WithTimeout или http.TimeoutHandler. TimeoutHandler отвечает клиенту 503 и отменяет контекст запроса
Что будет, если в хендлере случится паника?
Сервер не упадёт: net/http ловит панику в горутине соединения, пишет в лог http: panic serving со стеком и закрывает соединение. Клиент получит обрыв, а не 500. Поэтому ставят recover-middleware, которое отвечает 500 и логирует ошибку с контекстом запроса. Исключение — http.ErrAbortHandler: им обрывают ответ намеренно, и сервер не печатает для него стек
Как ограничить размер тела запроса?
Обернуть тело в http.MaxBytesReader(w, r.Body, n). Чтение больше n байт вернёт ошибку *http.MaxBytesError, по ней отвечают 413, и сервер закроет соединение, а не станет дочитывать остаток. Без этого json.NewDecoder(r.Body).Decode прочитает в память столько, сколько пришлёт клиент
Зачем оборачивать ResponseWriter и что при этом ломается?
Обёртка нужна, чтобы узнать статус и размер ответа: у ResponseWriter нет геттера статуса, поэтому перехватывают WriteHeader и Write. Сломаться может всё, что проверяет исходный writer на дополнительные интерфейсы: http.Flusher, http.Hijacker. С Go 1.20 есть http.NewResponseController, который умеет доставать исходный writer, если у обёртки есть метод Unwrap() http.ResponseWriter. Его стоит добавлять всегда
Что поменялось в encoding/json в Go 1.27?
Пакет encoding/json теперь работает поверх реализации v2: поведение старого API сохранили, могут отличаться только тексты ошибок, разбор стал заметно быстрее. Появился новый API encoding/json/v2 и низкоуровневый encoding/json/jsontext. v2 строже: отвергает повторяющиеся ключи и невалидный UTF-8, имена полей сравнивает с учётом регистра. Если новая реализация что-то сломала, её отключает GOEXPERIMENT=nojsonv2
net/http, chi или gin — что выберешь для нового сервиса?
Начну с net/http: с 1.22 у него есть методы и параметры в маршрутах, а middleware и хендлеры остаются стандартными. Chi возьму, если маршрутов много и нужны группы с общими middleware, он совместим с net/http и ничего не навязывает. Gin имеет смысл, если он уже в проекте: у него свой gin.Context и встроенная валидация, но стандартные middleware к нему нужно адаптировать
📚 Что почитать
- Routing Enhancements for Go 1.22 — пост авторов нового
ServeMuxс правилами приоритета и примерами конфликтов - Пакет net/http — описание полей
Server,ServeMux,ResponseControllerиMaxBytesReaderиз первых рук - The complete guide to Go net/http timeouts — разбор Cloudflare со схемой, какой таймаут на каком этапе запроса срабатывает. Статья старая, но механизм с тех пор не поменялся
- Go 1.27 Release Notes — раздел про
encoding/json/v2и что поменялось в старом пакете