← Все статьи

Типизированные асинхронные HTTP-клиенты

Несколько решений, которые делают Python-клиенты API предсказуемыми и не скрывают работу HTTP-слоя.

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

Не скрывайте границу транспорта

Принимайте httpx.AsyncClient (или небольшой совместимый с ним протокол), а не создавайте незаметно новый клиент для каждого запроса. Тогда вызывающее приложение может управлять пулом соединений, таймаутами, прокси и тестовым транспортом.

from typing import Protocol

class AsyncTransport(Protocol):
    async def get(self, url: str, **kwargs: object) -> "Response": ...

Сам протокол может быть уже, чем интерфейс полноценной HTTP-библиотеки. Важно не забирать у вызывающей стороны конфигурацию, которую библиотека не может обоснованно выбрать за неё.

Ошибки — часть контракта

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

Не превращайте каждую ошибку в None. Отсутствующий ресурс, недоступная сеть и сломанный ответ сервера требуют разной обработки.

Типизируйте границу, а не каждую переменную

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

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

← Другие статьиСвязаться →