← Блог
10 мин чтения
|
Опубликовано
|
Обновлено

Стратегии ограничения частоты API для разработчиков

Сравните фиксированное окно, скользящее окно, токен-корзину и дырявое ведро, реализуйте их атомарно через Redis Lua и отправляйте заголовки RateLimit.

Главы
C
Chaingateway Team
Эксперты по блокчейну

Проверил(а) Maurice Sobiera

Блоки входят в шлюз, который выпускает их по одному с постоянной скоростью

Ограничение частоты API (rate limiting) задаёт, сколько запросов клиент может отправить за период, чтобы один клиент не перегрузил сервис и не вытеснил других. Для большинства публичных API хорошим выбором по умолчанию служит счётчик скользящего окна: он почти точен и использует постоянный объём памяти на клиента. Если вы хотите разрешать всплески, используйте токен-корзину.


TL;DR:

  • Счётчик скользящего окна балансирует точность и память, поэтому подходит для общих публичных API с большим трафиком.
  • Скрипты Redis Lua делают шаги чтения, пополнения и списания атомарными, поэтому параллельные запросы не могут конкурировать между собой.
  • Скорость пополнения чуть выше обычного трафика p99, а ёмкость на 5–10 секунд всплеска — разумные стартовые значения.
  • Сообщайте клиентам их лимиты заголовками RateLimit и отправляйте Retry-After с каждым ответом 429.
  • Применяйте лимиты на границе и в приложении, а для каждого эндпоинта заранее решайте, что происходит, когда Redis недоступен.

Содержание

Как сравниваются основные алгоритмы ограничения частоты?

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

АлгоритмСостояние на клиентаТочностьПоведение при всплескахТипичное применение
Фиксированное окноОдин счётчикПриблизительнаяДопускает до 2 лимитов на границах оконПростые лимиты API, ограничение входа
Журнал скользящего окнаУпорядоченное множество меток времениТочнаяВсплесков нетAPI высокой ценности, журналы аудита
Счётчик скользящего окнаДва счётчикаПочти точнаяСглаженные границыУниверсальные лимиты API
Токен-корзинаХеш с количеством токенов и временем пополненияТочнаяДопускает контролируемые всплескиПульсирующий трафик со средним ограничением
Дырявое ведроХеш с одним или двумя полямиТочнаяВсплесков нет, равномерный сливКонтроль трафика перед хрупким бэкендом

Выбирайте по главному ограничению. Фиксированное окно дешевле всего в работе. Журнал скользящего окна точен, но его память растёт вместе с объёмом запросов. Счётчик скользящего окна даёт почти точные результаты при постоянной памяти. Токен-корзина подходит API для разработчиков, которым нужен запас на всплески, а дырявое ведро подходит для очередей перед чувствительными к нагрузке бэкендами.

Заметки о реализации каждого алгоритма

Каждому алгоритму нужна своя структура состояния и своя стоимость выполнения, поэтому выбор алгоритма — это, по сути, выбор структуры данных.

Таблица из пяти алгоритмов ограничения частоты (фиксированное окно, скользящий журнал, скользящий счётчик, токен-корзина, дырявое ведро) с признаками точности и памяти

Фиксированное окно хранит один счётчик на клиента и временной интервал. Он увеличивается с каждым запросом и сбрасывается, когда интервал заканчивается. Слабое место — граница. При лимите 100 запросов в минуту клиент может отправить 100 запросов в 12:00:59 и ещё 100 в 12:01:00. Это 200 запросов за две секунды, поэтому фиксированное окно используйте только для грубых лимитов с низким риском.

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

Счётчик скользящего окна хранит два счётчика: один для текущего окна и один для предыдущего. Он взвешивает количество предыдущего окна по доле, которая ещё перекрывается со скользящим окном. Возьмём лимит 100 в минуту, 80 запросов в предыдущей минуте и 30 за текущую, когда прошла 25 процентов текущей минуты. Оценка составит 80 × 0,75 + 30 = 90. У клиента осталось около 10 запросов.

Cloudflare описывает этот подход для собственного ограничения частоты. Ему нужны всего два числа на счётчик. По данным Cloudflare, в анализе 400 миллионов запросов от 270 000 различных источников 0,003 процента запросов были ошибочно разрешены или ограничены.

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

