Валидация запросов

Каждый POST-хендлер девятого урока заканчивался одной короткой проверкой руками: if in.Title == "". Один раз — не страшно; пять эндпоинтов — уже рутина; а когда к задачам добавятся пользователи и проекты, самодельные if-ы расползутся и начнут противоречить друг другу. Тема «валидация fiber» — о том, как вынести проверку из тела хендлера в декларацию на структуре и заставить Bind исполнять её сам.

Провода мы уже видели: девятый урок показал вызов validateStruct после разбора и честно предупредил, что config.StructValidator по умолчанию nil и шаг проверки молча пропускается. Сегодня в эту розетку втыкается штепсель. Документация Fiber формулирует распределение ролей без обиняков: Fiber does not bundle a validation library — библиотеки валидации в коробке нет, ядро остаётся без зависимостей, а фреймворк предлагает только слот fiber.Config.StructValidator и один вызов после каждого bind-метода. Кого ставить в слот — ваше решение; наш выбор традиционен для экосистемы: go-playground/validator десятого поколения — тот же движок, что крутится внутри gin, и поисковый запрос validator golang приводит в один и тот же репозиторий, откуда бы вы ни стартовали.

Сверимся с исходниками тега v3.5.0. В bind.go интерфейс объявлен четвёркой строк: док-комментарий StructValidator is an interface to register custom struct validator for binding — и единственный метод Validate(out any) error. Сравните с gin из параллельного курса: там интерфейс StructValidator живёт в binding/binding.go и требует два метода — ValidateStruct(any) error и Engine() any, а словарь тегов переключается SetTagName("binding"). Fiber просит меньше — один метод — и словарь не трогает вовсе: движок читает родные validate-теги, переключать нечего.

Второй источник — app.go, поле конфига. Док-комментарий там такой: If you want to validate header/form/query... automatically when to bind, you can define struct validator. Fiber doesn't have default validator, so it'll skip validator step if you don't use any validator — и ниже Default: nil. Из комментария следуют два факта, которые легко пропустить. Первый: параметр метода — any, то есть формально адаптер может получить что угодно; фильтрация «структура или нет» — забота не библиотеки, а самого bind.go, до неё дойдём. Второй: nil — не баг, а документированный дефолт: без валидатора шаг проверки пропускается молча, без предупреждений в логах. Именно поэтому в девятом уроке POST с пустым title спокойно возвращал 201 — провода были под напряжением, но вилку никто не воткнул.

Зависимость ставится одной командой: go get github.com/go-playground/validator/v10. Обратите внимание на суффикс /v10 — это отдельный модуль ветки десятого поколения; в исходниках gin документирована v10.6.1, в вашем go.mod может быть новее — интерфейс стабилен годами. Важно понимать, куда легла зависимость: пакет fiber ничего не импортирует из go-playground — документация подчёркивает, что ядро остаётся dependency-free; импорт живёт в вашем main.go, и удалить валидатор из проекта — значит вычеркнуть одну строку из конфига и одну из импортов.

Зато теперь проверка — настройка один раз, а не бойлерплейт в каждом хендлере: документация называет это a one-time setup instead of per-handler boilerplate. И это не ловушка вендора: интерфейс — один метод, так что самодельный валидатор на if-ах, другая библиотека или цепочка проверок — всё проходит через один и тот же слот. Дешёвая страховка на будущее: держите адаптер в отдельном файле вместе с регистрацией правил — одно место, куда смотрят при споре «как мы валидируем».

Что происходит на каждый bind-вызов. В bind.go вызов validateStruct стоит после каждого парсера семейства — Body, JSON, XML, Form, MsgPack, CBOR, Query, URI, Header, Cookie, Custom; документация так и говорит: every bind method (Body, Query, Form, and the rest) now triggers validation and returns its errors alongside binding errors. Внутри метода пять шагов, и почти каждый — потенциальный выход без проверки. Первый: shouldSkipValidation — флаг цепочки, которым управляет chainable-метод SkipValidation(skip bool) Bind: c.Bind().SkipValidation(true).Body(&in) разберёт тело, но проверку пропустит. Второй: validator := config.StructValidator; если nil — тихий выход, документированный дефолт из app.go. Третий: reflect.TypeOf(out) и разворот указателей — комментарий исходников описывает операцию дословно: unwrap pointers (e.g. T, **T) to inspect the underlying destination type. Четвёртый: если под указателем не структура — Kind() != reflect.Struct — выход: примечание официального гайда предупреждает, что StructValidator runs only for struct destinations (or pointers to structs), а биндинг в карты и прочие не-структуры проверку пропускает; fiber.Map и срезы адаптер не увидят. Пятый: validator.Validate(out) — вызов вашего адаптера с исходным указателем на заполненную структуру.

