Skip to content

1.6.x から 2.0.x への移行 ​

このガイドでは、Ktor アプリケーションを 1.6.x バージョンから 2.0.x へ移行する手順について説明します。

Ktor Server ​

サーバーコードの 'io.ktor.server.*' パッケージへの移動 ​

サーバーとクライアントの API を統一し、より明確に区別できるようにするため、サーバーコードは io.ktor.server.* パッケージに移動されました(KTOR-2865)。 これにより、以下に示すように、アプリケーションの依存関係およびインポートを更新する必要があります。

依存関係 ​

サブシステム1.6.x2.0.0
Locationsio.ktor:ktor-locationsio.ktor:ktor-server-locations
Webjarsio.ktor:ktor-webjarsio.ktor:ktor-server-webjars
AutoHeadResponseio.ktor:ktor-server-coreio.ktor:ktor-server-auto-head-response
StatusPagesio.ktor:ktor-server-coreio.ktor:ktor-server-status-pages
CallIdio.ktor:ktor-server-coreio.ktor:ktor-server-call-id
DoubleReceiveio.ktor:ktor-server-coreio.ktor:ktor-server-double-receive
HTML DSLio.ktor:ktor-html-builderio.ktor:ktor-server-html-builder
FreeMarkerio.ktor:ktor-freemarkerio.ktor:ktor-server-freemarker
Velocityio.ktor:ktor-velocityio.ktor:ktor-server-velocity
Mustacheio.ktor:ktor-mustacheio.ktor:ktor-server-mustache
Thymeleafio.ktor:ktor-thymeleafio.ktor:ktor-server-thymeleaf
Pebbleio.ktor:ktor-pebbleio.ktor:ktor-server-pebble
kotlinx.serializationio.ktor:ktor-serializationio.ktor:ktor-server-content-negotiation, io.ktor:ktor-serialization-kotlinx-json
Gsonio.ktor:ktor-gsonio.ktor:ktor-server-content-negotiation, io.ktor:ktor-serialization-gson
Jacksonio.ktor:ktor-jacksonio.ktor:ktor-server-content-negotiation, io.ktor:ktor-serialization-jackson
Authenticationio.ktor:ktor-authio.ktor:ktor-server-auth
JWT authenticationio.ktor:ktor-auth-jwtio.ktor:ktor-server-auth-jwt
LDAP authenticationio.ktor:ktor-auth-ldapio.ktor:ktor-server-auth-ldap
DataConversionio.ktor:ktor-server-coreio.ktor:ktor-server-data-conversion
DefaultHeadersio.ktor:ktor-server-coreio.ktor:ktor-server-default-headers
Compressionio.ktor:ktor-server-coreio.ktor:ktor-server-compression
CachingHeadersio.ktor:ktor-server-coreio.ktor:ktor-server-caching-headers
ConditionalHeadersio.ktor:ktor-server-coreio.ktor:ktor-server-conditional-headers
CORSio.ktor:ktor-server-coreio.ktor:ktor-server-cors
Forwarded headersio.ktor:ktor-server-coreio.ktor:ktor-server-forwarded-header
HSTSio.ktor:ktor-server-coreio.ktor:ktor-server-hsts
HttpsRedirectio.ktor:ktor-server-coreio.ktor:ktor-server-http-redirect
PartialContentio.ktor:ktor-server-coreio.ktor:ktor-server-partial-content
WebSocketsio.ktor:ktor-websocketsio.ktor:ktor-server-websockets
CallLoggingio.ktor:ktor-server-coreio.ktor:ktor-server-call-logging
Micrometer metricio.ktor:ktor-metrics-micrometerio.ktor:ktor-server-metrics-micrometer
Dropwizard metricsio.ktor:ktor-metricsio.ktor:ktor-server-metrics
Sessionsio.ktor:ktor-server-coreio.ktor:ktor-server-sessions

すべてのプラグインを一度に追加するには、io.ktor:ktor-server アーティファクトを使用できます。

インポート ​

