Скоупы и переиспользование запросов — func(db *gorm.DB) *gorm.DB, замыкания и композитные условия в GORM

К восьмому хендлеру проекта возникает узнаваемая боль: каждый метод репозитория начинается с одного и того же — только невыполненные задачи, сортировка по времени, ограничение размера. Копировать эти три строки в десять мест значит гарантированно однажды поправить их в шести. GORM предлагает встроенный ответ на эту боль — скоупы. Страница доки scopes.html открывается определением: Scopes allow you to re-use commonly used logic, the shared logic needs to be defined as type func(gorm.DB) gorm.DB. Разберём фразу по частям. Во-первых, re-use commonly used logic — переиспользование повторяющейся логики, ровно та копипаста, от которой мы хотим уйти. Во-вторых, контракт: func(gorm.DB) gorm.DB — функция, принимающая цепочку и возвращающая цепочку. Это тот же самый тип, который имеют результаты методов Where, Order и Limit, поэтому скоп встаёт в любое место запроса и не отличим для базы от условий, написанных руками. В-третьих, никакого отдельного реестра, интерфейса или генерации кода: скоуп — это просто функция в вашем пакете, которую вы зовёте руками, передаёте аргументом и тестируете как любую другую.

Что физически делает db.Scopes? Смотрим в chainable_api.go, и ответ обескураживает своей краткостью: метод вызывает getInstance(), дописывает переданные функции в срез Statement.scopes и возвращает цепочку. Всё. Ни одна ваша функция в этот момент не вызывается — Scopes лишь копит их на будущее. Исполнение происходит позже, при финишере: в callbacks.go метод processor.Execute перед любой операцией крутит цикл for len(db.Statement.scopes) > 0 { db = db.executeScopes() }, а executeScopes очищает срез и по очереди прогоняет цепочку через каждую функцию. Из этой механики следуют три практических вывода. Первый: скопы исполняются при любом финишере — Find, First, Take, Count, Update, Delete, — потому что все они проходят через один и тот же processor.Execute. Второй: порядок гарантирован — функции применяются в том порядке, в каком перечислены в Scopes, и каждая работает с результатом предыдущей. Третий: условия скопов всегда оказываются в WHERE после условий, добавленных методами цепочки напрямую, — цепочку Where вы построили до финишера, а скопы выполняются уже внутри него. Срез Statement.scopes живёт внутри Statement, а не в конфиге, поэтому скопы — часть конкретной цепочки, а не глобального состояния.

Базовый скоп — функция без памяти: одно условие, одни и те же значения. Как только фильтр должен подстраиваться под ввод, включается вторая ступень — параметризованный скоп. Дока показывает его на заказах: func OrderStatus(status []string) func (db gorm.DB) gorm.DB возвращает func (db gorm.DB) gorm.DB, внутри которой return db.Scopes(AmountGreaterThan1000).Where("status IN (?)", status). Конструкция двухэтажная, и это самое важное: внешняя функция — фабрика, она принимает значение и возвращает скоп; значение фиксируется замыканием и живёт внутри внутренней функции. Вызов OrderStatus([]string{"paid", "shipped"}) — это уже готовый скоп, как StatusScope, только с зашитым внутрь списком статусов. Полный пример из доки собирает три кирпича: db.Scopes(AmountGreaterThan1000, PaidWithCod).Find(&orders) — заказы COD дороже тысячи, db.Scopes(AmountGreaterThan1000, OrderStatus([]string{"paid", "shipped"})).Find(&orders) — оплаченные и отправленные дороже тысячи. Фабрики композируются свободно: один и тот же AmountGreaterThan1000 работает в обеих сборках. Замыкание здесь — не экзотика, а способ передать данные в фильтр, не протаскивая их через глобальные переменные и не ломая контракт func(gorm.DB) gorm.DB.

