ServeMux patterns с методами и wildcard в Go 1.22+

1. Зачем улучшать роутинг: меньше if — меньше боли

Когда вы только начинаете писать HTTP-сервер, кажется естественным сделать один handler и внутри него устроить «мини-диспетчер»: проверять r.URL.Path, проверять r.Method, резать строку пути, делать strings.Split, а потом надеяться, что вы нигде не забыли слэш. Это работает… ровно до момента, когда маршрутов становится больше трёх, а команда (или вы через неделю) пытается понять, почему POST /tasks вдруг попадает в обработчик «просмотра задачи».

В Go 1.22 стандартная библиотека сделала очень приятный шаг: у net/http.ServeMux появились patterns с методами и wildcard. То есть можно описывать маршруты как «GET /tasks» и «POST /tasks» прямо на уровне роутинга, а не вручную в коде handler’а. Туда же добавили wildcard-сегменты вроде {id} и {path...} (с захватом части пути). В релизных заметках Go 1.22 это прямо отмечено как обновление стандартной библиотеки: patterns, используемые net/http.ServeMux, теперь принимают методы и wildcard-сегменты, с примерами вида GET /task/{id}/.

Главная польза для нас, как для начинающих: меньше строкового «колдовства», больше декларативности. Сервер читабельнее, тестировать проще, а ошибок типа «ой, забыли проверку метода» становится заметно меньше.

2. http.ServeMux как диспетчер запросов

Представьте, что ваш сервер — это офис доставки, а запрос — курьер с бумажкой: «Метод: GET, путь: /api/v1/tasks/10». ServeMux — это секретарь на входе, который смотрит на бумажку и решает, к какому специалисту отправить курьера. Если секретарь тупит, все стоят в очереди и ругаются.

У ServeMux есть простая задача: сопоставить запрос с паттерном, который вы зарегистрировали через mux.Handle(...) или mux.HandleFunc(...). Раньше паттерны были в основном «про путь», и разработчики часто писали один паттерн /tasks, а затем внутри handler’а делали switch r.Method. Это было рабочим подходом, но он постоянно порождал копипасту и мелкие ошибки.

Теперь мы можем задать паттерн так, чтобы метод стал частью маршрута. То есть «секретарь» смотрит не только на «куда идут» (/tasks), но и на «зачем идут» (GET/POST). Это ровно то, что мы хотим для нормального API.

Чтобы закрепить картинку, вот схема «как запрос проходит через mux»:

flowchart TD
    A[Клиент отправляет запрос] --> B[http.Server]
    B --> C[ServeMux: ищем подходящий pattern]
    C -->|нашли| D[Handler]
    C -->|не нашли| E[404 / 405 в зависимости от ситуации]
    D --> F[Ответ клиенту]

Важно: мы всё ещё остаёмся в мире стандартного net/http, без внешних роутеров и без «магии фреймворков». Это тот же ServeMux, просто он стал умнее.

3. Method-aware patterns: GET /tasks без проверки r.Method

Когда вы впервые видите строку вида "GET /tasks", есть ощущение, что это какой-то хитрый синтаксис «как в фреймворках». Но на самом деле это очень приземлённая идея: ServeMux принимает строковый паттерн, и начиная с Go 1.22 этот паттерн может включать HTTP-метод.

Самая частая практическая выгода — вы перестаёте писать в каждом handler’е одно и то же:

if r.Method != http.MethodGet {
    w.WriteHeader(http.StatusMethodNotAllowed)
    return
}

и вместо этого просто регистрируете правильный маршрут. Handler’ы становятся короче и прямолинейнее: «делаю одно действие, для одного метода».

Минимальный пример: GET /health

package main

import (
	"fmt"
	"net/http"
)

func main() {
	mux := http.NewServeMux()

	mux.HandleFunc("GET /health", func(w http.ResponseWriter, r *http.Request) {
		w.WriteHeader(http.StatusOK)
		fmt.Fprintln(w, "ok") // ok
	})

	_ = http.ListenAndServe(":8080", mux)
}

Обратите внимание на форму: между методом и путём обязательно есть пробел. Это не «стиль», это часть синтаксиса паттерна.

Два метода на одном пути: GET /tasks и POST /tasks

В API это классика: GET — прочитать список, POST — создать.

package main

import (
	"net/http"
)

func main() {
	mux := http.NewServeMux()

	mux.HandleFunc("GET /tasks", func(w http.ResponseWriter, r *http.Request) {
		_, _ = w.Write([]byte("list tasks\n"))
	})

	mux.HandleFunc("POST /tasks", func(w http.ResponseWriter, r *http.Request) {
		w.WriteHeader(http.StatusCreated)
	})

	_ = http.ListenAndServe(":8080", mux)
}