サブシステム1.6.x2.0.0
Applicationimport io.ktor.application.*import io.ktor.server.application.*
Configurationimport io.ktor.config.*import io.ktor.server.config.*
Routingimport io.ktor.routing.*import io.ktor.server.routing.*
AutoHeadResponseimport io.ktor.features.*import io.ktor.server.plugins.autohead.*
StatusPagesimport io.ktor.features.*import io.ktor.server.plugins.statuspages.*
CallIdimport io.ktor.features.*import io.ktor.server.plugins.callid.*
DoubleReceiveimport io.ktor.features.*import io.ktor.server.plugins.doublereceive.*
Requestsimport io.ktor.request.*import io.ktor.server.request.*
Responsesimport io.ktor.response.*import io.ktor.server.response.*
Pluginsimport io.ktor.features.*import io.ktor.server.plugins.*
Locationsimport io.ktor.locations.*import io.ktor.server.locations.*
Static contentimport io.ktor.http.content.*import io.ktor.server.http.content.*
HTML DSLimport io.ktor.html.*import io.ktor.server.html.*
FreeMarkerimport io.ktor.freemarker.*import io.ktor.server.freemarker.*
Velocityimport io.ktor.velocity.*import io.ktor.server.velocity.*
Mustacheimport io.ktor.mustache.*import io.ktor.server.mustache.*
Thymeleafimport io.ktor.thymeleaf.*import io.ktor.server.thymeleaf.*
Pebbleimport io.ktor.pebble.*import io.ktor.server.pebble.*
ContentNegotiationimport io.ktor.features.*import io.ktor.server.plugins.contentnegotiation.*
kotlinx.serializationimport io.ktor.serialization.*import io.ktor.serialization.kotlinx.json.*
Gsonimport io.ktor.gson.*import io.ktor.serialization.gson.*
Jacksonimport io.ktor.jackson.*import io.ktor.serialization.jackson.*
Authenticationimport io.ktor.auth.*import io.ktor.server.auth.*
JWT authenticationimport io.ktor.auth.jwt.*import io.ktor.server.auth.jwt.*
LDAP authenticationimport io.ktor.auth.ldap.*import io.ktor.server.auth.ldap.*
Sessionsimport io.ktor.sessions.*import io.ktor.server.sessions.*
DefaultHeadersimport io.ktor.features.*import io.ktor.server.plugins.defaultheaders.*
Compressionimport io.ktor.features.*import io.ktor.server.plugins.compression.*
CachingHeadersimport io.ktor.features.*import io.ktor.server.plugins.cachingheaders.*
ConditionalHeadersimport io.ktor.features.*import io.ktor.server.plugins.conditionalheaders.*
CORSimport io.ktor.features.*import io.ktor.server.plugins.cors.*
Forwarded headersimport io.ktor.features.*import io.ktor.server.plugins.forwardedheaders.*
HSTSimport io.ktor.features.*import io.ktor.server.plugins.hsts.*
HttpsRedirectimport io.ktor.features.*import io.ktor.server.plugins.httpsredirect.*
PartialContentimport io.ktor.features.*import io.ktor.server.plugins.partialcontent.*
WebSocketsimport io.ktor.websocket.*import io.ktor.server.websocket.*
CallLoggingimport io.ktor.features.*import io.ktor.server.plugins.callloging.*
Micrometer metricimport io.ktor.metrics.micrometer.*import io.ktor.server.metrics.micrometer.*
Dropwizard metricsimport io.ktor.metrics.dropwizard.*import io.ktor.server.metrics.dropwizard.*

WebSockets コードの 'websockets' パッケージへの移動 ​

WebSockets のコードは http-cio から websockets パッケージに移動されました。これにより、インポートを以下のように更新する必要があります。

1.6.x2.0.0
import io.ktor.http.cio.websocket.*import io.ktor.websocket.*

この変更はクライアントにも影響することに注意してください。

Feature は Plugin に名称変更 ​

Ktor 2.0.0 では、リクエスト/レスポンスパイプラインをインターセプトする機能をより適切に表現するため、Feature が Plugin に改名されました(KTOR-2326)。 これは Ktor API 全体に影響し、以下のようにアプリケーションを更新する必要があります。

インポート ​

任意のプラグインのインストールにはインポートの更新が必要であり、サーバーコードの移動(io.ktor.server.* パッケージへ)にも依存します。

