Server Plugin

상태 페이지

필수 의존성: io.ktor:ktor-server-status-pages

코드 예제: status-pages

네이티브 서버

Ktor supports Kotlin/Native and allows you to run a server without an additional runtime or virtual machine.

지원: ✅

StatusPages 플러그인을 사용하면 Ktor 애플리케이션에서 발생한 예외나 상태 코드에 따라 모든 실패 상태에 적절하게 응답할 수 있습니다.

의존성 추가

StatusPages을 사용하려면 빌드 스크립트에 ktor-server-status-pages 아티팩트를 포함해야 합니다:

Gradle (Kotlin)Gradle (Groovy)Maven

StatusPages 설치

애플리케이션에 StatusPages 플러그인을 설치하려면, 지정된

모듈

Modules allow you to structure your application by grouping routes.

의 install 함수에 해당 플러그인을 전달하세요. 아래 코드 스니펫은 StatusPages을 설치하는 방법을 보여줍니다...

• ... embeddedServer 함수 호출 내부에서.
• ... Application 클래스의 확장 함수인 명시적으로 정의된 module 내부에서.

embeddedServermodule

StatusPages 설정

StatusPages 플러그인에서 제공하는 세 가지 주요 설정 옵션은 다음과 같습니다:

• exceptions: 매핑된 예외 클래스에 따른 응답을 설정합니다.
• status: 상태 코드 값에 따른 응답을 설정합니다.
• statusFile: 클래스패스(classpath)에 있는 파일 응답을 설정합니다.

Exceptions

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

status 핸들러는 상태 코드에 따라 특정 콘텐츠로 응답하는 기능을 제공합니다. 아래 예제는 서버에 리소스가 없는 경우(404 상태 코드) 요청에 응답하는 방법을 보여줍니다:

install(StatusPages) {
    status(HttpStatusCode.NotFound) { call, status ->
        call.respondText(text = "404: Page Not Found", status = status)
    }
}

Status file

statusFile 핸들러를 사용하면 상태 코드에 따라 HTML 페이지를 제공할 수 있습니다. 프로젝트의 resources 폴더에 error401.html 및 error402.html HTML 페이지가 포함되어 있다고 가정해 보겠습니다. 이 경우 다음과 같이 statusFile을 사용하여 401 및 402 상태 코드를 처리할 수 있습니다:

install(StatusPages) {
    statusFile(HttpStatusCode.Unauthorized, HttpStatusCode.PaymentRequired, filePattern = "error#.html")
}

statusFile 핸들러는 설정된 상태 코드 목록 내에서 # 문자를 해당 상태 코드 값으로 바꿉니다.

전체 예제는 여기에서 확인할 수 있습니다: status-pages.