타입 안전한 요청
필수 의존성: 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 아티팩트를 추가하세요:
implementation(ktorLibs.client.resources)implementation ktorLibs.client.resources<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-client-resources-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>Resources 설치
Resources 플러그인을 설치하려면 클라이언트 구성 블록의 install 함수에 전달하세요:
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 클래스를 정의하는 방법을 보여줍니다.
import io.ktor.resources.*
@Resource("/articles")
class Articles()쿼리 파라미터가 있는 리소스
아래의 Articles 클래스에는 쿼리 파라미터 역할을 하는 sort 문자열 프로퍼티가 있으며, sort 쿼리 파라미터가 포함된 /articles?sort=new 경로에 응답하는 리소스를 정의할 수 있게 해줍니다.
@Resource("/articles")
class Articles(val sort: String? = "new")중첩 클래스가 있는 리소스
여러 경로 세그먼트를 포함하는 리소스를 생성하기 위해 클래스를 중첩할 수 있습니다. 이 경우 중첩된 클래스에는 외부 클래스 타입을 갖는 프로퍼티가 있어야 합니다. 아래 예제는 /articles/new 경로에 응답하는 리소스를 보여줍니다.
@Resource("/articles")
class Articles() {
@Resource("new")
class New(val parent: Articles = Articles())
}경로 파라미터가 있는 리소스
아래 예제는 경로 세그먼트와 일치하고 이를 id라는 이름의 파라미터로 캡처하는 중첩된 {id} 정수형 경로 파라미터를 추가하는 방법을 보여줍니다.
@Resource("/articles")
class Articles() {
@Resource("{id}")
class Id(val parent: Articles = Articles(), val id: Long)
}예를 들어, 이 리소스는 /articles/12에 응답하는 데 사용할 수 있습니다.
예제: CRUD 작업을 위한 리소스
다음 예제는 CRUD 작업을 위한 Articles 리소스를 생성합니다:
@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 경로로 요청을 보냅니다:
@Resource("/articles")
class Articles()
fun main() {
runBlocking {
val client = HttpClient(CIO) {
install(Resources)
// ...
}
val getAllArticles = client.get(Articles())
}
}다음 예제는 예제: CRUD 작업을 위한 리소스에서 생성한 Articles 리소스에 타입 지정된 요청을 보냅니다.
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 요청 속성을 통해 타입 안전한 요청에 사용된 리소스 인스턴스에 접근할 수 있습니다:
onRequest { call, _ ->
val resource = call.attributes.getOrNull(RESOURCE)
}전체 예제는 client-type-safe-requests를 참조하세요.