1.6.x2.0.0
import io.ktor.features.*import io.ktor.server.plugins.*

カスタムプラグイン ​

Feature から Plugin への名称変更に伴い、カスタムプラグインに関連する API に以下の変更が加えられました。

  • ApplicationFeature インターフェースは BaseApplicationPlugin に改名されました。
  • Features パイプラインフェーズは Plugins に改名されました。

v2.0.0 以降、Ktor ではカスタムプラグインを作成するための新しい API が提供されています。通常、この API ではパイプラインやフェーズといった Ktor の内部概念を理解する必要はありません。代わりに、onCall、onCallReceive、onCallRespond などのさまざまなハンドラーを使用して、リクエストおよびレスポンスの処理における異なるステージへアクセスできます。パイプラインフェーズが新しい API のハンドラーにどのようにマッピングされるかについては、パイプラインフェーズと新しい API ハンドラーのマッピングセクションを参照してください。

コンテンツネゴシエーションとシリアライズ ​

コンテンツネゴシエーションとシリアライズのサーバー API は、サーバーとクライアント間でシリアライズライブラリを再利用できるようにリファクタリングされました。 主な変更点は以下のとおりです。

  • ContentNegotiation は ktor-server-core から独立した ktor-server-content-negotiation アーティファクトに移動されました。
  • シリアライズライブラリは ktor-* から、クライアントでも使用される ktor-serialization-* アーティファクトに移動されました。

以下に示すように、アプリケーションの依存関係およびインポートを更新する必要があります。

依存関係 ​

サブシステム1.6.x2.0.0
ContentNegotiationio.ktor:ktor-server-coreio.ktor:ktor-server-content-negotiation
kotlinx.serializationio.ktor:ktor-serializationio.ktor:ktor-serialization-kotlinx-json
Gsonio.ktor:ktor-gsonio.ktor:ktor-serialization-gson
Jacksonio.ktor:ktor-jacksonio.ktor:ktor-serialization-jackson

インポート ​

サブシステム1.6.x2.0.0
kotlinx.serializationimport io.ktor.serialization.*import io.ktor.serialization.kotlinx.json.*
Gsonimport io.ktor.gson.*import io.ktor.serialization.gson.*
Jacksonimport io.ktor.jackson.*import io.ktor.serialization.jackson.*

カスタムコンバーター ​

ContentConverter インターフェースが公開する関数のシグネチャが次のように変更されました。

kotlin
interface ContentConverter {
    suspend fun convertForSend(context: PipelineContext<Any, ApplicationCall>, contentType: ContentType, value: Any): Any?
    suspend fun convertForReceive(context: PipelineContext<ApplicationReceiveRequest, ApplicationCall>): Any?
}
kotlin
interface ContentConverter {
    suspend fun serialize(contentType: ContentType, charset: Charset, typeInfo: TypeInfo, value: Any): OutgoingContent?
    suspend fun deserialize(charset: Charset, typeInfo: TypeInfo, content: ByteReadChannel): Any?
}

テスティング API ​

v2.0.0 では、Ktor サーバーはテスト用の新しい API を使用するようになり、KTOR-971 で説明されているさまざまな問題が解決されました。主な変更点は以下のとおりです。

  • withTestApplication/withApplication 関数は、新しい testApplication 関数に置き換えられました。
  • testApplication 関数の内部では、既存の Ktor クライアントインスタンスを使用してサーバーにリクエストを送信し、結果を検証する必要があります。
  • 特定の機能(Cookie や WebSockets など)をテストするには、新しいクライアントインスタンスを作成し、対応するプラグインをインストールする必要があります。

1.6.x のテストを 2.0.0 に移行する例をいくつか見てみましょう。

基本的なサーバーテスト ​

以下のテストでは、handleRequest 関数が client.get リクエストに置き換えられています。

kotlin
@Test
fun testRootLegacyApi() {
    withTestApplication(Application::module) {
        handleRequest(HttpMethod.Get, "/").apply {
            assertEquals(HttpStatusCode.OK, response.status())
            assertEquals("Hello, world!", response.content)
        }
    }
}
kotlin
@Test
fun testRoot() = testApplication {
    val response = client.get("/")
    assertEquals(HttpStatusCode.OK, response.status)
    assertEquals("Hello, world!", response.bodyAsText())
}

