Как обрабатывать ошибки и исключения глобально в Ktor с помощью StatusPages?

Подключение плагина

// build.gradle.kts
dependencies {
    implementation("io.ktor:ktor-server-status-pages:2.3.12")
}

Базовая конфигурация

import io.ktor.http.*
import io.ktor.server.application.*
import io.ktor.server.plugins.statuspages.*
import io.ktor.server.response.*
import kotlinx.serialization.Serializable

@Serializable
data class ErrorResponse(val code: Int, val message: String, val details: String? = null)

fun Application.configureStatusPages() {
    install(StatusPages) {
        // Перехват конкретного исключения
        exception<IllegalArgumentException> { call, cause ->
            call.respond(
                HttpStatusCode.BadRequest,
                ErrorResponse(400, "Bad request", cause.message)
            )
        }

        // Перехват доменного исключения
        exception<NotFoundException> { call, cause ->
            call.respond(
                HttpStatusCode.NotFound,
                ErrorResponse(404, cause.message ?: "Not found")
            )
        }

        // Перехват всех необработанных исключений
        exception<Throwable> { call, cause ->
            call.application.environment.log.error("Unhandled error", cause)
            call.respond(
                HttpStatusCode.InternalServerError,
                ErrorResponse(500, "Internal server error")
            )
        }

        // Перехват по HTTP-статусу (например, 404 от роутера)
        status(HttpStatusCode.NotFound) { call, status ->
            call.respond(
                status,
                ErrorResponse(404, "Resource not found", call.request.uri)
            )
        }

        // Несколько статусов сразу
        status(HttpStatusCode.Unauthorized, HttpStatusCode.Forbidden) { call, status ->
            call.respond(
                status,
                ErrorResponse(status.value, status.description)
            )
        }
    }
}

Доменные исключения

// Иерархия исключений приложения
sealed class AppException(message: String) : Exception(message)
class NotFoundException(message: String) : AppException(message)
class ValidationException(val errors: List<String>) : AppException(errors.joinToString("; "))
class AuthException(message: String) : AppException(message)

// Регистрация в StatusPages
install(StatusPages) {
    exception<ValidationException> { call, cause ->
        call.respond(
            HttpStatusCode.UnprocessableEntity,
            mapOf("errors" to cause.errors)
        )
    }
    exception<AuthException> { call, _ ->
        call.respond(HttpStatusCode.Unauthorized, mapOf("error" to "Unauthorized"))
    }
    exception<NotFoundException> { call, cause ->
        call.respond(HttpStatusCode.NotFound, mapOf("error" to cause.message))
    }
}

// Использование в маршруте
get("/users/{id}") {
    val id = call.parameters["id"] ?: throw IllegalArgumentException("id is required")
    val user = userRepository.findById(id)
        ?: throw NotFoundException("User $id not found")
    call.respond(user)
}

Тестирование StatusPages

import io.ktor.client.request.*
import io.ktor.client.statement.*
import io.ktor.server.testing.*
import kotlin.test.*

class StatusPagesTest {
    @Test
    fun `returns 404 for unknown route`() = testApplication {
        application { configureStatusPages() }
        val response = client.get("/nonexistent")
        assertEquals(HttpStatusCode.NotFound, response.status)
        assertTrue(response.bodyAsText().contains("not found"))
    }
}

Подводные камни

• StatusPages должен быть установлен до Routing — иначе исключения, выброшенные внутри маршрутов, не будут перехвачены.
• Обработчик exception<Throwable> перехватывает всё, включая CancellationException корутин — не вызывайте долгие операции внутри обработчика и не проглатывайте CancellationException.
• Если не установлен ContentNegotiation, передача data-класса в call.respond() внутри StatusPages вызовет ещё одно исключение — лучше использовать respondText или убедиться, что сериализация настроена.
• Блок status{} перехватывает только «голые» статусы без тела — например, 404 от роутера. Если маршрут сам вызвал call.respond(HttpStatusCode.NotFound, body), блок status не сработает.
• Порядок блоков exception важен при иерархии: более специфичный тип нужно регистрировать первым, иначе он будет перехвачен базовым Throwable.
• Не логируйте тело запроса в обработчике ошибок — тело уже прочитано или закрыто, повторное чтение вызовет исключение.

• Путать термин «status pages» с соседним механизмом Ktor.
• Не называть границу lifecycle, transaction, thread или request для «status pages».
• Игнорировать production-эффекты «status pages»: latency, SQL shape, memory, security или observability.

• Попросить объяснить механизм «status pages» на минимальном примере.
• Проверить, видит ли кандидат failure mode и диагностику для «status pages».
• Уточнить, какие настройки или API меняют «status pages» в реальном сервисе.