組み込み型のシリアライズ
Kotlinシリアライゼーション(Kotlin serialization)は、プリミティブ型や文字列などの基本型や、特定の標準ライブラリのクラスを含む、さまざまな組み込み型をサポートしています。 以下のセクションでは、これらの型について詳しく説明し、シリアライズ方法を示します。
基本型
Kotlinシリアライゼーションは、シリアライズされたデータ内で単一の値として表される型に対して、組み込みのシリアライザーを提供します。 これには、プリミティブ、文字列、列挙型(enum)が含まれます。
例えば、Long 型をシリアライズする方法は次のとおりです。
// 必要なライブラリの宣言をインポート
import kotlinx.serialization.*
import kotlinx.serialization.json.*
@Serializable
class Data(val signature: Long)
fun main() {
val data = Data(0x1CAFE2FEED0BABE0)
println(Json.encodeToString(data))
// {"signature":2067120338512882656}
}数値
整数や浮動小数点数を含むすべてのKotlinの数値型は、JSONの自然な表現を使用してシリアライズできます。
import kotlinx.serialization.*
import kotlinx.serialization.json.*
import kotlin.math.PI
@Serializable
class Data(
val answer: Int,
val pi: Double
)
fun main() {
val data = Data(42, PI)
println(Json.encodeToString(data))
// {"answer":42,"pi":3.141592653589793}
}符号なし数値
Kotlinシリアライゼーションは、UByte や UInt などのKotlinの符号なし整数型をサポートしています。 JSONでは、これらの値は通常のJSON数値としてシリアライズされ、完全な符号なしの範囲が保持されます。
import kotlinx.serialization.*
import kotlinx.serialization.json.*
@Serializable
class Counter(val counted: UByte, val description: String)
fun main() {
val counted = 239.toUByte()
println(Json.encodeToString(Counter(counted, "tries")))
// {"counted":239,"description":"tries"}
}JSONでは符号なし数値の全範囲が保持されますが、他のシリアライゼーションフォーマットでは扱いが異なる場合があります。 例えば、ProtoBufやCBORでは、これらの型は対応する符号付きの型を使用してシリアライズされます。
文字列としての Long 数値
JSONで Long 数値を文字列として表現できます。 これは、JavaScriptの Number 型がKotlinのすべての Long 値を正確に表現できず、精度の低下につながる可能性があるJavaScript環境で役立ちます。
LongAsStringSerializer を @Serializable アノテーションと共に使用することで、JSON内で Long 値を文字列としてエンコードします。
import kotlinx.serialization.*
import kotlinx.serialization.builtins.*
import kotlinx.serialization.json.*
@Serializable
class Data(
@Serializable(LongAsStringSerializer::class)
val signature: Long
)
fun main() {
val data = Data(0x1CAFE2FEED0BABE0)
println(Json.encodeToString(data))
// {"signature":"2067120338512882656"}
}ファイル内のすべてのプロパティに対して LongAsStringSerializer などのシリアライザーを指定することもできます。 詳細については、ファイルに対するシリアライザーの指定を参照してください。
Enum クラス
すべての enum クラスは、@Serializable アノテーションがなくてもデフォルトでシリアライズ可能です。 JSONでシリアライズされる場合、enum は文字列としてエンコードされます。
import kotlinx.serialization.*
import kotlinx.serialization.json.*
// enum クラスには @Serializable アノテーションは不要です
enum class Status { SUPPORTED }
@Serializable
class Project(val name: String, val status: Status)
fun main() {
val data = Project("kotlinx.serialization", Status.SUPPORTED)
println(Json.encodeToString(data))
// {"name":"kotlinx.serialization","status":"SUPPORTED"}
}Kotlin/JSまたはKotlin/Nativeをターゲットにする場合、encodeToString<Status>(Status.SUPPORTED) のように enum クラスをルートオブジェクトとして使用するには、その enum クラスに @Serializable アノテーションを付与する必要があります。
Enum エントリのシリアル名のカスタマイズ
Enumエントリのシリアル名をカスタマイズするには、@SerialName アノテーションを使用し、enumクラスに @Serializable を付与します。
import kotlinx.serialization.*
import kotlinx.serialization.json.*
// @SerialName を使用するため @Serializable アノテーションが必要です
@Serializable
enum class Status { @SerialName("maintained") SUPPORTED }
@Serializable
class Project(val name: String, val status: Status)
fun main() {
val data = Project("kotlinx.serialization", Status.SUPPORTED)
println(Json.encodeToString(data))
// {"name":"kotlinx.serialization","status":"maintained"}
}シリアル名のカスタマイズに関する詳細については、シリアル名のカスタマイズを参照してください。
標準ライブラリの型
Kotlinシリアライゼーションは標準ライブラリのいくつかの型をサポートしていますが、範囲(range)や Regex クラスなどの一部のクラスはサポートされていません。
Pair と Triple
Kotlin標準ライブラリの Pair および Triple クラスをシリアライズできます。
import kotlinx.serialization.*
import kotlinx.serialization.json.*
@Serializable
class Project(val name: String)
fun main() {
val pair = 1 to Project("kotlinx.serialization")
println(Json.encodeToString(pair))
// {"first":1,"second":{"name":"kotlinx.serialization"}}
}コレクション
Kotlinシリアライゼーションは、List、Set、および Map の読み取り専用および可変バリアントを含むコレクション型をサポートしています。 また、ArrayList や LinkedHashSet などの具象実装、およびジェネリック配列やプリミティブ配列の型もサポートしています。 これらのコレクションがどのように表現されるかは、シリアライゼーションフォーマットに依存します。
JSONでは、リストとセットはJSON配列としてシリアライズされ、マップはJSONオブジェクトとして表現されます。
KotlinはJSONのデシリアライズに宣言された型を使用します。 デシリアライズ中、結果のオブジェクトの型はソースコードで指定された静的型によって決定されます。 この型は、プロパティの型またはデコード関数の型パラメータのいずれかになります。
リストのシリアライズ
Kotlinシリアライゼーションは、List 型をJSON配列としてシリアライズします。 クラスのリストの例を以下に示します。
import kotlinx.serialization.*
import kotlinx.serialization.json.*
@Serializable
class Project(val name: String)
fun main() {
val list = listOf(
Project("kotlinx.serialization"),
Project("kotlinx.coroutines")
)
println(Json.encodeToString(list))
// [{"name":"kotlinx.serialization"},{"name":"kotlinx.coroutines"}]
}セットのシリアライズ
Set 型は、List 型と同様にJSON配列としてシリアライズされます。
import kotlinx.serialization.*
import kotlinx.serialization.json.*
@Serializable
class Project(val name: String)
fun main() {
val set = setOf(
Project("kotlinx.serialization"),
Project("kotlinx.coroutines")
)
println(Json.encodeToString(set))
// [{"name":"kotlinx.serialization"},{"name":"kotlinx.coroutines"}]
}デフォルトでは、重複するエントリを含むセットをデシリアライズできます。重複の処理動作は実装によって定義されます。
マップのシリアライズ
Kotlinシリアライゼーションは、プリミティブ型またはenumのキーを持つ Map 型をサポートしています。
import kotlinx.serialization.*
import kotlinx.serialization.json.*
@Serializable
class Project(val name: String)
fun main() {
// Int型のキーを持つマップを作成
val map = mapOf(
1 to Project("kotlinx.serialization"),
2 to Project("kotlinx.coroutines")
)
println(Json.encodeToString(map))
// {"1":{"name":"kotlinx.serialization"},"2":{"name":"kotlinx.coroutines"}}
}マップのシリアライゼーションはフォーマットに依存します。 JSONでは、マップはオブジェクトとして表現されます。JSONオブジェクトのキーは常に文字列であるため、Kotlinで数値であってもキーは文字列としてエンコードされます。 CBORなどの他のフォーマットは、非プリミティブキーを持つマップをサポートし、そのまま保持します。
JSONはネイティブでは複合キー(複雑なキー)をサポートしていません。 構造化オブジェクトをマップのキーとしてエンコードする方法については、構造化されたマップキーの許可を参照してください。
コレクションのデシリアライズ動作
KotlinはJSONのデシリアライズに宣言された型を使用します。 例えばコレクションの場合、List は重複を保持しますが、Set は一意性を強制します。
import kotlinx.serialization.*
import kotlinx.serialization.json.*
@Serializable
data class Data(
val a: List<Int>,
val b: Set<Int>
)
fun main() {
val data = Json.decodeFromString<Data>("""
{
"a": [42, 42],
"b": [42, 42]
}
""")
// Set型は要素の一意性を強制するため、data.b から重複が削除されます
println(data)
// Data(a=[42, 42], b=[42])
}Kotlinのコレクションに関する詳細については、コレクションの概要を参照してください。
Unit とシングルトンオブジェクト
Kotlinの Unit 型およびその他のシングルトンオブジェクトはシリアライズ可能です。 シングルトンとはインスタンスが1つしか存在しないクラスであり、その状態は外部プロパティではなくオブジェクト自体によって定義されます。 JSONでは、シングルトンオブジェクトは空の構造体としてシリアライズされます。
import kotlinx.serialization.*
import kotlinx.serialization.json.*
@Serializable
object SerializationVersion {
val libraryVersion: String = "1.0.0"
}
fun main() {
println(Json.encodeToString(SerializationVersion))
// {}
println(Json.encodeToString(Unit))
// {}
}シリアライズされたシングルトンオブジェクトは、閉じたポリモーフィック階層において、追加フィールドのないケースを表現するために使用できます。
Duration と Instant
Kotlinの Duration 型は、ISO-8601-2形式を使用して文字列にシリアライズされます。
import kotlinx.serialization.*
import kotlinx.serialization.json.*
import kotlin.time.*
fun main() {
val duration = 1000.toDuration(DurationUnit.SECONDS)
println(Json.encodeToString(duration))
// "PT16M40S"
}Kotlinの Instant 型も、ISO-8601-1形式を使用して時点を表す文字列としてシリアライズできます。
import kotlinx.serialization.*
import kotlinx.serialization.json.*
import kotlin.time.*
fun main() {
val instant = Instant.fromEpochMilliseconds(1607505416124)
println(Json.encodeToString(instant))
// "2020-12-09T09:16:56.124Z"
}Nothing
Nothing 型はデフォルトでシリアライズ可能です。 これにはインスタンスが存在しないため、エンコードまたはデコードしようとすると例外がスローされます。 ジェネリック基底型を持つポリモーフィック階層のように、構文上型が必要であってもシリアライゼーションには関与しない場合に Nothing を使用します。
import kotlinx.serialization.*
import kotlinx.serialization.builtins.*
import kotlinx.serialization.json.*
@Serializable
sealed class ParametrizedParent<out R> {
@Serializable
data class ChildWithoutParameter(val value: Int) : ParametrizedParent<Nothing>()
}
fun main() {
println(Json.encodeToString(ParametrizedParent.ChildWithoutParameter(42)))
// {"value":42}
}次のステップ
- クラスのシリアライズ方法や、
@Serializableアノテーションのデフォルトの動作を変更する方法については、クラスのシリアライズをご覧ください。 - より複雑なJSONシリアライゼーションのシナリオを探るには、JSONシリアライゼーションの概要を参照してください。
- ポリモーフィズムや、共通の基底クラスを通じた異なる型のシリアライズの詳細については、ポリモーフィックなクラスのシリアライズを参照してください。
