Skip to content
Server Plugin

数据转换

代码示例: data-conversion

所需依赖项:io.ktor:ktor-server-data-conversion

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

DataConversion 插件允许您序列化和反序列化值列表。默认情况下,Ktor 通过 DefaultConversionService 处理字符串以及常见类型,包括数值类型、无符号整数类型、Uuid 和枚举。

您可以通过安装并配置 DataConversion 插件来扩展此服务,以处理其他类型。

添加依赖项 ​

要使用 DataConversion,请将 ktor-server-data-conversion 工件添加到构建脚本中:

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

安装 DataConversion ​

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

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

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

添加转换器 ​

您可以在 DataConversion 配置中定义类型转换。为指定类型提供 convert<T> 方法,并使用可用函数来序列化和反序列化值列表:

  • 使用 decode() 函数反序列化值列表。它接收一个表示 URL 中重复值的字符串列表,并返回解码后的值。

    kotlin
    decode { values -> // 转换器: (values: List<String>) -> Any?
      // 反序列化值
    }
  • 使用 encode() 函数序列化值。该函数接收任意值并返回表示该值的字符串列表。

    kotlin
       encode { value -> // 转换器: (value: Any?) -> List<String>
         // 序列化值
        }

访问服务 ​

您可以从当前上下文中访问 DataConversion 服务:

kotlin
val dataConversion = application.conversionService

随后您可以使用转换器服务来调用回调函数:

  • fromValues(values: List<String>, type: TypeInfo) 回调函数接收作为字符串列表的 values 以及要将值转换为的目标 TypeInfo,并返回解码后的值。
  • toValues(value: Any?) 回调函数接收任意值,并返回表示该值的字符串列表。

示例 ​

在以下示例中,定义并配置了针对 LocalDate 类型的转换器,用于序列化和反序列化值。当调用 encode 函数时,该服务将使用 SimpleDateFormat 转换该值,并返回包含格式化后值的列表。当调用 decode 函数时,该服务会将日期格式化为 LocalDate 并将其返回。

kotlin
    install(DataConversion) {
        convert<LocalDate> { // this: DelegatingConversionService
            val formatter = DateTimeFormatterBuilder()
                .appendValue(ChronoField.YEAR, 4, 4, SignStyle.NEVER)
                .appendValue(ChronoField.MONTH_OF_YEAR, 2)
                .appendValue(ChronoField.DAY_OF_MONTH, 2)
                .toFormatter(Locale.ROOT)

            decode { values -> // 转换器: (values: List<String>) -> Any?
                LocalDate.from(formatter.parse(values.single()))
            }

            encode { value -> // 转换器: (value: Any?) -> List<String>
                listOf(SimpleDateFormat.getInstance().format(value))
            }
        }
    }

随后可以手动调用该转换服务来获取编码和解码后的值:

kotlin
val encodedDate = application.conversionService.toValues(call.parameters["date"])
val decodedDate = application.conversionService.fromValues(encodedDate, typeInfo<LocalDate>())

有关完整示例,请参阅 data-conversion