Тут важная мысль: один путь — несколько маршрутов. И это нормально. Секретарь (mux) просто видит разные «правила маршрутизации».

Почему это считается «по-Go»

Go очень любит, когда инфраструктурные правила выражаются в одном месте. Когда вы размазываете проверку метода по handler’ам, вы получаете кучу маленьких расхождений. А потом кто-то добавляет PUT, забывает прописать Allow, где-то возвращает 400 вместо 405 — и начинается зоопарк.

Если вы уже встречали идею «оборачивать handler’ы адаптером», то это из той же философии. В старых материалах от Go-команды есть пример, где делают свой тип appHandler (функциональный тип) и реализуют на нём ServeHTTP, чтобы централизованно обрабатывать ошибки. Там прямо подчёркивается: receiver может быть функцией, и это помогает держать инфраструктуру в одном месте.

С method-aware patterns похожий эффект: часть «инфраструктуры» переезжает из тела handler’а в место регистрации маршрутов.

4. Wildcards в ServeMux: {id} и {path...}

Если method-aware patterns убирают у нас боль с r.Method, то wildcard’ы убирают боль со строковыми операциями над путём. А строковые операции над путём — это тот жанр багов, который сначала выглядит как «ну я же аккуратно», а потом внезапно ломается на двойном слэше, пустом сегменте или неожиданном хвосте.

{id}: один сегмент пути

Паттерн вида:

• GET /tasks/{id}

означает: после /tasks/ должен быть ровно один сегмент, например /tasks/12 или /tasks/abc. На этом этапе нам важно понимать только матчинг: маршрут существует, и запрос «попадает» в handler.

Смысл {id} — «тут переменная часть пути». Да, мы ещё не разбираем, как именно достать значение (это отдельная тема), но сам факт «переменного сегмента» уже избавляет нас от ручного strings.Split.

{path...}: хвост пути из нескольких сегментов

Иногда нужно матчить не один сегмент, а «всё, что дальше». Типичный пример — раздача статических файлов (внутри API-шки такое встречается реже, но как учебный пример — отлично).

Паттерн вида:

• GET /assets/{path...}

означает: после /assets/ может быть хоть logo.png, хоть css/app.css, хоть images/icons/edit.svg — всё это «хвост», который матчится целиком. Удобно, когда вы хотите один handler, который обслуживает целую «директорию» URL’ов.

Зачем это нужно на практике

Потому что как только вы начинаете делать API с ресурсами, у вас почти неизбежно появляется шаблон:

• список: GET /tasks
• работа с конкретной сущностью: GET /tasks/{id}
• удаление: DELETE /tasks/{id}

И если вы не используете wildcard, вы почти наверняка скатитесь в «давай распарсим r.URL.Path руками». Это та самая тропинка в лес, где очень легко наступить на грабли.

Как ServeMux выбирает лучший маршрут

Когда маршрутов становится больше, появляется естественный вопрос: а если «подходит» несколько паттернов, кто победит?

Вместо сухого перечисления правил (которое обычно читают как заклинание), давайте представим бытовую логику. Если у секретаря есть два правила:

• «все запросы на /assets/… отправляй в отдел статики»
• «все запросы на /assets/logo.png отправляй дизайнеру, он очень любит этот файл»

то более конкретное правило должно выигрывать.

В ServeMux идея такая же: выигрывает более специфичный паттерн. А method-aware patterns добавляют ещё один уровень специфичности: GET /tasks специфичнее, чем просто /tasks «для всех методов». То есть если вы зарегистрировали и то, и другое, то запрос GET /tasks логичнее отправить в «GET-ветку».

Ещё один нюанс, о котором полезно помнить новичку: query-параметры (после ?) не участвуют в выборе handler’а. То есть /tasks?done=true всё равно матчится как /tasks. Если пытаться писать паттерн вроде "GET /tasks?done=true", вы просто не попадёте в handler и будете долго смотреть на 404 с лицом «но ведь всё правильно!».

5. Каркас HTTP-приложения: регистрируем маршруты

Сейчас наша цель — не реализовать хранение задач и не построить CRUD (это отдельная история), а собрать каркас роутинга, где видно, какие маршруты есть, и как метод+путь превращаются в конкретный handler.

Сделаем минимальный сервер, который:

• отвечает ok на GET /health
• умеет отличать GET /api/v1/tasks от POST /api/v1/tasks
• имеет маршруты для работы с задачей по id: GET и DELETE на /api/v1/tasks/{id}
• показывает пример «хвостового wildcard» на /assets/{path...}

package main

import (
	"fmt"
	"net/http"
)