x-www-form-urlencoded ​

以下のテストでは、handleRequest 関数が client.post リクエストに置き換えられています。

kotlin
@Test
fun testPostLegacyApi() = withTestApplication(Application::main) {
    with(handleRequest(HttpMethod.Post, "/signup"){
        addHeader(HttpHeaders.ContentType, ContentType.Application.FormUrlEncoded.toString())
        setBody(listOf("username" to "JetBrains", "email" to "example@jetbrains.com", "password" to "foobar", "confirmation" to "foobar").formUrlEncode())
    }) {
        assertEquals("The 'JetBrains' account is created", response.content)
    }
}
kotlin
@Test
fun testPost() = testApplication {
    val response = client.post("/signup") {
        header(HttpHeaders.ContentType, ContentType.Application.FormUrlEncoded.toString())
        setBody(listOf("username" to "JetBrains", "email" to "example@jetbrains.com", "password" to "foobar", "confirmation" to "foobar").formUrlEncode())
    }
    assertEquals("The 'JetBrains' account is created", response.bodyAsText())
}

multipart/form-data ​

v2.0.0 で multipart/form-data を構築するには、クライアントの setBody 関数に MultiPartFormDataContent を渡す必要があります。

kotlin
    @Test
    fun testUploadLegacyApi() = withTestApplication(Application::main) {
        with(handleRequest(HttpMethod.Post, "/upload"){
            val boundary = "WebAppBoundary"
            val fileBytes = File("ktor_logo.png").readBytes()

            addHeader(HttpHeaders.ContentType, ContentType.MultiPart.FormData.withParameter("boundary", boundary).toString())
            setBody(boundary, listOf(
                PartData.FormItem("Ktor logo", { }, headersOf(
                    HttpHeaders.ContentDisposition,
                    ContentDisposition.Inline
                        .withParameter(ContentDisposition.Parameters.Name, "description")
                        .toString()
                )),
                PartData.FileItem({ fileBytes.inputStream().asInput() }, {}, headersOf(
                    HttpHeaders.ContentDisposition,
                    ContentDisposition.File
                        .withParameter(ContentDisposition.Parameters.Name, "image")
                        .withParameter(ContentDisposition.Parameters.FileName, "ktor_logo.png")
                        .toString()
                ))
            ))
        }) {
            assertEquals("Ktor logo is uploaded to 'uploads/ktor_logo.png'", response.content)
        }
    }
kotlin
@Test
fun testUpload() = testApplication {
    val boundary = "WebAppBoundary"
    val response = client.post("/upload") {
        setBody(
            MultiPartFormDataContent(
                formData {
                    append("description", "Ktor logo")
                    append("image", File("ktor_logo.png").readBytes(), Headers.build {
                        append(HttpHeaders.ContentType, "image/png")
                        append(HttpHeaders.ContentDisposition, "filename=\"ktor_logo.png\"")
                    })
                },
                boundary,
                ContentType.MultiPart.FormData.withParameter("boundary", boundary)
            )
        )
    }
    assertEquals("Ktor logo is uploaded to 'uploads/ktor_logo.png'", response.bodyAsText())
}

JSON データ ​

v1.6.x では、kotlinx.serialization ライブラリが提供する Json.encodeToString 関数を使用して JSON データをシリアライズできます。 v2.0.0 では、新しいクライアントインスタンスを作成し、特定の形式でコンテンツをシリアライズ/デシリアライズできるようにする ContentNegotiation プラグインをインストールする必要があります。

kotlin
@Test
fun testPostCustomerLegacyApi() = withTestApplication(Application::main) {
    with(handleRequest(HttpMethod.Post, "/customer"){
        addHeader(HttpHeaders.ContentType, ContentType.Application.Json.toString())
        setBody(Json.encodeToString(Customer(3, "Jet", "Brains")))
    }) {
        assertEquals("Customer stored correctly", response.content)
        assertEquals(HttpStatusCode.Created, response.status())
    }
}
kotlin
@Test
fun testPostCustomer() = testApplication {
    val client = createClient {
        install(ContentNegotiation) {
            json()
        }
    }
    val response = client.post("/customer") {
        contentType(ContentType.Application.Json)
        setBody(Customer(3, "Jet", "Brains"))
    }
    assertEquals("Customer stored correctly", response.bodyAsText())
    assertEquals(HttpStatusCode.Created, response.status)
}

