Skip to content
Server Plugin

Ktor Server 中的内容协商与序列化

所需依赖项: io.ktor:ktor-server-content-negotiation

代码示例: json-kotlinx

原生服务器Ktor 支持 Kotlin/Native,并允许您在无需额外运行时或虚拟机的情况下运行服务器。支持: ✅

ContentNegotiation 插件有两个主要用途:

  • 在客户端和服务器之间协商媒体类型。为此,它使用 Accept 和 Content-Type 标头。
  • 以特定格式序列化/反序列化内容。Ktor 开箱即用支持以下格式:JSON、XML、CBOR 和 ProtoBuf。

在客户端上,Ktor 提供了用于序列化/反序列化内容的 ContentNegotiation 插件。

添加依赖项 ​

ContentNegotiation ​

要使用 ContentNegotiation,请将 ktor-server-content-negotiation 工件添加到您的构建脚本中:

kotlin
implementation(ktorLibs.server.contentNegotiation)
上述代码段使用 Ktor 版本目录 (version catalog) 来指定 Ktor 依赖项。
groovy
implementation ktorLibs.server.contentNegotiation
上述代码段使用 Ktor 版本目录 (version catalog) 来指定 Ktor 依赖项。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-server-content-negotiation-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

请注意,特定格式的序列化器需要额外的工件。例如,kotlinx.serialization 处理 JSON 需要 ktor-serialization-kotlinx-json 依赖项。

序列化 ​

在使用 kotlinx.serialization 转换器之前,您需要按照 Setup 部分中的说明添加 Kotlin 序列化插件。

JSON ​

要序列化/反序列化 JSON 数据,您可以选择以下库之一:kotlinx.serialization、Gson 或 Jackson。

在构建脚本中添加 ktor-serialization-kotlinx-json 工件:

kotlin
implementation(ktorLibs.serialization.kotlinx.json)
上述代码段使用 Ktor 版本目录 (version catalog) 来指定 Ktor 依赖项。
groovy
implementation ktorLibs.serialization.kotlinx.json
上述代码段使用 Ktor 版本目录 (version catalog) 来指定 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 版本目录 (version catalog) 来指定 Ktor 依赖项。
groovy
implementation ktorLibs.serialization.gson
上述代码段使用 Ktor 版本目录 (version catalog) 来指定 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 版本目录 (version catalog) 来指定 Ktor 依赖项。
groovy
implementation ktorLibs.serialization.jackson
上述代码段使用 Ktor 版本目录 (version catalog) 来指定 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 版本目录 (version catalog) 来指定 Ktor 依赖项。
groovy
implementation ktorLibs.serialization.kotlinx.xml
上述代码段使用 Ktor 版本目录 (version catalog) 来指定 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 版本目录 (version catalog) 来指定 Ktor 依赖项。
groovy
implementation ktorLibs.serialization.kotlinx.cbor
上述代码段使用 Ktor 版本目录 (version catalog) 来指定 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 版本目录 (version catalog) 来指定 Ktor 依赖项。
groovy
implementation ktorLibs.serialization.kotlinx.protobuf
上述代码段使用 Ktor 版本目录 (version catalog) 来指定 Ktor 依赖项。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-serialization-kotlinx-protobuf-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

安装 ContentNegotiation ​

要将 ContentNegotiation 插件安装到应用程序中, 请将其传递给指定模块模块允许您通过对路由进行分组来构建应用程序结构。中的 install 函数。 以下示例展示了如何安装 ContentNegotiation:

  • 在 embeddedServer() 函数调用中。
  • 在 Application 类上显式定义的 module() 扩展函数中。
kotlin
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.plugins.contentnegotiation.*

fun main() {
    embeddedServer(Netty, port = 8080) {
        install(ContentNegotiation)
        // ...
    }.start(wait = true)
}
kotlin
import io.ktor.server.application.*
import io.ktor.server.plugins.contentnegotiation.*
// ...
fun Application.module() {
    install(ContentNegotiation)
    // ...
}

配置序列化器 ​

Ktor 开箱即用支持以下格式:JSON、XML、CBOR。您还可以实现自己的自定义序列化器。

JSON 序列化器 ​

要在应用程序中注册 JSON 序列化器,请调用 json 方法:

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

install(ContentNegotiation) {
    json()
}

json 方法还允许您调整 JsonBuilder 提供的序列化设置,例如:

kotlin

    install(ContentNegotiation) {
        json(Json {
            prettyPrint = true
            isLenient = true
        })

要在应用程序中注册 Gson 序列化器,请调用 gson 方法:

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

install(ContentNegotiation) {
    gson()
}

gson 方法还允许您调整 GsonBuilder 提供的序列化设置,例如:

kotlin
install(ContentNegotiation) {
    gson {
        registerTypeAdapter(LocalDate::class.java, LocalDateAdapter())
        setDateFormat(DateFormat.LONG, DateFormat.SHORT)
        setPrettyPrinting()
    }

要在应用程序中注册 Jackson 序列化器,请调用 jackson 方法:

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

install(ContentNegotiation) {
    jackson()
}

jackson 方法还允许您调整 ObjectMapper 提供的序列化设置,例如:

kotlin
install(ContentNegotiation) {
    jackson {
        configure(SerializationFeature.INDENT_OUTPUT, true)
        setDefaultPrettyPrinter(DefaultPrettyPrinter().apply {
            indentArraysWith(DefaultPrettyPrinter.FixedSpaceIndenter.instance)
            indentObjectsWith(DefaultIndenter("  ", "\n"))
        })
        registerModule(JavaTimeModule())  // 支持 java.time.* 类型
    }
}

XML 序列化器 ​

要在应用程序中注册 XML 序列化器,请调用 xml 方法:

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

install(ContentNegotiation) {
    xml()
}

xml 方法还允许您访问 XML 序列化设置,例如:

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

install(ContentNegotiation) {
    xml(format = XML {
        xmlDeclMode = XmlDeclMode.Charset
    })
}

CBOR 序列化器 ​

要在应用程序中注册 CBOR 序列化器,请调用 cbor 方法:

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

install(ContentNegotiation) {
    cbor()
}

cbor 方法还允许您访问 CborBuilder 提供的 CBOR 序列化设置,例如:

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

install(ContentNegotiation) {
    cbor(Cbor {
        ignoreUnknownKeys = true
    })
}

ProtoBuf 序列化器 ​

要在应用程序中注册 ProtoBuf 序列化器,请调用 protobuf 方法:

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

install(ContentNegotiation) {
    protobuf()
}

protobuf 方法还允许您访问 ProtoBufBuilder 提供的 ProtoBuf 序列化设置,例如:

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

install(ContentNegotiation) {
    protobuf(ProtoBuf {
        encodeDefaults = true
    })
}

自定义序列化器 ​

要为指定的 Content-Type 注册自定义序列化器,需要调用 register 方法。在下面的示例中,注册了两个自定义序列化器来反序列化 application/json 和 application/xml 数据:

kotlin
install(ContentNegotiation) {
    register(ContentType.Application.Json, CustomJsonConverter())
    register(ContentType.Application.Xml, CustomXmlConverter())
}

接收和发送数据 ​

创建数据类 ​

要将接收到的数据反序列化为对象,您需要创建一个数据类,例如:

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

如果您使用 kotlinx.serialization,请确保该类带有 @Serializable 注解:

kotlin
import kotlinx.serialization.*
@Serializable
data class Customer(val id: Int, val firstName: String, val lastName: String)

kotlinx.serialization 库支持以下类型的序列化/反序列化:

接收数据 ​

要接收并转换请求的内容,请调用接受数据类作为形参的 receive 方法:

kotlin

        post("/customer") {
            val customer = call.receive<Customer>()
            customerStorage.add(customer)
            call.respondText("Customer stored correctly", status = HttpStatusCode.Created)

请求的 Content-Type 将用于选择处理该请求的序列化器。以下示例展示了一个包含 JSON 或 XML 数据的示例 HTTP 客户端请求,该数据会在服务器端转换为 Customer 对象:

HTTP
POST http://0.0.0.0:8080/customer
Content-Type: application/json

{
  "id": 3,
  "firstName": "Jet",
  "lastName": "Brains"
}
HTTP
POST http://0.0.0.0:8080/customer
Content-Type: application/xml

<Customer id="3" firstName="Jet" lastName="Brains"/>

您可以在此处找到完整示例:json-kotlinx。

发送数据 ​

要在响应中传递数据对象,可以使用 respond 方法:

kotlin
routing {
    get("/customer/{id}") {
        val id: Int by call.parameters
        val customer: Customer = customerStorage.find { it.id == id }!!
        call.respond(customer)

在这种情况下,Ktor 使用 Accept 标头来选择所需的序列化器。您可以在此处找到完整示例:json-kotlinx。

实现自定义序列化器 ​

在 Ktor 中,您可以编写自己的序列化器来序列化/反序列化数据。为此,您需要实现 ContentConverter 接口:

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?
}

请参阅 GsonConverter 类作为实现示例。