HTTP клиент

Модуль HTTP-клиента описывает исходящие HTTP-вызовы приложения: реализацию транспорта, преобразование запроса, преобразование ответа, телеметрию и перехватчики. В Kora типизированные клиенты описываются декларативно через @HttpClient и @HttpRoute, либо используется общий интерфейс HttpClient напрямую, когда запрос нужно собрать в коде.

Декларативный подход подходит для большинства интеграций с внешними службами: контракт метода становится контрактом удаленного вызова, а Kora во время компиляции создает реализацию без использования Reflection во время работы. Императивный подход полезен для низкоуровневых или динамических сценариев, где путь, заголовки, параметры или тело запроса удобнее собирать вручную.

Все вызовы HTTP-клиента в Kora синхронные и блокирующие: HttpClient.execute() возвращает HttpClientResponse напрямую, а декларативный метод сразу возвращает результат. Параллелизм обеспечивается виртуальными потоками, а не реактивными или корутинными типами возврата.

Если нужен пошаговый разбор перед справочным описанием, смотрите HTTP-клиент и продвинутый HTTP-клиент.

OkHttp¶

Реализация HTTP-клиента на базе библиотеки OkHttp. Сам модуль Kora написан на Java, но библиотека OkHttp написана на Kotlin и тянет собственные зависимости. Этот транспорт стоит выбирать, если нужны HTTP/2 или HTTP/3, сжатие GZip либо иные специфичные для OkHttp настройки.

Подключение¶

implementation "io.koraframework:http-client-ok"

@KoraApp
public interface Application extends OkHttpClientModule { }

implementation("io.koraframework:http-client-ok")

@KoraApp
interface Application : OkHttpClientModule

Реализацией интерфейса HttpClient выступает OkHttpClient из пакета io.koraframework.http.client.ok.

Конфигурация¶

Основные параметры конфигурации клиента OkHttp:

httpClient {
    connectTimeout = "5s" //(1)!
    readTimeout = "2m" //(2)!
}

httpClient:
  connectTimeout: "5s" #(1)!
  readTimeout: "2m" #(2)!

httpClient {
    ok {
        followRedirects = true //(1)!
        retryOnConnectionFailure = true //(2)!
        httpVersion = "HTTP_1_1" //(3)!
    }
    connectTimeout = "5s" //(4)!
    readTimeout = "2m" //(5)!
    useEnvProxy = false //(6)!
    proxy {
        host = "localhost" //(7)!
        port = 8090 //(8)!
        user = "user" //(9)!
        password = "password" //(10)!
        nonProxyHosts = [ "host1", "host2" ] //(11)!
    }
}

httpClient:
  ok:
    followRedirects: true #(1)!
    retryOnConnectionFailure: true #(2)!
    httpVersion: "HTTP_1_1" #(3)!
  connectTimeout: "5s" #(4)!
  readTimeout: "2m" #(5)!
  useEnvProxy: false #(6)!
  proxy:
    host: "localhost" #(7)!
    port: 8090  #(8)!
    user: "user"  #(9)!
    password: "password" #(10)!
    nonProxyHosts: [ "host1", "host2" ] #(11)!

Телеметрия не настраивается в секции транспорта: логирование, метрики и трассировка настраиваются для каждого декларативного клиента по пути httpClient.<clientName>.telemetry, смотрите Конфигурацию клиента.

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

Конфигуратор¶

Построитель транспорта настраивается компонентом Configurer<OkHttpClient.Builder>. Kora применяет его последним, уже после собственной настройки:

@Component
public final class SomeConfigurer implements Configurer<OkHttpClient.Builder> {

    @Override
    public OkHttpClient.Builder configure(OkHttpClient.Builder builder) {
        return builder.callTimeout(Duration.ofSeconds(30));
    }
}

@Component
class SomeConfigurer : Configurer<OkHttpClient.Builder> {

    override fun configure(builder: OkHttpClient.Builder): OkHttpClient.Builder {
        return builder.callTimeout(Duration.ofSeconds(30))
    }
}

Configurer находится в пакете io.koraframework.common и является общим контрактом настройки всех транспортов Kora.

Apache HttpClient¶

Реализация HTTP-клиента на базе Apache HttpClient 5. Используется классический (блокирующий) API и пул соединений, что напрямую соответствует синхронному контракту клиента Kora.

Подключение¶

implementation "io.koraframework:http-client-apache"

@KoraApp
public interface Application extends ApacheHttpClientModule { }

implementation("io.koraframework:http-client-apache")