テスト中に Cookie を保持 ​

v1.6.x では、テスト時にリクエスト間で Cookie を保持するために cookiesSession を使用します。v2.0.0 では、新しいクライアントインスタンスを作成し、HttpCookies プラグインをインストールする必要があります。

kotlin
    @Test
    fun testRequestsLegacyApi() = withTestApplication(Application::main) {
        fun doRequestAndCheckResponse(path: String, expected: String) {
            handleRequest(HttpMethod.Get, path).apply {
                assertEquals(expected, response.content)
            }
        }

        cookiesSession {
            handleRequest(HttpMethod.Get, "/login") {}.apply {}
            doRequestAndCheckResponse("/user", "Session ID is 123abc. Reload count is 0.")
            doRequestAndCheckResponse("/user", "Session ID is 123abc. Reload count is 1.")
            doRequestAndCheckResponse("/user", "Session ID is 123abc. Reload count is 2.")

            handleRequest(HttpMethod.Get, "/logout").apply {}
            doRequestAndCheckResponse("/user", "Session doesn't exist or is expired.")
        }
    }
kotlin
    @Test
    fun testRequests() = testApplication {
        val client = createClient {
            install(HttpCookies)
        }

        val loginResponse = client.get("/login")
        val response1 = client.get("/user")
        assertEquals("Session ID is 123abc. Reload count is 1.", response1.bodyAsText())
        val response2 = client.get("/user")
        assertEquals("Session ID is 123abc. Reload count is 2.", response2.bodyAsText())
        val response3 = client.get("/user")
        assertEquals("Session ID is 123abc. Reload count is 3.", response3.bodyAsText())
        val logoutResponse = client.get("/logout")
        assertEquals("Session doesn't exist or is expired.", logoutResponse.bodyAsText())
    }

WebSockets ​

旧 API では、WebSocket のやり取りをテストするために handleWebSocketConversation が使用されていました。v2.0.0 では、クライアントが提供する WebSockets プラグインを使用することで WebSocket のやり取りをテストできます。

kotlin
    @Test
    fun testConversationLegacyApi() {
        withTestApplication(Application::module) {
            handleWebSocketConversation("/echo") { incoming, outgoing ->
                val greetingText = (incoming.receive() as Frame.Text).readText()
                assertEquals("Please enter your name", greetingText)

                outgoing.send(Frame.Text("JetBrains"))
                val responseText = (incoming.receive() as Frame.Text).readText()
                assertEquals("Hi, JetBrains!", responseText)
            }
        }
    }
kotlin
    @Test
    fun testConversation() {
        testApplication {
            val client = createClient {
                install(WebSockets)
            }

            client.webSocket("/echo") {
                val greetingText = (incoming.receive() as? Frame.Text)?.readText() ?: ""
                assertEquals("Please enter your name", greetingText)

                send(Frame.Text("JetBrains"))
                val responseText = (incoming.receive() as Frame.Text).readText()
                assertEquals("Hi, JetBrains!", responseText)
            }
        }
    }

DoubleReceive ​

v2.0.0 では、DoubleReceive プラグイン設定に receiveEntireContent とは逆の働きをする cacheRawRequest プロパティが導入されました。

  • v1.6.x では、receiveEntireContent プロパティのデフォルト値は false に設定されています。
  • v2.0.0 では、cacheRawRequest のデフォルト値は true に設定されています。receiveEntireContent プロパティは削除されました。

Forwarded headers ​

v2.0.0 では、ForwardedHeaderSupport および XForwardedHeaderSupport プラグインがそれぞれ ForwardedHeaders および XForwardedHeaders に改名されました。

Caching headers ​

キャッシュオプションを定義するために使用される options 関数は、OutgoingContent に加えて ApplicationCall もラムダ引数として受け取るようになりました。

