클라이언트 엔진

Ktor HTTP 클라이언트는 멀티플랫폼을 지원하며 JVM, Android, JavaScript (웹어셈블리 (WebAssembly) 포함), Native 타겟에서 실행됩니다. 각 플랫폼은 네트워크 요청을 처리하기 위한 특정 엔진이 필요합니다. 예를 들어, JVM 애플리케이션에는 Apache 또는 Jetty를, Android에는 OkHttp 또는 Android를, Kotlin/Native를 대상으로 하는 데스크톱 애플리케이션에는 Curl을 사용할 수 있습니다. 모든 엔진은 기능과 구성에서 약간씩 다르므로, 플랫폼과 사용 사례 요구 사항에 가장 적합한 엔진을 선택할 수 있습니다.

지원되는 플랫폼

아래 표는 각 엔진이 지원하는 플랫폼을 나열합니다:

엔진	플랫폼
`Apache5`	JVM
`Java`	JVM
`Jetty`	JVM
`Android`	JVM, Android
`OkHttp`	JVM, Android
`Darwin`	Native
`WinHttp`	Native
`Curl`	Native
`CIO`	JVM, Android, Native, JavaScript, WasmJs
`Js`	JavaScript

지원되는 Android/Java 버전

JVM 또는 JVM과 Android를 모두 대상으로 하는 클라이언트 엔진은 다음 Android/Java 버전을 지원합니다:

엔진	Android 버전	Java 버전
`Apache5`		8+
`Java`		11+
`Jetty`		11+
`CIO`	7.0+ ^*	8+
`Android`	1.x+	8+
`OkHttp`	5.0+	8+

* 구형 Android 버전에서 CIO 엔진을 사용하려면 Java 8 API desugaring을 활성화해야 합니다.

엔진 종속성 추가

ktor-client-core 아티팩트 외에도 Ktor 클라이언트는 특정 엔진에 대한 종속성을 추가해야 합니다. 각 지원 플랫폼에는 해당 섹션에 설명된 사용 가능한 엔진 세트가 있습니다:

JVM
JVM 및 Android
JavaScript
네이티브

Ktor는 -jvm 또는 -js와 같은 접미사가 붙은 플랫폼별 아티팩트를 제공합니다. 예를 들어, ktor-client-cio-jvm과 같습니다. 빌드 도구에 따라 종속성 해결 방식이 다릅니다. Gradle은 주어진 플랫폼에 적합한 아티팩트를 해결하지만, Maven은 이 기능을 지원하지 않습니다. 이는 Maven의 경우 플랫폼 접미사를 수동으로 지정해야 함을 의미합니다.

엔진 지정

특정 엔진을 사용하려면 HttpClient 생성자에 엔진 클래스를 인수로 전달합니다. 다음 예제는 CIO 엔진으로 클라이언트를 생성합니다:

kotlin

import io.ktor.client.*
import io.ktor.client.engine.cio.*

val client = HttpClient(CIO)

기본 엔진

엔진 인수를 생략하면 클라이언트는 빌드 스크립트에 포함된 종속성을 기반으로 자동으로 엔진을 선택합니다.

kotlin

import io.ktor.client.*

val client = HttpClient()

이는 멀티플랫폼 프로젝트에서 특히 유용합니다. 예를 들어, Android 및 iOS를 모두 대상으로 하는 프로젝트의 경우, androidMain 소스 세트에 Android 종속성을 추가하고 iosMain 소스 세트에 Darwin 종속성을 추가할 수 있습니다. HttpClient 생성 시 런타임에 적절한 엔진이 선택됩니다.

엔진 구성

엔진을 구성하려면 engine {} 함수를 사용합니다. 모든 엔진은 HttpClientEngineConfig에서 노출되는 공통 옵션을 사용하여 구성할 수 있습니다:

kotlin

HttpClient() {
    engine {
        // this: HttpClientEngineConfig
        threadsCount = 4
        pipelining = true
    }
}

다음 섹션에서는 다양한 플랫폼에서 특정 엔진을 구성하는 방법을 알아볼 수 있습니다.

JVM

JVM 타겟은 Apache5, Java, Jetty 엔진을 지원합니다.

Apache5