@KoraApp
interface Application : ApacheHttpClientModule

Реализацией интерфейса HttpClient выступает ApacheHttpClient из пакета io.koraframework.http.client.apache.

Конфигурация¶

Основные параметры конфигурации Apache HttpClient:

httpClient {
    connectTimeout = "5s" //(1)!
    readTimeout = "2m" //(2)!
}

httpClient:
  connectTimeout: "5s" #(1)!
  readTimeout: "2m" #(2)!

httpClient {
    apache {
        followRedirects = true //(1)!
        maxRedirects = 3 //(2)!
        maxConnections = 1000 //(3)!
    }
    connectTimeout = "5s" //(4)!
    readTimeout = "2m" //(5)!
    useEnvProxy = false //(6)!
    proxy {
        host = "localhost" //(7)!
        port = 8090 //(8)!
        user = "user" //(9)!
        password = "password" //(10)!
        nonProxyHosts = [ "host1", "host2" ] //(11)!
    }
}

httpClient:
  apache:
    followRedirects: true #(1)!
    maxRedirects: 3 #(2)!
    maxConnections: 1000 #(3)!
  connectTimeout: "5s" #(4)!
  readTimeout: "2m" #(5)!
  useEnvProxy: false #(6)!
  proxy:
    host: "localhost" #(7)!
    port: 8090  #(8)!
    user: "user"  #(9)!
    password: "password" #(10)!
    nonProxyHosts: [ "host1", "host2" ] #(11)!

Конфигуратор¶

Транспорт Apache принимает два конфигуратора: Configurer<RequestConfig.Builder> для настроек запроса по умолчанию и Configurer<HttpClientBuilder> для самого клиента. Оба опциональны:

@Component
public final class SomeRequestConfigurer implements Configurer<RequestConfig.Builder> {

    @Override
    public RequestConfig.Builder configure(RequestConfig.Builder builder) {
        return builder.setConnectionRequestTimeout(1, TimeUnit.SECONDS);
    }
}

@Component
public final class SomeClientConfigurer implements Configurer<HttpClientBuilder> {

    @Override
    public HttpClientBuilder configure(HttpClientBuilder builder) {
        return builder.setUserAgent("my-service");
    }
}

@Component
class SomeRequestConfigurer : Configurer<RequestConfig.Builder> {

    override fun configure(builder: RequestConfig.Builder): RequestConfig.Builder {
        return builder.setConnectionRequestTimeout(1, TimeUnit.SECONDS)
    }
}

@Component
class SomeClientConfigurer : Configurer<HttpClientBuilder> {

    override fun configure(builder: HttpClientBuilder): HttpClientBuilder {
        return builder.setUserAgent("my-service")
    }
}

Java клиент¶

Реализация HTTP-клиента на базе встроенного в JDK клиента. Kora запускает его на исполнителе виртуальных потоков, поэтому у транспорта нет собственных настроек пула потоков.

Подключение¶

implementation "io.koraframework:http-client-jdk"

@KoraApp
public interface Application extends JdkHttpClientModule { }

implementation("io.koraframework:http-client-jdk")

@KoraApp
interface Application : JdkHttpClientModule

Реализацией интерфейса HttpClient выступает JdkHttpClient из пакета io.koraframework.http.client.jdk.

Конфигурация¶

Основные параметры конфигурации JDK HttpClient:

httpClient {
    connectTimeout = "5s" //(1)!
    readTimeout = "2m" //(2)!
}

httpClient:
  connectTimeout: "5s" #(1)!
  readTimeout: "2m" #(2)!

httpClient {
    jdk {
        followRedirects = true //(1)!
        httpVersion = "HTTP_1_1" //(2)!
    }
    connectTimeout = "5s" //(3)!
    readTimeout = "2m" //(4)!
    useEnvProxy = false //(5)!
    proxy {
        host = "localhost" //(6)!
        port = 8090 //(7)!
        user = "user" //(8)!
        password = "password" //(9)!
        nonProxyHosts = [ "host1", "host2" ] //(10)!
    }
}

httpClient:
  jdk:
    followRedirects: true #(1)!
    httpVersion: "HTTP_1_1" #(2)!
  connectTimeout: "5s" #(3)!
  readTimeout: "2m" #(4)!
  useEnvProxy: false #(5)!
  proxy:
    host: "localhost" #(6)!
    port: 8090 #(7)!
    user: "user" #(8)!
    password: "password" #(9)!
    nonProxyHosts: [ "host1", "host2" ] #(10)!