kotlin
install(CachingHeaders) {
    options { outgoingContent ->
        // ...
    }
}
kotlin
install(CachingHeaders) {
    options { call, outgoingContent ->
        // ...
    }
}

Conditional headers ​

リソースバージョンのリストを定義するために使用される version 関数は、OutgoingContent に加えて ApplicationCall もラムダ引数として受け取るようになりました。

kotlin
install(ConditionalHeaders) {
    version { outgoingContent ->
        // ... 
    }
}
kotlin
install(ConditionalHeaders) {
    version { call, outgoingContent ->
        // ... 
    }
}

CORS ​

CORS 設定で使用されるいくつかの関数が改名されました。

  • host -> allowHost
  • header -> allowHeader
  • method -> allowMethod
kotlin
install(CORS) {
    host("0.0.0.0:5000")
    header(HttpHeaders.ContentType)
    method(HttpMethod.Options)
}
kotlin
install(CORS) {
    allowHost("0.0.0.0:5000")
    allowHeader(HttpHeaders.ContentType)
    allowMethod(HttpMethod.Options)
}

MicrometerMetrics ​

v1.6.x では、HTTP リクエストの監視に使用される Ktor メトリクスのベース名(プレフィックス)を指定するために baseName プロパティが使用されていました。 デフォルトでは ktor.http.server と等しくなっています。 v2.0.0 では、baseName は metricName に置き換えられ、そのデフォルト値は ktor.http.server.requests になりました。

Ktor Client ​

リクエストとレスポンス ​

v2.0.0 では、リクエストの送信とレスポンスの受信に使用される API が更新され、一貫性と発見しやすさが向上しました(KTOR-29)。

リクエスト関数 ​

複数のパラメータを持つリクエスト関数は非推奨になりました。たとえば、port および path パラメータは、HttpRequestBuilder が公開する url パラメータに置き換える必要があります。

kotlin
client.get(port = 8080, path = "/customer/3")
kotlin
client.get { url(port = 8080, path = "/customer/3") }

また、HttpRequestBuilder を使用すると、リクエスト関数のラムダ内で追加のリクエストパラメータを指定することもできます。

リクエストボディ ​

リクエストボディを設定するために使用されていた HttpRequestBuilder.body プロパティは、HttpRequestBuilder.setBody 関数に置き換えられました。

kotlin
client.post("http://localhost:8080/post") {
    body = "Body content"
}
kotlin
client.post("http://localhost:8080/post") {
    setBody("Body content")
}

レスポンス ​

v2.0.0 では、リクエスト関数(get、post、put、submitForm など)は特定タイプのオブジェクトを受信するためのジェネリクス引数を受け取らなくなりました。 現在、すべてのリクエスト関数は HttpResponse オブジェクトを返します。このオブジェクトは、特定タイプのインスタンスを受信するためのジェネリクス引数を持つ body 関数を公開しています。 また、bodyAsText や bodyAsChannel を使用して、コンテンツを文字列やチャネルとして受信することもできます。

kotlin
val httpResponse: HttpResponse = client.get("https://ktor.io/")
val stringBody: String = httpResponse.receive()
val byteArrayBody: ByteArray = httpResponse.receive()
kotlin
val httpResponse: HttpResponse = client.get("https://ktor.io/")
val stringBody: String = httpResponse.body()
val byteArrayBody: ByteArray = httpResponse.body()

ContentNegotiation プラグインをインストールすると、以下のように任意のオブジェクトを受信できます。

kotlin
val customer: Customer = client.get("http://localhost:8080/customer/3")
kotlin
val customer: Customer = client.get("http://localhost:8080/customer/3").body()

ストリーミングレスポンス ​

リクエスト関数からのジェネリクス引数の削除に伴い、ストリーミングレスポンスの受信には別の関数が必要になりました。 これを実現するために、prepareGet や preparePost など、prepare プレフィックスが付いた関数が追加されました。

kotlin
public suspend fun HttpClient.prepareGet(builder: HttpRequestBuilder): HttpStatement
public suspend fun HttpClient.preparePost(builder: HttpRequestBuilder): HttpStatement

この場合のコード変更例を以下に示します。

