API-фильтр дает разные результаты при одинаковом запросе: как исправить

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

Сохраните два полных request с headers и ответы с ID записей. Сравните endpoint version, tenant, timezone, выбранную реплику, cache status и порядок. Добавьте уникальный tie-breaker к сортировке и повторите тест на неизменяемом наборе данных.

Что проверить в первую очередь

Начните с одного воспроизводимого сценария. Зафиксируйте точное время, идентификатор объекта, пользователя или операции, версию приложения и последнее известное рабочее состояние. Не меняйте несколько параметров одновременно: один контролируемый шаг должен подтверждать или исключать одну гипотезу. Перед работой с данными и конфигурацией подготовьте резервную копию и проверенный способ отката.

• Проверьте явный ORDER BY и наличие уникального поля в конце сортировки.
• Сравните offset or cursor и изменения данных между запросами.
• Убедитесь, что все параметры, tenant и права входят в cache key.
• Проверьте timezone, locale, null handling и нормализацию дат.

Почему возникает проблема

Внешний симптом часто появляется дальше по цепочке, чем первичная ошибка. Интерфейс может показывать неверное состояние из-за backend, очереди, кеша, прав доступа, фоновой задачи или внешнего API. Поэтому важно проследить данные от источника до результата и найти первую точку расхождения, а не исправлять только последнее сообщение об ошибке.

• ORDER BY использует неуникальное created_at, и строки с равным значением меняются местами.
• Offset pagination смещается при вставке или удалении записей.
• Реплики отстают и возвращают разные версии данных.
• Кеш не учитывает один фильтр, роль или заголовок языка.
• Даты интерпретируются в локальном timezone разных серверов.

Пошаговая диагностика

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

• Запишите сгенерированный SQL и bind parameters для тестового запроса.
• Выполните запрос несколько раз на одной транзакционной snapshot.
• Добавьте временно ORDER BY выбранное поле plus primary key.
• Проверьте cache key и Vary-like параметры на фактическом запросе.
• Сравните primary and replica lag, transaction isolation и время обновления индекса поиска.

Как обеспечить детерминированную выборку

Фильтр должен иметь каноническое представление параметров и полный стабильный порядок. Для изменяемых больших наборов cursor pagination надежнее offset, если cursor содержит все поля сортировки и однозначный ID.

• Параметры валидируются, нормализуются и сортируются перед формированием cache key.
• ORDER BY завершается уникальным primary key как tie-breaker.
• Cursor кодирует последнее значение каждого поля сортировки.
• Требования к свежести определяют, можно ли читать с replica или search index.

Как исправить проблему

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

• Добавьте стабильную сортировку с уникальным ID.
• Перейдите с offset на cursor для ленты, изменяемой между запросами.
• Исправьте cache key, включив tenant, права и все влияющие параметры.
• Нормализуйте даты в UTC на границе API и явно документируйте interval semantics.
• Для критичных read-after-write запросов используйте primary или механизм ожидания нужной версии.

Безопасный порядок внедрения

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

Как проверить результат

Разовый успешный тест недостаточен. Повторите операцию, проверьте крайние значения, одновременные действия и восстановление после перезапуска или временного сбоя. Для важного сценария сохраните автоматический тест либо короткий регрессионный чек-лист. Итог должен подтверждаться не только интерфейсом, но и состоянием базы, очереди, внешнего сервиса и журналом действий.

• Повтор одного запроса на неизменных данных возвращает одинаковый порядок ID.
• Переход по cursor не пропускает и не дублирует элементы при новых вставках.
• Разные tenant и роли не получают общий кешированный ответ.
• Границы дат одинаковы на всех экземплярах приложения.

Типичные ошибки при исправлении

• Добавлять случайную сортировку или сортировать только на клиенте.
• Считать primary key неважным при равных значениях основного поля.
• Кешировать по URL, игнорируя права и скрытые server-side filters.
• Исправлять проблему увеличением page size.

Как предотвратить повторение

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

• Добавьте contract tests повторяемости и пагинации на одинаковых данных.
• Логируйте query fingerprint, cache hit и data source без чувствительных значений.
• Контролируйте replica lag и задержку поискового индекса.
• Документируйте сортировку, timezone и поведение null для клиентов API.

Что контролировать после выпуска

• Количество успешных и ошибочных операций в разрезе версии, канала и типа сценария.
• Возраст необработанных записей, длину очередей, число повторных попыток и долю окончательных отказов.
• Расхождение между пользовательским статусом и фактическим состоянием в базе или внешней системе.
• Появление новых кодов ошибок после релиза и изменение времени выполнения ключевой операции.
• Сигналы от поддержки и бизнес-метрики, которые могут показать скрытый частичный сбой.

Что подготовить для технического разбора

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

Частые вопросы

Всегда ли cursor pagination лучше offset?

Для быстро меняющихся больших наборов обычно надежнее. Offset удобен для небольших стабильных списков и перехода к номеру страницы.

Может ли причина быть в базе данных?

Да. Без полного ORDER BY SQL не гарантирует постоянный порядок, а реплики и уровни изоляции могут показывать разные версии.

Когда нужна помощь специалиста

Если API-фильтры пропускают или дублируют записи, я могу воспроизвести запрос, проверить SQL, кеш и реплики, затем внедрить стабильную сортировку и pagination contract.