Skip to content
Client Plugin

Ktor Client 中的內容協商與序列化

必要相依性:io.ktor:ktor-client-content-negotiation

程式碼範例: client-json-kotlinx

ContentNegotiation 外掛程式主要有兩個用途:

  • 使用 Accept 和 Content-Type 標頭在用戶端與伺服器之間協商媒體類型。
  • 以支援的格式序列化請求主體以及還原序列化回應主體。Ktor 內建支援 JSON、XML、CBOR 和 ProtoBuf。

在伺服器端,Ktor 提供了 ContentNegotiation 外掛程式來序列化和還原序列化內容。

新增相依性 ​

內容協商 ​

若要使用 ContentNegotiation,請將 ktor-client-content-negotiation 構件新增至您的建置指令碼中:

kotlin
implementation(ktorLibs.client.contentNegotiation)
上述程式碼片段使用 Ktor 版本目錄來指定 Ktor 相依性。
groovy
implementation ktorLibs.client.contentNegotiation
上述程式碼片段使用 Ktor 版本目錄來指定 Ktor 相依性。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-client-content-negotiation-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

特定格式的序列化程式需要額外的構件。

例如,kotlinx.serialization 針對 JSON 需要 ktor-serialization-kotlinx-json 相依性。根據所包含的構件,Ktor 會自動選擇預設的序列化程式。如有需要,您可以明確指定序列化程式並進行配置。

若要了解更多有關 Ktor 用戶端所需構件的資訊,請參閱新增用戶端相依性了解如何將用戶端相依性新增至現有專案中。。

序列化 ​

在使用 kotlinx.serialization 轉換器之前,請依照安裝設定 (Setup) 一節中的說明新增 Kotlin 序列化外掛程式。

JSON ​

若要序列化和還原序列化 JSON 資料,請將序列化程式庫新增至您的專案中。Ktor 支援 kotlinx.serialization、Gson 或 Jackson。

將 ktor-serialization-kotlinx-json 構件新增至您的建置指令碼中:

kotlin
implementation(ktorLibs.serialization.kotlinx.json)
上述程式碼片段使用 Ktor 版本目錄來指定 Ktor 相依性。
groovy
implementation ktorLibs.serialization.kotlinx.json
上述程式碼片段使用 Ktor 版本目錄來指定 Ktor 相依性。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-serialization-kotlinx-json-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

將 ktor-serialization-gson 構件新增至您的建置指令碼中:

kotlin
implementation(ktorLibs.serialization.gson)
上述程式碼片段使用 Ktor 版本目錄來指定 Ktor 相依性。
groovy
implementation ktorLibs.serialization.gson
上述程式碼片段使用 Ktor 版本目錄來指定 Ktor 相依性。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-serialization-gson-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

將 ktor-serialization-jackson 構件新增至您的建置指令碼中:

kotlin
implementation(ktorLibs.serialization.jackson)
上述程式碼片段使用 Ktor 版本目錄來指定 Ktor 相依性。
groovy
implementation ktorLibs.serialization.jackson
上述程式碼片段使用 Ktor 版本目錄來指定 Ktor 相依性。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-serialization-jackson-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

XML ​

若要序列化和還原序列化 XML,請將 ktor-serialization-kotlinx-xml 構件新增至您的建置指令碼中:

kotlin
implementation(ktorLibs.serialization.kotlinx.xml)
上述程式碼片段使用 Ktor 版本目錄來指定 Ktor 相依性。
groovy
implementation ktorLibs.serialization.kotlinx.xml
上述程式碼片段使用 Ktor 版本目錄來指定 Ktor 相依性。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-serialization-kotlinx-xml-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

CBOR ​

若要序列化和還原序列化 CBOR,請將 ktor-serialization-kotlinx-cbor 構件新增至您的建置指令碼中:

kotlin
implementation(ktorLibs.serialization.kotlinx.cbor)
上述程式碼片段使用 Ktor 版本目錄來指定 Ktor 相依性。
groovy
implementation ktorLibs.serialization.kotlinx.cbor
上述程式碼片段使用 Ktor 版本目錄來指定 Ktor 相依性。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-serialization-kotlinx-cbor-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

ProtoBuf ​

若要序列化和還原序列化 ProtoBuf,請將 ktor-serialization-kotlinx-protobuf 構件新增至您的建置指令碼中:

kotlin
implementation(ktorLibs.serialization.kotlinx.protobuf)
上述程式碼片段使用 Ktor 版本目錄來指定 Ktor 相依性。
groovy
implementation ktorLibs.serialization.kotlinx.protobuf
上述程式碼片段使用 Ktor 版本目錄來指定 Ktor 相依性。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-serialization-kotlinx-protobuf-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

安裝 ContentNegotiation ​

若要安裝 ContentNegotiation 外掛程式,請在用戶端配置區塊中將其傳遞給 install 函式:

kotlin
val client = HttpClient(CIO) {
    install(ContentNegotiation)
}

接著您便可以配置所需的 JSON 序列化程式。

配置序列化程式 ​

JSON 序列化程式 ​

