Практика системного анализа · 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 | Добавлен 107 | 104, 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}. После обхода нужны три самостоятельных проверки:
- Все возвращённые ID входят в S0, все ID S0 присутствуют в результате.
- Количество полученных элементов равно количеству уникальных ID.
- Порядок убывает на каждой странице и между страницами; токен окончания завершает обход.
Первая проверка ловит пропуски и лишние объекты. Вторая находит дубли. Третья проверяет порядок и завершение обхода. Проверка только количества не замечает замену 104 на повторный 105.
Ещё один тест меняет фильтр при продолжении. Контракт должен определить отказ или начало нового обхода; молчаливое смешение двух фильтров сделает результат непроверяемым. Отдельно проверяют истёкший токен, повтор запроса той же страницы и нулевой результат поиска.
Что передать команде
Результат анализа — набор S0, расписание мутаций и ожидаемые страницы. LLM может составить дополнительные перестановки, но каждую нужно связать с выбранной семантикой. Формулировка «добавить тесты cursor pagination» не заменяет эти данные.
Если сервер не поддерживает снимок, исправьте контракт и ожидания до автоматизации. Нельзя объявлять API дефектным лишь за то, что он реализует живой обход, когда документация именно это и обещает.
Проверку формата отдельного ответа дополняют ошибки и границы OpenAPI. Расхождение ожидаемого поведения и примеров удобно оформить по разбору контракта API.
Вопросы по пагинации
Почему валидная страница не доказывает полноту?
Схема проверяет форму ответа. Она не знает ожидаемый состав объединения страниц и не обнаружит объект, который сервер ни разу не вернул.
Курсор всегда устраняет пропуски?
Нет. Результат зависит от сортировки, изменяемости полей и обещаний сервера. Курсор без снимка может обходить живое множество.
Нужно ли включать новые записи в текущую выгрузку?
Это решение контракта. В примере снимок S0 исключает ID 107; другая семантика может включать его при соблюдении собственных правил.
Как проверить дубли без знания полного набора?
Сравните длину списка ID с размером множества ID. Это обнаружит повторы, но не докажет отсутствие пропущенных объектов.
Что фиксировать в дефекте пагинации?
Исходный набор, сортировку, фильтр, токены, изменения между запросами и фактические страницы. Без этой последовательности ошибку трудно воспроизвести.
Автор: Иннокентий Бодров, автор Аналитической мастерской.