Как обычно реализуются пагинация и фильтрация данных в API?

Question

Пагинация разбивает большой результат на страницы. Чаще всего используется пагинация по смещению (offset) с параметрами ?page=2&limit=50 или по курсору (cursor) с параметром ?after=cursor_token. Курсорная пагинация более эффективна для больших и часто меняющихся данных. Фильтрация позволяет выбирать подмножество данных по критериям через параметры запроса, например: ?status=active&min_price=100. Параметры фильтрации должны быть интуитивно понятными, документированными и безопасными (чтобы избежать инъекций). Часто пагинация и фильтрация используются вместе.

YeaHub · Accepted Answer

Пагинация и фильтрация — обязательные механизмы для любого API, возвращающего потенциально большие коллекции данных. Они повышают производительность (меньше данных за раз), снижают нагрузку на сеть и БД, и улучшают UX клиента.Реализация пагинации (Pagination)Цель — возвращать данные порциями (страницами).Пагинация по смещению (Offset-based Pagination):Как работает: Клиент указывает номер страницы (page) и размер страницы (limit/per_page). Сервер вычисляет смещение: offset = (page - 1) * limit.Пример запроса: GET /api/users?page=3&per_page=20Как реализовать (SQL):sqlSELECT * FROM users ORDER BY id LIMIT 20 OFFSET 40; -- (page=3, per_page=20)Плюсы: Простота понимания и реализации. Позволяет переходить к произвольной странице (random access).Минусы: Неэффективна на больших смещениях. OFFSET 10000 заставляет БД пройти через 10000 записей, прежде чем вернуть нужные. Данные могут "уплывать" при вставке/удалении между запросами (дубли или пропуски).Пагинация по курсору (Cursor-based Pagination):Как работает: Клиент получает "указатель" (курсор) на последний элемент текущей страницы и использует его для запроса следующей. Курсор — это закодированное значение уникального, упорядочиваемого поля (например, id или created_at).Пример запроса: GET /api/users?limit=20&after=eyJpZCI6NDB9 (где after — курсор, указывающий на последний ID предыдущей страницы).Как реализовать (SQL):sqlSELECT * FROM users WHERE id > :last_seen_id ORDER BY id LIMIT 20;Плюсы: Высокая производительность, так как использует индекс по полю курсора. Устойчива к изменениям данных (новые записи не ломают навигацию "вперед").Минусы: Не позволяет перепрыгнуть на произвольную страницу (только последовательная навигация "вперед/назад"). Сложнее в реализации, особенно для составных курсоров.Что возвращать в ответе API:Массив данных на текущей странице.Мета-информацию: total_count (для offset), has_next_page, has_prev_page, next_cursor, prev_cursor.Реализация фильтрации (Filtering)Цель — позволить клиенту ограничивать результаты по определенным критериям.Подходы к параметрам запроса:Прямые параметры: GET /api/products?category=books&in_stock=trueОператоры сравнения (часто через суффиксы):price_gt=100 (цена больше 100)created_at_before=2023-12-31name_like=*apple* (поиск по подстроке)Специальный параметр filter или query: Можно передавать сложные условия в формате JSON или специальном языке запросов. Более мощный, но сложнее в документировании и использовании.Ключевые аспекты:Безопасность: Все параметры фильтрации должны быть валидированы и экранированы для защиты от SQL-инъекций. Никогда не подставлять их напрямую в запрос.Документация: Четко документировать все доступные параметры фильтрации, их типы и допустимые значения.Индексы: Поля, по которым часто фильтруют, должны быть проиндексированы в БД для скорости.Пример безопасной реализации на сервере:python# Допустимые поля для фильтрации
ALLOWED_FILTERS = {'category', 'min_price', 'max_price', 'status'}

def get_products(request):
    query = Product.objects.all()  # ORM-запрос (например, Django)

# Обрабатываем каждый разрешенный параметр
    if 'category' in request.GET:
        query = query.filter(category=request.GET['category'])
    if 'min_price' in request.GET:
        # Безопасное преобразование типа
        query = query.filter(price__gte=float(request.GET['min_price']))
    if 'status' in request.GET and request.GET['status'] in ['active', 'draft']:
        query = query.filter(status=request.GET['status'])

# Применяем пагинацию (курсорную)
    cursor = decode_cursor(request.GET.get('after'))
    if cursor:
        query = query.filter(id__gt=cursor['id'])
    paginated_results = query.order_by('id')[:PAGE_SIZE]
    return paginated_resultsКомбинирование пагинации и фильтрацииОбычно фильтрация применяется первой, чтобы получить нужное подмножество данных, а затем к этому подмножеству применяется пагинация.Пример конечного запроса:GET /api/orders?status=completed&min_total=500&limit=50&after=MzA=Это означает: "Дай 50 завершенных заказов с суммой больше 500, следующих после курсора MzA=".ВыводСтоит применять курсорную пагинацию для лент новостей, логов, любых длинных последовательностей данных, где важна производительность и стабильность. Offset-пагинацию можно использовать для небольших, статичных справочников, где нужен переход к конкретной странице. Фильтрацию необходимо проектировать исходя из потребностей клиента, всегда обеспечивая валидацию и документирование параметров. Правильная реализация этих механизмов — признак зрелого и продуманного API.