В JDK-транспорте readTimeout — положительное значение, используемое как ограничение запроса по умолчанию; нулевое или отрицательное значение его отключает. Это ограничение JDK HttpRequest, а не отдельный таймер каждого чтения из возвращённого InputStream. При ручном создании JdkHttpClient передайте длительность вторым аргументом конструктора: перегрузка только с java.net.http.HttpClient не задаёт это значение.

Конфигуратор¶

@Component
public final class SomeConfigurer implements Configurer<java.net.http.HttpClient.Builder> {

    @Override
    public java.net.http.HttpClient.Builder configure(java.net.http.HttpClient.Builder builder) {
        return builder.sslContext(SSLContext.getDefault());
    }
}

@Component
class SomeConfigurer : Configurer<java.net.http.HttpClient.Builder> {

    override fun configure(builder: java.net.http.HttpClient.Builder): java.net.http.HttpClient.Builder {
        return builder.sslContext(SSLContext.getDefault())
    }
}

Декларативный клиент¶

Для создания декларативного клиента предлагается использовать специальные аннотации:

• @HttpClient - указывает, что интерфейс является декларативным HTTP-клиентом
• @HttpRoute - указывает тип HTTP-запроса и путь запроса

@HttpClient
public interface SomeClient {

    @HttpRoute(method = HttpMethod.GET, path = "/hello/world")
    void hello();
}

@HttpClient
interface SomeClient {

    @HttpRoute(method = HttpMethod.GET, path = "/hello/world")
    fun hello()
}

HttpMethod — это контейнер строковых констант (GET, HEAD, POST, PUT, DELETE, CONNECT, OPTIONS, TRACE, PATCH, QUERY), поэтому запись method = "GET" также корректна.

Интерфейс клиента может наследовать другие интерфейсы: маршруты, объявленные в родителе, тоже будут реализованы, а переопределенный в клиенте метод заменяет унаследованный маршрут.

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

По умолчанию конфигурация конкретной реализации @HttpClient ищется по пути httpClient.{имя класса с маленькой буквы}. Если путь требуется указать явно, он передается значением аннотации:

@HttpClient("httpClient.someClient") //(1)!
public interface SomeClient {

    @HttpRoute(method = HttpMethod.GET, path = "/hello/world")
    void hello();
}

@HttpClient("httpClient.someClient") //(1)!
interface SomeClient {

    @HttpRoute(method = HttpMethod.GET, path = "/hello/world")
    fun hello()
}

В @HttpClient также можно указать теги внедряемых компонентов:

• httpClientTag — тег для выбора конкретного транспортного HttpClient, когда в графе есть несколько реализаций с разными @Tag
• telemetryTag — тег для выбора конкретной фабрики HttpClientTelemetryFactory

@HttpClient(
    value = "httpClient.someClient",
    httpClientTag = CustomTransport.class,
    telemetryTag = CustomTelemetry.class
)
public interface SomeClient {

    @HttpRoute(method = HttpMethod.GET, path = "/hello/world")
    void hello();
}

@HttpClient(
    value = "httpClient.someClient",
    httpClientTag = CustomTransport::class,
    telemetryTag = CustomTelemetry::class
)
interface SomeClient {

    @HttpRoute(method = HttpMethod.GET, path = "/hello/world")
    fun hello()
}

Эти теги выбирают, какой компонент внедрить, когда в графе присутствует несколько. Вторая часть — предоставить этот компонент под тем же @Tag. Например, чтобы дать одному клиенту выделенный транспорт (отдельный пул соединений, другие таймауты, свой OkHttpConfigurer и т.д.), предоставьте HttpClient с тегом и сошлитесь на тот же класс-тег из httpClientTag:

public final class CustomTransport { } //(1)!

@Module
public interface TransportModule {

    @Tag(CustomTransport.class) //(2)!
    default HttpClient customHttpClient(okhttp3.OkHttpClient okHttp) {
        return new OkHttpClient(okHttp); //(3)!
    }
}

class CustomTransport //(1)!

@Module
interface TransportModule {

    @Tag(CustomTransport::class) //(2)!
    fun customHttpClient(okHttp: okhttp3.OkHttpClient): HttpClient {
        return OkHttpClient(okHttp) //(3)!
    }
}

telemetryTag работает так же для HttpClientTelemetryFactory с тегом. Если тег не указан, используются транспорт и телеметрия по умолчанию.

Основные параметры конфигурации декларативного клиента:

httpClient {
    someClient {
        url = "https://localhost:8090" //(1)!
        requestTimeout = "10s" //(2)!
    }
}

