Skip to content
Client Plugin

타입 안전한 요청

필수 의존성: io.ktor:ktor-client-resources

코드 예제: client-type-safe-requests

Ktor는 타입 안전한 클라이언트 요청을 만들기 위한 Resources 플러그인을 제공합니다. 이를 위해 서버 엔드포인트를 나타내는 클래스를 정의하고 @Resource 키워드로 어노테이션을 지정합니다.

리소스 클래스는 kotlinx.serialization을 사용하여 프로퍼티를 경로 및 쿼리 파라미터로 변환합니다.

서버 측에서 Ktor는 타입 안전한 라우팅을 제공합니다.

의존성 추가 ​

kotlinx.serialization 추가 ​

Resources 플러그인은 kotlinx.serialization에 의존합니다. kotlinx.serialization 설정 가이드에 설명된 대로 Kotlin 직렬화 플러그인을 활성화하세요.

Resources 의존성 추가 ​

Resources을(를) 사용하려면 빌드 스크립트에 ktor-client-resources 아티팩트를 추가하세요:

kotlin
implementation(ktorLibs.client.resources)
위 코드 스니펫은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.
groovy
implementation ktorLibs.client.resources
위 코드 스니펫은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-client-resources-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>
Ktor 클라이언트에 필요한 아티팩트에 대해 자세히 알아보려면 클라이언트 의존성 추가하기기존 프로젝트에 클라이언트 의존성을 추가하는 방법을 알아봅니다.를 참조하세요.

Resources 설치 ​

Resources 플러그인을 설치하려면 클라이언트 구성 블록의 install 함수에 전달하세요:

kotlin
import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.resources.*
//...
val client = HttpClient(CIO) {
    install(Resources)
}

리소스 클래스 생성 ​

각 리소스 클래스에는 @Resource 어노테이션이 있어야 합니다. 아래에서는 단일 경로 세그먼트, 쿼리 및 경로 파라미터 등을 정의하는 리소스 클래스의 몇 가지 예제를 살펴보겠습니다.

리소스 URL ​

아래 예제는 /articles 경로에 응답하는 리소스를 지정하는 Articles 클래스를 정의하는 방법을 보여줍니다.

kotlin
import io.ktor.resources.*

@Resource("/articles")
class Articles()

쿼리 파라미터가 있는 리소스 ​

아래의 Articles 클래스에는 쿼리 파라미터 역할을 하는 sort 문자열 프로퍼티가 있으며, sort 쿼리 파라미터가 포함된 /articles?sort=new 경로에 응답하는 리소스를 정의할 수 있게 해줍니다.

kotlin
@Resource("/articles")
class Articles(val sort: String? = "new")

중첩 클래스가 있는 리소스 ​

여러 경로 세그먼트를 포함하는 리소스를 생성하기 위해 클래스를 중첩할 수 있습니다. 이 경우 중첩된 클래스에는 외부 클래스 타입을 갖는 프로퍼티가 있어야 합니다. 아래 예제는 /articles/new 경로에 응답하는 리소스를 보여줍니다.

kotlin
@Resource("/articles")
class Articles() {
    @Resource("new")
    class New(val parent: Articles = Articles())
}

경로 파라미터가 있는 리소스 ​

아래 예제는 경로 세그먼트와 일치하고 이를 id라는 이름의 파라미터로 캡처하는 중첩된 {id} 정수형 경로 파라미터를 추가하는 방법을 보여줍니다.

kotlin
@Resource("/articles")
class Articles() {
    @Resource("{id}")
    class Id(val parent: Articles = Articles(), val id: Long)
}

예를 들어, 이 리소스는 /articles/12에 응답하는 데 사용할 수 있습니다.

예제: CRUD 작업을 위한 리소스 ​

다음 예제는 CRUD 작업을 위한 Articles 리소스를 생성합니다:

kotlin
@Resource("/articles")
class Articles() {
    @Resource("new")
    class New(val parent: Articles = Articles())

    @Resource("{id}")
    class Id(val parent: Articles = Articles(), val id: Long) {
        @Resource("edit")
        class Edit(val parent: Id)
    }
}

이 리소스는 모든 기사 목록 조회, 새 기사 작성, 기존 기사 수정에 사용할 수 있습니다.

다음 섹션에서는 이 리소스를 사용하여 타입 안전한 요청을 만드는 방법을 보여줍니다.

전체 예제는 client-type-safe-requests를 참조하세요.

타입 안전한 요청 만들기 ​

타입이 지정된 리소스에 요청을 보내려면, request(), get(), post(), put()과 같은 요청 함수에 리소스 클래스 인스턴스를 전달하세요.

다음 예제는 /articles 경로로 요청을 보냅니다:

kotlin
@Resource("/articles")
class Articles()

fun main() {
    runBlocking {
        val client = HttpClient(CIO) {
            install(Resources)
            // ...
        }
        val getAllArticles = client.get(Articles())
    }
}

다음 예제는 예제: CRUD 작업을 위한 리소스에서 생성한 Articles 리소스에 타입 지정된 요청을 보냅니다.

kotlin
fun main() {
    defaultServer(Application::module).start()
    runBlocking {
        val client = HttpClient(CIO) {
            install(Resources)
            defaultRequest {
                host = "0.0.0.0"
                port = 8080
                url { protocol = URLProtocol.HTTP }
            }
        }

        val getAllArticles = client.get(Articles())
        val newArticle = client.get(Articles.New())
        val postArticle = client.post(Articles()) { setBody("Article content") }
        val getArticle = client.get(Articles.Id(id = 12))
        val editArticlePage = client.get(Articles.Id.Edit(Articles.Id(id = 12)))
        val putArticle = client.put(Articles.Id(id = 12)) { setBody("New article content") }
        val deleteArticle = client.delete(Articles.Id(id = 12))
}

defaultRequest() 함수는 모든 요청에 대한 기본 URL을 지정합니다.

클라이언트 플러그인 또는 계측(instrumentation)을 개발할 때, RESOURCE 요청 속성을 통해 타입 안전한 요청에 사용된 리소스 인스턴스에 접근할 수 있습니다:

kotlin
onRequest { call, _ ->
  val resource = call.attributes.getOrNull(RESOURCE)
}

전체 예제는 client-type-safe-requests를 참조하세요.