Дырявое ведро бывает в двух формах. Форма контроля (policing) отбрасывает запросы, которые превышают скорость слива. Форма шейпинга (shaping) ставит их в очередь на последующую обработку. Используйте её, когда эндпоинт стоит перед базой данных или сторонним сервисом, который не выдерживает всплесков.

Совет: Оборачивайте пополнение и списание в один скрипт Lua вместо отдельных вызовов GET и SET. Последовательность «чтение, затем запись» в два обращения к серверу — именно та гонка, для предотвращения которой существуют атомарные скрипты.

Как построить ограничитель, который работает на нескольких экземплярах?

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

  1. Храните счётчики в Redis, чтобы каждый экземпляр приложения читал и писал одно и то же состояние.
  2. Используйте скрипты Redis Lua, чтобы объединить шаги чтения, пополнения и списания в одну атомарную операцию. Руководство Redis объясняет причину: при отдельных командах параллельные запросы могут прочитать одно и то же состояние, оба решить, что проходят, и оба записать результат.
  3. Для сервисов с большим объёмом агрегируйте счётчики локально на экземпляре или на точке присутствия, прежде чем синхронизировать их с центральным хранилищем. Так не нужен вызов Redis на каждый запрос.
  4. Добавьте дырявое ведро на уровне шлюза, например в NGINX, как внешнюю стену против злоупотребляющего трафика. Более тонкие лимиты по ключу держите в приложении.
  5. Решите для каждого эндпоинта между fail-open и fail-closed до того, как инцидент заставит принять решение.

Используйте fail-open на публичных эндпоинтах с преобладанием чтения, чтобы сбой Redis не остановил весь API. Используйте fail-closed на эндпоинтах аутентификации и платежей, где неограниченный трафик представляет больший риск.

Совет: Логируйте каждое событие fail-open отдельно от обычного трафика. Сбой Redis, который тихо отключает ваши лимиты, обычно выясняется только на разборе инцидента.

Какой алгоритм подходит какому эндпоинту?

Перед написанием кода проверьте четыре вещи. Сколько памяти можно тратить на клиента? Законны ли всплески или они угроза? Насколько хрупка нижестоящая система? Допустимы ли оценки вместо точных счётчиков?

Тип эндпоинтаРекомендуемый алгоритмПричина
Публичные API для разработчиковСчётчик скользящего окна или токен-корзинаОба выдерживают разумные всплески без накладных расходов на точный подсчёт
Платежи и аутентификацияЖурнал скользящего окна или fail-closed по умолчаниюТочный подсчёт, а отказ безопаснее, чем пропуск подозрительного трафика
Потоки, ограниченные нижестоящим сервисомДырявое ведроСкорость выдачи никогда не превышает то, что выдержит бэкенд
Внутренний трафик с большим объёмом и низким рискомФиксированное окноСамая простая реализация, а всплески на границах допустимы

Если вы не можете сказать, что происходит, когда Redis недоступен, проект не завершён, каким бы алгоритмом вы ни воспользовались.

Как сообщать клиентам об их лимитах?

Передавайте текущее состояние лимита в заголовках ответа и отправляйте Retry-After с каждым ответом 429. Клиенты не должны гадать, в каком положении они находятся.

Рабочая группа IETF по HTTP API стандартизирует заголовки в черновике RateLimit header fields for HTTP. В текущей редакции (draft 11, май 2026) поле RateLimit-Policy описывает квоту, а поле RateLimit сообщает, что осталось:

RateLimit-Policy: "default";q=100;w=60
RateLimit: "default";r=50;t=30

Здесь q — квота, w — окно в секундах, r — оставшаяся квота, а t — секунды до сброса окна. Это заменяет более старые редакции черновика, которые использовали отдельные поля RateLimit-Limit, RateLimit-Remaining и RateLimit-Reset. Многие API по-прежнему отправляют заголовки с префиксом производителя X-RateLimit-*, которые появились раньше черновика. Поскольку черновик не финальный, проверьте текущую редакцию, прежде чем выбирать формат.

Отклонённый запрос должен получать статус 429. RFC 6585 определяет его как Too Many Requests. Ответ может содержать заголовок Retry-After с количеством секунд ожидания, как в примере из RFC:

HTTP/1.1 429 Too Many Requests
Retry-After: 3600

