Конфигурация HTTP-клиента

Настройки читаются из глобального Setup с префиксом api.. Для интерфейса @Api(name = "catalog") используется секция api.catalog:

api.catalog.<параметр>=<значение>

Секция обязательна даже при передаче URL вторым аргументом getClient().

Общие параметры

Ключ По умолчанию Назначение

api.<key>.name

пустая строка

Человекочитаемое имя. Используется в сообщениях и description MBean. Если оно пустое, MBean получает имя ключа API.

api.<key>.url

нет

Base URL. Обязателен, если URL не передан в getClient(clazz, url).

api.<key>.ignoreSSL

false

Отключает проверку сертификата и имени узла для этого клиента.
ignoreSSL=true принимает любой сертификат и любое имя узла. Настройка допустима только для контролируемого тестового контура и не должна использоваться для обхода проблем сертификата в рабочей среде.

HTTP и логирование

Ключ По умолчанию Назначение

api.<key>.http.connectTimeout

10000

Тайм-аут установления соединения, мс.

api.<key>.http.readTimeout

10000

Тайм-аут чтения ответа, мс.

api.<key>.http.logLevel

NONE

Уровень HttpLoggingInterceptor: NONE, BASIC, HEADERS или BODY.

Уровень BODY пишет тела запросов и ответов, а HEADERS — заголовки. В них могут оказаться токены, персональные данные и большие документы. Включать эти уровни следует только на ограниченное время и после проверки состава данных.

Пул соединений и Dispatcher

Ключ По умолчанию Назначение

api.<key>.http.pool.idle

5

Максимальное число простаивающих соединений OkHttp.

api.<key>.http.pool.keepAlive

5

Срок хранения простаивающего соединения.

api.<key>.http.pool.timeUnit

MINUTES

Единица java.util.concurrent.TimeUnit для keepAlive.

api.<key>.worker.pool.maxRequests

64

Максимум одновременно выполняемых запросов Dispatcher.

api.<key>.worker.pool.maxRequestsPerHost

5

Максимум одновременно выполняемых запросов к одному узлу.

Пул соединений и Dispatcher создаются лениво при сборке первого клиента и кэшируются по ключу @Api.name. Поэтому разные интерфейсы с одинаковым name делят эти компоненты.

Rate Limiter

Rate Limiter Resilience4j ограничивает число начатых вызовов за период. Он отключён по умолчанию.

Ключ По умолчанию Назначение

api.<key>.rate.limiter.enabled

false

Включить ограничитель.

api.<key>.rate.limiter.limitRefreshPeriod

500

Период пополнения разрешений, мс.

api.<key>.rate.limiter.limitForPeriod

50

Число разрешений на период.

api.<key>.rate.limiter.timeoutDuration

10000

Сколько ждать свободное разрешение, мс.

Если разрешение не появилось за timeoutDuration, клиент выбрасывает BGMessageException с сообщением о превышении частоты запросов.

Circuit Breaker

Circuit Breaker Resilience4j прекращает обращения к нестабильному сервису. Он отключён по умолчанию и использует автоматический переход OPEN → HALF_OPEN.

Ключ По умолчанию Назначение

api.<key>.circuit.breaker.enabled

false

Включить Circuit Breaker.

api.<key>.circuit.breaker.failureRateThreshold

50

Процент ошибок, после которого цепь открывается.

api.<key>.circuit.breaker.waitDurationInOpenState

10000

Время состояния OPEN до перехода в HALF_OPEN, мс.

api.<key>.circuit.breaker.slowCallRateThreshold

50

Допустимый процент медленных вызовов.

api.<key>.circuit.breaker.slowCallDurationThreshold

60000

Порог медленного вызова, мс.

api.<key>.circuit.breaker.permittedNumberOfCallsInHalfOpenState

3

Число пробных вызовов в состоянии HALF_OPEN.

api.<key>.circuit.breaker.slidingWindowSize

10

Размер скользящего окна вызовов.

api.<key>.circuit.breaker.minimumNumberOfCalls

10

Минимум накопленных вызовов до расчёта процента ошибок.

Ошибками для Circuit Breaker считаются TimeoutException, IOException, ApiException и ResourceNotFoundException. Наследники BGException, включая BGMessageException, не меняют его статистику. Поведение исключений на границе компонента описано в разделе об ошибках.

Полный пример

api.catalog.name=Каталог товаров
api.catalog.url=https://catalog.example.test/
api.catalog.ignoreSSL=false

api.catalog.auth.type=STATIC_TOKEN
api.catalog.auth.header=Authorization
api.catalog.auth.token=<service-token>

api.catalog.http.connectTimeout=5000
api.catalog.http.readTimeout=15000
api.catalog.http.logLevel=BASIC
api.catalog.http.pool.idle=5
api.catalog.http.pool.keepAlive=5
api.catalog.http.pool.timeUnit=MINUTES

api.catalog.worker.pool.maxRequests=32
api.catalog.worker.pool.maxRequestsPerHost=8

api.catalog.rate.limiter.enabled=true
api.catalog.rate.limiter.limitRefreshPeriod=1000
api.catalog.rate.limiter.limitForPeriod=20
api.catalog.rate.limiter.timeoutDuration=2000

api.catalog.circuit.breaker.enabled=true
api.catalog.circuit.breaker.failureRateThreshold=50
api.catalog.circuit.breaker.waitDurationInOpenState=10000
api.catalog.circuit.breaker.slowCallRateThreshold=50
api.catalog.circuit.breaker.slowCallDurationThreshold=5000
api.catalog.circuit.breaker.permittedNumberOfCallsInHalfOpenState=3
api.catalog.circuit.breaker.slidingWindowSize=10
api.catalog.circuit.breaker.minimumNumberOfCalls=10

Параметры авторизации приведены отдельно в разделе авторизации.

Изменение настроек без перезапуска

getClient() каждый раз заново читает конфигурацию и строит Retrofit/OkHttp. Уже полученный объект API не обновляется. После изменения настройки код должен получить клиент повторно либо использовать поставщик, который делает это перед вызовом.

Пулы и компоненты Resilience4j сравнивают новую конфигурацию с закэшированной. При отличии компонент пересоздаётся и его MBean регистрируется заново. Из-за текущей реализации первый getClient() после изменения ещё получает прежний компонент, а пересозданный начинает использоваться со следующего getClient().