Настоящая сила подхода раскрывается на композитных условиях — сборках, где несколько фильтров работают одновременно. Правило сборки простое: Where-база и Scopes-фильтры не конкурируют, а складываются. База — это то, что вызывающий пишет руками: db.Where("priority >= ?", 2) как обязательный контекст конкретного хендлера. Фильтры — то, что вносится скопами: каждая функция дописывает свой клоз, и все они склеиваются через AND. Порядок выражений в WHERE предсказуем: сначала условия, добавленные методами цепочки, затем условия скопов — в том порядке, в каком скопы перечислены и в каком вызывались сами db.Scopes. Второе правило композиции: скоп может быть композитором, то есть звать Scopes сам. Так устроен OrderStatus из доки — его внутренняя функция начинает с db.Scopes(AmountGreaterThan1000), подтягивая чужой фильтр, и только потом добавляет своё условие по статусам. Так скоупы gorm образуют не плоский список, а дерево: мелкие кирпичи — одно условие, средние — комбинации, композитный скоп уровня ForList — готовая политика целой страницы. Логику ИЛИ не размазывайте по соседним скопам — каждый скоп склеивается с соседями через AND, поэтому ветвление прячьте внутрь одного фильтра группой условий, как показывал седьмой урок.

Семнадцатый урок уже показал скоп Paginate — и это не случайность, а эталон жанра: Paginate(r http.Request) func(db gorm.DB) gorm.DB читает page и page_size из параметров URL, защищает границы (page <= 0 превращается в единицу, pageSize <= 0 — в десятку, потолок — 100) и возвращает db.Offset(offset).Limit(pageSize) с формулой offset := (page - 1) pageSize. Здесь нам важен не пересчёт границ — он остался в семнадцатом уроке, — а сам факт: пагинация идеально ложится на формат скопа, потому что это универсальный, не зависящий от модели хвост запроса. Один и тот же Paginate обслуживает db.Scopes(Paginate(r)).Find(&users) и db.Scopes(Paginate(r)).Find(&articles), не зная ни про одну структуру. В связке с фильтрами получается полный конвейер страницы: db.Scopes(StatusScope, Paginate(r)).Find(&items) — отфильтруй, потом порежь на страницы. Для глубокой навигации по ленте offset из семнадцатого урока уступает курсору — keyset-условию WHERE id < ?, и это тоже собирается скопом: параметризованный фабричный фильтр с курсором плюс ограничитель размера. Метка «есть ещё» из семнадцатого урока — запрос pageSize+1 строк и срез хвоста — работает без изменений поверх любой такой сборки.

Пора собрать всё в композитный скоп уровня политики — именованный фильтр целой страницы. В каталоге задач это ForList: только невыполненные, свежие вперёд, тай-брейк по ключу, фиксированный размер двадцать. Код — пять строк, но за ними стоит архитектурное решение: SQL-политика списка живёт в одном месте, и хендлеры перестают её дублировать. Композитный скоп устроен как OrderStatus из доки — внутри он зовёт Scopes: ForList подтягивает StatusScope как базу и добавляет сортировку с лимитом. Вызывающий код сокращается до db.Scopes(ForList).Find(&items), а точечные надстройки клеятся следом без редактирования ForList: db.Scopes(ForList, PriorityScope).Find(&items) — тот же список, но только с высоким приоритетом. Когда продакт просит показывать выполненные тоже, меняется одна строка в одном скопе — и все хендлеры курса обновляются. Это и есть переиспользование в строгом смысле: не «скопировать условие», а «сослаться на владельца условия». Отдельный бонус — тест: скоп чистая функция, ей можно подать DryRun-цепочку и сверить собранный SQL с эталоном, не трогая базу; DryRun из десятого урока здесь работает без изменений.

Дока явно выделяет раздел Scope examples for updating/deleting — скопы работают не только на чтение. Канонический пример CurOrganization(r) решает типовую задачу API: разрезать таблицу по организации из параметров запроса. Внутри фабрики происходит важный трюк: org := r.Query("org"), затем db.Session(&Session{}).First(&organization, "name = ?", org) — внутренний запрос выполняется на свежем statement, который Session создаёт с нуля, поэтому поиск организации не подмешивает свои условия и скопы в ту цепочку, которую скопу передали. Если организация нашлась, фабрика возвращает db.Where("org_id = ?", organization.ID) — готовый фильтр по чужому ключу; если нет — db.AddError("invalid organization") и return db: это тот же механизм регистрации ошибки, что мы применяли в хуках шестнадцатого урока, цепочка доедет до финишера и вернёт ошибку наверх. Применение — оба финишера записи: db.Model(&article).Scopes(CurOrganization(r)).Update("Name", "name 1") превращается в UPDATE articles SET name = "name 1" WHERE org_id = 111, а db.Scopes(CurOrganization(r)).Delete(&Article{}) — в DELETE FROM articles WHERE org_id = 111. Скоп на записи — это страховка от самого дорогого бага ORM: массового апдейта или удаления, потерявшего WHERE.

