Пагинация и сортировка — Offset/Limit, Order и keyset-пагинация в GORM

Живой сервис редко показывает таблицу целиком: лента задач, история заказов, лог событий — всё это отдаётся страницами, и размер страницы выбираете вы, а не база. В SQL за это отвечают три клоза: LIMIT ограничивает число строк, OFFSET пропускает начало, ORDER BY фиксирует порядок — без него «страница» вообще не определена, база вправе вернуть строки в любом порядке. GORM оборачивает всё тремя методами цепочки, и дока описывает их без лишних слов: Limit — specify the max number of records to retrieve («задать максимум строк»), Offset — specify the number of records to skip before starting to return the records («сколько строк пропустить перед выдачей»), Order — specify order when retrieving records from the database. Шестой урок уже трогал Limit(1) внутри First — здесь разберём пару Limit/Offset как самостоятельный инструмент: внутренности clause.Limit, отмены условий, сортировку по нескольким полям, цену OFFSET на глубоких страницах и заменяющий её keyset-курсор.

Сверим chainable_api.go. Limit(limit int) — это одна строка: tx.Statement.AddClause(clause.Limit{Limit: &limit}); Offset(offset int) — тоже одна: tx.Statement.AddClause(clause.Limit{Offset: offset}). Оба метода пишут в один и тот же клоз: в clause/limit.go у структуры clause.Limit{Limit int; Offset int} метод Name() возвращает «LIMIT», так что оба вызова дополняют одно место в запросе, а не создают два клоза. Слияние делает MergeClause: новый лимит перетирает старый, если задан; новый offset перетирает старый, если ненулевой; отрицательный offset обнуляется. Отсюда свойство, которое стоит запомнить как таблицу умножения: порядок Limit и Offset в цепочке не важен — db.Limit(10).Offset(5) и db.Offset(5).Limit(10) дают идентичный клоз. Доковский след «SELECT FROM users OFFSET 5 LIMIT 10» описывает семантику, а Build в clause/limit.go печатает сначала LIMIT, потом OFFSET — порядок клозов в тексте запроса; PostgreSQL принимает оба, MySQL требует LIMIT первым. Кому нужна байтовая точность следа — смотрите на логгер своего диалекта. Отмена через минус единицу работает по той же схеме: MergeClause сохраняет старое значение только для nil и нуля, минус единица проходит дальше, а Build печатает LIMIT лишь при значении не меньше нуля и OFFSET — при положительном. Кто ищет по запросу limit offset gorm, обычно спотыкается ровно здесь: хочет «отменить» лимит нулём, а ноль в цепочке означает «не трогать».

Дока формулирует предмет одной строкой: Specify order when retrieving records from the database. Строковая форма самая частая: db.Order("age desc, name").Find(&users) даёт ORDER BY age desc, name — несколько полей и направлений в одной строке через запятую. Вторая доковская форма — цепочка из нескольких Order: db.Order("age desc").Order("name").Find(&users) даёт тот же ORDER BY age desc, name: клозы накапливаются. Механика — в clause/order_by.go: MergeClause приклеивает новые колонки к уже накопленным в порядке вызовов, а флаг Reorder у OrderByColumn обрубает накопленное и начинает список заново — пригодится в скопах, когда базовый порядок надо заменить, а не дополнить. Третья форма — Expression: доковский пример с clause.OrderBy{Expression: clause.Expr{SQL: "FIELD(id,?)", Vars: []interface{}{[]int{1, 2, 3}}, WithoutParentheses: true}} сортирует строки в заданном порядке значений — ORDER BY FIELD(id,1,2,3). Пустая строка игнорируется: Order("") не добавит клоза, в chainable_api.go стоит проверка if v != "". И связка, которую стоит знать заранее: First и Last из finisher_api.go дописывают свою сортировку по первичному ключу в конец вашего списка — ваша колонка выигрывает, ключ лишь ломает ничьи между равными.

