URLParam: параметры пути и query-строка

Шаблон маршрута пишется фигурными скобками: r.Get("/notes/{id}", getNote). Имя внутри скобок — произвольный идентификатор: {id}, {noteID}, {slug} — это метка сегмента, а не переменная Go. Когда приходит запрос GET /notes/42, chi сопоставляет путь с шаблоном сегмент за сегментом, находит несовпадающую позицию и запоминает: id равно 42. Хендлер достаёт значение функцией chi.URLParam(r, "id") из контекста запроса, куда роутер положил разбор. Два жёстких правила. Первое: {id} ловит ровно один сегмент — до следующего слэша; /notes/42/comments в этот маршрут не влезет, для хвостов произвольной длины есть маршруты со звёздочкой, о них дальше по курсу. Второе: имя в chi.URLParam обязано совпасть с именем в шаблоне — не по смыслу, а по буквам: "ID" и "id" — разные метки. Chi не валидирует имена заранее и не ругается на незнакомое: вернёт пустую строку, о последствиях — отдельным блоком ниже. В одном маршруте параметров может быть несколько: /users/{userID}/notes/{noteID} — легальный шаблон с двумя метками.

URLParam возвращает string, всегда, без исключений. В пути нет типов: 42 — это символы «4» и «2», и пока вы только вставляете их в ответ или лог, строка устраивает. Но база ждёт int64, арифметика сравнения версий ждёт int — значит, нужен разбор: strconv.Atoi переводит строку в int и честно возвращает ошибку. Ошибка здесь не украшение: пользователь вольен вписать в адрес что угодно — /notes/hello, /notes/99999999999999999999, /notes/-5 — и все три случая Atoi отвергнет: первый не число, второй не влезает в int, третий синтаксически валиден, но пусть бизнес-логика решает сама. Правило каркаса: разбор параметра — первая строка хендлера, и на ошибке хендлер отвечает 400 Bad Request с внятным текстом, а не падает и не лезет в базу с мусором. Код ответа важен: 400 говорит «ошибка на стороне клиента», и пейджер мониторинга не будет дёргать дежурных из-за опечатки пользователя в адресе.

Параметры пути и query-строка выглядят похоже — и то, и другое «данные в адресе», — но назначения у них разные, и путаница между ними портит API быстрее, чем любые опечатки. Параметр пути определяет, какой ресурс запрошен: /notes/42 — конкретная заметка, её идентичность, и другой заметки по этому адресу быть не может. Query-строка фильтрует или оформляет представление коллекции: /notes?page=2&tag=go — всё та же страница «списка заметок», просто в другом разрезе. Практический тест для дизайна API: если убрать параметр и адрес перестаёт указывать на конкретный ресурс — это путь; если адрес всё равно ведёт на тот же список — это query. Закладки, кэши и журналы читаются легче, когда ресурсы живут в пути, а настройки вида — после знака вопроса. Разборы в chi тоже разные: URLParam достаёт метки шаблона, а query читается средствами net/http из r.URL — роутер тут не нужен, об этом ниже.

Для query-строки в chi нет собственной функции — и правильно: query разбирает стандартная библиотека, адрес запроса и так принадлежит net/http. r.URL.Query() возвращает map[string][]string — ключи и значения, разложенные по знакам & и =; значения — срез, потому что один ключ может повторяться. На практике почти всегда берут метод Get: r.URL.Query().Get("page") возвращает первое значение или пустую строку, если ключа нет, — то же молчаливое поведение, что у URLParam, и те же проверки нужны следом. Разбор query нужен ради дефолтов: пустая page — значит 1, пустой limit — значит 20. Из строки снова делают число той же strconv.Atoi с той же обработкой ошибки. Отдельно запомните: URLParam на query-ключи не работает никогда — метки живут только в шаблоне пути, и chi.URLParam(r, "page") вернёт пустоту, даже если адрес содержит ?page=2. Промах не репортится — это самая коварная разновидность опечатки имени.

Шаблон /users/{userID}/notes/{noteID} описывает классическую вложенность: заметки конкретного пользователя. Имена обязаны различаться — два {id} в одном маршруте превратили бы разбор в лотерею, — поэтому метки зовут по смыслу: userID и noteID. В хендлере обе метки достаются парой вызовов chi.URLParam, а логика «заметка 3 принадлежит пользователю 7» проверяется в сервисном слое: если заметка у другого владельца, это 404, а не 200 с чужими данными. Вложенность — удобный приём, но не бесплатный: цепочка /users/7/notes/3/comments/9 растёт в глубину быстрее, чем в полезность, и на четвёртом уровне шаблон проще развернуть в отдельный ресурс. Для сравнения: в Gin те же метки пишутся двоеточием — /users/:userID — и достаются функцией c.Param; механика совпадает вплоть до опечаток, различается синтаксис. Тот же разбор на другом фреймворке — в уроке Gin про параметры.