httpClient:
  someClient:
    url: "https://localhost:8090" #(1)!
    requestTimeout: "10s" #(2)!

httpClient {
    someClient {
        url = "https://localhost:8090" //(1)!
        requestTimeout = "10s" //(2)!
        telemetry {
            logging {
                enabled = false //(3)!
                maskQueries = [ ] //(4)!
                maskHeaders = [ "authorization", "cookie", "set-cookie" ] //(5)!
                pathFull = false //(6)!
                maxRequestBodyLogSize = "2MiB" //(7)!
                maxResponseBodyLogSize = "2MiB" //(8)!
            }
            metrics {
                enabled = false //(9)!
                slo = [ 1, 10, 50, 100, 200, 500, 1000, 2000, 5000, 10000, 20000, 30000, 60000, 90000 ] //(10)!
                tags = { // (11)!
                    "key1" = "value1"
                    "key2" = "value2"
                }
            }
            tracing {
                enabled = true //(12)!
                pathFull = true //(13)!
                attributes = { // (14)!
                    "key1" = "value1"
                    "key2" = "value2"
                }
            }
        }
    }
}

httpClient:
  someClient:
    url: "https://localhost:8090" #(1)!
    requestTimeout: "10s" #(2)!
    telemetry:
      logging:
        enabled: false #(3)!
        maskQueries: [ ] #(4)!
        maskHeaders: [ "authorization", "cookie", "set-cookie" ] #(5)!
        pathFull: false #(6)!
        maxRequestBodyLogSize: "2MiB" #(7)!
        maxResponseBodyLogSize: "2MiB" #(8)!
      metrics:
        enabled: false #(9)!
        slo: [ 1, 10, 50, 100, 200, 500, 1000, 2000, 5000, 10000, 20000, 30000, 60000, 90000 ] #(10)!
        tags: #(11)!
          key1: value1
          key2: value2
      tracing:
        enabled: true #(12)!
        pathFull: true #(13)!
        attributes: #(14)!
          key1: value1
          key2: value2

Конфигурация метода¶

Для конкретного метода часть параметров настраивается отдельно. Путь конфигурации метода складывается из пути клиента и имени метода: если путь клиента httpClient.someClient, то итоговый путь для метода hello — httpClient.someClient.hello.

Конфигурация метода накладывается поверх конфигурации клиента: requestTimeout метода заменяет значение клиента, а настройки телеметрии метода переопределяют только явно указанные поля.

Основные параметры конфигурации метода:

httpClient {
    someClient {
        hello {
            requestTimeout = "10s" //(1)!
        }
    }
}

httpClient:
  someClient:
    hello:
      requestTimeout: "10s" #(1)!

httpClient {
    someClient {
        hello {
            requestTimeout = "10s" //(1)!
            telemetry {
                logging {
                    enabled = false //(2)!
                    maskQueries = [ ] //(3)!
                    maskHeaders = [ "authorization", "cookie", "set-cookie" ] //(4)!
                    pathFull = false //(5)!
                    maxRequestBodyLogSize = "2MiB" //(6)!
                    maxResponseBodyLogSize = "2MiB" //(7)!
                }
                metrics {
                    enabled = false //(8)!
                    slo = [ 1, 10, 50, 100, 200, 500, 1000, 2000, 5000, 10000, 20000, 30000, 60000, 90000 ] //(9)!
                    tags = { // (10)!
                        "key1" = "value1"
                        "key2" = "value2"
                    }
                }
                tracing {
                    enabled = true //(11)!
                    pathFull = true //(12)!
                    attributes = { // (13)!
                        "key1" = "value1"
                        "key2" = "value2"
                    }
                }
            }
        }
    }
}

httpClient:
  someClient:
    hello:
      requestTimeout: "10s" #(1)!
      telemetry:
        logging:
          enabled: false #(2)!
          maskQueries: [ ] #(3)!
          maskHeaders: [ "authorization", "cookie", "set-cookie" ] #(4)!
          pathFull: false #(5)!
          maxRequestBodyLogSize: "2MiB" #(6)!
          maxResponseBodyLogSize: "2MiB" #(7)!
        metrics:
          enabled: false #(8)!
          slo: [ 1, 10, 50, 100, 200, 500, 1000, 2000, 5000, 10000, 20000, 30000, 60000, 90000 ] #(9)!
          tags: #(10)!
            key1: value1
            key2: value2
        tracing:
          enabled: true #(11)!
          pathFull: true #(12)!
          attributes: #(13)!
            key1: value1
            key2: value2

Запрос¶

