← Назад к блогу

Практика системного анализа · 5 минут

Пагинация API: как проверить пропуски и дубли при изменении данных

Как проверить полноту страниц при изменении данных: воспроизвести дубли offset, задать семантику снимка и сверить множество ID, порядок и токен окончания.

Проверка пагинации сопоставляет объединение страниц с ожидаемым набором объектов. Корректный JSON одной страницы не доказывает полноту выгрузки. Между запросами данные могут измениться: смещение укажет на другую строку, а курсор продолжит обход уже другого множества.

Дубль после вставки

Учебный API возвращает заявки по убыванию числового ID. Размер страницы — два объекта. Исходный набор: [106, 105, 104, 103, 102, 101]. Данные и ответы сконструированы для разбора; рабочий API не вызывался.

Первая страница при offset=0 содержит [106, 105]. Между запросами появляется заявка 107. Теперь начало списка выглядит как [107, 106, 105, 104]. Вторая страница при offset=2 содержит [105, 104]: объект 105 пришёл повторно.

Это воспроизводимый эффект смещения на изменяемом списке. Если вместо вставки удалить уже прочитанную строку 106, список станет [105, 104, 103, 102, 101]. Запрос с offset=2 вернёт [103, 102]; объект 104 выпадет из обхода.

Проверка должна смотреть на ID всех страниц. Количество элементов на каждой из них в обоих случаях выглядит допустимым.

Сначала выбрать обещание выгрузки

Перед тестированием нужно договориться, какой набор система обещает вернуть. Возможны разные контракты: фиксированный снимок на начало обхода, продолжение по живому списку или выгрузка изменений после контрольной точки. Они требуют разных ожиданий.

Для примера выберем снимок S0 с шестью исходными ID. Добавления и удаления после его создания не меняют состав S0. Сервер должен поддерживать такую семантику: одного имени snapshot в ответе недостаточно.

ШагИзменение живых данныхСтраница из S0
1Снимок создан106, 105
2Добавлен 107104, 103
3Удалён 102 из живого списка102, 101
4Конец обходаПустой токен продолжения

Возврат удалённого 102 допустим только в выбранном контракте исторического снимка. Для живого списка ожидание было бы другим. Не следует использовать эту таблицу как универсальное требование к любому API.

Почему курсора может не хватить

Курсор задаёт способ продолжения. Он не гарантирует снимок, срок жизни набора или стабильность полей сортировки. Если API сортирует по изменяемому updated_at, объект может перескочить через границу уже прочитанной страницы.

Для сортировки по времени нужен устойчивый порядок при совпадении значений, например пара (created_at, id). Оба поля должны входить в условие продолжения. В нашем числовом примере ID уникален и неизменяем, поэтому дополнительное поле не требуется.

Google AIP-158 описывает непрозрачные токены страниц и сохранение параметров запроса при продолжении. Аналитик должен отдельно выяснить, что токен означает для конкретного API: позицию, снимок или иной серверный контекст. Формат токена не даёт этого ответа.

Проверки объединения

Для снимка ожидаемое множество равно {101,102,103,104,105,106}. После обхода нужны три самостоятельных проверки:

  1. Все возвращённые ID входят в S0, все ID S0 присутствуют в результате.
  2. Количество полученных элементов равно количеству уникальных ID.
  3. Порядок убывает на каждой странице и между страницами; токен окончания завершает обход.

Первая проверка ловит пропуски и лишние объекты. Вторая находит дубли. Третья проверяет порядок и завершение обхода. Проверка только количества не замечает замену 104 на повторный 105.

Ещё один тест меняет фильтр при продолжении. Контракт должен определить отказ или начало нового обхода; молчаливое смешение двух фильтров сделает результат непроверяемым. Отдельно проверяют истёкший токен, повтор запроса той же страницы и нулевой результат поиска.

Что передать команде

Результат анализа — набор S0, расписание мутаций и ожидаемые страницы. LLM может составить дополнительные перестановки, но каждую нужно связать с выбранной семантикой. Формулировка «добавить тесты cursor pagination» не заменяет эти данные.

Если сервер не поддерживает снимок, исправьте контракт и ожидания до автоматизации. Нельзя объявлять API дефектным лишь за то, что он реализует живой обход, когда документация именно это и обещает.

Проверку формата отдельного ответа дополняют ошибки и границы OpenAPI. Расхождение ожидаемого поведения и примеров удобно оформить по разбору контракта API.

Вопросы по пагинации

Почему валидная страница не доказывает полноту?

Схема проверяет форму ответа. Она не знает ожидаемый состав объединения страниц и не обнаружит объект, который сервер ни разу не вернул.

Курсор всегда устраняет пропуски?

Нет. Результат зависит от сортировки, изменяемости полей и обещаний сервера. Курсор без снимка может обходить живое множество.

Нужно ли включать новые записи в текущую выгрузку?

Это решение контракта. В примере снимок S0 исключает ID 107; другая семантика может включать его при соблюдении собственных правил.

Как проверить дубли без знания полного набора?

Сравните длину списка ID с размером множества ID. Это обнаружит повторы, но не докажет отсутствие пропущенных объектов.

Что фиксировать в дефекте пагинации?

Исходный набор, сортировку, фильтр, токены, изменения между запросами и фактические страницы. Без этой последовательности ошибку трудно воспроизвести.

Автор: Иннокентий Бодров, автор Аналитической мастерской.