Динамические запросы и builder-стиль — сборка WHERE по условиям и безопасные фильтры API в GORM

У каталога задач появился настоящий эндпоинт: /tasks?status=todo&priority=3&sort=created — и вот характер запроса перестал быть известным на этапе написания кода. Пять параметров дают десятки непустых комбинаций: со статусом и без, с приоритетом и без, с сортировкой и с дефолтом, плюс страница. Девятнадцатый урок отвечал на такую волатильность заготовками — кирпич-скоп на статус, фабрика на значение, композитный скоп на готовую политику списка, — и до поры до времени этого хватало. Но правило честное: как только комбинаций становится M на N, заготовленные скопы перестают угадывать форму запроса — надо было бы написать скоп на каждую перестановку, и реестр превратился бы в свалку. Ответ жанра — динамические запросы, то есть динамический WHERE: цепочка собирается по условиям прямо во время обработки запроса. Каждый клоз добавляет отдельный if: параметр пришёл — условие появилось, параметра нет — клоза нет. Это и называют builder-стилем: вы строите запрос по кирпичику из данных, а не выбираете из заранее собранных. Важная оговорка, чтобы не кидаться переписывать всё: builder не отменяет скопы из девятнадцатого урока — стабильные политики вроде «только невыполненные, свежие вперёд, двадцать штук» остаются именованными скопами; builder забирает себе волатильную часть — те клозы, что зависят от ввода пользователя. Седьмой урок дал строительный материал (три формы условия, плейсхолдеры, ИЛИ группой), шестой — предупреждение о хранении цепочки в переменной, семнадцатый — пагинацию; теперь всё это собирается в один конвейер безопасных фильтров API.

Строка q = q.Where(...) выглядит как рискованное трюкачество — шестой урок приучил бояться сохранённых цепочек. Разберём, почему здесь дисциплина соблюдена. Механика из chainable_api.go: Where вызывает getInstance(), прогоняет условие через tx.Statement.BuildCondition(query, args...) и дописывает результат в Statement вызовом tx.Statement.AddClause(clause.Where{Exprs: conds}) — других действий нет. Переприсваивание q = q.Where(...) безопасно, потому что вы в каждой строке берёте свежий результат и старый инстанс тут же забываете: хранится ровно одна версия цепочки, и каждый клоз добавлен ровно один раз. Ловушка из шестого урока возвращается в другой раскладке: база собирается один раз в переменную, а финишируется из разных веток. Если из одного q сделать два Find — без переприсваивания, из двух мест кода, — второй запрос доедет с условиями первого: условия остались на инстансе и склеились. Builder-стиль закрывает проблему архитектурно: сборщик — функция, её зовут заново от db на каждый запрос, и каждая сборка стартует с чистого листа. Если же многоразовая база всё-таки нужна — храните инстанс после Session(&gorm.Session{}), как показывал шестой урок: каждая новая цепочка получит копию Statement, а не допишет условия в общий. Правило сборки переменной: один построенный запрос — один финишер; нужно два запроса — зови сборщик дважды или берись за Session.

Канонический TodoFilter скрывает дыру: bool не отличает «не задано» от «выполнено нет», а int — «не задано» от «приоритет ноль». База done = false спасает каталог, но представьте админский фильтр «показать только выполненные»: нужен предикат done = true при Done = true и отсутствие клоза при «не выбрано» — а у bool лишь два значения. Классическое решение Go — указатели: Status string, Priority int, Done bool, где nil означает «параметр не пришёл», а непустой указатель — «фильтруй по значению, даже если оно нулевое». Красота в том, что структурную форму Where можно оставить как есть — механика уже всё умеет. Седьмой урок показывал правило нулевых полей: BuildCondition собирает условие только по ненулевым полям, пропуская нули проверкой isZero. Заглянем глубже в исходники, чтобы понять, как указатели проходят эту проверку. В schema/field.go функция ValueOf возвращает значение поля и флаг: fieldValue.Interface(), fieldValue.IsZero(). Для указательного поля fieldValue — сам указатель, и IsZero() для него означает nil, а не разыменованный ноль! А BuildCondition в statement.go решает так: if v, isZero := field.ValueOf(stmt.Context, reflectValue); !isZero || selected — добавляет clause.Eq только для ненулевых полей. Итог: nil-указатель — ноль, клоза нет; bool, указывающий на false, — не ноль, условие done = false честно попадает в WHERE. Указатель = явное «поле выбрано», и false больше не теряется.