В этом разделе описаны преобразования HTTP-запроса для декларативного HTTP-клиента. Параметры запроса задаются специальными аннотациями.

Преобразование параметров¶

HttpClientParameterWriter<T> преобразует значение параметра в строку, прежде чем Kora подставит его в путь, параметр запроса, заголовок или куки. У интерфейса один метод:

public interface HttpClientParameterWriter<T> {
    String convert(T value);
}

String, Integer, Long, Boolean и примитивы Java записываются напрямую и вообще не требуют писателя. Для любого другого типа Kora ищет компонент HttpClientParameterWriter<T> по точному типу параметра. Если параметр имеет тип Map<String, T>, писатель ищется для типа значения T; если используется Map<String, List<T>>, он применяется к каждому элементу списка; для List<T> / Set<T> / Collection<T> — к каждому элементу коллекции.

Встроенные писатели доступны для Boolean, Short, Integer, Long, Double, Float, UUID, BigDecimal, BigInteger, Duration, OffsetTime, OffsetDateTime, LocalTime, LocalDate, LocalDateTime, ZonedDateTime и Instant. Типы даты и времени записываются в формате ISO. Для собственных типов нужно предоставить компонент HttpClientParameterWriter<T>:

public record UserId(long value) {}

@Module
public interface UserIdModule {

    default HttpClientParameterWriter<UserId> userIdParameterWriter() {
        return value -> Long.toString(value.value());
    }
}

data class UserId(val value: Long)

@Module
interface UserIdModule {

    fun userIdParameterWriter(): HttpClientParameterWriter<UserId> {
        return HttpClientParameterWriter { value -> value.value.toString() }
    }
}

После этого тип можно использовать в параметрах клиента:

@HttpClient
public interface SomeClient {

    @HttpRoute(method = HttpMethod.GET, path = "/users/{id}")
    User get(@Path("id") UserId id);
}

@HttpClient
interface SomeClient {

    @HttpRoute(method = HttpMethod.GET, path = "/users/{id}")
    fun get(@Path("id") id: UserId): User
}

Для перечислений есть EnumHttpClientParameterWriter из пакета io.koraframework.http.client.common.request.mapper: он строит писатель из констант перечисления и функции преобразования, и именно его использует генератор OpenAPI.

Параметр пути¶

@Path - обозначает значение части пути запроса, сам параметр указывается в {кавычках} в пути, а имя параметра указывается в value либо по умолчанию равно имени аргумента метода. Значения пути кодируются в URL, поэтому пробел превращается в %20.

@HttpClient
public interface SomeClient {

    @HttpRoute(method = HttpMethod.GET, path = "/hello/{pathName}")
    void hello(@Path("pathName") String pathValue);
}

@HttpClient
interface SomeClient {

    @HttpRoute(method = HttpMethod.GET, path = "/hello/{pathName}")
    fun hello(@Path("pathName") pathValue: String)
}

Каждому placeholder-у {name} в пути должен соответствовать параметр @Path, иначе сборка падает с ошибкой Path template contains parameters that have no matching @Path method parameter.

Параметр запроса¶

@Query - значение параметра запроса, имя указывается в value либо по умолчанию равно имени аргумента метода. Поддерживаются одиночные значения, List<T>, Set<T>, Collection<T>, Map<String, T> и Map<String, List<T>>. Для нестроковых значений используется доступный HttpClientParameterWriter<T>. Пустая коллекция отправляется как параметр без значения.

@HttpClient
public interface SomeClient {

    @HttpRoute(method = HttpMethod.GET, path = "/hello/world")
    void hello(@Query("queryName") String queryValue,
               @Query("queryNameList") List<String> queryValues);
}

@HttpClient
interface SomeClient {

    @HttpRoute(method = HttpMethod.GET, path = "/hello/world")
    fun hello(@Query("queryName") queryValue: String,
              @Query("queryNameList") queryValues: List<String>)
}

Параметры запроса можно отправлять в формате ключ-значение через Map, где ключ является именем параметра и должен быть String. Если значением Map является список, каждый его элемент отправляется как отдельное значение того же параметра. Если элемент списка равен null, параметр отправляется без значения.

@HttpClient
public interface SomeClient {

    @HttpRoute(method = HttpMethod.GET, path = "/hello/world")
    void hello(@Query Map<String, String> queryValues);
}

@HttpClient
interface SomeClient {

    @HttpRoute(method = HttpMethod.GET, path = "/hello/world")
    fun hello(@Query queryValues: Map<String, String>)
}

Заголовок¶