На практике придерживайтесь этих правил:

  • Отправляйте заголовки лимита в каждом ответе, а не только при отказах.
  • Отправляйте Retry-After каждый раз, когда отклоняете запрос с 429.
  • Относитесь к заголовкам как к подсказкам. Черновик указывает, что клиенты не должны считать, будто положительная доступная квота гарантирует выполнение следующих запросов.
  • На стороне клиента используйте экспоненциальную задержку с джиттером вместо фиксированной паузы, чтобы повторы не приходили синхронными волнами.

Настройка скорости пополнения, ёмкости и оповещений

Начинайте с измеренного трафика, а не с догадок. Возьмите из метрик p95 и p99 запросов в секунду на клиента и задайте скорость пополнения немного выше устойчивого p99, чтобы обычное использование никогда не срабатывало на ограничитель. Ёмкость корзины подбирайте так, чтобы она поглощала примерно 5–10 секунд трафика p99. Это стартовые значения, а не стандарт.

Например, если у одного клиента p99 составляет 20 запросов в секунду, скорость пополнения 24 в секунду и ёмкость 200 токенов позволяют всплеск из 200 запросов. После такого всплеска корзине нужно 200 / 24, примерно 8,3 секунды, чтобы полностью восстановиться.

После запуска ограничителя следите за такими сигналами:

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

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

Совет: Когда вы ужесточаете лимит, объявите изменение и новые заголовки потребителям API до выпуска. Неожиданный 429 без контекста создаёт больше обращений в поддержку, чем злоупотребление, которое он должен был остановить.

Где эти схемы встречаются в продакшене

Большинство продакшен-стеков разделяет контроль между двумя слоями.

  • Граница: конфигурация дырявого ведра в NGINX поглощает злоупотребляющий трафик и очевидный скрейпинг до того, как он дойдёт до серверов приложений.
  • Приложение: скрипт Redis Lua, реализующий токен-корзину или счётчик скользящего окна, применяет лимиты по ключу, обычно с fail-open на эндпоинтах только для чтения.
  • Публичные API для разработчиков: счётчик скользящего окна или токен-корзина, настроенные под тарифный план клиента.
  • Эндпоинты аутентификации: строгие лимиты с малой ёмкостью, часто с fail-closed.
  • Обработчики вебхуков: дырявое ведро или ограничитель на базе очереди, потому что повторы от отправляющего сервиса нужно сглаживать, а не просто отклонять.

Справедливость и защита от злоупотреблений

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

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

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

Три отдельные полосы запросов, у каждой свой шлюз; всплеск красных блоков в одной полосе не замедляет две другие

Источники

Рекомендуем

Часто задаваемые вопросы

Сочетайте алгоритм, подходящий шаблону трафика, с атомарным применением. Счётчик скользящего окна подходит для универсальных API, а токен-корзина — для клиентов с всплесками. Атомарное применение означает, что параллельные запросы не могут обойти лимит. Лимиты на границе плюс лимиты по ключу в приложении добавляют второй уровень, как в подходе Cloudflare.

Храните счётчики или состояние токенов в общем хранилище, например Redis, и оберните шаги чтения, пополнения и списания в один атомарный скрипт Lua. Возвращайте заголовки RateLimit в каждом ответе, а заголовок Retry-After — при отказах, чтобы клиенты знали, как себя вести.

Проверьте бюджет памяти, толерантность к всплескам и хрупкость нижестоящих систем. Затем подберите алгоритм под эти ограничения: счётчик скользящего окна или токен-корзину для публичных API, журнал скользящего окна или fail-closed по умолчанию для чувствительных эндпоинтов. Настраивайте скорость пополнения по измеренному трафику p99.

Ограничение частоты API задаёт, сколько запросов клиент может сделать за определённый период. Оно защищает сервис от перегрузки и поддерживает справедливое распределение ресурсов между клиентами. Серверы обычно сообщают лимит и остаток квоты в заголовках ответа, которые стандартизирует черновик IETF RateLimit.

Как мы пишем эти статьи

Готовы собрать это сами? Получите свой API-ключ — 7-дневный пробный период, без карты — или посмотрите API блокчейна для полного справочника по эндпоинтам.

C
Chaingateway Team
Эксперты по блокчейну

Команда Chaingateway стремится упростить интеграцию блокчейна для разработчиков по всему миру.