func main() {
	mux := http.NewServeMux()

	mux.HandleFunc("GET /health", health)

	mux.HandleFunc("GET /api/v1/tasks", listTasks)
	mux.HandleFunc("POST /api/v1/tasks", createTask)

	mux.HandleFunc("GET /api/v1/tasks/{id}", getTask)
	mux.HandleFunc("DELETE /api/v1/tasks/{id}", deleteTask)

	mux.HandleFunc("GET /assets/{path...}", assets)

	_ = http.ListenAndServe(":8080", mux)
}

func health(w http.ResponseWriter, r *http.Request) {
	fmt.Fprintln(w, "ok") // ok
}

func listTasks(w http.ResponseWriter, r *http.Request) {
	fmt.Fprintln(w, "list tasks") // list tasks
}

func createTask(w http.ResponseWriter, r *http.Request) {
	w.WriteHeader(http.StatusCreated)
	fmt.Fprintln(w, "created") // created
}

func getTask(w http.ResponseWriter, r *http.Request) {
	fmt.Fprintln(w, "get task by id") // get task by id
}

func deleteTask(w http.ResponseWriter, r *http.Request) {
	w.WriteHeader(http.StatusNoContent)
}

func assets(w http.ResponseWriter, r *http.Request) {
	fmt.Fprintln(w, "static asset") // static asset
}

Что важно в этом коде:

• Мы не проверяем r.Method внутри handler’ов, потому что ServeMux уже выбрал handler по методу.
• Мы не парсим r.URL.Path. Мы просто зарегистрировали маршруты. Да, handler getTask пока не знает, какой именно {id} пришёл — но он хотя бы гарантированно вызван только на /api/v1/tasks/{id}, а не на что-то ещё. Это уже большой выигрыш.
• Мы явно создаём mux := http.NewServeMux() и передаём его в ListenAndServe. Это уменьшает шанс «потерять» маршруты, случайно зарегистрировав их на DefaultServeMux и запустив сервер с другим mux (классический баг: «почему у меня 404 на всё?»).

Что меняется в ощущениях от кода

Если сказать без высоких слов, method-aware patterns и wildcard’ы делают сервер менее «строчным» и более «структурным».

Когда вы смотрите на блок регистрации маршрутов, вы видите почти спецификацию API. Это похоже на маленькую табличку «что поддерживаем». И если в будущем вы захотите, например, корректно различать ситуации «маршрута нет» и «маршрут есть, но метод не подходит», то наличие метода в паттерне делает это поведение гораздо более естественным.

Плюс, чисто психологически: меньше ручных if, меньше точек, где можно ошибиться. А начинающему разработчику это особенно важно, потому что мозг и так занят тем, чтобы не перепутать := и = и не забыть импорт.

6. Типичные ошибки при работе с ServeMux patterns

Ошибка №1: забыли пробел между методом и путём.
Строка паттерна — это не «как-нибудь распарсится», а конкретный синтаксис. Если написать "GET/api/v1/tasks" вместо "GET /api/v1/tasks", вы получите маршрут, который не матчится вообще, и будете смотреть на 404, пока не начнёте подозревать, что у вас сломался интернет.

Ошибка №2: пытаются засунуть query-параметры в pattern.
"/tasks?done=true" в паттерне не работает по смыслу: query не часть пути. Правильный паттерн будет "GET /tasks", а фильтрация — это отдельная логика чтения r.URL.Query() (и она не должна влиять на выбор handler’а).

Ошибка №3: смешивают два стиля без причины: и method-aware patterns, и switch r.Method внутри.
Иногда это делают «на всякий случай», а потом забывают обновить оба места. В итоге ServeMux уже гарантирует метод, но handler всё равно может вернуть 405 из-за устаревшей проверки. Получается поведение «сам себе враг». Выберите один стиль для конкретного участка кода: если метод в паттерне — в handler’е метод обычно уже не проверяем.

Ошибка №4: пытаются парсить r.URL.Path вручную даже при наличии {id}.
Это привычка из других языков или из ранних экспериментов. Проблема в том, что ручной парсинг пути быстро превращается в комок условий, которые тяжело покрывать тестами и легко сломать. Если ServeMux умеет wildcard — лучше дать ему работать, а не конкурировать с ним в «угадай слэш».

Ошибка №5: регистрируют маршруты на DefaultServeMux, а сервер запускают с другим mux.
Когда вы пишете http.HandleFunc(...), вы работаете с DefaultServeMux. Когда пишете mux := http.NewServeMux() и mux.HandleFunc(...), вы работаете с конкретным mux. Если перепутать эти два мира, маршруты «исчезнут». Поэтому в учебных проектах лучше держать правило: всегда создаём явный mux и всегда передаём его в ListenAndServe.