Асинхронный клиент полезен, когда программа много ждёт сеть. Но заменить обычный цикл на запуск тысячи задач недостаточно. Без ограничений можно перегрузить внешний сервис, исчерпать соединения и получить волну повторов. Правильный старт - небольшой список, общий клиент, явный лимит и понятные правила ошибок.
Подставное API позволяет проверить частичный успех и ограниченный повтор без реальных сетевых вызовов.
В примере HTTP API полностью подставной: MockTransport возвращает ответы внутри процесса. Никакие реальные сервисы не вызываются. Так можно воспроизвести временную ошибку и проверить клиент без ключа, расходов и случайных ограничений внешнего поставщика.
Разделите три ограничения
Семафор ограничивает число одновременно выполняемых участков кода. Пул соединений HTTPX ограничивает сетевые подключения. Ограничение частоты задаёт, сколько запросов допустимо за интервал времени. Это разные механизмы: три параллельных запроса могут всё равно выполняться слишком часто для конкретного тарифа API.
Таймаут тоже состоит из частей: соединение, чтение, запись и ожидание подключения из пула. Установите значения сознательно по задаче. Отдельный общий предел времени может ограничивать всю операцию, включая ожидание и повторные попытки. Один параметр таймаута не обязательно заменяет остальные уровни.
Проверяйте документацию внешнего API: допустимую частоту, заголовки повторения, лимиты и требования к идентичности операции. В учебном клиенте ниже правила упрощены и не являются универсальной политикой для любого сайта.
Когда повтор имеет смысл
Для безопасного чтения иногда допустим повтор после временной сетевой ошибки или статуса вроде 429 и 503. Но неправильную авторизацию 401 обычно нужно исправлять, а не долбить тем же запросом. Ошибка валидации 400 тоже не исчезнет от короткого ожидания.
Если запрос создаёт заказ, платёж или публикацию, таймаут не доказывает отсутствия результата. Сначала нужны идемпотентный контракт или сверка. Приведённый пример выполняет только GET к подставному источнику и поэтому не демонстрирует безопасный повтор внешней записи.
Задержка между попытками должна предотвращать одновременную волну повторов. В реальной системе полезны ограниченное экспоненциальное ожидание, случайное смещение и корректное соблюдение Retry-After, если он предоставлен. В тесте используется короткая детерминированная задержка, чтобы проверка была воспроизводимой.
Минимальный клиент с подставным транспортом
import asyncio
import httpx
calls = {}
def handler(request):
path = request.url.path
calls[path] = calls.get(path, 0) + 1
if path == "/limited" and calls[path] == 1:
return httpx.Response(429, json={"error": "try later"})
if path == "/bad":
return httpx.Response(400, json={"error": "invalid request"})
return httpx.Response(200, json={"path": path})
async def fetch(client, path, semaphore):
for attempt in range(3):
async with semaphore:
response = await client.get(path)
if response.status_code in {429, 502, 503, 504} and attempt < 2:
await asyncio.sleep(0.01 * (2 ** attempt))
continue
response.raise_for_status()
return response.json()
raise RuntimeError("attempt limit")
async def main():
semaphore = asyncio.Semaphore(3)
async with httpx.AsyncClient(
base_url="https://example.test",
transport=httpx.MockTransport(handler),
timeout=httpx.Timeout(5.0, connect=2.0),
limits=httpx.Limits(max_connections=3),
) as client:
results = await asyncio.wait_for(
asyncio.gather(
*(fetch(client, p, semaphore)
for p in ["/ok", "/limited", "/bad"]),
return_exceptions=True,
), timeout=2.0,
)
assert results[0] == {"path": "/ok"}
assert results[1] == {"path": "/limited"}
assert isinstance(results[2], httpx.HTTPStatusError)
assert calls["/limited"] == 2
assert calls["/bad"] == 1
asyncio.run(main())
Временный 429 повторился один раз и завершился ответом. Ошибка 400 сохранилась как отдельное исключение и не уничтожила результаты двух других чтений. return_exceptions=True здесь выбран осознанно: вызывающий код должен просмотреть каждый элемент и не выдать исключение за успешные данные.
Общий клиент повторно использует настройки и ресурсы. Создание нового клиента внутри каждого шага лишает процесс части преимуществ пула и усложняет управление соединениями. Закрытие через async with делает время жизни клиента явным.
Что пример не скрывает за коротким кодом
В нём не повторяются сетевые исключения: они возвращаются в результате gather и требуют отдельной классификации. Если добавите обработку TransportError, ограничьте число попыток и не расширяйте повтор на любые исключения. Ошибка разбора JSON может означать изменившийся контракт, а не временную сеть.
Подставной транспорт не проверяет реальный TLS, работу DNS, скорость сервера и фактическое ограничение частоты. Для интеграционной проверки нужен разрешённый тестовый endpoint. Не называйте успешный тест с MockTransport доказательством доступности production API.
Если вход содержит миллионы адресов, создание задачи на каждый сразу может занять много памяти, даже при семафоре на сетевой участок. Используйте ограниченную очередь и фиксированное число исполнителей. Ограничение активных запросов и ограничение объёма ожидающей работы решают разные проблемы.
Сохраните наблюдаемость
Записывайте идентификатор задачи, число попыток, итоговый статус и длительность, исключая секреты и лишние личные данные. Не помещайте API-ключ в URL, который потом окажется в журнале. Ошибку можно описать безопасным типом и кодом, не выводя весь ответ авторизации.
Если часть чтений не удалась, возвращайте частичный результат с явным списком ошибок или отклоняйте весь отчёт по заранее выбранному правилу. Молчаливо пропустить неудачные записи и назвать итог полным опасно для дальнейших решений.
Упражнения и ответы
- Измените первый ответ
/limitedна 401. Сколько попыток будет? Одна, поскольку 401 не входит в список повторяемых статусов. - Возвращайте 503 всегда. Что произойдёт? После трёх попыток
raise_for_statusсоздаст ошибку; бесконечного цикла нет. - Лимит соединений равен трём. Гарантирует ли это три запроса в секунду? Нет: параллельность и частота различаются.
Частые вопросы
Asyncio ускоряет тяжёлые вычисления? Этот пример выигрывает от организации ожидания, а не от параллельного выполнения процессорной работы.
Нужно ли повторять любой таймаут? Нет. Учитывайте тип операции, неизвестный результат и контракт внешней системы.
Можно ли скрыть ошибки в пустом списке? Лучше явно показать их вызывающему коду, иначе пустой ответ будет трудно отличить от отсутствия данных.
Откройте Кодик, чтобы посмотреть доступные учебные направления и выбрать подходящий маршрут. Сначала воспроизведите ошибки на подставном транспорте, затем подключайте разрешённый тестовый источник.
