レスポンスの検証

コード例: client-validate-2xx-response, client-validate-non-2xx-response

デフォルトでは、Ktor はステータスコードに応じたレスポンスの検証を行いません。 必要に応じて、以下の検証戦略を使用できます。

• expectSuccess プロパティを使用して、2xx以外のレスポンスに対して例外をスローする。
• 2xxレスポンスに対してより厳格な検証を追加する。
• 2xx以外のレスポンスの検証をカスタマイズする。

デフォルトの検証を有効にする

Ktorでは、expectSuccess プロパティを true に設定することで、デフォルトの検証を有効にできます。 これは、クライアント設定レベルで設定できます...

import io.ktor.client.*
import io.ktor.client.engine.cio.*

val client = HttpClient(CIO) {
    expectSuccess = true
}

... または、リクエストレベルで同じプロパティを使用することもできます。 この場合、2xx以外のエラーレスポンスに対して、以下の例外がスローされます。

• RedirectResponseException 3xxレスポンスの場合。
• ClientRequestException 4xxレスポンスの場合。
• ServerResponseException 5xxレスポンスの場合。

カスタム検証

2xxレスポンスに追加の検証を追加したり、デフォルトの検証をカスタマイズしたりするには、 HttpCallValidator プラグインを使用します。HttpCallValidator をインストールするには、クライアント設定ブロック内で HttpResponseValidator 関数を呼び出します。

val client = HttpClient(CIO) {
    HttpResponseValidator {
        // ...
    }
}

2xxレスポンスの検証

前述の通り、デフォルトの検証は2xx以外のエラーレスポンスに対して例外をスローします。より厳格な検証を追加し、2xxレスポンスをチェックする必要がある場合は、 HttpCallValidator で利用可能な validateResponse 関数を使用します。

以下の例では、クライアントがエラー詳細をJSON形式で含む2xxレスポンスを受け取ります。 validateResponse は CustomResponseException を発生させるために使用されます。

val client = HttpClient(CIO) {
    install(ContentNegotiation) { json() }
    HttpResponseValidator {
        validateResponse { response ->
            val error: Error = response.body()
            if (error.code != 0) {
                throw CustomResponseException(response, "Code: ${error.code}, message: ${error.message}")
            }
        }
    }
}

2xx以外の例外を処理する

デフォルトの検証をカスタマイズし、2xx以外のレスポンスに対する例外を特定の方法で処理する必要がある場合は、 handleResponseExceptionWithRequestを使用します。 以下の例では、クライアントは404レスポンスに対して、デフォルトの ClientRequestException ではなく、カスタムの MissingPageException を発生させます。

val client = HttpClient(CIO) {
    expectSuccess = true
    HttpResponseValidator {
        handleResponseExceptionWithRequest { exception, request ->
            val clientException = exception as? ClientRequestException ?: return@handleResponseExceptionWithRequest
            val exceptionResponse = clientException.response
            if (exceptionResponse.status == HttpStatusCode.NotFound) {
                val exceptionResponseText = exceptionResponse.bodyAsText()
                throw MissingPageException(exceptionResponse, exceptionResponseText)
            }
        }
    }
}