kotlin
client.get<HttpStatement>("https://ktor.io/").execute { httpResponse ->
    val channel: ByteReadChannel = httpResponse.receive()
    while (!channel.isClosedForRead) {
        // Read data
    }
}
kotlin
client.prepareGet("https://ktor.io/").execute { httpResponse ->
    val channel: ByteReadChannel = httpResponse.body()
    while (!channel.isClosedForRead) {
        // Read data
    }
}

完全な例はこちらを参照してください: データのストリーミング。

レスポンス検証 ​

v2.0.0 では、レスポンス検証に使用される expectSuccess プロパティのデフォルト値が false に設定されています。 これにより、コードに以下の変更が必要になります。

HttpResponseValidator ​

handleResponseException 関数は handleResponseExceptionWithRequest に置き換えられました。これにより、HttpRequest にアクセスして例外で追加情報を提供できるようになりました。

kotlin
HttpResponseValidator {
    handleResponseException { exception ->
        // ...
    }
}
kotlin
HttpResponseValidator {
    handleResponseExceptionWithRequest { exception, request ->
        // ...
    }
}

コンテンツネゴシエーションとシリアライズ ​

Ktor クライアントはコンテンツネゴシエーションをサポートするようになり、Ktor サーバーとシリアライズライブラリを共有します。 主な変更点は以下のとおりです。

  • JsonFeature は非推奨となり、代わりに ktor-client-content-negotiation アーティファクトに含まれる ContentNegotiation が使用されます。
  • シリアライズライブラリは ktor-client-* から ktor-serialization-* アーティファクトに移動されました。

以下に示すように、クライアントコードの依存関係およびインポートを更新する必要があります。

依存関係 ​

サブシステム1.6.x2.0.0
ContentNegotiationn/aio.ktor:ktor-client-content-negotiation
kotlinx.serializationio.ktor:ktor-client-serializationio.ktor:ktor-serialization-kotlinx-json
Gsonio.ktor:ktor-client-gsonio.ktor:ktor-serialization-gson
Jacksonio.ktor:ktor-client-jacksonio.ktor:ktor-serialization-jackson

インポート ​

サブシステム1.6.x2.0.0
ContentNegotiationn/aimport io.ktor.client.plugins.contentnegotiation.*
kotlinx.serializationimport io.ktor.client.features.json.*import io.ktor.serialization.kotlinx.json.*
Gsonimport io.ktor.client.features.json.*import io.ktor.serialization.gson.*
Jacksonimport io.ktor.client.features.json.*import io.ktor.serialization.jackson.*

Bearer 認証 ​

refreshTokens 関数は、HttpResponse ラムダ引数(it)の代わりに、RefreshTokenParams インスタンスをラムダレシーバー(this)として使用するようになりました。

kotlin
bearer {
    refreshTokens {  // it: HttpResponse
        // ...
    }
}
kotlin
bearer {
    refreshTokens { // this: RefreshTokenParams
        // ...
    }
}

RefreshTokenParams は以下のプロパティを公開しています。

  • レスポンスパラメータにアクセスするための response
  • トークンをリフレッシュするリクエストを送信するための client
  • loadTokens を使用して取得したトークンにアクセスするための oldTokens

HttpSend ​

HttpSend プラグインの API は次のように変更されました。

kotlin
client[HttpSend].intercept { originalCall, request ->
    if (originalCall.something()) {
        val newCall = execute(request)
        // ...
    }
}
kotlin
client.plugin(HttpSend).intercept { request ->
    val originalCall = execute(request)
    if (originalCall.something()) {
        val newCall = execute(request)
        // ...
    }
}

v2.0.0 では、プラグインへのアクセスにインデックスアクセスが使用できなくなったことに注意してください。代わりに HttpClient.plugin 関数を使用してください。

HttpClient.get(plugin: HttpClientPlugin) 関数の削除 ​

2.0.0 バージョンでは、クライアントプラグインを受け取る HttpClient.get 関数が削除されました。代わりに HttpClient.plugin 関数を使用してください。

kotlin
client.get(HttpSend).intercept { ... }
// または
client[HttpSend].intercept { ... }
kotlin
client.plugin(HttpSend).intercept { ... }