Строки с плейсхолдерами — не единственная валюта Where. В statement.go BuildCondition разбирает аргументы switch-ем, и среди веток — не только строки, карты и структуры: case clause.Expression: conds = append(conds, v) и case []clause.Expression: conds = append(conds, v...). Вторая ветка — готовый хук под builder-хелпер: соберите условия в срез выражений и отдайте весь срез одним вызовом db.Where(filterExprs(f)) — он развернётся в один WHERE-клоз с конъюнкцией через AND. Выражения типизированы: clause.Eq{Column: "status", Value: f.Status} — равенство, clause.Gte — «не меньше», clause.IN{Column: "status", Values: statuses} — перечисление, причём пустой срез значений даёт IN (NULL), как и строковая форма из седьмого урока. Для сложных предикатов есть групповые условия — отдельная фича доки: Group Conditions in GORM provide a more readable and maintainable way to write complex SQL queries involving multiple conditions. Пример из доки собирает вложенные цепочки: db.Where(db.Where("pizza = ?", "pepperoni").Where(db.Where("size = ?", "small").Or("size = ?", "medium")),).Or(db.Where("pizza = ?", "hawaiian").Where("size = ?", "xlarge"),).Find(&Pizza{}) — и получает WHERE (pizza = "pepperoni" AND (size = "small" OR size = "medium")) OR (pizza = "hawaiian" AND size = "xlarge"): вложенный db.Where выступает скобками. В пакете clause есть фабрики Or и And — clause.Or(expr1, expr2) складывает условия скобочной ИЛИ-группой прямо внутри одного клоза. Выражения композицибельны, как функции: хелпер возвращает []clause.Expression, его можно расширять, тестировать и переиспользовать независимо от цепочки.

Остался самый коварный параметр — Sort. У WHERE есть плейсхолдеры, у сортировки их нет: строка Order попадает в SQL как есть, и седьмой урок уже перечислял методы, чьи строковые аргументы не экранируются, а семнадцатый показывал подноготную — clause.Column{Name: v, Raw: true}. Страница Security ставит условие раньше всех примеров: User's input should be only used as an argument — ввод пользователя должен быть только аргументом запроса, а не частью строки SQL. Дока страхуется отдельным разделом: SQL injection Methods приводит db.Order("name; drop table users;").First(&user) в списке методов, куда ввод подставляется без экранирования, — сортировка соседствует с Select, Group, Table и Raw. Общее правило там сформулировано честно и широко: The general rule to avoid SQL injection is don't trust user-submitted data, you can perform whitelist validation to test user input against an existing set of known, approved, and defined input, and when using user's input, only use them as an argument. Белый список — это и есть безопасные фильтры API в чистом виде: пользователь выбирает не колонку, а имя из каталога, которое вы сами перевели в колонку. Реализация — карта имя-колонка: sortColumns := map[string]string{"created": "created_at", "priority": "priority", "title": "title"}. Параметр сначала ищется в карте; нашли — берём значение колонки, не нашли — это не ошибка БД, а понятный ответ клиенту: дефолтная сортировка или 400 с внятным сообщением. Направление сортируем отдельным белым списком из двух констант — asc и desc, а не «что пришло, то и в SQL». Пользовательский ввод в Order не должен появиться никогда — ни целиком, ни по частям.

Пришло время свести счета девятнадцатого урока с этим. Сначала неудобная правда: buildQuery(q gorm.DB) gorm.DB — функция с тем же контрактом, что у скопа; её можно передать в db.Scopes и она честно сработает. Разница не в механике, а в организации знания. Скоп — это именованная политика: фильтр живёт отдельно от вызывающего кода, тесты и правки в одной точке, вызов — одна строка. Builder — это конвейер: форма запроса вычисляется из данных на каждом вызове, if-ы видны прямо в сборщике. Выбирайте скоп, когда политика стабильна: «каталог — это невыполненные, свежие вперёд, двадцать штук» не зависит от ввода, и менять её на лету не нужно. Выбирайте builder, когда комбинаций много и все они равноправны: пять параметров API дают десятки сочетаний — заготовленный скоп на каждую перестановку будет свалкой, а builder описывает всё семейство одним алгоритмом. Честно и про цену: builder с десятью if-ами труднее читать, чем скоп в пять строк, — поэтому крупный builder разбивают на мелкие функции-условия, каждая из которых, кстати, снова скоп по форме. Гибрид работает лучше всего: волатильный динамический WHERE собирает buildQuery, а стабильные хвосты наклеиваются скопами — пагинация из семнадцатого урока ложится следом одной строкой, сортировка-белый список сидит в карте, обязательная база — в композитном скопе списка. Это не война парадигм, а деление труда: скопы для словаря политик, builder для произвольных фильтров API.

