클라이언트 엔진
Ktor HTTP 클라이언트는 멀티플랫폼을 지원하며 JVM, Android, JavaScript (WebAssembly 포함) 및 Native 타깃에서 실행됩니다. 각 플랫폼마다 네트워크 요청을 처리하기 위한 특정 클라이언트 엔진이 필요합니다.
Ktor는 다양한 플랫폼에 맞는 여러 엔진을 제공합니다. 예를 들어 JVM 애플리케이션에는 Apache나 Jetty를, Android에는 OkHttp나 Android를, Kotlin/Native를 타깃으로 하는 데스크톱 애플리케이션에는 Curl을 사용할 수 있습니다.
각 엔진은 서로 다른 기능과 구성 옵션을 지원합니다. 멀티플랫폼 프로젝트에서는 Ktor의 기본 엔진을 사용하거나 개별 타깃에 맞는 특정 엔진을 선택할 수 있습니다.
지원되는 플랫폼
아래 표는 각 엔진에서 지원하는 플랫폼을 보여줍니다.
| 엔진 | 플랫폼 |
|---|---|
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 클라이언트는 ktor-client-core 아티팩트 외에도 특정 엔진에 대한 의존성이 필요합니다.
특정 엔진 사용
지원되는 각 플랫폼에는 사용 가능한 엔진 집합이 있으며, 해당 섹션에서 자세히 설명합니다.
Ktor는 -jvm 또는 -js와 같은 접미사가 붙은 플랫폼별 아티팩트를 제공합니다. 예를 들면 ktor-client-cio-jvm과 같습니다. 의존성 해결(resolution) 방식은 빌드 도구에 따라 다릅니다. Gradle은 지정된 플랫폼에 적합한 아티팩트를 자동으로 확인하지만, Maven은 이 기능을 지원하지 않습니다. 따라서 Maven의 경우 플랫폼 접미사를 직접 지정해야 합니다.
멀티플랫폼 프로젝트에서 기본 엔진 사용
대부분의 Kotlin Multiplatform 프로젝트에서는 ktor-client-engine-defaults 아티팩트를 사용하면 됩니다. 이 아티팩트는 각 타깃 플랫폼에 적합하게 선별된 클라이언트 엔진을 제공하므로, 플랫폼별 소스 세트에 별도의 엔진 의존성을 선언할 필요가 없습니다.
commonMain 소스 세트에 ktor-client-engine-defaults 아티팩트를 추가합니다.
kotlin {
sourceSets {
commonMain {
dependencies {
api("io.ktor:ktor-client-engine-defaults:3.6.1")
}
}
}
}엔진 지정
특정 엔진을 사용하려면 HttpClient 생성자에 엔진 클래스를 전달합니다. 다음 예제는 CIO 엔진을 사용하여 클라이언트를 생성합니다.
import io.ktor.client.*
import io.ktor.client.engine.cio.*
val client = HttpClient(CIO)자동 엔진 선택
엔진 인자를 생략하면 클라이언트는 빌드 스크립트에서 사용 가능한 엔진 의존성 중에서 엔진을 자동으로 선택합니다.
import io.ktor.client.*
val client = HttpClient()타깃 플랫폼에 사용할 수 있는 엔진이 하나뿐이라면 Ktor는 해당 엔진을 사용합니다. 여러 엔진을 사용할 수 있는 경우 Ktor는 우선순위가 가장 높은 엔진을 선택합니다.
기본적으로 CIO는 가장 낮은 우선순위를 갖습니다. 즉, 동일한 플랫폼에서 CIO와 다른 지원 엔진을 모두 사용할 수 있다면 Ktor는 다른 엔진을 선택합니다. CIO는 더 높은 우선순위의 엔진이 없을 때 사용됩니다.
Kotlin Multiplatform 프로젝트의 경우, ktor-client-engine-defaults 의존성이 각 타깃에 대한 기본 엔진을 제공합니다. 또는 해당 플랫폼 소스 세트에 특정 엔진 의존성을 추가할 수도 있습니다.
엔진 구성
엔진을 구성하려면 engine {} 함수를 사용합니다. 모든 엔진은 HttpClientEngineConfig의 공통 옵션을 사용하여 구성할 수 있습니다.
HttpClient() {
engine {
// this: HttpClientEngineConfig
threadsCount = 4
pipelining = true
}
}다음 섹션에서는 다양한 플랫폼에 맞는 특정 엔진의 구성 방법을 알아봅니다.
JVM
JVM 타깃은 Apache5, Java, Jetty 엔진을 지원합니다.
Apache5
Apache5 엔진은 HTTP/1.1과 HTTP/2를 모두 지원하며, 기본적으로 HTTP/2가 활성화되어 있습니다. 새 프로젝트에 권장되는 Apache 기반 엔진입니다.
이전 Apache 엔진은 지원 중단(deprecated)된 Apache HttpClient 4에 의존합니다. 이는 오직 하위 호환성을 위해서만 유지되고 있습니다. 모든 새 프로젝트에는 Apache5를 사용하세요.
ktor-client-apache5의존성을 추가합니다.kotlinimplementation(ktorLibs.client.apache5)위 코드 스니펫은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.groovyimplementation ktorLibs.client.apache5위 코드 스니펫은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.xml<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-apache5-jvm</artifactId> <version>${ktor_version}</version> </dependency>HttpClient생성자의 인자로Apache5클래스를 전달합니다.kotlinimport io.ktor.client.* import io.ktor.client.engine.apache5.* val client = HttpClient(Apache5)engine {}블록을 사용하여Apache5EngineConfig의 프로퍼티에 접근하고 설정합니다.kotlinimport 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 // Apache5 ConnectionManager 구성 configureConnectionManager { setMaxConnPerRoute(1_000) setMaxConnTotal(2_000) } // 기타 설정을 위해 기본 Apache 클라이언트 커스터마이즈 customizeClient { // this: HttpAsyncClientBuilder setProxy(HttpHost("127.0.0.1", 8080)) // ... } // 요청별 설정 커스터마이즈 customizeRequest { // this: RequestConfig.Builder } } }- 최대 연결 수와 같은 커넥션 매니저 설정에는
configureConnectionManager를 사용하세요. 이렇게 하면 Ktor가 관리하는 엔진 동작이 유지됩니다. - 프록시, 인터셉터, 로깅 등 커넥션 매니저와 무관한 설정에만
customizeClient를 사용하세요.
- 최대 연결 수와 같은 커넥션 매니저 설정에는
Java
Java 엔진은 Java 11에서 도입된 Java HTTP Client를 사용합니다. 이를 사용하려면 아래 단계를 따르세요.
ktor-client-java의존성을 추가합니다.kotlinimplementation(ktorLibs.client.java)위 코드 스니펫은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.groovyimplementation ktorLibs.client.java위 코드 스니펫은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.xml<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-java-jvm</artifactId> <version>${ktor_version}</version> </dependency>HttpClient생성자의 인자로 Java 클래스를 전달합니다.kotlinimport io.ktor.client.* import io.ktor.client.engine.java.* val client = HttpClient(Java)엔진을 구성하려면
engine {}블록에서JavaHttpConfig의 프로퍼티를 설정합니다.kotlinimport 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의존성을 추가합니다.kotlinimplementation(ktorLibs.client.jetty)위 코드 스니펫은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.groovyimplementation ktorLibs.client.jetty위 코드 스니펫은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.xml<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-jetty-jakarta-jvm</artifactId> <version>${ktor_version}</version> </dependency>HttpClient생성자의 인자로Jetty클래스를 전달합니다.kotlinimport io.ktor.client.* import io.ktor.client.engine.jetty.jakarta.* val client = HttpClient(Jetty)엔진을 구성하려면
engine {}블록에서JettyEngineConfig의 프로퍼티를 설정합니다.kotlinimport 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의존성을 추가합니다.kotlinimplementation(ktorLibs.client.android)위 코드 스니펫은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.groovyimplementation ktorLibs.client.android위 코드 스니펫은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.xml<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-android-jvm</artifactId> <version>${ktor_version}</version> </dependency>HttpClient생성자의 인자로Android클래스를 전달합니다.kotlinimport io.ktor.client.* import io.ktor.client.engine.android.* val client = HttpClient(Android)엔진을 구성하려면
engine {}블록에서AndroidEngineConfig의 프로퍼티를 설정합니다.kotlinimport 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의존성을 추가합니다.kotlinimplementation(ktorLibs.client.okhttp)위 코드 스니펫은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.groovyimplementation ktorLibs.client.okhttp위 코드 스니펫은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.xml<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-okhttp-jvm</artifactId> <version>${ktor_version}</version> </dependency>HttpClient생성자의 인자로OkHttp클래스를 전달합니다.kotlinimport io.ktor.client.* import io.ktor.client.engine.okhttp.* val client = HttpClient(OkHttp)엔진을 구성하려면
engine {}블록에서OkHttpConfig의 프로퍼티를 설정합니다.kotlinimport 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 duplexStreamingEnabled = true // HTTP/2 연결에서만 사용 가능 } }
Native
Ktor는 Kotlin/Native 타깃을 위해 Darwin, WinHttp, Curl 엔진을 제공합니다.
Kotlin/Native 프로젝트에서 Ktor를 사용하려면 새로운 메모리 관리자(new memory manager)가 필요하며, 이는 Kotlin 1.7.20부터 기본적으로 활성화되어 있습니다.
Darwin
Darwin 엔진은 macOS, iOS, tvOS, watchOS와 같은 Darwin 기반 운영체제를 타깃으로 합니다. 내부적으로 NSURLSession을 사용합니다. Darwin 엔진을 사용하려면 아래 단계를 따르세요.
ktor-client-darwin의존성을 추가합니다.kotlinimplementation("io.ktor:ktor-client-darwin:$ktor_version")groovyimplementation "io.ktor:ktor-client-darwin:$ktor_version"xml<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-darwin-macosx64</artifactId> <version>${ktor_version}</version> </dependency>HttpClient생성자의 인자로Darwin클래스를 전달합니다.kotlinimport io.ktor.client.* import io.ktor.client.engine.darwin.* val client = HttpClient(Darwin)DarwinClientEngineConfig를 사용하여engine {}블록에서 엔진을 구성합니다. 예를 들어,configureRequest로 요청을 사용자 정의하거나configureSession으로 세션을 사용자 정의할 수 있습니다.kotlinval client = HttpClient(Darwin) { engine { configureRequest { setAllowsCellularAccess(true) } } }전체 예제는 client-engine-darwin을 참조하세요.
WinHttp
WinHttp 엔진은 Windows 기반 운영체제를 타깃으로 합니다. WinHttp 엔진을 사용하려면 아래 단계를 따르세요.
ktor-client-winhttp의존성을 추가합니다.kotlinimplementation("io.ktor:ktor-client-winhttp:$ktor_version")groovyimplementation "io.ktor:ktor-client-winhttp:$ktor_version"xml<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-winhttp-mingwx64</artifactId> <version>${ktor_version}</version> </dependency>HttpClient생성자의 인자로WinHttp클래스를 전달합니다.kotlinimport io.ktor.client.* import io.ktor.client.engine.winhttp.* val client = HttpClient(WinHttp)WinHttpClientEngineConfig를 사용하여engine {}블록에서 엔진을 구성합니다. 예를 들어,protocolVersion프로퍼티를 사용하여 HTTP 버전을 변경할 수 있습니다.kotlinval client = HttpClient(WinHttp) { engine { protocolVersion = HttpProtocolVersion.HTTP_1_1 } }전체 예제는 client-engine-winhttp를 참조하세요.
Curl
데스크톱 플랫폼을 위해 Ktor는 Curl 엔진을 제공합니다. 이는 linuxX64, linuxArm64, macosX64, macosArm64, mingwX64에서 지원됩니다. Curl 엔진을 사용하려면 아래 단계를 따르세요.
ktor-client-curl의존성을 추가합니다.kotlinimplementation("io.ktor:ktor-client-curl:$ktor_version")groovyimplementation "io.ktor:ktor-client-curl:$ktor_version"xml<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-curl-macosx64</artifactId> <version>${ktor_version}</version> </dependency>HttpClient생성자의 인자로Curl클래스를 전달합니다.kotlinimport io.ktor.client.* import io.ktor.client.engine.curl.* val client = HttpClient(Curl)CurlClientEngineConfig를 사용하여engine {}블록에서 엔진을 구성합니다. 예를 들어, 테스트 목적으로 SSL 검증을 비활성화할 수 있습니다.kotlinval 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의존성을 추가합니다.kotlinimplementation(ktorLibs.client.cio)위 코드 스니펫은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.groovyimplementation ktorLibs.client.cio위 코드 스니펫은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.xml<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-cio-jvm</artifactId> <version>${ktor_version}</version> </dependency>HttpClient생성자의 인자로CIO클래스를 전달합니다.kotlinimport io.ktor.client.* import io.ktor.client.engine.cio.* val client = HttpClient(CIO)CIOEngineConfig를 사용하여engine {}블록에서 엔진을 구성합니다.kotlinimport 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) } dnsResolver = CioDnsResolver( server = "1.1.1.1", timeout = 3.seconds ) } }
JavaScript
Js 엔진은 Kotlin/JS 프로젝트에서 사용할 수 있습니다. 브라우저 애플리케이션에서는 Fetch API를 사용하고, Node.js에서는 node-fetch를 사용합니다.
Js 엔진을 사용하려면 아래 단계를 따르세요.
ktor-client-js의존성을 추가합니다.kotlinimplementation("io.ktor:ktor-client-js:$ktor_version")groovyimplementation "io.ktor:ktor-client-js:$ktor_version"xml<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-js-macosx64</artifactId> <version>${ktor_version}</version> </dependency>HttpClient()생성자의 인자로Js클래스를 전달합니다.kotlinimport io.ktor.client.* import io.ktor.client.engine.js.* val client = HttpClient(Js)또는
JsClient()함수를 호출하여Js엔진 싱글톤을 가져올 수도 있습니다.kotlinimport io.ktor.client.engine.js.* val client = JsClient()전체 예제는 client-engine-js를 참조하세요.
fetch 재정의(Override)
기본적으로 Js 엔진은 전역 fetch() 함수를 사용합니다. 사용자 정의 구현을 사용하려면 엔진 구성에서 fetch 프로퍼티를 설정하세요.
val client = HttpClient(Js) {
engine {
fetch = { url, init ->
Promise.reject(IllegalStateException("Networking not available"))
}
}
}이 방법은 자체 fetch() 구현이나 래퍼(wrapper)를 제공하는 JavaScript 라이브러리와 통합할 때 유용합니다.
제약 사항
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 구성 옵션을 제공합니다.
프록시 지원
일부 엔진은 프록시를 지원하지 않습니다. 전체 목록은 프록시 문서를 참조하세요.
로깅
Logging 플러그인은 타깃 플랫폼에 따라 다양한 로거 타입을 제공합니다.
타임아웃
HttpTimeout 플러그인은 특정 엔진에서 몇 가지 제약 사항이 있습니다. 전체 목록은 타임아웃 제약 사항을 참조하세요.
예제: 멀티플랫폼 모바일 프로젝트에서 엔진을 구성하는 방법
멀티플랫폼 프로젝트를 빌드할 때 expected 및 actual 선언을 사용하여 각 타깃 플랫폼별로 엔진을 선택하고 구성할 수 있습니다. 이를 통해 대부분의 클라이언트 구성을 공통 코드에서 공유하면서 플랫폼별 코드에서 엔진 전용 옵션을 적용할 수 있습니다. 크로스 플랫폼 모바일 애플리케이션 만들기 튜토리얼에서 생성된 프로젝트를 사용하여 이를 구현하는 방법을 살펴보겠습니다.
shared/src/commonMain/kotlin/com/example/kmpktor/Platform.kt 파일을 열고, 구성 블록을 받아
HttpClient를 반환하는 최상위httpClient()함수를 추가합니다.kotlinexpect fun httpClient(config: HttpClientConfig<*>.() -> Unit = {}): HttpClientshared/src/androidMain/kotlin/com/example/kmpktor/Platform.kt 파일을 열고, Android 모듈을 위한
httpClient()함수의 actual 선언을 추가합니다.kotlinimport 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 선언을 추가합니다.kotlinimport 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()함수 호출로 변경합니다.kotlinprivate val client = httpClient()