Седьмой урок ввёл правило: пользовательский ввод — только через аргументы, а для конечных множеств — белые списки; там же перечислены методы, чьи строковые аргументы не экранируются, и Order в их числе. Теперь источник этой правды виден буквально: в chainable_api.go строковая форма оборачивается в clause.Column{Name: v, Raw: true} — Raw означает, что строка будет вписана в SQL как есть, без кавычек и без экранирования. Вклеили туда пользовательский sort=created_at с мусором — получили инъекцию через сортировку: ORDER BY вычисляется для каждой строки результата, и через условные подзапросы из него вытаскивают данные не хуже, чем через WHERE. Параметр сортировки из API — типичная ловушка: «сортировать по колонке X по убыванию» звучит как запрос строки, но строкой его отдавать нельзя. Безопасный путь — белый список: карта разрешённых колонок, направление отдельным списком ASC/DESC, и только после проверки собирать Order из констант. Структурная форма OrderByColumn добавляет кавычки через WriteQuoted, но не проверяет существование колонки — имя всё равно сверяйте со схемой. Тот же принцип действует для Group и Select: меняется клоз, правило нет.

Дока отвечает на вопрос «зачем» сразу: The Count method in GORM is used to retrieve the number of records that match a given query — число записей, подходящих под запрос (gorm.io/docs/advanced_query.html). Внутри finisher_api.go Count(&count) делает три вещи, о которых стоит знать. Первая: если своего SELECT нет, клоз временно подменяется на count() — доковские комментарии показывают SELECT count(1) FROM users, а в исходниках дефолтное выражение count(); для счёта это одно и то же число. Вторая: ORDER BY при подсчёте выбрасывается — если клоза ORDER BY есть и GROUP BY нет, Count удаляет её, выполняет запрос и возвращает на место через defer; сортировать строки, которые вы лишь считаете, — лишняя работа для базы. Третья: с GROUP BY, а также во всех случаях, когда вернулось не ровно одна строка, в count записывается RowsAffected — доковский пример с Group("name") на четырёх пользователях с тремя разными именами даёт count => 3. Distinct работает: Distinct("name").Count(&count) даёт COUNT(DISTINCT(...)). Парного финишера «посчитай и отдай страницу» одним вызовом в ядре нет — grep по исходникам пуст; в первой версии библиотеки существовал FindAndCount, во второй ветке пара Count + Find собирается руками. Цена вопроса: каждый Count — отдельный полный проход по индексу, платить его на каждый клик по страницам не обязательно — об этом ниже.

Пользователь приходит с номером страницы, а не со смещением. Перевод — одна строка: offset := (page - 1) * pageSize — третья страница по десять записей начинается с OFFSET 20. Но номер страницы — данные из внешнего мира, им нужны границы. Доковский Paginate из scopes.html (там же: Refer to Pagination for details on how to make a paginator) ставит ровно три: page <= 0 -> 1, pageSize <= 0 -> 10 и потолок pageSize > 100 -> 100 — потолок одной строкой кода защищает базу от запроса page_size=1000000. Для интерфейса обычно нужен и total: totalPages := (total + pageSize - 1) / pageSize — целочисленный потолок деления, без float. Стоит понимать цену. OFFSET n просит базу прочитать и выбросить n строк: OFFSET 100000 на большой таблице — сто тысяч отсканированных строк ради десяти, и чем глубже страница, тем дороже поездка. Вторая беда — дрейф: вставка или удаление между запросами сдвигает все окна, и строки дублируются или пропадают при листании. Для глубокой ленты это лечится keyset-курсором — следующий блок; для админки с пятьюдесятью страницами offset достаточен.