@Header - значение заголовка запроса, имя параметра указывается в value либо по умолчанию равно имени аргумента метода. Поддерживаются одиночные значения, List<T>, Set<T>, Collection<T>, Map<String, T> и готовый объект HttpHeaders.

@HttpClient
public interface SomeClient {

    @HttpRoute(method = HttpMethod.GET, path = "/hello/world")
    void hello(@Header("headerName") String headerValue,
               @Header("headerNameList") List<String> headerValues);
}

@HttpClient
interface SomeClient {

    @HttpRoute(method = HttpMethod.GET, path = "/hello/world")
    fun hello(@Header("headerName") headerValue: String,
              @Header("headerNameList") headerValues: List<String>)
}

Заголовки можно отправлять в формате ключ-значение через HttpHeaders или Map, где ключ является именем заголовка и должен быть String. Для нестроковых значений используется доступный HttpClientParameterWriter<T>:

@HttpClient
public interface SomeClient {

    @HttpRoute(method = HttpMethod.GET, path = "/hello/world")
    void hello(@Header HttpHeaders headers);
}

@HttpClient
interface SomeClient {

    @HttpRoute(method = HttpMethod.GET, path = "/hello/world")
    fun hello(@Header headers: HttpHeaders)
}

Тело запроса¶

Тело запроса указывается аргументом метода без специальных аннотаций. Из коробки поддерживаются byte[], ByteBuffer, String, HttpBodyOutput, FormUrlEncoded и FormMultipart, поскольку HttpClientRequestMapperModule предоставляет реализации HttpClientRequestMapper именно для этих типов.

Json¶

Чтобы указать, что тело является JSON и для него требуется внедрить JsonWriter<T>, используя тег-аннотация @Json:

@HttpClient
public interface SomeClient {

    record MyBody(String name) { }

    @HttpRoute(method = HttpMethod.POST, path = "/hello/world")
    void hello(@Json MyBody body); //(1)!
}

@HttpClient
interface SomeClient {

    data class MyBody(val name: String)

    @HttpRoute(method = HttpMethod.POST, path = "/hello/world")
    fun hello(@Json body: MyBody) //(1)!
}

Требуется модуль Json, а также наличие JsonWriter<MyBody> — обычно это достигается аннотацией @Json на самом типе.

Текстовая форма¶

Используйте FormUrlEncoded (из ru.tinkoff.kora.http.common.form) как тип аргумента тела, чтобы отправить тело с типом содержимого application/x-www-form-urlencoded (форма данных). Аннотации @Json или @Mapping не требуются — для этого типа в Kora есть встроенный writer.

FormUrlEncoded — это набор именованных частей, где каждая часть может содержать одно или несколько значений:

• FormUrlEncoded.FormPart(String name, String value) — часть с одним значением
• FormUrlEncoded.FormPart(String name, List<String> values) — часть с несколькими значениями (поле повторяется для каждого значения)
• new FormUrlEncoded(FormPart...) / new FormUrlEncoded(List<FormPart>) / new FormUrlEncoded(Map<String, FormPart>) — создание формы; части с одинаковым именем объединяются в одну

Объявите метод клиента с параметром FormUrlEncoded:

@HttpClient
public interface SomeClient {

    @HttpRoute(method = HttpMethod.POST, path = "/form/encoded")
    HttpResponseEntity<String> formEncoded(FormUrlEncoded body);
}

@HttpClient
interface SomeClient {

    @HttpRoute(method = HttpMethod.POST, path = "/form/encoded")
    fun formEncoded(body: FormUrlEncoded): HttpResponseEntity<String>
}

Пример вызова метода с такой формой выглядит так:

var response = someClient.formEncoded(new FormUrlEncoded(
        new FormUrlEncoded.FormPart("name", "Bob"),
        new FormUrlEncoded.FormPart("password", "12345"),
        new FormUrlEncoded.FormPart("roles", List.of("admin", "user")) //(1)!
));

val response = someClient.formEncoded(
    FormUrlEncoded(
        FormUrlEncoded.FormPart("name", "Bob"),
        FormUrlEncoded.FormPart("password", "12345"),
        FormUrlEncoded.FormPart("roles", listOf("admin", "user")) //(1)!
    )
)

Бинарная форма¶

Используйте FormMultipart (из ru.tinkoff.kora.http.common.form) как тип аргумента тела, чтобы отправить тело multipart/form-data (бинарная форма), обычно используется для загрузки файлов вместе с текстовыми полями. Аннотации @Json или @Mapping не требуются.

