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 構件新增至您的建置指令碼中:
implementation(ktorLibs.client.contentNegotiation)implementation ktorLibs.client.contentNegotiation<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 會自動選擇預設的序列化程式。如有需要,您可以明確指定序列化程式並進行配置。
序列化
在使用 kotlinx.serialization 轉換器之前,請依照安裝設定 (Setup) 一節中的說明新增 Kotlin 序列化外掛程式。
JSON
若要序列化和還原序列化 JSON 資料,請將序列化程式庫新增至您的專案中。Ktor 支援 kotlinx.serialization、Gson 或 Jackson。
將 ktor-serialization-kotlinx-json 構件新增至您的建置指令碼中:
implementation(ktorLibs.serialization.kotlinx.json)implementation ktorLibs.serialization.kotlinx.json<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-serialization-kotlinx-json-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>將 ktor-serialization-gson 構件新增至您的建置指令碼中:
implementation(ktorLibs.serialization.gson)implementation ktorLibs.serialization.gson<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-serialization-gson-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>將 ktor-serialization-jackson 構件新增至您的建置指令碼中:
implementation(ktorLibs.serialization.jackson)implementation ktorLibs.serialization.jackson<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-serialization-jackson-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>XML
若要序列化和還原序列化 XML,請將 ktor-serialization-kotlinx-xml 構件新增至您的建置指令碼中:
implementation(ktorLibs.serialization.kotlinx.xml)implementation ktorLibs.serialization.kotlinx.xml<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-serialization-kotlinx-xml-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>CBOR
若要序列化和還原序列化 CBOR,請將 ktor-serialization-kotlinx-cbor 構件新增至您的建置指令碼中:
implementation(ktorLibs.serialization.kotlinx.cbor)implementation ktorLibs.serialization.kotlinx.cbor<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-serialization-kotlinx-cbor-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>ProtoBuf
若要序列化和還原序列化 ProtoBuf,請將 ktor-serialization-kotlinx-protobuf 構件新增至您的建置指令碼中:
implementation(ktorLibs.serialization.kotlinx.protobuf)implementation ktorLibs.serialization.kotlinx.protobuf<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-serialization-kotlinx-protobuf-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>安裝 ContentNegotiation
若要安裝 ContentNegotiation 外掛程式,請在用戶端配置區塊中將其傳遞給 install 函式:
val client = HttpClient(CIO) {
install(ContentNegotiation)
}接著您便可以配置所需的 JSON 序列化程式。
配置序列化程式
JSON 序列化程式
要在應用程式中註冊 JSON 序列化程式,請呼叫 json() 函式:
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.json.*
val client = HttpClient(CIO) {
install(ContentNegotiation) {
json()
}
}若要自訂 JSON 序列化,請在 json() 建構函式中傳入 Json 配置:
val client = HttpClient(CIO) {
install(ContentNegotiation) {
json(Json {
prettyPrint = true
isLenient = true
})
}
}有關可用的配置選項,請參閱 JsonBuilder。
完整範例請參閱 client-json-kotlinx。
要在應用程式中註冊 Gson 序列化程式,請呼叫 gson() 函式:
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.gson.*
val client = HttpClient(CIO) {
install(ContentNegotiation) {
gson()
}
}若要自訂 Gson 序列化,請傳遞配置區塊給 gson() 函式。有關可用的配置選項,請參閱 GsonBuilder。
要在應用程式中註冊 Jackson 序列化程式,請呼叫 jackson() 函式:
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.jackson.*
val client = HttpClient(CIO) {
install(ContentNegotiation) {
jackson()
}
}若要自訂 Jackson 序列化,請使用 ObjectMapper 提供的設定:
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() 函式:
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.xml.*
val client = HttpClient(CIO) {
install(ContentNegotiation) {
xml()
}
}若要自訂 XML 序列化,請將所需選項傳遞給 xml() 函式:
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() 函式:
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.cbor.*
val client = HttpClient(CIO) {
install(ContentNegotiation) {
cbor()
}
}若要自訂 CBOR 序列化,請在 cbor() 建構函式中傳入 Cbor 配置:
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() 函式:
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.protobuf.*
val client = HttpClient(CIO) {
install(ContentNegotiation) {
protobuf()
}
}若要自訂 ProtoBuf 序列化,請將 ProtoBuf 配置傳遞給 protobuf() 函式:
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:
val client = HttpClient(CIO) {
install(ContentNegotiation) {
register(ContentType.Application.Json, noOpJsonConverter)
acceptHeaderMergeStrategy = ContentTypeMergeStrategy.SkipIfPresent
}
}使用 SkipIfPresent 時,外掛程式會保留現有的 Accept 標頭。如果請求中不包含 Accept 標頭,外掛程式則會照常新增已註冊的內容類型。
發送與接收資料
建立資料類別
以下範例使用 Customer 資料類別來表示用戶端發送與接收的資料:
data class Customer(val id: Int, val firstName: String, val lastName: String)如果您使用 kotlinx.serialization,請使用 @Serializable 為該類別加上註解:
@Serializable
data class Customer(val id: Int, val firstName: String, val lastName: String)kotlinx.serialization 程式庫支援以下型別的序列化/還原序列化:
- 內建類別
- 序列 (Sequences) 的還原序列化
- 流程 (Flows) 的序列化
發送資料
若要在請求主體中發送類別執行個體,請使用 setBody() 函式指派此執行個體,並使用 contentType() 函式設定內容類型。
以下範例以 JSON 格式發送 Customer 物件:
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() 函式:
val customer: Customer = client.get("http://localhost:8080/customer/3").body()完整範例請參閱 client-json-kotlinx。
