Skip to content

从 1.6.x 迁移到 2.0.x ​

本指南介绍了如何将 Ktor 应用程序从 1.6.x 版本迁移到 2.0.x。

Ktor 服务端 ​

服务端代码移至 '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
身份验证io.ktor:ktor-authio.ktor:ktor-server-auth
JWT 身份验证io.ktor:ktor-auth-jwtio.ktor:ktor-server-auth-jwt
LDAP 身份验证io.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 标头io.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 指标io.ktor:ktor-metrics-micrometerio.ktor:ktor-server-metrics-micrometer
Dropwizard 指标io.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.*
配置import io.ktor.config.*import io.ktor.server.config.*
路由import 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.*
请求import io.ktor.request.*import io.ktor.server.request.*
响应import io.ktor.response.*import io.ktor.server.response.*
插件import io.ktor.features.*import io.ktor.server.plugins.*
Locationsimport io.ktor.locations.*import io.ktor.server.locations.*
静态内容import 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.*
身份验证import io.ktor.auth.*import io.ktor.server.auth.*
JWT 身份验证import io.ktor.auth.jwt.*import io.ktor.server.auth.jwt.*
LDAP 身份验证import 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 标头import 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 指标import io.ktor.metrics.micrometer.*import io.ktor.server.metrics.micrometer.*
Dropwizard 指标import 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,您需要将 MultiPartFormDataContent 传递给客户端的 setBody 函数:

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 中,cookiesSession 用于在测试时的各请求之间保留 Cookie。在 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 中,handleWebSocketConversation 用于测试 WebSocket 会话。在 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 插件配置引入了 cacheRawRequest 属性,它与 receiveEntireContent 相反:

  • 在 v1.6.x 中,receiveEntireContent 属性默认设置为 false。
  • 在 v2.0.0 中,cacheRawRequest 默认设置为 true。receiveEntireContent 属性已被移除。

Forwarded 标头 ​

在 v2.0.0 中,ForwardedHeaderSupport 和 XForwardedHeaderSupport 插件分别更名为 ForwardedHeaders 和 XForwardedHeaders。

缓存标头 ​

用于定义缓存选项的 options 函数除 OutgoingContent 外,现在还接受 ApplicationCall 作为 lambda 实参:

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

条件标头 ​

用于定义资源版本列表的 version 函数除 OutgoingContent 外,现在还接受 ApplicationCall 作为 lambda 实参:

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 中,baseName 属性用于指定监控 HTTP 请求所用的 Ktor 指标的基本名称(前缀)。 默认情况下,它等于 ktor.http.server。 在 v2.0.0 中,baseName 被替换为 metricName,其默认值为 ktor.http.server.requests。

Ktor 客户端 ​

请求与响应 ​

在 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 还允许您在请求函数 lambda 内部指定额外的请求参数。

请求体 ​

用于设置请求体的 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()

流式响应 ​

由于请求函数中移除了泛型实参,接收流式响应需要单独的函数。 为此,添加了带有 prepare 前缀的函数,例如 prepareGet 或 preparePost:

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。 这需要对代码进行以下更改:

  • 要启用默认验证并在出现非 2xx 响应时抛出异常,请将 expectSuccess 属性设置为 true。
  • 如果您使用 handleResponseExceptionWithRequest 处理非 2xx 异常,还需要显式启用 expectSuccess。

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 函数现在使用 RefreshTokenParams 实例作为 lambda 接收者 (this),而不是 HttpResponse lambda 实参 (it):

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

RefreshTokenParams 公开了以下属性:

  • response:访问响应参数;
  • client:用于发起刷新令牌的请求;
  • oldTokens:访问使用 loadTokens 获取的令牌。

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 { ... }
// or
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.*
WebSocketsThe Websockets plugin allows you to create a multi-way communication session between a server and a client.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 内存模型:启用新内存模型 (Enable the new 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 插件使用 DefaultRequestBuilder 配置类代替 HttpRequestBuilder:

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