Skip to content
Server Plugin

資料轉換

程式碼範例: data-conversion

必要相依性:io.ktor:ktor-server-data-conversion

Native 伺服器Ktor 支援 Kotlin/Native,可讓您在無需額外執行階段或虛擬機的情況下執行伺服器。 支援:✅

DataConversion 外掛程式可讓您序列化和還原序列化值清單。預設情況下,Ktor 透過 DefaultConversionService 處理字串和常見型別,包括數值型別、無正負號整數型別、Uuid 以及列舉。

您可以透過安裝並配置 DataConversion 外掛程式來擴充此服務,以處理其他型別。

新增相依性 ​

若要使用 DataConversion,請在建置指令碼中新增 ktor-server-data-conversion 構件:

kotlin
implementation(ktorLibs.server.dataConversion)
上述程式碼片段使用 Ktor version catalog 來指定 Ktor 相依性。
groovy
implementation ktorLibs.server.dataConversion
上述程式碼片段使用 Ktor version catalog 來指定 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 -> // converter: (values: List<String>) -> Any?
      // 還原序列化值
    }
  • 使用 encode() 函式序列化值。該函式接收任意值,並傳回代表該值的字串清單。

    kotlin
       encode { value -> // converter: (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 -> // converter: (values: List<String>) -> Any?
                LocalDate.from(formatter.parse(values.single()))
            }

            encode { value -> // converter: (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