要在應用程式中註冊 JSON 序列化程式,請呼叫 json() 函式:

kotlin
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.json.*

val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        json()
    }
}

若要自訂 JSON 序列化,請在 json() 建構函式中傳入 Json 配置:

kotlin
val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        json(Json {
            prettyPrint = true
            isLenient = true
        })
    }
}

有關可用的配置選項,請參閱 JsonBuilder。

完整範例請參閱 client-json-kotlinx。

要在應用程式中註冊 Gson 序列化程式,請呼叫 gson() 函式:

kotlin
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.gson.*

val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        gson()
    }
}

若要自訂 Gson 序列化,請傳遞配置區塊給 gson() 函式。有關可用的配置選項,請參閱 GsonBuilder。

要在應用程式中註冊 Jackson 序列化程式,請呼叫 jackson() 函式:

kotlin
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.jackson.*

val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        jackson()
    }
}

若要自訂 Jackson 序列化,請使用 ObjectMapper 提供的設定:

kotlin
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.jackson.*
import com.fasterxml.jackson.databind.*
import java.text.DateFormat

val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        jackson {
            enable(SerializationFeature.INDENT_OUTPUT)
            dateFormat = DateFormat.getDateInstance()
        }
    }
}

XML 序列化程式 ​

要在應用程式中註冊 XML 序列化程式,請呼叫 xml() 函式:

kotlin
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.xml.*

val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        xml()
    }
}

若要自訂 XML 序列化,請將所需選項傳遞給 xml() 函式:

kotlin
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.xml.*
import nl.adaptivity.xmlutil.*
import nl.adaptivity.xmlutil.serialization.*

val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        xml(format = XML {
            xmlDeclMode = XmlDeclMode.Charset
        })
    }
}

CBOR 序列化程式 ​

要在應用程式中註冊 CBOR 序列化程式,請呼叫 cbor() 函式:

kotlin
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.cbor.*

val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        cbor()
    }
}

若要自訂 CBOR 序列化,請在 cbor() 建構函式中傳入 Cbor 配置:

kotlin
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.cbor.*
import kotlinx.serialization.cbor.*

val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        cbor(Cbor {
            ignoreUnknownKeys = true
        })
    }
}

有關可用的配置選項,請參閱 CborBuilder。

ProtoBuf 序列化程式 ​

要在應用程式中註冊 ProtoBuf 序列化程式,請呼叫 protobuf() 函式:

kotlin
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.protobuf.*

val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        protobuf()
    }
}

若要自訂 ProtoBuf 序列化,請將 ProtoBuf 配置傳遞給 protobuf() 函式:

kotlin
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.protobuf.*
import kotlinx.serialization.protobuf.*

val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        protobuf(ProtoBuf {
            encodeDefaults = true
        })
    }
}

有關可用選項,請參閱 ProtoBufBuilder。

配置 Accept 標頭 ​

預設情況下,ContentNegotiation 外掛程式會將已註冊的內容類型新增到外發請求的 Accept 標頭中。

如果您明確設定了 Accept 標頭,且不希望該外掛程式新增已註冊的內容類型,請將 acceptHeaderMergeStrategy 屬性設定為 ContentTypeMergeStrategy.SkipIfPresent:

kotlin
val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        register(ContentType.Application.Json, noOpJsonConverter)
        acceptHeaderMergeStrategy = ContentTypeMergeStrategy.SkipIfPresent
    }
}

使用 SkipIfPresent 時,外掛程式會保留現有的 Accept 標頭。如果請求中不包含 Accept 標頭,外掛程式則會照常新增已註冊的內容類型。

發送與接收資料 ​

建立資料類別 ​

以下範例使用 Customer 資料類別來表示用戶端發送與接收的資料:

kotlin
data class Customer(val id: Int, val firstName: String, val lastName: String)

如果您使用 kotlinx.serialization,請使用 @Serializable 為該類別加上註解:

kotlin
@Serializable
data class Customer(val id: Int, val firstName: String, val lastName: String)

kotlinx.serialization 程式庫支援以下型別的序列化/還原序列化:

發送資料 ​

若要在請求主體中發送類別執行個體,請使用 setBody() 函式指派此執行個體,並使用 contentType() 函式設定內容類型。

以下範例以 JSON 格式發送 Customer 物件:

kotlin
val response: HttpResponse = client.post("http://localhost:8080/customer") {
    contentType(ContentType.Application.Json)
    setBody(Customer(3, "Jet", "Brains"))
}

ContentNegotiation 外掛程式會使用配置好的序列化程式將請求主體轉換為指定的格式。

若要以其他已註冊的格式發送資料,請指定相應的內容類型,例如 ContentType.Application.Xml 或 ContentType.Application.Cbor。

接收資料 ​

當伺服器回傳帶有支援內容類型的回應時,ContentNegotiation 外掛程式可以將回應主體還原序列化為預期的型別。

例如,若要將 JSON 回應還原序列化為 Customer 物件,請呼叫 body() 函式:

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

完整範例請參閱 client-json-kotlinx。