Feature は Plugin に名称変更 ​

Ktor サーバーと同様に、クライアント API でも Feature は Plugin に名称変更されました。 これにより、以下で説明するようにアプリケーションに影響が生じる可能性があります。

インポート ​

プラグインのインストールに関するインポートを更新してください。

サブシステム1.6.x2.0.0
  • デフォルトリクエストDefaultRequest プラグインを使用すると、すべてのリクエストに対するデフォルトのパラメータを設定できます。
  • User agentUserAgent プラグインは、すべてのリクエストに User-Agent ヘッダーを追加します。
  • 文字セットこのプラグインを使用すると、リクエストおよびレスポンス内のプレーンテキストコンテンツを処理できます。登録された文字セットで Accept ヘッダーを設定し、ContentType の文字セットに従ってリクエストボディをエンコードし、レスポンスボディをデコードします。
  • レスポンス検証ステータスコードに応じたレスポンスのバリデーション方法について学びます。
  • タイムアウトコード例: client-timeout
  • HttpCacheHttpCacheプラグインを使用すると、以前に取得したリソースをインメモリまたは永続キャッシュに保存できます。
  • HttpSendコード例: client-http-send
import io.ktor.client.features.*import io.ktor.client.plugins.*
認証Auth プラグインは、クライアントアプリケーションにおける認証と認可を処理します。 import io.ktor.client.features.auth.* import io.ktor.client.features.auth.providers.* import io.ktor.client.plugins.auth.* import io.ktor.client.plugins.auth.providers.*
CookieHttpCookies プラグインは Cookie を自動的に処理し、ストレージ内に呼び出し間で保持します。import io.ktor.client.features.cookies.*import io.ktor.client.plugins.cookies.*
ロギング必要な依存関係: io.ktor:ktor-client-loggingimport io.ktor.client.features.logging.*import io.ktor.client.plugins.logging.*
WebSocketsWebsockets プラグインを使用すると、サーバーとクライアント間で双方向の通信セッションを作成できます。import io.ktor.client.features.websocket.*import io.ktor.client.plugins.websocket.*
コンテンツエンコーディングContentEncoding プラグインを使用すると、指定した圧縮アルゴリズム('gzip' や 'deflate' など)を有効にし、その設定を行うことができます。import io.ktor.client.features.compression.*import io.ktor.client.plugins.compression.*

カスタムプラグイン ​

HttpClientFeature インターフェースは HttpClientPlugin に改名されました。

Native ターゲット向けの新しいメモリモデル ​

v2.0.0 では、Native ターゲットで Ktor クライアントを使用する際に、新しい Kotlin/Native メモリモデルを有効にする必要があります: 新しい MM の有効化。

v2.2.0 以降では、新しい Kotlin/Native メモリモデルがデフォルトで有効になっています。

'Ios' エンジンは 'Darwin' に名称変更 ​

Ios エンジンは iOS だけでなく macOS や tvOS などの他のオペレーティングシステムもターゲットにしているため、v2.0.0 で Darwin に改名されました。これにより、以下の変更が発生します。

  • io.ktor:ktor-client-ios アーティファクトは io.ktor:ktor-client-darwin に改名されました。
  • HttpClient インスタンスを作成するには、引数として Darwin クラスを渡す必要があります。
  • IosClientEngineConfig 設定クラスは DarwinClientEngineConfig に改名されました。

Darwin エンジンの設定方法については、Darwin セクションを参照してください。

WebSockets コードの 'websockets' パッケージへの移動 ​

WebSockets のコードは http-cio から websockets パッケージに移動されました。これにより、インポートを以下のように更新する必要があります。

1.6.x2.0.0
import io.ktor.http.cio.websocket.*import io.ktor.websocket.*

デフォルトリクエスト ​

DefaultRequest プラグインは、HttpRequestBuilder の代わりに DefaultRequestBuilder 設定クラスを使用するようになりました。

kotlin
val client = HttpClient(CIO) {
    defaultRequest {
        // this: HttpRequestBuilder
    }
}
kotlin
val client = HttpClient(CIO) {
    defaultRequest {
        // this: DefaultRequestBuilder
    }
}