Skip to content

클라이언트 의존성 추가 ​

프로젝트에서 Ktor HTTP 클라이언트를 사용하려면 저장소를 구성하고 다음 의존성을 추가해야 합니다.

  • ktor-client-core

    ktor-client-core에는 Ktor 클라이언트의 핵심 기능이 포함되어 있습니다.

  • 엔진 의존성

    엔진은 네트워크 요청을 처리하는 데 사용됩니다. 특정 플랫폼에서는 네트워크 요청을 처리하기 위해 특정 엔진이 필요할 수 있습니다.

  • (선택 사항) 로깅 의존성

    구조화되고 유연한 로깅 기능을 사용할 수 있도록 로깅 프레임워크를 제공합니다.

  • (선택 사항) 플러그인 의존성

    플러그인은 클라이언트에 특정 기능을 확장하는 데 사용됩니다.

저장소 구성

Ktor 의존성을 추가하기 전에 먼저 이 프로젝트에 대한 저장소를 구성해야 합니다:

  • 프로덕션(Production)

    Ktor의 프로덕션 릴리스는 Maven Central 저장소에서 제공됩니다. 빌드 스크립트에 다음과 같이 이 저장소를 선언할 수 있습니다:

    kotlin
    repositories {
        mavenCentral()
    }
    groovy
    repositories {
        mavenCentral()
    }

    프로젝트가 Super POM으로부터 중앙 저장소를 상속받으므로 pom.xml 파일에 Maven Central 저장소를 추가할 필요가 없습니다.

  • Early Access Program (EAP)

    Ktor의 EAP 버전을 사용하려면 Space 저장소를 참조해야 합니다:

    kotlin
    repositories {
        maven {
            url = uri("https://redirector.kotlinlang.org/maven/ktor-eap")
        }
    }
    groovy
    repositories {
        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)를 필요로 할 수 있습니다:

    kotlin
    repositories {
        maven {
            url = uri("https://redirector.kotlinlang.org/maven/dev")
        }
    }
    groovy
    repositories {
        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 아티팩트에서 제공됩니다. 사용하는 빌드 시스템에 따라 다음과 같은 방법으로 추가할 수 있습니다:

kotlin
implementation(ktorLibs.client.core)
위 코드 조각은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.
groovy
implementation ktorLibs.client.core
위 코드 조각은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-client-core-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

멀티플랫폼 ​

멀티플랫폼 프로젝트의 경우, settings.gradle.kts 파일에서 Ktor 버전 카탈로그를 가져옵니다:

kotlin
dependencyResolutionManagement {
    versionCatalogs {
        create("ktorLibs").from("io.ktor:ktor-version-catalog:3.6.1")
    }
}

그런 다음, commonMain 소스 세트에 ktor-client-core를 의존성으로 추가합니다:

kotlin
kotlin {
    sourceSets {
        commonMain {
            dependencies {
              implementation(ktorLibs.client.core)
            }
        }
    }
}

엔진 의존성 ​

엔진은 네트워크 요청을 처리하는 역할을 담당합니다. Ktor는 다양한 플랫폼에 맞는 여러 클라이언트 엔진을 제공합니다.

예를 들어, 다음과 같이 CIO 엔진을 추가할 수 있습니다:

kotlin
implementation(ktorLibs.client.cio)
위 코드 조각은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.
groovy
implementation ktorLibs.client.cio
위 코드 조각은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-client-cio-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

멀티플랫폼 ​

기본 엔진 사용 ​

멀티플랫폼 프로젝트에서는 ktor-client-engine-defaults 아티팩트를 사용하여 각 타깃 플랫폼에 적합하게 선별된 클라이언트 엔진을 제공할 수 있습니다.

해당 아티팩트 의존성을 commonMain 소스 세트에 추가합니다:

kotlin
kotlin {
    sourceSets {
        commonMain {
            dependencies {
                api(ktorLibs.client.engineDefaults)
            }
        }
    }
}
위 코드 조각은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.
특정 엔진 사용 ​

특정 엔진이 필요한 경우, 대신 해당하는 플랫폼 소스 세트에 해당 엔진의 의존성을 추가합니다. 예를 들어 Android에서 OkHttp를 사용하려면 androidMain 소스 세트에 ktorLibs.client.okhttp를 추가합니다:

kotlin
sourceSets {
    androidMain.dependencies {
        implementation(ktorLibs.client.okhttp)
    }
}
위 코드 조각은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.

각 엔진에 필요한 의존성은 엔진 의존성 추가를 참조하세요.

로깅 의존성 ​

JVM에서 Ktor는 로깅을 위한 추상화 계층으로 Java용 Simple Logging Facade(SLF4J)를 사용합니다. SLF4J는 로깅 API를 기본 로깅 구현과 분리하므로, 애플리케이션 요구사항에 가장 적합한 로깅 프레임워크를 통합할 수 있습니다. 일반적으로 Logback 또는 Log4j가 많이 사용됩니다. 프레임워크가 제공되지 않으면 SLF4J는 기본적으로 NOP(No-Operation) 구현을 사용하며, 이는 사실상 로깅을 비활성화합니다.

로깅을 활성화하려면 Logback과 같이 필요한 SLF4J 구현이 포함된 아티팩트를 추가합니다:

kotlin
implementation("ch.qos.logback:logback-classic:$logback_version")
groovy
implementation "ch.qos.logback:logback-classic:$logback_version"
xml
<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 의존성을 추가하려면 빌드 스크립트에 다음과 같이 선언합니다:

kotlin
implementation(platform("io.ktor:ktor-bom:$ktor_version"))
groovy
implementation platform "io.ktor:ktor-bom:$ktor_version"
xml
  <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에서 원하는 이름으로 버전 카탈로그를 생성합니다:

kotlin
dependencyResolutionManagement {
    versionCatalogs {
        create("ktorLibs") {
            from("io.ktor:ktor-version-catalog:3.6.1")
        }
    }
}

그런 다음 해당 카탈로그 이름을 참조하여 모듈의 build.gradle.kts에 의존성을 추가할 수 있습니다:

kotlin
dependencies {
    implementation(ktorLibs.client.core)
    // ...
}