Настоящий список-эндпоинт отвечает двумя запросами: сколько всего и одна страница. Builder здесь раскрывается полностью: сборщик зову дважды, и оба раза от чистого db — ловушка сохранённой цепочки не при делах, потому что ни одна сборка не финишируется дважды. Первая сборка считает total: buildQuery(db.Model(&TodoItem{}), f).Count(&total) — те же фильтры, что и у страницы, поэтому число честное. Вторая собирает страницу: buildQuery(db, f).Order(order).Offset((page-1)size).Limit(size).Find(&items) — offset-формула и потолок размера страницы остались в семнадцатом уроке; туда же по ссылку, если нужно освежить границы и метку «есть ещё». Для глубокой ленты offset уступает курсору: добавьте в фильтр указатель-курсор и в buildQuery один if — if f.After != nil { q = q.Where("id < ?", f.After) } — и лента станет keyset-пагинацией, где сортировка обязана иметь тай-брейк по ключу. Обратите внимание, как органично курсор-указатель сочетается с темой nil-фильтров: первая страница приходит с nil-курсором и клоз не добавляется вовсе. Обе сборки делят один filterExprs и один sortColumns — фильтры и порядок вычисляются в одном месте, а Count и Find лишь выбирают, что с этим делать: посчитать или отрезать страницу.

Сборщик — чистая логика над клозами, и его хочется тестировать без базы. Это ровно режим DryRun из доки: DryRun Generates SQL without executing. It can be used to prepare or test generated SQL. Подаёте цепочке сессию db.Session(&gorm.Session{DryRun: true}) — финишер соберёт Statement и вернётся без поездки в СУБД, а след читается из stmt.SQL.String() и аргументы из stmt.Vars. Десятый урок уже показывал DryRun в деле; теперь у него системная работа — таблица тестов для сборщика: строка фильтров на входе, ожидаемый SQL и ожидаемые Vars на выходе. Собрали buildQuery — прогнали три случая: пустой фильтр с одной базой, полный набор клозов, чужое имя сортировки с дефолтом. Честности ради — две оговорки доки. Первая: разные диалекты генерируют разный SQL — PostgreSQL подставляет $1, MySQL знак вопроса, поэтому тест прикалывается к конкретному драйверу, как и SQL-следы этого курса. Вторая: итоговый SQL не всегда безопасно исполнять руками — GORM only uses it for logs, а из логгера строка выходит не полностью экранированной; тест сверяет плейсхолдеры и Vars, а не собранный со значениями текст. DryRun закрывает ещё один сценарий: логирование сборки в CI — падение теста покажет ровно тот клоз, который съел ваши фильтры.

Builder-стиль держится на соседних уроках всем составом. Материал клозов — строки с плейсхолдерами, структурная форма и её нулевые поля, карта, IN с пустым срезом, ИЛИ и скобки — это седьмой урок про Where. Окно страницы, offset-формула, курсор и тай-брейк сортировки остались в семнадцатом уроке — пагинация наклеивается на собранный builder-ом WHERE одной строкой. Кирпичи-политики, замыкания-фабрики и композитный скоп списка разобраны в девятнадцатом уроке — там же честный контракт func(db gorm.DB) gorm.DB, который builder унаследовал. Ловушка сохранённой цепочки и Session(&gorm.Session{}) — шестой урок, DryRun — десятый, индексы под сортировку и фильтры — восемнадцатый. Карта всех тем курса — на странице курса. Дальше строится мост к данным, которых в Go нет: двадцать первый урок — «Работа с NULL и указателями» — заберёт указательные фильтры этого урока в модель и покажет sql.Null-типы, nullable-теги и то, как NULL из базы превращается в ноль или указатель в коде. Динамические запросы собраны — теперь научимся честно хранить отсутствующие значения.