Ktor类型安全路由序列化失败时自定义异常未触发的问题排查与解决

我在Ktor中实现了路径为/articles/{version}的类型安全路由，其中version为enum class ApiVersion类型，并为此实现了自定义序列化器。相关代码如下：

@Resource("/articles/{version}")
data class Articles(val version: @Contextual ApiVersion)

fun main() {
    embeddedServer(CIO, port = 8080) {
        // plugins
        install(Resources) {
            serializersModule = SerializersModule { contextual(ApiVersion::class, ApiVersionSerializer) }
        }
        install(ContentNegotiation) { json() }
        install(StatusPages) {
            exception<InvalidApiVersion> { call, cause ->
                call.respond(HttpStatusCode.NotFound, cause.message)
            }
        }

        // Routes
        routing {
            get<Articles> { article ->
                call.respondText("articles version ${article.version}")
            }
        }
    }.start(true)
}

ApiVersion枚举、自定义异常及序列化器代码：

internal data class InvalidApiVersion(override val message: String) : Exception(message)

enum class ApiVersion(val version: String) {
    VERSION_1_0("v1.0"),
    VERSION_1_1("v1.1"),
    VERSION_1_2("v1.2"),
    VERSION_1_3("v1.3");
    companion object {
        fun fromString(versionString: String): ApiVersion =
            try { entries.associateBy(ApiVersion::version).getValue(versionString) }
            catch (e: Exception) { throw InvalidApiVersion("Invalid path: $versionString - is not a valid or supported api version.") }
    }
}

object ApiVersionSerializer : KSerializer<ApiVersion> {
    override val descriptor: SerialDescriptor = PrimitiveSerialDescriptor("ApiVersion", PrimitiveKind.STRING)
    override fun deserialize(decoder: Decoder): ApiVersion =
        ApiVersion.fromString(decoder.decodeString())

    override fun serialize(encoder: Encoder, value: ApiVersion) {
        encoder.encodeString(value.version)
    }
}

当访问包含无效版本的路由（如articles/v1.88）时，触发的是Ktor的BadRequestException而非自定义的InvalidApiVersion异常。

问题1：为何会出现这种情况？ #

Ktor在解析路径参数的过程中，会将自定义序列化器抛出的异常统一包装为BadRequestException。因为路径参数解析失败属于请求格式不符合预期，框架默认将这类异常归类为400 Bad Request范畴，因此直接抛出的InvalidApiVersion会被上层封装。

此外，根据REST规范，无效API版本需返回404 NotFound而非400 BadRequest。若直接捕获BadRequestException并返回404，会将所有400请求转为404，不符合需求。

问题2：能否仅针对该场景触发InvalidApiVersion异常？ #

可以通过捕获BadRequestException并追溯其根异常的方式，仅处理API版本无效的情况。@aleksei-tirman的方案可解决基础场景，但部分情况下自定义异常可能嵌套较深，需要多层获取cause才能拿到根异常。以下是优化后的实现：

install(StatusPages) {
    exception<BadRequestException> { call, cause ->
        val root = getRootCause(cause)
        if (root is InvalidApiVersion) {
            call.respond(HttpStatusCode.NotFound, root.message)
        } else {
            throw cause
        }
    }
}
fun getRootCause(exception: Throwable): Throwable {
    var rootCause: Throwable = exception
    while (rootCause.cause != null) {
        rootCause = rootCause.cause!!
    }
    return rootCause
}

内容的提问来源于stack exchange，提问作者Vencat