Отдельный сюрприз спрятан в Bind().All: на время слияния источников он глушит shouldSkipValidation, а validateStruct зовёт один раз в конце — уже на итоговой, собранной из URI, тела, query, заголовков и cookie структуре, причём через returnErr. Значит, в режиме WithAutoHandling именно All вернёт проваленную проверку как *Error со статусом 400 — отличие, о котором мы ещё вспомним.

Слово omitempty встречается в двух словарях, и это разные команды. В словаре encoding/json из девятого урока omitempty говорит «не сериализуй пустое поле». В словаре validator omitempty говорит «если значение пустое — пропусти все правила этого поля»: ноль, пустая строка, nil, false. Поле Priority помечено и там, и там, и команды не мешают друг другу: json-движок решает, печатать ли ключ в ответе, валидатор — проверять ли значение во входе. Связка omitempty,oneof=low medium high читается как «пусто — значит без приоритета; любое другое значение — только из трёх».

На ID та же связка решает типовую задачу: клиент, создающий задачу, ID не присылает — omitempty пропускает min=1 для нуля; но приславший отрицательный ID получит FieldError. Каталог остального — из gin-курса: email, url, gte, lte и десятки других лежат в том же словаре и работают одинаково, потому что движок общий. Из технических мелочей одна: min и max на строках считают руны, не байты, поэтому кириллица считается честно — «пв» не пройдёт min=3, сколько бы байтов ни занимал.

На return err из одного Body сходятся теперь три семейства, и различать их — обязательный навык. Первое — из девятого урока: BindError с полями Err, Source и Field — тело не разобралось: битый JSON, не тот тип поля. Второе — новое: validator.ValidationErrors; это срез FieldError, а у среза есть метод Error(), то есть тип реализует error и летит по обычному каналу ошибок. Сообщение каноничное: Key: 'Task.Title' Error:Field validation for 'Title' failed on the 'min' tag — а для списка ошибок такие строки склеиваются переводами строк. Третье — Error самого Fiber: так выглядит ошибка в режиме WithAutoHandling или созданная fiber.NewError.

Ключевой факт из bind.go: validateStruct возвращает ошибку валидации СЫРОЙ. Обёртка returnBindErr, которая заворачивает ошибки разбора в BindError с Source и Field, на путь валидации не действует — Source и Field у валидационной ошибки не заполняются, информацию о полях несёт сам ValidationErrors. Следствие для авторежима: WithAutoHandling снимает флаг shouldSkipErrHandling, но статус 400 от этого получает только ошибка РАЗБОРА; проваленная проверка из Body() вернётся сырой — и, возвращённая как есть, уедет в DefaultErrorHandler на 500. Исключение мы уже знаем: All() прогоняет validateStruct через returnErr, и там авторежим даёт Error 400. Порядок проверки в хендлере: errors.As на validator.ValidationErrors, затем на fiber.BindError — семейства не пересекаются, но обе ветки должны существовать.

Каким кодом отвечать на проваленную проверку? Официальный рецепт Fiber выбирает 400 Bad Request: Step 4 документации собирает ответ c.Status(fiber.StatusBadRequest).JSON(...) со списком ошибок. Против 400 есть аргумент из свежего словаря RFC 9110: 422 там называется Unprocessable Content — «содержимое синтаксически корректно, но семантика не прошла», а пустой title — ровно такой случай. За 400 — практика: gin в девятом уроке курса отвечал 400, и клиенты чаще всего ожидают именно его. Нюанс, который нельзя игнорировать: 422 в нашем API уже занята — девятый урок отдал её ErrUnprocessableEntity, ситуации «парсер под Content-Type не нашёлся».

Если спор цифр хочется закрыть один раз и навсегда, спрячьте его в адаптер: пусть Validate при errors.As(err, &ve) возвращает fiber.NewError(fiber.StatusUnprocessableEntity, "поля заполнены неверно"). Это готовая *Error — DefaultErrorHandler сам поставит 422 и запишет message в text/plain, а хендлеры продолжат просто возвращать err. Правило одно: выберите цифру один раз и держите единой весь API — каталог ошибок и клиентский код завязаны на неё сильнее, чем на любую философию RFC.

