상태 페이지
필수 의존성: io.ktor:ktor-server-status-pages
코드 예제: status-pages
네이티브 서버Ktor는 Kotlin/Native를 지원하므로 추가 런타임이나 가상 머신 없이도 서버를 실행할 수 있습니다. 지원: ✅
StatusPages 플러그인을 사용하면 Ktor 애플리케이션이 발생한 예외나 상태 코드를 기반으로 모든 실패 상태에 적절히 응답할 수 있습니다.
의존성 추가
StatusPages을(를) 사용하려면 빌드 스크립트에 ktor-server-status-pages 아티팩트를 추가합니다:
implementation(ktorLibs.server.statusPages)implementation ktorLibs.server.statusPages<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-server-status-pages-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>StatusPages 설치
애플리케이션에 StatusPages 플러그인을 설치하려면, 지정된 모듈모듈을 사용하면 라우트를 그룹화하여 애플리케이션의 구조를 설계할 수 있습니다.의 install 함수에 전달합니다. 다음 예제는 StatusPages을(를) 설치하는 방법을 보여줍니다:
embeddedServer()함수 호출 내에서 설치.Application클래스에 명시적으로 정의된module()확장 함수 내에서 설치.
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.plugins.statuspages.*
fun main() {
embeddedServer(Netty, port = 8080) {
install(StatusPages)
// ...
}.start(wait = true)
}import io.ktor.server.application.*
import io.ktor.server.plugins.statuspages.*
// ...
fun Application.module() {
install(StatusPages)
// ...
}StatusPages 구성
StatusPages 플러그인에서 제공하는 세 가지 주요 구성 옵션은 다음과 같습니다:
- exceptions: 매핑된 예외 클래스를 기반으로 응답 구성
- status: 상태 코드 값에 대한 응답 구성
- statusFile: 클래스패스(classpath)의 파일 응답 구성
예외
exception 핸들러를 사용하면 Throwable 예외를 발생시키는 호출을 처리할 수 있습니다. 가장 기본적인 경우, 모든 예외에 대해 500 HTTP 상태 코드를 구성할 수 있습니다:
install(StatusPages) {
exception<Throwable> { call, cause ->
call.respondText(text = "500: $cause" , status = HttpStatusCode.InternalServerError)
}
}특정 예외를 확인하고 필요한 내용으로 응답할 수도 있습니다:
install(StatusPages) {
exception<Throwable> { call, cause ->
if(cause is AuthorizationException) {
call.respondText(text = "403: $cause" , status = HttpStatusCode.Forbidden)
} else {
call.respondText(text = "500: $cause" , status = HttpStatusCode.InternalServerError)
}
}
}상태 코드
status 핸들러는 상태 코드를 기반으로 특정 콘텐츠를 응답하는 기능을 제공합니다. 아래 예제는 서버에 리소스가 없는 경우(404 상태 코드) 요청에 응답하는 방법을 보여줍니다:
install(StatusPages) {
status(HttpStatusCode.NotFound) { call, status ->
call.respondText(text = "404: Page Not Found", status = status)
}
}상태 파일
statusFile 핸들러를 사용하면 상태 코드를 기반으로 HTML 페이지를 제공할 수 있습니다. 프로젝트의 resources 폴더에 error401.html 및 error402.html HTML 페이지가 포함되어 있다고 가정해 보겠습니다. 이 경우 다음과 같이 statusFile을 사용하여 401 및 402 상태 코드를 처리할 수 있습니다:
install(StatusPages) {
statusFile(HttpStatusCode.Unauthorized, HttpStatusCode.PaymentRequired, filePattern = "error#.html")
}statusFile 핸들러는 구성된 상태 목록 내에서 임의의 # 문자를 해당 상태 코드 값으로 대체합니다.
전체 예제는 여기에서 확인할 수 있습니다: status-pages.