FormMultipart — это список частей, создаваемых через статические фабричные методы:

• FormMultipart.data(String name, String value) — текстовое поле
• FormMultipart.file(String name, String fileName, String contentType, byte[] content) — файловая часть, загруженная в память (fileName и contentType могут быть null)
• FormMultipart.file(String name, String fileName, String contentType, Flow.Publisher<ByteBuffer> content) — потоковая файловая часть для больших данных, которые не следует полностью буферизовать в памяти
• new FormMultipart(List<? extends FormPart>) — создание формы из частей

Объявите метод клиента с параметром FormMultipart:

@HttpClient
public interface SomeClient {

    @HttpRoute(method = HttpMethod.POST, path = "/form/multipart")
    HttpResponseEntity<String> formMultipart(FormMultipart body);
}

@HttpClient
interface SomeClient {

    @HttpRoute(method = HttpMethod.POST, path = "/form/multipart")
    fun formMultipart(body: FormMultipart): HttpResponseEntity<String>
}

Пример вызова метода с такой формой выглядит так:

var response = someClient.formMultipart(new FormMultipart(List.of(
        FormMultipart.data("field1", "some data content"), //(1)!
        FormMultipart.file("field2", "example1.txt", "text/plain",
                "some file content".getBytes(StandardCharsets.UTF_8)) //(2)!
)));

val response = someClient.formMultipart(
    FormMultipart(
        listOf(
            FormMultipart.data("field1", "some data content"), //(1)!
            FormMultipart.file(
                "field2",
                "example1.txt",
                "text/plain",
                "some file content".toByteArray(StandardCharsets.UTF_8)
            ) //(2)!
        )
    )
)

Метод FormMultipart.file(String name, String fileName, HttpBodyOutput content) отправляет часть формы потоком, а не массивом байт.

Свое тело¶

Если тело требуется записать способом, отличным от стандартных механизмов, можно использовать специальный интерфейс HttpClientRequestMapper для реализации собственной логики:

@HttpClient
public interface SomeClient {

    record UserBody(String id) {}

    final class UserRequestMapper implements HttpClientRequestMapper<UserBody> {

        @Override
        public HttpBodyOutput apply(UserBody value) {
            return HttpBody.plaintext(value.id());
        }
    }

    @HttpRoute(method = HttpMethod.POST, path = "/hello/world")
    HttpResponseEntity<String> hello(@Mapping(UserRequestMapper.class) UserBody body);
}

@HttpClient
interface SomeClient {

    data class UserBody(val id: String)

    class UserRequestMapper : HttpClientRequestMapper<UserBody> {

        override fun apply(value: UserBody): HttpBodyOutput {
            return HttpBody.plaintext(value.id)
        }
    }

    @HttpRoute(method = HttpMethod.POST, path = "/hello/world")
    fun hello(@Mapping(UserRequestMapper::class) body: UserBody): HttpResponseEntity<String>
}

Пример: сериализация Protobuf

Обратите внимание, что HttpBody.of принимает сначала тип содержимого, а затем полезную нагрузку:

@HttpClient
public interface ProtobufClient {

    final class ProtobufRequestMapper implements HttpClientRequestMapper<MyMessage> {

        @Override
        public HttpBodyOutput apply(MyMessage value) {
            byte[] protobufBytes = value.toByteArray();
            return HttpBody.of("application/x-protobuf", protobufBytes);
        }
    }

    @HttpRoute(method = HttpMethod.POST, path = "/message")
    void sendMessage(@Mapping(ProtobufRequestMapper.class) MyMessage message);
}

@HttpClient
interface ProtobufClient {

    class ProtobufRequestMapper : HttpClientRequestMapper<MyMessage> {

        override fun apply(value: MyMessage): HttpBodyOutput {
            val protobufBytes = value.toByteArray()
            return HttpBody.of("application/x-protobuf", protobufBytes)
        }
    }

    @HttpRoute(method = HttpMethod.POST, path = "/message")
    fun sendMessage(@Mapping(ProtobufRequestMapper::class) message: MyMessage)
}

Куки¶

@Cookie - значение Cookie, имя параметра указывается в value либо по умолчанию равно имени аргумента метода. Поддерживаются одиночные значения, List<T>, Set<T>, Collection<T>, Map<String, T> и готовый объект Cookie. Каждая кука записывается отдельным значением заголовка Cookie в формате name=value.

@HttpClient
public interface SomeClient {

    @HttpRoute(method = HttpMethod.GET, path = "/hello/world")
    void hello(@Cookie("cookieName") String cookieValue);
}