Apache5 엔진은 HTTP/1.1과 HTTP/2를 모두 지원하며, HTTP/2는 기본적으로 활성화되어 있습니다. 이 엔진은 새 프로젝트에 권장되는 Apache 기반 엔진입니다.

이전 Apache 엔진은 지원 중단된 Apache HttpClient 4에 의존합니다. 이는 이전 버전과의 호환성을 위해서만 유지됩니다. 모든 새 프로젝트에는 Apache5를 사용하십시오.

ktor-client-apache5 종속성을 추가합니다:
Gradle (Kotlin)Gradle (Groovy)Maven
Kotlin
Groovy
XML

Apache5 클래스를 HttpClient 생성자의 인수로 전달합니다:

kotlin

import io.ktor.client.*
import io.ktor.client.engine.apache5.*

val client = HttpClient(Apache5)

engine {} 블록을 사용하여 Apache5EngineConfig의 속성에 액세스하고 설정합니다:

kotlin

import io.ktor.client.*
import io.ktor.client.engine.apache5.*
import org.apache.hc.core5.http.*

val client = HttpClient(Apache5) {
    engine {
        // this: Apache5EngineConfig
        followRedirects = true
        socketTimeout = 10_000
        connectTimeout = 10_000
        connectionRequestTimeout = 20_000
        customizeClient {
            // this: HttpAsyncClientBuilder
            setProxy(HttpHost("127.0.0.1", 8080))
            // ...
        }
        customizeRequest {
            // this: RequestConfig.Builder
        }
    }
}

Java

Java 엔진은 Java 11에 도입된 Java HTTP 클라이언트를 사용합니다. 사용하려면 다음 단계를 따르십시오:

ktor-client-java 종속성을 추가합니다:
Gradle (Kotlin)Gradle (Groovy)Maven
Kotlin
Groovy
XML

Java 클래스를 HttpClient 생성자의 인수로 전달합니다:

kotlin

import io.ktor.client.*
import io.ktor.client.engine.java.*

val client = HttpClient(Java)

엔진을 구성하려면 engine {} 블록에서 JavaHttpConfig의 속성을 설정합니다:

kotlin

import io.ktor.client.*
import io.ktor.client.engine.*
import io.ktor.client.engine.java.*

val client = HttpClient(Java) {
    engine {
        // this: JavaHttpConfig
        threadsCount = 8
        pipelining = true
        proxy = ProxyBuilder.http("http://proxy-server.com/")
        protocolVersion = java.net.http.HttpClient.Version.HTTP_2
    }
}

Jetty

Jetty 엔진은 HTTP/2만 지원하며 다음과 같이 구성할 수 있습니다:

ktor-client-jetty-jakarta 종속성을 추가합니다:
Gradle (Kotlin)Gradle (Groovy)Maven
Kotlin
Groovy
XML

Jetty 클래스를 HttpClient 생성자의 인수로 전달합니다:

kotlin

import io.ktor.client.*
import io.ktor.client.engine.jetty.jakarta.*

val client = HttpClient(Jetty)

엔진을 구성하려면 engine {} 블록에서 JettyEngineConfig의 속성을 설정합니다:

kotlin

import io.ktor.client.*
import io.ktor.client.engine.jetty.jakarta.*
import org.eclipse.jetty.util.ssl.SslContextFactory

val client = HttpClient(Jetty) {
    engine {
        // this: JettyEngineConfig
        sslContextFactory = SslContextFactory.Client()
        clientCacheSize = 12
    }
}

JVM 및 Android

이 섹션에서는 JVM/Android에서 사용할 수 있는 엔진과 해당 구성을 살펴보겠습니다.

Android

Android 엔진은 Android를 대상으로 하며 다음과 같이 구성할 수 있습니다:

ktor-client-android 종속성을 추가합니다:
Gradle (Kotlin)Gradle (Groovy)Maven
Kotlin
Groovy
XML

Android 클래스를 HttpClient 생성자의 인수로 전달합니다:

kotlin

import io.ktor.client.*
import io.ktor.client.engine.android.*

val client = HttpClient(Android)

엔진을 구성하려면 engine {} 블록에서 AndroidEngineConfig의 속성을 설정합니다:

kotlin

import io.ktor.client.*
import io.ktor.client.engine.android.*
import java.net.Proxy
import java.net.InetSocketAddress