Keyset меняет вопрос: не «пропусти n строк», а «дай следующие n после курсора». Курсор — значение сортировочного ключа последней показанной строки, чаще всего первичный ключ. Лента с новыми сверху: db.Where("id < ?", lastID).Order("id DESC").Limit(n).Find(&feed) — строго меньше последнего показанного ключа, новые вперёд. Прямая хроника зеркальна: db.Where("id > ?", lastID).Order("id ASC").Limit(n).Find(&next) — та самая формула через WHERE id > ? ORDER BY id LIMIT n, которой шестнадцатый урок обещал пагинацию. Выигрыш двойной. Скорость: вместо сканирования и выбрасывания offset строк база делает поиск по индексу — логарифм на любой глубине страницы. Стабильность: окно привязано к ключу, а не к позиции, поэтому вставки и удаления между запросами не сдвигают страницы — дрейфа нет. Цена тоже честная. Произвольного доступа нет: «прыгнуть на страницу семь» нельзя, только «ещё». Total без отдельного Count не узнать. И сортировка обязана быть полной: при упорядочивании по created_at добавляйте тай-брейк по ключу — ORDER BY created_at DESC, id DESC, иначе строки с одинаковым временем будут теряться на границе курсора. Индекс, который делает такой поиск быстрым, — тема следующего урока.

Шестнадцатый урок обронил фразу про LIMIT n+1 — теперь развяжем. Метка «есть ещё» нужна почти каждой ленте, и первый порыв — посчитать total через Count. Но Count — отдельный полный проход по индексу на каждый запрос страницы, ради одного бита информации. Приём дешевле: попросите на одну строку больше, чем нужно, — Limit(n + 1), — и посмотрите на длину ответа. Вернулось n+1 строк — следующая страница существует; срежьте хвост items[:n] и не показывайте лишнее. Вернулось n или меньше — это была последняя страница. Работает одинаково с keyset (курсором для следующего запроса служит ключ строки n) и с offset-окнами (запасная строка лежит сразу за окном). Сам приём — не специфичное GORM-решение, а общий приём SQL, но он честно сочетается с методами, которые вы уже знаете: Limit(n + 1).Find. Когда Count всё же нужен — нумерованные страницы и подпись «найдено 1234»: там без total интерфейс не собрать, и цену прохода приходится платить; для бесконечных лент хватает HasNext. И не забудьте срезать запасную строку до сериализации — иначе клиент получит n+1 запись и сломает вёрстку.

Разбор page/pageSize хочется написать один раз и применять к любой модели. Для этого в GORM есть Scopes: chainable_api.go складывает функции-фильтры в Statement.scopes, и executeScopes применяет их к цепочке перед выполнением; полный разбор скоупов ждёт девятнадцатый урок, здесь — базово. Дока показывает канонический скоп Paginate (scopes.html#pagination): func Paginate(r http.Request) func(db gorm.DB) gorm.DB читает page и page_size из параметров URL, ставит дефолты и потолок, считает offset := (page - 1) pageSize и возвращает db.Offset(offset).Limit(pageSize). Применение — два вызова на разных моделях: db.Scopes(Paginate(r)).Find(&users) и db.Scopes(Paginate(r)).Find(&articles): один хелпер, ноль дублирования. Дженерик-обёртка FetchPage[T] — тот же приём, свёрнутый в функцию: типизированный срез, границы и HasNext через запасную строку внутри. В generics.go у новой цепочки gorm.G[T] Limit, Offset, Order и Count(ctx, column) есть из коробки — связка «страница плюс счёт» на типах. Выбор формы за вами: скоп — для цепочек, дженерик — для сервисных функций.

Пагинация опирается на соседние темы курса. Ловушка chaining и финишеры разобраны в шестом уроке, правило белых списков для строковых клозов — в седьмом уроке про Where, конвейер, из которого растёт AfterFind у длинных выборок, — в шестнадцатом уроке про хуки. Дальше по маршруту: восемнадцатый урок «Индексы и производительность» покажет, какие индексы делают keyset и offset-выборки быстрыми и почему поиск по курсору без них теряет смысл; девятнадцатый урок «Скоупы и переиспользование запросов» развернёт Scopes, на которых построен Paginate. Карта из 25 уроков — на странице курса. Домашка ниже гоняет страницы по канону от первой до последней.