Основные понятия#

Eazy SDK разделяет описание API, доставку запроса и данные пользователя. Это позволяет менять HTTP-клиент или собирать несколько сервисов, не переписывая операции.

У каждого объекта одна роль.

Объект	Отвечает на вопрос	Что в нём хранится
Операция	Что отправить и какой результат вернуть?	Поля запроса, метод, путь, типы ответов
Роутер	Какие операции принадлежат одному сервису?	Операции, адрес и общие правила сервиса
Клиент	Как доставить байты?	Обработчик, соединения, повторы, ограничения транспорта
Корень SDK	Как собрать публичный SDK?	Группы роутеров и привязки к клиентам
`Identity`	От чьего имени идёт вызов?	Авторизация, ключи подписи, зависимости, наблюдатель

Операция описывает один вызов#

Операцию объявляют неизменяемым классом. Её поля становятся аргументами публичного метода и указывают, куда попадёт каждое значение: в путь, строку запроса, заголовок или тело. Объявление транспорта задаёт HTTP-метод и путь, а параметр типа у HttpOperation задаёт результат.

При вызове роутера SDK создаёт значение операции, проверяет план запроса и передаёт его в общий конвейер исполнения. Поэтому сигнатура метода известна редактору кода до первого запроса.

Роутер описывает сервис#

SyncApi и AsyncApi публикуют операции через op(...). Роутер также хранит контракт, общий для сервиса: адрес, ошибки, требования к авторизации, подпись, шифрование и формат данных. Эти правила наследуются операциями, если более точное объявление их не переопределило.

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

Клиент доставляет байты#

Client и AsyncClient связывают SDK с обработчиком HTTP. Клиент управляет соединениями, повторами, перенаправлениями, лимитом частоты и защитой транспорта. Он не решает, какие методы есть у сервиса и кто выполняет запрос.

Жизненный цикл клиента задаёт код, который его создал. Роутер или корень, получивший готовый клиент через конструктор, не закрывает его за вызывающий код.

Корень собирает несколько роутеров#

SyncRoot и AsyncRoot образуют публичную точку входа в большой SDK. api_group(...) добавляет роутер как именованную группу, например sdk.messages или sdk.auth. Сам корень операций не объявляет.

По умолчанию группы используют клиент корня. Привязка через bind(...) может дать отдельному сервису другой клиент или адрес. Группы создаются при первом обращении и затем используются повторно.

Identity представляет вызывающую сторону#

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

Один Identity, переданный корню, обслуживает все его роутеры. Чтобы работать от имени другого пользователя, создайте другой Identity; новый пул соединений для этого не нужен.

Как объекты связаны#

Прикладной код вызывает операцию на роутере. Роутер добавляет правила сервиса, корень выбирает для него клиент, а Identity даёт данные вызывающей стороны. Клиент выполняет подготовленный запрос и возвращает ответ в общий конвейер. Там SDK сопоставляет ответ с объявленным типом результата.

Если SDK состоит из одного роутера, корень не обязателен. Если запросы не требуют авторизации, подписи, внедрения зависимостей или наблюдения, можно не передавать Identity.