val client = HttpClient(Android) {
    engine {
        // this: AndroidEngineConfig
        connectTimeout = 100_000
        socketTimeout = 100_000
        proxy = Proxy(Proxy.Type.HTTP, InetSocketAddress("localhost", 8080))
    }
}

OkHttp

OkHttp 엔진은 OkHttp 기반이며 다음과 같이 구성할 수 있습니다:

ktor-client-okhttp 종속성을 추가합니다:
Gradle (Kotlin)Gradle (Groovy)Maven
Kotlin
Groovy
XML

OkHttp 클래스를 HttpClient 생성자의 인수로 전달합니다:

kotlin

import io.ktor.client.*
import io.ktor.client.engine.okhttp.*

val client = HttpClient(OkHttp)

엔진을 구성하려면 engine {} 블록에서 OkHttpConfig의 속성을 설정합니다:

kotlin

import io.ktor.client.*
import io.ktor.client.engine.okhttp.*

val client = HttpClient(OkHttp) {
    engine {
        // this: OkHttpConfig
        config {
            // this: OkHttpClient.Builder
            followRedirects(true)
            // ...
        }
        addInterceptor(interceptor)
        addNetworkInterceptor(interceptor)

        preconfigured = okHttpClientInstance
    }
}

네이티브

Ktor는 Kotlin/Native 타겟을 위한 Darwin, WinHttp, Curl 엔진을 제공합니다.

Kotlin/Native 프로젝트에서 Ktor를 사용하려면 새로운 메모리 관리자가 필요하며, 이는 Kotlin 1.7.20부터 기본적으로 활성화됩니다.

Darwin

Darwin 엔진은 macOS, iOS, tvOS, watchOS와 같은 Darwin 기반 운영 체제를 대상으로 합니다. 내부적으로 NSURLSession을 사용합니다. Darwin 엔진을 사용하려면 다음 단계를 따르십시오:

ktor-client-darwin 종속성을 추가합니다:
Gradle (Kotlin)Gradle (Groovy)Maven
Kotlin
Groovy
XML

Darwin 클래스를 HttpClient 생성자의 인수로 전달합니다:

kotlin

import io.ktor.client.*
import io.ktor.client.engine.darwin.*

val client = HttpClient(Darwin)

engine {} 블록에서 DarwinClientEngineConfig을 사용하여 엔진을 구성합니다. 예를 들어, configureRequest로 요청을 사용자 지정하거나 configureSession으로 세션을 사용자 지정할 수 있습니다:
kotlin
```
val client = HttpClient(Darwin) {
    engine {
        configureRequest {
            setAllowsCellularAccess(true)
        }
    }
}
```
전체 예제는 다음에서 확인할 수 있습니다: client-engine-darwin.

WinHttp

WinHttp 엔진은 Windows 기반 운영 체제를 대상으로 합니다. WinHttp 엔진을 사용하려면 다음 단계를 따르십시오:

ktor-client-winhttp 종속성을 추가합니다:
Gradle (Kotlin)Gradle (Groovy)Maven
Kotlin
Groovy
XML

WinHttp 클래스를 HttpClient 생성자의 인수로 전달합니다:

kotlin

import io.ktor.client.*
import io.ktor.client.engine.winhttp.*

val client = HttpClient(WinHttp)

engine {} 블록에서 WinHttpClientEngineConfig을 사용하여 엔진을 구성합니다. 예를 들어, protocolVersion 속성을 사용하여 HTTP 버전을 변경할 수 있습니다:
kotlin
```
val client = HttpClient(WinHttp) {
    engine {
        protocolVersion = HttpProtocolVersion.HTTP_1_1
    }
}
```
전체 예제는 다음에서 확인할 수 있습니다: client-engine-winhttp.

Curl

데스크톱 플랫폼을 위해 Ktor는 Curl 엔진을 제공합니다. 이 엔진은 linuxX64, linuxArm64, macosX64, macosArm64, mingwX64 플랫폼에서 지원됩니다. Curl 엔진을 사용하려면 다음 단계를 따르십시오:

ktor-client-curl 종속성을 추가합니다:
Gradle (Kotlin)Gradle (Groovy)Maven
Kotlin
Groovy
XML

