클라이언트 의존성 추가
프로젝트에서 Ktor HTTP 클라이언트를 사용하려면 저장소를 구성하고 다음 의존성을 추가해야 합니다.
ktor-client-core에는 Ktor 클라이언트의 핵심 기능이 포함되어 있습니다.엔진은 네트워크 요청을 처리하는 데 사용됩니다. 특정 플랫폼에서는 네트워크 요청을 처리하기 위해 특정 엔진이 필요할 수 있습니다.
(선택 사항) 로깅 의존성
구조화되고 유연한 로깅 기능을 사용할 수 있도록 로깅 프레임워크를 제공합니다.
(선택 사항) 플러그인 의존성
플러그인은 클라이언트에 특정 기능을 확장하는 데 사용됩니다.
저장소 구성
Ktor 의존성을 추가하기 전에 먼저 이 프로젝트에 대한 저장소를 구성해야 합니다:
프로덕션(Production)
Ktor의 프로덕션 릴리스는 Maven Central 저장소에서 제공됩니다. 빌드 스크립트에 다음과 같이 이 저장소를 선언할 수 있습니다:
kotlinrepositories { mavenCentral() }groovyrepositories { mavenCentral() }프로젝트가 Super POM으로부터 중앙 저장소를 상속받으므로 pom.xml 파일에 Maven Central 저장소를 추가할 필요가 없습니다.
Early Access Program (EAP)
Ktor의 EAP 버전을 사용하려면 Space 저장소를 참조해야 합니다:
kotlinrepositories { maven { url = uri("https://redirector.kotlinlang.org/maven/ktor-eap") } }groovyrepositories { maven { url "https://redirector.kotlinlang.org/maven/ktor-eap" } }xml<repositories> <repository> <id>ktor-eap</id> <url>https://redirector.kotlinlang.org/maven/ktor-eap</url> </repository> </repositories>Ktor EAP 버전은 Kotlin 개발 저장소(dev repository)를 필요로 할 수 있습니다:
kotlinrepositories { maven { url = uri("https://redirector.kotlinlang.org/maven/dev") } }groovyrepositories { maven { url "https://redirector.kotlinlang.org/maven/dev" } }xml<repositories> <repository> <id>ktor-eap</id> <url>https://redirector.kotlinlang.org/maven/dev</url> </repository> </repositories>
의존성 추가
다양한 플랫폼을 위해 Ktor는 ktor-client-core-jvm과 같이 -jvm 또는 -js와 같은 접미사가 붙은 플랫폼별 아티팩트를 제공합니다. Gradle은 주어진 플랫폼에 적합한 아티팩트를 자동으로 확인하고 해결하지만, Maven은 이 기능을 지원하지 않습니다. 따라서 Maven을 사용할 때는 플랫폼별 접미사를 직접 추가해야 합니다.
클라이언트 의존성
핵심 클라이언트 기능은 ktor-client-core 아티팩트에서 제공됩니다. 사용하는 빌드 시스템에 따라 다음과 같은 방법으로 추가할 수 있습니다:
implementation(ktorLibs.client.core)implementation ktorLibs.client.core<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-client-core-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>멀티플랫폼
멀티플랫폼 프로젝트의 경우, settings.gradle.kts 파일에서 Ktor 버전 카탈로그를 가져옵니다:
dependencyResolutionManagement {
versionCatalogs {
create("ktorLibs").from("io.ktor:ktor-version-catalog:3.6.1")
}
}그런 다음, commonMain 소스 세트에 ktor-client-core를 의존성으로 추가합니다:
kotlin {
sourceSets {
commonMain {
dependencies {
implementation(ktorLibs.client.core)
}
}
}
}엔진 의존성
엔진은 네트워크 요청을 처리하는 역할을 담당합니다. Ktor는 다양한 플랫폼에 맞는 여러 클라이언트 엔진을 제공합니다.
예를 들어, 다음과 같이 CIO 엔진을 추가할 수 있습니다:
implementation(ktorLibs.client.cio)implementation ktorLibs.client.cio<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-client-cio-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>멀티플랫폼
기본 엔진 사용
멀티플랫폼 프로젝트에서는 ktor-client-engine-defaults 아티팩트를 사용하여 각 타깃 플랫폼에 적합하게 선별된 클라이언트 엔진을 제공할 수 있습니다.
해당 아티팩트 의존성을 commonMain 소스 세트에 추가합니다:
kotlin {
sourceSets {
commonMain {
dependencies {
api(ktorLibs.client.engineDefaults)
}
}
}
}특정 엔진 사용
특정 엔진이 필요한 경우, 대신 해당하는 플랫폼 소스 세트에 해당 엔진의 의존성을 추가합니다. 예를 들어 Android에서 OkHttp를 사용하려면 androidMain 소스 세트에 ktorLibs.client.okhttp를 추가합니다:
sourceSets {
androidMain.dependencies {
implementation(ktorLibs.client.okhttp)
}
}각 엔진에 필요한 의존성은 엔진 의존성 추가를 참조하세요.
로깅 의존성
JVM에서 Ktor는 로깅을 위한 추상화 계층으로 Java용 Simple Logging Facade(SLF4J)를 사용합니다. SLF4J는 로깅 API를 기본 로깅 구현과 분리하므로, 애플리케이션 요구사항에 가장 적합한 로깅 프레임워크를 통합할 수 있습니다. 일반적으로 Logback 또는 Log4j가 많이 사용됩니다. 프레임워크가 제공되지 않으면 SLF4J는 기본적으로 NOP(No-Operation) 구현을 사용하며, 이는 사실상 로깅을 비활성화합니다.
로깅을 활성화하려면 Logback과 같이 필요한 SLF4J 구현이 포함된 아티팩트를 추가합니다:
implementation("ch.qos.logback:logback-classic:$logback_version")implementation "ch.qos.logback:logback-classic:$logback_version"<dependency>
<groupId>ch.qos.logback</groupId>
<artifactId>logback-classic</artifactId>
<version>${logback_version}</version>
</dependency>Ktor에서의 로깅에 관한 자세한 내용은 Ktor Client 로깅을 참조하세요.
플러그인 의존성
Ktor를 사용하면 인증이나 직렬화와 같이 기본적으로 제공되지 않는 추가 클라이언트 기능(플러그인)을 사용할 수 있습니다. 이러한 기능 중 일부는 별도의 아티팩트로 제공됩니다. 필요한 플러그인에 대한 주제 문서에서 어떤 의존성이 필요한지 확인할 수 있습니다.
멀티플랫폼 프로젝트의 경우 플러그인 의존성은 commonMain 소스 세트에 추가해야 합니다. 일부 플러그인은 특정 플랫폼에 대해 제한 사항이 있을 수 있습니다.
Ktor 버전 일관성 보장
Ktor BOM 의존성 사용
Ktor BOM을 사용하면 각 의존성의 버전을 개별적으로 지정하지 않고도 모든 Ktor 모듈이 동일하고 일관된 버전을 사용하도록 보장할 수 있습니다.
Ktor BOM 의존성을 추가하려면 빌드 스크립트에 다음과 같이 선언합니다:
implementation(platform("io.ktor:ktor-bom:$ktor_version"))implementation platform "io.ktor:ktor-bom:$ktor_version" <dependencyManagement>
<dependencies>
<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-bom</artifactId>
<version>3.6.1</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>게시된 버전 카탈로그 사용
게시된 버전 카탈로그를 사용하여 Ktor 의존성 선언을 중앙 집중식으로 관리할 수도 있습니다. 이 방식은 다음과 같은 이점을 제공합니다:
- 자체 카탈로그에서 Ktor 버전을 수동으로 선언할 필요가 없습니다.
- 단일 네임스페이스 아래에 모든 Ktor 모듈을 노출합니다.
카탈로그를 선언하려면 settings.gradle.kts에서 원하는 이름으로 버전 카탈로그를 생성합니다:
dependencyResolutionManagement {
versionCatalogs {
create("ktorLibs") {
from("io.ktor:ktor-version-catalog:3.6.1")
}
}
}그런 다음 해당 카탈로그 이름을 참조하여 모듈의 build.gradle.kts에 의존성을 추가할 수 있습니다:
dependencies {
implementation(ktorLibs.client.core)
// ...
}