К содержимому
Войти

Go Road Map

🌍 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/jsonencoding/json/v2
{"name":"pen","name":"cup"}берёт последнее, cupошибка duplicate object member name "name"
{"NAME":"pen"} в поле с тегом nameзаполняет без учёта регистраполе остаётся пустым
невалидный UTF-8 в строкезаменяет символошибка

Если обновление до 1.27 что-то сломало, старую реализацию возвращает GOEXPERIMENT=nojsonv2 при сборке. Этот флаг обещают убрать в одном из следующих релизов

Когда брать chi или gin

net/httpchigin
Сигнатура хендлераhttp.Handlerhttp.Handlerfunc(*gin.Context)
Middlewarefunc(http.Handler) http.Handlerте же, стандартныесвои, через gin.Context
Группы маршрутовнет, собираются вручнуюr.Route, r.Groupr.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 и что поменялось в старом пакете