Curl 클래스를 HttpClient 생성자의 인수로 전달합니다:

kotlin

import io.ktor.client.*
import io.ktor.client.engine.curl.*

val client = HttpClient(Curl)

engine {} 블록에서 CurlClientEngineConfig를 사용하여 엔진을 구성합니다. 예를 들어, 테스트 목적으로 SSL 확인을 비활성화할 수 있습니다:
kotlin
```
val client = HttpClient(Curl) {
    engine {
        sslVerify = false
    }
}
```
전체 예제는 다음에서 확인할 수 있습니다: client-engine-curl.

JVM, Android, Native, JS 및 WasmJs

CIO

CIO 엔진은 JVM, Android, Native, JavaScript 및 WebAssembly JavaScript (WasmJs) 플랫폼에서 사용할 수 있는 완전한 비동기 코루틴 기반 엔진입니다. 현재 HTTP/1.x만 지원합니다. 사용하려면 다음 단계를 따르십시오:

ktor-client-cio 종속성을 추가합니다:
Gradle (Kotlin)Gradle (Groovy)Maven
Kotlin
Groovy
XML

CIO 클래스를 HttpClient 생성자의 인수로 전달합니다:

kotlin

import io.ktor.client.*
import io.ktor.client.engine.cio.*

val client = HttpClient(CIO)

engine {} 블록에서 CIOEngineConfig를 사용하여 엔진을 구성합니다:

kotlin

import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.network.tls.*

val client = HttpClient(CIO) {
    engine {
        // this: CIOEngineConfig
        maxConnectionsCount = 1000
        endpoint {
            // this: EndpointConfig
            maxConnectionsPerRoute = 100
            pipelineMaxSize = 20
            keepAliveTime = 5000
            connectTimeout = 5000
            connectAttempts = 5
        }
        https {
            // this: TLSConfigBuilder
            serverName = "api.ktor.io"
            cipherSuites = CIOCipherSuites.SupportedSuites
            trustManager = myCustomTrustManager
            random = mySecureRandom
            addKeyStore(myKeyStore, myKeyStorePassword)
        }
    }
}

JavaScript

Js 엔진은 JavaScript 프로젝트에 사용할 수 있습니다. 이 엔진은 브라우저 애플리케이션용으로 fetch API를 사용하고 Node.js용으로 node-fetch를 사용합니다. 사용하려면 다음 단계를 따르십시오:

ktor-client-js 종속성을 추가합니다:
Gradle (Kotlin)Gradle (Groovy)Maven
Kotlin
Groovy
XML
Js 클래스를 HttpClient 생성자의 인수로 전달합니다:
kotlin
```
import io.ktor.client.*
import io.ktor.client.engine.js.*

val client = HttpClient(Js)
```
Js 엔진 싱글톤을 가져오기 위해 JsClient() 함수를 호출할 수도 있습니다:
kotlin
```
import io.ktor.client.engine.js.*

val client = JsClient()
```

전체 예제는 다음에서 확인할 수 있습니다: client-engine-js.

제한 사항

HTTP/2 및 WebSockets

모든 엔진이 HTTP/2 프로토콜을 지원하는 것은 아닙니다. 엔진이 HTTP/2를 지원하는 경우, 엔진 구성에서 이를 활성화할 수 있습니다. 예를 들어, Java 엔진의 경우와 같습니다.

아래 표는 특정 엔진이 HTTP/2 및 WebSockets를 지원하는지 여부를 보여줍니다:

엔진	HTTP/2	WebSockets
`Apache5`	✅️	✖️
`Java`	✅	✅️
`Jetty`	✅	✖️
`CIO`	✖️	✅
`Android`	✖️	✖️
`OkHttp`	✅	✅
`Js`	✅	✅
`Darwin`	✅	✅
`WinHttp`	✅	✅
`Curl`	✅	✅

보안

SSL은 엔진별로 구성해야 합니다. 각 엔진은 자체 SSL 구성 옵션을 제공합니다.

프록시 지원

일부 엔진은 프록시를 지원하지 않습니다. 전체 목록은 프록시 문서를 참조하십시오.

로깅

로깅 플러그인은 타겟 플랫폼에 따라 다른 로거 유형을 제공합니다.

타임아웃

