net/http как фреймворк: Handler, ServeMux 1.22 и маршрутизация без зависимостей

Один интерфейс, один метод

Прежде чем тянуться за библиотекой-роутером, разберись, что stdlib уже даёт тебе — ответ изменит каждое последующее решение о зависимостях.

Весь HTTP-стек Go — роутеры, middleware, фреймворки, ваш код — говорит на одном контракте:

type Handler interface {
	ServeHTTP(w http.ResponseWriter, r *http.Request)
}

// HandlerFunc адаптирует обычную функцию к интерфейсу —
// это именованный функциональный тип с методом ServeHTTP, вызывающим саму функцию.
type HandlerFunc func(http.ResponseWriter, *http.Request)

func (f HandlerFunc) ServeHTTP(w http.ResponseWriter, r *http.Request) { f(w, r) }

На HandlerFunc стоит задержаться: это функциональный тип, реализующий интерфейс, поэтому любая функция с нужной сигнатурой превращается в Handler без единой аллокации — mux.Handle("/x", http.HandlerFunc(myFunc)) или короче mux.HandleFunc("/x", myFunc). А ServeMux сам реализует Handler, поэтому роутеры вкладываются друг в друга: mux может быть хендлером внутри другого mux, middleware оборачивает mux так же, как одиночный эндпоинт. Эта однородность — причина, по которой экосистема Go так чисто композируется: нет фреймворочной сигнатуры хендлера, к которой нужен мост, есть один метод. Серверная сторона зеркальна: http.Server принимает любой Handler как корень; http.ListenAndServe(addr, mux) порождает по горутине на соединение, так что код хендлеров конкурентен по умолчанию и обязан быть к этому готов — обычная map, разделяемая хендлерами без мьютекса, становится гонкой данных на втором одновременном запросе.

ServeMux 1.22: методы, шаблоны, приоритет

До Go 1.22 stdlib-mux матчил только литеральные префиксы — ни методов, ни path-параметров — и именно эту дыру десятилетие закрывали сторонние роутеры. Паттерны 1.22 её закрыли:

mux := http.NewServeMux()
mux.HandleFunc("GET /users/{id}", getUser)        // {id} матчит один сегмент
mux.HandleFunc("POST /users", createUser)          // привязка к методу
mux.HandleFunc("GET /files/{path...}", serveFile)  // {path...} матчит остаток
mux.HandleFunc("GET /{$}", home)                   // {$} = ровно "/", без поддерева

func getUser(w http.ResponseWriter, r *http.Request) {
	id := r.PathValue("id") // значение шаблона, без танцев с контекстом
	// ...
}

Правила, которые важны в проде:

• Паттерны с методом: паттерн с методом матчит только этот метод — кроме GET, который матчит ещё и HEAD (сервер отбрасывает тело). Паттерн без метода матчит все методы. Запрос, совпавший по пути, но не по методу, автоматически получает 405 Method Not Allowed.
• Приоритет — у более специфичного паттерна, а не у зарегистрированного первым: GET /users/new побеждает GET /users/{id}, а /users/{id} побеждает /users/. Порядок регистрации не важен — сознательное решение дизайна, чтобы поведение маршрута никогда молча не зависело от порядка init.
• Конфликты — паника при регистрации: если два паттерна пересекаются и ни один не специфичнее (GET /a/{x}/c против GET /a/b/{y} — оба матчат /a/b/c), Handle паникует на старте. Громко и рано лучше, чем тихо и неправильно.
• Паттерн с завершающим слэшем вроде /static/ матчит всё поддерево и даёт 301-редирект с /static на /static/.

Когда фреймворк действительно нужен

Когда рука тянется к библиотеке-роутеру, спроси себя: что конкретно нужно такого, чего у mux нет — список окажется короче, чем кажется.

Будем честны в том, что сторонние веб-фреймворки добавляют поверх этого: биндинг и валидацию параметров, помощники content negotiation, экосистемы middleware, группы маршрутов. Ничего из этого не маршрутизация — mux 1.22 матчит запрос значительно быстрее микросекунды, что исчезает на фоне одного похода в базу за 200 мкс. Издержки фреймворка реальны и постоянны: нестандартная сигнатура хендлера, под которую приходится адаптировать каждый middleware, дерево зависимостей, которое вы аудируете вечно, и абстракция между вами и ResponseWriter ровно тогда, когда нужны Flusher или Hijacker. Прагматичная линия большинства Go-команд: начинать с net/http плюс тонкая цепочка middleware; брать библиотеку-роутер, только когда нужно то, чего у mux действительно нет (regex-ограничения, DSL для per-route middleware). Чего делать не стоит — криво написать валидацию руками и назвать это «без фреймворка»: берите сфокусированную библиотеку под сфокусированную задачу, а не фреймворк под всё.