@HttpClient
interface SomeClient {

    @HttpRoute(method = HttpMethod.GET, path = "/hello/world")
    fun hello(@Cookie("cookieName") cookieValue: String)
}

Обязательные параметры¶

Необязательные параметры¶

@HttpClient
public interface SomeClient {

    @HttpRoute(method = HttpMethod.GET, path = "/hello/world")
    void hello(@Nullable @Query("queryValue") String queryValue); //(1)!
}

@HttpClient
interface SomeClient {

    @HttpRoute(method = HttpMethod.GET, path = "/hello/world")
    fun hello(@Query("queryValue") queryValue: String?)
}

Параметр запроса, заголовок или кука со значением null просто не попадают в запрос.

Ответ¶

В разделе описано преобразование HTTP-ответа для декларативного HTTP-клиента.

Тело ответа¶

Kora поставляет реализации HttpClientResponseMapper для ограниченного набора типов, все они объявлены в HttpClientResponseMapperModule:

Для любого другого типа требуется собственный маппер, смотрите Свой ответ.

Json¶

Если тело требуется читать как Json, над методом нужно использовать аннотацию @Json.

@HttpClient
public interface SomeClient {

    record MyResponse(String name) { }

    @Json //(1)!
    @HttpRoute(method = HttpMethod.GET, path = "/hello/world")
    MyResponse hello();
}

@HttpClient
interface SomeClient {

    data class MyResponse(val name: String)

    @Json //(1)!
    @HttpRoute(method = HttpMethod.GET, path = "/hello/world")
    fun hello(): MyResponse
}

Требуется модуль Json.

Ответ с метаданными¶

Если нужно прочитать тело и вдобавок получить заголовки и код статуса ответа, предназначен HttpResponseEntity — обертка над телом ответа, которая предоставляет code(), headers() и body().

Ниже пример, аналогичный примеру с Json, но с оберткой HttpResponseEntity:

@HttpClient
public interface SomeClient {

    record MyResponse(String name) { }

    @Json
    @HttpRoute(method = HttpMethod.GET, path = "/hello/world")
    HttpResponseEntity<MyResponse> hello();
}

@HttpClient
interface SomeClient {

    data class MyResponse(val name: String)

    @Json
    @HttpRoute(method = HttpMethod.GET, path = "/hello/world")
    fun hello(): HttpResponseEntity<MyResponse>
}

Обертку Kora строит сама из маппера полезной нагрузки, поэтому для HttpResponseEntity<Void> — обычного приема, когда от ответа нужен только код статуса, — в графе должен быть HttpClientResponseMapper<Void>. Встроенного нет, поэтому его объявляют компонентом и не указывают через @Mapping: с @Mapping маппер обязан произвести весь тип HttpResponseEntity<Void>, тогда как шаблонная фабрика фреймворка ждет маппер полезной нагрузки и оборачивает его в entity сама.

@HttpClient("httpClient.userApi")
public interface UserApiClient {

    @Component
    final class VoidResponseMapper implements HttpClientResponseMapper<Void> {

        @Override
        public Void apply(HttpClientResponse response) throws IOException {
            try (var body = response.body()) {
                body.asInputStream().readAllBytes();
            }
            return null;
        }
    }

    @HttpRoute(method = HttpMethod.DELETE, path = "/users/{userId}")
    HttpResponseEntity<Void> deleteUser(@Path String userId);
}

@HttpClient("httpClient.userApi")
interface UserApiClient {

    @Component
    class VoidResponseMapper : HttpClientResponseMapper<Void> {

        override fun apply(response: HttpClientResponse): Void? {
            response.body().use { body ->
                body.asInputStream().readAllBytes()
            }
            return null
        }
    }

    @HttpRoute(method = HttpMethod.DELETE, path = "/users/{userId}")
    fun deleteUser(@Path userId: String): HttpResponseEntity<Void>
}

Без этого компонента сборка падает с ошибкой No component found for dependency: HttpClientResponseMapper<java.lang.Void>.

Either¶

Either<T, E> описывает вызов, для которого неуспешный код статуса является нормальным исходом, а не исключением. Ответ 2xx Kora преобразует маппером типа T в Either.Left, любой другой код статуса — маппером типа E в Either.Right, и HttpClientResponseException для такого метода никогда не бросается.

@HttpClient
public interface SomeClient {

    record Success(String id) {}

    record Error(String message) {}

    @HttpRoute(method = HttpMethod.GET, path = "/users/{id}")
    Either<@Json Success, @Json Error> get(@Path String id); //(1)!
}