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 アーティファクトを追加します。
implementation(ktorLibs.server.contentNegotiation)implementation ktorLibs.server.contentNegotiation<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 アーティファクトを追加します:
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 関数に渡します。 以下の例は、ContentNegotiation のインストール方法を示しています。
embeddedServer()関数呼び出し内でのインストール。Applicationクラスで明示的に定義されたmodule()拡張関数内でのインストール。
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)
}import io.ktor.server.application.*
import io.ktor.server.plugins.contentnegotiation.*
// ...
fun Application.module() {
install(ContentNegotiation)
// ...
}シリアライザーの設定
Ktor は標準で JSON、XML、CBOR の各形式をサポートしています。また、独自のカスタムシリアライザーを実装することもできます。
JSON シリアライザー
アプリケーションに JSON シリアライザーを登録するには、json メソッドを呼び出します:
import io.ktor.server.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.json.*
install(ContentNegotiation) {
json()
}また、json メソッドを使用すると、JsonBuilder で提供されているシリアライゼーション設定を調整することもできます。たとえば次のようになります:
install(ContentNegotiation) {
json(Json {
prettyPrint = true
isLenient = true
})アプリケーションに Gson シリアライザーを登録するには、gson メソッドを呼び出します:
import io.ktor.server.plugins.contentnegotiation.*
import io.ktor.serialization.gson.*
install(ContentNegotiation) {
gson()
}また、gson メソッドを使用すると、GsonBuilder で提供されているシリアライゼーション設定を調整することもできます。たとえば次のようになります:
install(ContentNegotiation) {
gson {
registerTypeAdapter(LocalDate::class.java, LocalDateAdapter())
setDateFormat(DateFormat.LONG, DateFormat.SHORT)
setPrettyPrinting()
}アプリケーションに Jackson シリアライザーを登録するには、jackson メソッドを呼び出します:
import io.ktor.server.plugins.contentnegotiation.*
import io.ktor.serialization.jackson.*
install(ContentNegotiation) {
jackson()
}また、jackson メソッドを使用すると、ObjectMapper で提供されているシリアライゼーション設定を調整することもできます。たとえば次のようになります:
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 メソッドを呼び出します:
import io.ktor.server.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.xml.*
install(ContentNegotiation) {
xml()
}また、xml メソッドを使用すると、XML シリアライゼーション設定にアクセスすることもできます。たとえば次のようになります:
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 メソッドを呼び出します:
import io.ktor.server.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.cbor.*
install(ContentNegotiation) {
cbor()
}また、cbor メソッドを使用すると、CborBuilder で提供されている CBOR シリアライゼーション設定にアクセスすることもできます。たとえば次のようになります:
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 メソッドを呼び出します:
import io.ktor.server.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.protobuf.*
install(ContentNegotiation) {
protobuf()
}また、protobuf メソッドを使用すると、ProtoBufBuilder で提供されている ProtoBuf シリアライゼーション設定にアクセスすることもできます。たとえば次のようになります:
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つのカスタムシリアライザーが登録されています:
install(ContentNegotiation) {
register(ContentType.Application.Json, CustomJsonConverter())
register(ContentType.Application.Xml, CustomXmlConverter())
}データの受信と送信
データクラスの作成
受信したデータをオブジェクトにデシリアライズするには、データクラスを作成する必要があります。たとえば次のようになります:
data class Customer(val id: Int, val firstName: String, val lastName: String)kotlinx.serialization を使用する場合は、このクラスに @Serializable アノテーションが付与されていることを確認してください:
import kotlinx.serialization.*
@Serializable
data class Customer(val id: Int, val firstName: String, val lastName: String)以下の型のシリアライズ/デシリアライズは、kotlinx.serialization ライブラリによってサポートされています:
- 組み込みクラス (Builtin classes)
- Sequence のデシリアライズ
- Flow のシリアライズ
データの受信
リクエストのコンテンツを受信して変換するには、パラメータとしてデータクラスを受け取る receive メソッドを呼び出します:
post("/customer") {
val customer = call.receive<Customer>()
customerStorage.add(customer)
call.respondText("Customer stored correctly", status = HttpStatusCode.Created)リクエストの処理には、そのリクエストの Content-Type に応じたシリアライザーが選択されて使用されます。以下の例は、サーバー側で Customer オブジェクトに変換される JSON または XML データを含むサンプルの HTTP クライアントリクエストを示しています:
POST http://0.0.0.0:8080/customer
Content-Type: application/json
{
"id": 3,
"firstName": "Jet",
"lastName": "Brains"
}POST http://0.0.0.0:8080/customer
Content-Type: application/xml
<Customer id="3" firstName="Jet" lastName="Brains"/>完全なサンプルコードはこちらで確認できます: json-kotlinx。
データの送信
レスポンスでデータオブジェクトを渡すには、respond メソッドを使用できます:
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 インターフェースを実装する必要があります:
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 クラスを参照してください。
