Kotlin multiplatform / multi-format reflectionless serialization　を訳してみた

原典：[Kotlin/kotlinx.serialization](https://github.com/Kotlin/kotlinx.serialization/blob/master/README.md)

#Kotlinマルチフラットフォーム/マルチフォーマット リフレクションレス シリアライゼーション


　Kotlinのシリアライズは、シリアライズ可能なクラスのビジタコードを生成するコンパイラプラグイン、コアシリアライズAPIを持つランタイムライブラリ、様々なシリアライズフォーマットを持つサポートライブラリで構成されています。


* `@Serializable`とマークされたKotlinクラスと標準コレクションをサポートします。
* [JSON](https://github.com/Kotlin/kotlinx.serialization/blob/master/formats/README.md#JSON)、 [Protobuf](https://github.com/Kotlin/kotlinx.serialization/blob/master/formats/README.md#ProtoBuf)、 [CBOR](https://github.com/Kotlin/kotlinx.serialization/blob/master/formats/README.md#CBOR),、[Hocon](https://github.com/Kotlin/kotlinx.serialization/blob/master/formats/README.md#HOCON) そして [Properties](https://github.com/Kotlin/kotlinx.serialization/blob/master/formats/README.md#properties) フォーマットを提供します。
* 完全なマルチプラットフォーム(JVM、JS、ネイティブ)に対応。

## 目次

<!--- TOC -->

* [イントロダクションとリファレンス](#イントロダクションとリファレンス)
* [セットアップ](#セットアップ)
  * [Gradle](#gradle)
     * [`plugins`](#apply-plugin-%E3%82%92%E4%BD%BF%E3%81%86-%E5%BE%93%E6%9D%A5%E3%81%AE%E6%96%B9%E6%B3%95) ブロックを使う
     * [`apply plugin`](#apply-plugin-%E3%82%92%E4%BD%BF%E3%81%86-%E5%BE%93%E6%9D%A5%E3%81%AE%E6%96%B9%E6%B3%95) を使う(従来のやり方)
     * [JSONライブラリ](#json%E3%83%A9%E3%82%A4%E3%83%96%E3%83%A9%E3%83%AA%E3%81%B8%E3%81%AE%E4%BE%9D%E5%AD%98%E6%80%A7)への依存性
  * [Android](#android)
  * [マルチプラットフォーム (Common, JS, Native)](#%E3%83%9E%E3%83%AB%E3%83%81%E3%83%97%E3%83%A9%E3%83%83%E3%83%88%E3%83%95%E3%82%A9%E3%83%BC%E3%83%A0common-js-native)
  * [Maven](#maven)

<!--- END -->

##イントロダクションとリファレンス

　ちょっとした例をご紹介します。

```kotlin
import kotlinx.serialization.*
import kotlinx.serialization.json.*

@Serializable 
data class Project(val name: String, val language: String)

fun main() {
    // Serializing objects
    val data = Project("kotlinx.serialization", "Kotlin")
    val string = Json.encodeToString(data)  
    println(string) // {"name":"kotlinx.serialization","language":"Kotlin"} 
    // Deserializing back into objects
    val obj = Json.decodeFromString<Project>(string)
    println(obj) // Project(name=kotlinx.serialization, language=Kotlin)
}
``` 

> 完全なコードは[こちら](https://github.com/Kotlin/kotlinx.serialization/blob/master/guide/example/example-readme-01.kt)から取得できます。

<!--- TEST_NAME ReadmeTest -->

<!--- TEST 
{"name":"kotlinx.serialization","language":"Kotlin"}
Project(name=kotlinx.serialization, language=Kotlin)
-->

**詳細は [Kotlin Serialization Guide] (https://github.com/Kotlin/kotlinx.serialization/blob/master/docs/serialization-guide.md) を参照してください。(非公認翻訳版は[こちら](https://qiita.com/guijiu/items/097e858e4930b6d7e6c0))。

　[GitHub Pages](https://kotlin.github.io/kotlinx.serialization/)に自動生成されたドキュメントサイトがあります。

## セットアップ

　Kotlin SerializationプラグインはKotlinコンパイラのディストリビューションに同梱されており、IDEAプラグインはKotlinプラグインにバンドルされています。Kotlin Serializationを使用するには、Kotlinコンパイラ `1.4.0` 以降が必要です。IDEに対応するKotlinプラグインがインストールされていることを確認してください。

### Gradle


####`plugins` ブロックを使う

　シリアル化プラグインをKotlinプラグインで設定するには、以下のようにします。
[Gradle plugins DSL](https://docs.gradle.org/current/userguide/plugins.html#sec:plugins_block):

Kotlin DSL:

```kotlin
plugins {
    kotlin("jvm") version "1.4.10" // or kotlin("multiplatform") or any other kotlin plugin
    kotlin("plugin.serialization") version "1.4.10"
}
```       

Groovy DSL:

```gradle
plugins {
    id 'org.jetbrains.kotlin.multiplatform' version '1.4.10'
    id 'org.jetbrains.kotlin.plugin.serialization' version '1.4.10'
}
```

> 1.4.0以前のKotlinのバージョンは、Kotlinシリアライズの安定版リリースではサポートされていません。

#### `apply plugin` を使う (従来の方法)

　まず、他の[compiler plugins](https://kotlinlang.org/docs/reference/compiler-plugins.html)と同様に、シリアライズプラグインをクラスパスに追加する必要があります。

Kotlin DSL:

```kotlin
buildscript {
    repositories { jcenter() }

    dependencies {
        val kotlinVersion = "1.4.10"
        classpath(kotlin("gradle-plugin", version = kotlinVersion))
        classpath(kotlin("serialization", version = kotlinVersion))
    }
}
```

Groovy DSL:

```gradle
buildscript {
    ext.kotlin_version = '1.4.10'
    repositories { jcenter() }

    dependencies {
        classpath "org.jetbrains.kotlin:kotlin-serialization:$kotlin_version"
    }
}
```

そして、`apply plugin`(example in Groovy) を実行する。

```gradle
apply plugin: 'kotlin' // or 'kotlin-multiplatform' for multiplatform projects
apply plugin: 'kotlinx-serialization'
```

#### JSONライブラリへの依存性

　プラグインの設定を行った後、シリアライズライブラリに依存関係を追加する必要があります。プラグインのバージョンはコンパイラのバージョンと同じですが、ランタイムライブラリはコーディネート、リポジトリ、バージョン管理が異なるので注意してください。

Kotlin DSL:

```kotlin
repositories {
    // Artifacts are also available on Maven Central
    jcenter()
}

dependencies {
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.0.1")
}
```

Groovy DSL:

```gradle
repositories {
    // Artifacts are also available on Maven Central
    jcenter()
}

dependencies {
    implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:1.0.1"
}
```

>また、`kotlinx-serialization-core` は、すべてのシリアライズ API を含んでいますが、 バンドルされたシリアライズフォーマットは持っていません。

### Android
　ライブラリはAndroid上で "そのまま "動作するはずです。proguardを使っている場合は、これを `proguard-rules.pro` に追加する必要があります。



```proguard
-keepattributes *Annotation*, InnerClasses
-dontnote kotlinx.serialization.AnnotationsKt # core serialization annotations

# kotlinx-serialization-json specific. Add this if you have java.lang.NoClassDefFoundError kotlinx.serialization.json.JsonObjectSerializer
-keepclassmembers class kotlinx.serialization.json.** {
    *** Companion;
}
-keepclasseswithmembers class kotlinx.serialization.json.** {
    kotlinx.serialization.KSerializer serializer(...);
}

# Change here com.yourcompany.yourpackage
-keep,includedescriptorclasses class com.yourcompany.yourpackage.**$$serializer { *; } # <-- change package name to your app's
-keepclassmembers class com.yourcompany.yourpackage.** { # <-- change package name to your app's
    *** Companion;
}
-keepclasseswithmembers class com.yourcompany.yourpackage.** { # <-- change package name to your app's
    kotlinx.serialization.KSerializer serializer(...);
}
```

　また、定義したすべてのカスタムシリアライザを保持しておくとよいでしょう。

### マルチプラットフォーム（Common, JS, Native）

　ほとんどのモジュールはKotlin/JSやKotlin/Nativeでも利用可能です。必要なモジュールに依存関係を追加することができます。

```gradle
commonMain {
    dependencies {
        // Works as common dependency as well as the platform one
        implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:$serialization_version"
    }
}
```

　同じアーティファクト座標( artifact coordinates)は、プラットフォーム固有のソースセットにおいて、プラットフォーム固有のアーティファクトに依存して使用することができます。（The same artifact coordinates can be used to depend on platform-specific artifact in platform-specific source-set.）

### Maven

　Kotlinのバージョンとシリアライズのバージョンが適切であることを確認してください。

```xml
<properties>
    <kotlin.version>1.4.10</kotlin.version>
    <serialization.version>1.0.1</serialization.version>
</properties>
```

　JCenterや`https://kotlin.bintray.com/kotlinx` Bintrayリポジトリを利用することもできます。

　Kotlinコンパイラプラグインにシリアライズプラグインを追加する。

```xml
<build>
    <plugins>
        <plugin>
            <groupId>org.jetbrains.kotlin</groupId>
            <artifactId>kotlin-maven-plugin</artifactId>
            <version>${kotlin.version}</version>
            <executions>
                <execution>
                    <id>compile</id>
                    <phase>compile</phase>
                    <goals>
                        <goal>compile</goal>
                    </goals>
                </execution>
            </executions>
            <configuration>
                <compilerPlugins>
                    <plugin>kotlinx-serialization</plugin>
                </compilerPlugins>
            </configuration>
            <dependencies>
                <dependency>
                    <groupId>org.jetbrains.kotlin</groupId>
                    <artifactId>kotlin-maven-serialization</artifactId>
                    <version>${kotlin.version}</version>
                </dependency>
            </dependencies>
        </plugin>
    </plugins>
</build>
```

　シリアライズ ランタイム ライブラリへの依存関係を追加しました。

```xml
<dependency>
    <groupId>org.jetbrains.kotlinx</groupId>
    <artifactId>kotlinx-serialization-json</artifactId>
    <version>${serialization.version}</version>
</dependency>
```