Skip to content
Server Plugin

Ktor Server におけるコンテンツネゴシエーションとシリアライゼーション

必要な依存関係: io.ktor:ktor-server-content-negotiation

コード例: json-kotlinx

Native サーバーKtorはKotlin/Nativeをサポートしており、追加のランタイムや仮想マシンなしでサーバーを実行できます。のサポート: ✅

ContentNegotiation プラグインには、主に2つの目的があります。

  • クライアントとサーバー間でのメディアタイプのネゴシエーション。このために Accept および Content-Type ヘッダーを使用します。
  • 特定の形式でのコンテンツのシリアライズ/デシリアライズ。Ktor は標準で JSON、XML、CBOR、ProtoBuf の各形式をサポートしています。

クライアント側では、コンテンツをシリアライズ/デシリアライズするために Ktor は ContentNegotiation プラグインを提供しています。

依存関係の追加 ​

ContentNegotiation ​

ContentNegotiation を使用するには、ビルドスクリプトに ktor-server-content-negotiation アーティファクトを追加します。

kotlin
implementation(ktorLibs.server.contentNegotiation)
上記のコードスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログを使用しています。
groovy
implementation ktorLibs.server.contentNegotiation
上記のコードスニペットでは、Ktor の依存関係を指定するために 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 コンバーターを使用する前に、セットアップセクションの説明に従って Kotlin serialization プラグインを追加する必要があります。

JSON ​

JSON データをシリアライズ/デシリアライズするには、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 関数に渡します。 以下の例は、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 データをデシリアライズするために2つのカスタムシリアライザーが登録されています:

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 に応じたシリアライザーが選択されて使用されます。以下の例は、サーバー側で Customer オブジェクトに変換される JSON または XML データを含むサンプルの HTTP クライアントリクエストを示しています:

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 クラスを参照してください。