HttpTimeout 플러그인에는 특정 엔진에 대한 몇 가지 제한 사항이 있습니다. 전체 목록은 타임아웃 제한 사항을 참조하십시오.

예시: 멀티플랫폼 모바일 프로젝트에서 엔진을 구성하는 방법

멀티플랫폼 프로젝트를 빌드할 때, expected 및 actual 선언을 사용하여 각 타겟 플랫폼에 대한 엔진을 선택하고 구성할 수 있습니다. 이를 통해 대부분의 클라이언트 구성을 공통 코드에서 공유하면서 플랫폼 코드에서 엔진별 옵션을 적용할 수 있습니다. 크로스 플랫폼 모바일 애플리케이션 생성 튜토리얼에서 생성된 프로젝트를 사용하여 이를 달성하는 방법을 시연하겠습니다:

shared/src/commonMain/kotlin/com/example/kmpktor/Platform.kt 파일을 열고 구성 블록을 받아 HttpClient를 반환하는 최상위 httpClient() 함수를 추가합니다:
kotlin
```
expect fun httpClient(config: HttpClientConfig<*>.() -> Unit = {}): HttpClient
```

shared/src/androidMain/kotlin/com/example/kmpktor/Platform.kt 를 열고 Android 모듈용 httpClient() 함수의 actual 선언을 추가합니다:

kotlin

import io.ktor.client.*
import io.ktor.client.engine.okhttp.*
import java.util.concurrent.TimeUnit

actual fun httpClient(config: HttpClientConfig<*>.() -> Unit) = HttpClient(OkHttp) {
   config(this)

   engine { 
      config {
         retryOnConnectionFailure(true)
         connectTimeout(0, TimeUnit.SECONDS)
      }
   }
}

이 예제는 OkHttp 엔진을 구성하는 방법을 보여주지만, Android에서 지원되는 다른 엔진도 사용할 수 있습니다.

shared/src/iosMain/kotlin/com/example/kmpktor/Platform.kt를 열고 iOS 모듈용 httpClient() 함수의 actual 선언을 추가합니다:

kotlin

import io.ktor.client.*
import io.ktor.client.engine.darwin.*

actual fun httpClient(config: HttpClientConfig<*>.() -> Unit) = HttpClient(Darwin) {
   config(this)
   engine {
      configureRequest {
         setAllowsCellularAccess(true)
      }
   }
}

이제 공유 코드에서 어떤 엔진이 사용되는지 걱정할 필요 없이 httpClient()를 호출할 수 있습니다.

공유 코드에서 클라이언트를 사용하려면 shared/src/commonMain/kotlin/com/example/kmpktor/Greeting.kt를 열고 HttpClient() 생성자를 httpClient() 함수 호출로 바꿉니다:
kotlin
```
private val client = httpClient()
```

종속성 추가

템플릿

인증 및 권한 부여

JSON 웹 토큰

WebSocket

Fat JAR 생성

인증 및 권한 부여

WebSocket

클라이언트 엔진 ​

지원되는 플랫폼 ​

지원되는 Android/Java 버전 ​

엔진 종속성 추가 ​

엔진 지정 ​

기본 엔진 ​

엔진 구성 ​

JVM ​

Apache5 ​

Java ​

Jetty ​

JVM 및 Android ​

Android ​

OkHttp ​

네이티브 ​

Darwin ​

WinHttp ​

Curl ​

JVM, Android, Native, JS 및 WasmJs ​

CIO ​

JavaScript ​

제한 사항 ​

HTTP/2 및 WebSockets ​

보안 ​

프록시 지원 ​

로깅 ​

타임아웃 ​

예시: 멀티플랫폼 모바일 프로젝트에서 엔진을 구성하는 방법 ​

클라이언트 엔진

지원되는 플랫폼

지원되는 Android/Java 버전

엔진 종속성 추가

엔진 지정

기본 엔진

엔진 구성

JVM

Apache5

Java

Jetty

JVM 및 Android

Android

OkHttp

네이티브

Darwin

WinHttp

Curl

JVM, Android, Native, JS 및 WasmJs

CIO

JavaScript

제한 사항

HTTP/2 및 WebSockets

보안

프록시 지원

로깅

타임아웃

예시: 멀티플랫폼 모바일 프로젝트에서 엔진을 구성하는 방법