타입 안전한 라우팅
필요한 의존성: io.ktor:ktor-server-resources
코드 예제: resource-routing
네이티브 서버Ktor는 Kotlin/Native를 지원하므로 추가 런타임이나 가상 머신 없이도 서버를 실행할 수 있습니다. 지원: ✅
Ktor는 타입 안전한 라우팅을 구현할 수 있도록 Resources 플러그인을 제공합니다. 이를 수행하려면 타입 지정된 라우트 역할을 할 클래스를 생성한 다음, @Resource 키워드를 사용하여 이 클래스에 어노테이션을 지정해야 합니다. @Resource 어노테이션은 kotlinx.serialization 라이브러리에서 제공하는 @Serializable 동작을 포함하고 있습니다.
Ktor 클라이언트는 서버로 타입 지정된 요청을 보낼 수 있는 기능을 제공합니다.
의존성 추가
kotlinx.serialization 추가
리소스 클래스는 @Serializable 동작을 가져야 하므로, 설정(Setup) 섹션에 설명된 대로 Kotlin 직렬화 플러그인을 추가해야 합니다.
Resources 의존성 추가
Resources을(를) 사용하려면 빌드 스크립트에 ktor-server-resources 아티팩트를 추가합니다:
implementation(ktorLibs.server.resources)implementation ktorLibs.server.resources<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-server-resources-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>Resources 설치
애플리케이션에 Resources 플러그인을 설치하려면, 지정된 모듈모듈을 사용하면 라우트를 그룹화하여 애플리케이션의 구조를 설계할 수 있습니다.의 install 함수에 전달하세요. 다음 예제는 Resources을(를) 설치하는 방법을 보여줍니다:
embeddedServer()함수 호출 내에서 설치.Application클래스에 명시적으로 정의된module()확장 함수 내에서 설치.
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.resources.*
fun main() {
embeddedServer(Netty, port = 8080) {
install(Resources)
// ...
}.start(wait = true)
}import io.ktor.server.application.*
import io.ktor.server.resources.*
// ...
fun Application.module() {
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(val sort: String? = "new") {
@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)
}
}이 리소스는 모든 기사 목록 조회, 새 기사 등록, 기사 수정 등에 사용할 수 있습니다. 다음 장에서는 이 리소스에 대한 라우트 핸들러를 정의하는 방법을 살펴보겠습니다.
전체 예제는 여기에서 확인할 수 있습니다: resource-routing.
라우트 핸들러 정의
타입 지정된 리소스에 대해 라우트 핸들러를 정의하려면 HTTP 동사 함수(get, post, put 등)에 리소스 클래스를 전달해야 합니다. 예를 들어 아래의 라우트 핸들러는 /articles 경로에 응답합니다.
@Resource("/articles")
class Articles()
fun Application.module() {
install(Resources)
routing {
get<Articles> { articles ->
// Get all articles ...
call.respondText("List of articles: $articles")
}
}
}아래 예제는 예제: CRUD 작업을 위한 리소스에서 생성한 Articles 리소스에 대한 라우트 핸들러를 정의하는 방법을 보여줍니다. 라우트 핸들러 내부에서 Article을 파라미터로 접근하여 해당 프로퍼티 값을 얻을 수 있습니다.
fun Application.module() {
install(Resources)
routing {
get<Articles> { article ->
// Get all articles ...
call.respondText("List of articles sorted starting from ${article.sort}")
}
get<Articles.New> {
// Show a page with fields for creating a new article ...
call.respondText("Create a new article")
}
post<Articles> {
// Save an article ...
call.respondText("An article is saved", status = HttpStatusCode.Created)
}
get<Articles.Id> { article ->
// Show an article with id ${article.id} ...
call.respondText("An article with id ${article.id}", status = HttpStatusCode.OK)
}
get<Articles.Id.Edit> { article ->
// Show a page with fields for editing an article ...
call.respondText("Edit an article with id ${article.parent.id}", status = HttpStatusCode.OK)
}
put<Articles.Id> { article ->
// Update an article ...
call.respondText("An article with id ${article.id} updated", status = HttpStatusCode.OK)
}
delete<Articles.Id> { article ->
// Delete an article ...
call.respondText("An article with id ${article.id} deleted", status = HttpStatusCode.OK)
}
}
}각 엔드포인트에 대한 요청 처리에 관한 몇 가지 팁은 다음과 같습니다:
get<Articles>이 라우트 핸들러는
sort쿼리 파라미터에 따라 정렬된 모든 기사를 반환하도록 되어 있습니다. 예를 들어 모든 기사가 포함된 HTML 페이지 또는 JSON 객체일 수 있습니다.get<Articles.New>이 엔드포인트는 새 기사를 작성하기 위한 필드가 포함된 웹 폼으로 응답합니다.
post<Articles>post<Articles>엔드포인트는 웹 폼을 통해 전송된 파라미터를 수신하도록 되어 있습니다. Ktor에서는ContentNegotiation플러그인을 사용하여 JSON 데이터를 객체로 수신할 수도 있습니다.get<Articles.Id>이 라우트 핸들러는 지정된 식별자를 가진 기사를 반환하도록 되어 있습니다. 기사를 보여주는 HTML 페이지이거나 기사 데이터가 포함된 JSON 객체일 수 있습니다.
get<Articles.Id.Edit>이 엔드포인트는 기존 기사를 편집하기 위한 필드가 포함된 웹 폼으로 응답합니다.
put<Articles.Id>post<Articles>엔드포인트와 유사하게,put핸들러는 웹 폼을 통해 전송된 폼 파라미터를 수신합니다.delete<Articles.Id>이 라우트 핸들러는 지정된 식별자를 가진 기사를 삭제합니다.
전체 예제는 여기에서 확인할 수 있습니다: resource-routing.
리소스로부터 링크 생성
리소스 정의는 라우팅에 사용하는 것 외에도 링크를 생성하는 데 사용할 수 있습니다. 이를 종종 _역방향 라우팅(reverse routing)_이라고 부릅니다. 리소스로부터 링크를 생성하는 기능은 HTML DSL로 작성된 HTML 문서에 이러한 링크를 추가해야 하거나 리디렉션 응답을 생성해야 할 때 유용할 수 있습니다.
Resources 플러그인은 오버로드된 href 메서드로 Application을 확장하여 Resource로부터 링크를 생성할 수 있도록 지원합니다. 예를 들어 아래의 코드 스니펫은 위에서 정의한 Edit 리소스에 대한 링크를 생성합니다:
val link: String = href(Articles.Id.Edit(Articles.Id(id = 123)))조부모 리소스인 Articles가 기본값 new를 갖는 sort 쿼리 파라미터를 정의하고 있으므로, link 변수에는 다음 내용이 포함됩니다:
/articles/123/edit?sort=new호스트와 프로토콜이 지정된 URL을 생성하려면 href 메서드에 URLBuilder를 전달할 수 있습니다. 다음 예제에서 볼 수 있듯이 URLBuilder를 사용하여 추가 쿼리 파라미터를 지정할 수도 있습니다:
val urlBuilder = URLBuilder(URLProtocol.HTTPS, "ktor.io", parameters = parametersOf("token", "123"))
href(Articles(sort = null), urlBuilder)
val link: String = urlBuilder.buildString()이후 link 변수에는 다음이 포함됩니다:
https://ktor.io/articles?token=123예제
아래 예제는 리소스로부터 생성된 링크를 HTML 응답에 추가하는 방법을 보여줍니다:
get {
call.respondHtml {
body {
this@module.apply {
p {
val link: String = href(Articles())
a(link) { +"Get all articles" }
}
p {
val link: String = href(Articles.New())
a(link) { +"Create a new article" }
}
p {
val link: String = href(Articles.Id.Edit(Articles.Id(id = 123)))
a(link) { +"Edit an exising article" }
}
p {
val urlBuilder = URLBuilder(URLProtocol.HTTPS, "ktor.io", parameters = parametersOf("token", "123"))
href(Articles(sort = null), urlBuilder)
val link: String = urlBuilder.buildString()
i { a(link) { +link } }
}
}
}
}
}전체 예제는 여기에서 확인할 수 있습니다: resource-routing.