Срез — развилка, где Fiber расходится с gin радикально. В девятом уроке курса gin batch-запрос []TodoInput проверялся сам: когда ShouldBindJSON получал &batch, binding gin-а видел Slice, ходил по элементам в цикле и собирал ошибки в собственный тип binding.SliceValidationError — отдельное семейство с индексами в сообщениях. В Fiber v3 validateStruct смотрит на назначение: []Task под указателем — Kind() == Slice, а не Struct — и выход без проверки, ни единого правила на элементы. Документация предупреждает одной строкой (StructValidator runs only for struct destinations), но цена промаха высока: батч-импорт из девятого урока молча примет задачи с пустыми title и вернёт 201.

Лечение — ручной прогон движка: engine.Var(in, "omitempty,dive"). Var проверяет одиночное значение по строке тегов, а dive спускает правила в элементы среза — механика dive разобрана в gin-курсе, напомним одной строкой: dive на не-срезе и не-карте — паника. Ошибка прилетит той же ValidationErrors, и хендлер различит её тем же errors.As. Срезы ВНУТРИ структуры ведут себя наоборот: поле Members []Member с validate:"dive" проверяется автоматически — validateStruct вызван на внешней структуре, а движок сам спускается по dive в элементы. Два маршрута запомните одним правилом: сверху Fiber не спускается, внутри структуры движок спускается по тегу.

Свой тег — короткий финальный штрих, и он почти без изменений переезжает из девятого урока gin: RegisterValidation(tag, func(fl FieldLevel) bool) регистрирует правило под именем тега, функция возвращает булево. Отличия — в месте и моменте. У gin движок спрятан за binding.Validator и доставался Engine() из недр фреймворка; у Fiber движок ваш с первого дня: вы сами вызвали validator.New(), сами держите ссылку, и регистрация живёт в init рядом с RegisterTagNameFunc — до первого запроса. Опоздаете — первый же запрос с неизвестным тегом упадёт в панику Undefined validation function, та же самая, что в gin-уроке.

Наш тег workhours параметризованный: в теге estimate написано workhours=40, и функция читает «40» через fl.Param(). Контракт такой: fl.Field() — reflect.Value проверяемого поля, fl.Param() — строка-параметр из тега, возврат false даёт FieldError с Tag() = workhours и Param() = 40. То же самое покрыли бы встроенные gte=1,lte=40 — наш пример нужен ради контракта, а каталог кастомных правил держите в одном init-файле рядом с адаптером: это место, где бизнес-логика встречается с формой данных.

Соберите каркас и прогоните пять сценариев. Первый — светлая дорожка: curl -i -X POST localhost:8080/api/tasks -H "Content-Type: application/json" -H "X-API-Key: s3cret" -d '{"title":"позвонить клиенту","priority":"high"}' — 201 и созданная задача с id и created_at. Второй — короткий title: -d '{"title":"пв"}' — 400 и {"errors":[{"field":"title","rule":"min","param":"3"}]}: json-имя Field() взял из RegisterTagNameFunc. Третий — внеполосный приоритет: "priority":"ultra" — 400 и param "low medium high". Четвёртый — батч: POST /api/tasks:import с [{"title":"ок"},{"note":"нет title"}] — 400, и в ответе path Task[1].title укажет на второй элемент. Пятый — ловушка наивного адаптера: уберите обе ветки errors.As и верните err как есть — 500 и Key: 'Task.Title' Error:Field validation... в text/plain.

Материал держится на трёх столбах: провода bind.go и формы ошибок — из девятого урока, слои и страж — из восьмого, каталог тегов, dive и RegisterValidation — из девятого урока курса gin; полный план — на странице курса Fiber. В браузерной песочнице сайта сетевые приложения не запускаются — runner-ов в уроках Fiber нет, проверяйте примеры в терминале с локальным Go.

Дальше — одиннадцатый урок: формы и загрузка файлов. Bind().Form и multipart пройдут тот же validateStruct, так что проверки формы достанутся бесплатно; файлам понадобятся свои проверки размера и типа, но место для них — та же цепочка после разбора.