Четвёртый раздел доки — Use Scopes to dynamically set the query Table: скоп имеет право поменять не только WHERE, но и FROM. Фабрика TableOfYear(user User, year int) собирает имя таблицы конкатенацией user.TableName() + strconv.Itoa(year) и возвращает db.Table(tableName); вызовы DB.Scopes(TableOfYear(user, 2019)).Find(&users) и DB.Scopes(TableOfYear(user, 2020)).Find(&users) дают SELECT FROM users_2019 и SELECT FROM users_2020 — один и тот же код читает годовые секции таблицы. Соседняя фабрика TableOfOrg уводит таблицу в чужую базу: tableName := dbName + "." + user.TableName() — и DB.Scopes(TableOfOrg(user, "org1")).Find(&users) исполняет SELECT FROM org1.users. Приём стоит держать в загашнике для партиций по времени и мультитенантных схем, но с одной жёсткой оговоркой о безопасности: имя таблицы не параметризуется плейсхолдерами — Table вставляет его в SQL как есть, поэтому конкатенация годится только из доверенных источников, вроде внутренних справочников и конфигов. Значение, пришедшее из HTTP-параметра, обязано пройти белый список допустимых суффиксов, иначе скоп превратится в дыру: то же правило строк против белых списков, что и в седьмом уроке, только ставка выше — FROM инъецируется так же охотно, как WHERE.

Слово «встроенные» в заголовке требует честности: реестра именованных скопов, который можно было бы импортировать, в GORM нет — db.Scopes принимает исключительно функции с контрактом func(gorm.DB) gorm.DB, и строкой «paid» он воспользоваться не даст. Встроенное — это не список готовых фильтров, а три другие вещи. Первая — сама механика: срез Statement.scopes в цепочке, цикл executeScopes при каждом финишере и исполнение скопов даже внутри подзапросов — когда gorm.DB используется аргументом условия, statement.go явно вызывает v.executeScopes() на вложенной цепочке, так что фильтры сработают и там. Вторая — единая форма: любой метод-цепочка (Where, Order, Limit) возвращает gorm.DB, поэтому ваши скопы и встроенные методы взаимозаменяемы внутри одной сборки, а Session даёт свежий statement для внутренних запросов скопа, как в CurOrganization. Третья — четыре шаблона из доки, Query, Pagination, Dynamically Table и Updates, которые вместе покрывают практически весь спрос: фильтрация, страницы, таблицы, запись. Всё остальное — ваша территория, и в этом дизайн библиотеки: GORM не навязывает репозиторий, а даёт точку входа db.Scopes и контракт, который уживается с любой архитектурой — от простых хендлеров до слоёв репозиториев с собственным DSL фильтров, к чему мы и перейдём в следующем уроке.

Скоупы держатся за соседние темы курса всем составом. Условия, из которых сделан любой фильтр, — строковая и структурная формы, IN, LIKE, Or и Not — разобраны в седьмом уроке про Where. Скоп-пагинация Paginate с границами page и page_size, offset-формула и метка «есть ещё» без COUNT остались в семнадцатом уроке. Составной индекс ленты idx_feed, под который заточен FeedScope, и цена индексов при записи — в восемнадцатом уроке; карта всех тем курса — на странице курса. Следующий рубеж заберёт двадцатый урок — «Динамические запросы и builder-стиль»: когда фильтры приходят из API произвольным набором, заранее заготовленные скопы перестают угадывать форму запроса, и на сцену выходит ручная сборка клозов по условиям — безопасные фильтры API без копипасты и без инъекций. Замыкания и композитные кирпичи этого урока там не пропадут: builder тоже собирается из функций, просто ядро сборки переезжает с db.Scopes на явную работу с клозами.