This is an automated email from the ASF dual-hosted git repository.
chaokunyang pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/fory-site.git
The following commit(s) were added to refs/heads/main by this push:
new eb0822ce000 Fix kotlin blog compatibility (#506)
eb0822ce000 is described below
commit eb0822ce000b14ea3c3516a0b61f07c0fac3d07d
Author: Shawn Yang <[email protected]>
AuthorDate: Tue Sep 8 12:20:59 2026 +0800
Fix kotlin blog compatibility (#506)
---
blog/2026-09-07-fory_kotlin_json.md | 16 ++--
.../2026-09-07-fory_kotlin_json.md | 104 ++++++++++-----------
2 files changed, 59 insertions(+), 61 deletions(-)
diff --git a/blog/2026-09-07-fory_kotlin_json.md
b/blog/2026-09-07-fory_kotlin_json.md
index 2f09c6aa158..26e1c5d848d 100644
--- a/blog/2026-09-07-fory_kotlin_json.md
+++ b/blog/2026-09-07-fory_kotlin_json.md
@@ -6,17 +6,15 @@ authors: [chaokunyang]
tags: [fory, kotlin, java, json, serialization, performance]
---
-**TL;DR**: Apache Fory JSON brings high-performance JSON serialization to
Kotlin/JVM. Use data classes, constructor defaults, nullable properties, value
classes, and sealed hierarchies directly, with String and UTF-8 APIs and no
`kotlin-reflect` dependency. In benchmarks covering small messages and large
documents, Fory delivers higher throughput than kotlinx.serialization, Moshi,
and Jackson Kotlin.
+**TL;DR**: Apache Fory JSON brings high-performance JSON serialization to
Kotlin/JVM. It maps data classes, value classes, and sealed hierarchies to JSON
while preserving constructor defaults and nullability. In benchmarks covering
small messages and large documents, Fory delivers **2.78×–12.12× the
throughput** of kotlinx.serialization, Moshi, and Jackson Kotlin.
<img src="/img/fory-logo-light.png" width="50%"/>
-## JSON That Fits Your Kotlin Models {#kotlin-models-as-json-contracts}
+## JSON Serialization in Kotlin Applications {#kotlin-models-as-json-contracts}
-Kotlin applications often describe API requests and responses with data
classes. Default arguments determine what happens when an input is omitted,
while nullable types express where null is allowed. Value classes distinguish
domain values such as account IDs, and sealed hierarchies model alternatives
such as different payment methods.
+Kotlin applications exchange JSON through HTTP APIs, message queues, and
stored documents. Application code works with typed models, so each exchange
involves converting between JSON and Kotlin objects. Reading a document
includes constructing an object with the right arguments and running its
initialization logic; writing it must preserve the values needed to reconstruct
that object.
-A JSON library should follow those declarations when reading and writing your
models. It should apply defaults to missing properties, enforce nullability
inside collections, and run constructor initialization and validation when
reconstructing objects. Its output should preserve the values needed to read
the object back correctly.
-
-Apache Fory JSON supports these Kotlin models directly. Its Kotlin/JVM mapping
layer preserves their type and construction rules while using Fory's
high-performance JSON engine. Applications can exchange standard JSON text or
UTF-8 bytes using familiar Kotlin declarations, without writing a custom
adapter for each data class.
+These conversions also consume CPU time and allocate temporary objects,
especially when a service processes many messages or large documents. Apache
Fory JSON combines Kotlin object mapping with a high-performance JSON engine:
the Kotlin layer follows the model's type and construction rules, while the
engine handles JSON parsing and output. The same mapping is available through
String and direct UTF-8 APIs.
## Getting Started
@@ -227,10 +225,10 @@ The measurements describe the selected models and
configuration on one machine.
## JVM, Android, and GraalVM {#jvm-and-deployment-support}
-This module targets Kotlin/JVM and does not require `kotlin-reflect`. The
runtime is built with Kotlin 2.3.20; model compatibility follows the supported
versions of Kotlin's metadata reader. The [installation
guide](/docs/json/kotlin#installation) covers compatibility, and the [runtime
guide](/docs/json/getting-started) includes the recommended `java.lang.invoke`
opening on JDK 25 and later.
+This module targets Kotlin/JVM and does not require `kotlin-reflect`. The
[installation guide](/docs/json/kotlin#installation) covers compatibility, and
the [runtime guide](/docs/json/getting-started) includes the recommended
`java.lang.invoke` opening on JDK 25 and later.
Android API 26 and later uses interpreted JSON mapping. With R8 or ProGuard
enabled, add `fory-json-kotlin-ksp` and annotate required source models with
`JsonType` to preserve mapping information. GraalVM Native Image uses the
`ForyJsonProvider` workflow to install the Kotlin module and select reachable
models for code generation. The [platform
guide](/docs/json/kotlin#graalvm-and-android) covers both setups.
Kotlin/Native, Kotlin/JS, and Kotlin/Wasm are outside this module's scope.
-## Get Started {#learn-more}
+## Further Reading {#learn-more}
-Add `fory-json-kotlin` to your application and try a round trip with one of
your Kotlin models. The [Kotlin JSON guide](/docs/json/kotlin) covers type
mapping and configuration; see [Custom Codecs](/docs/json/custom-codecs) for
application-specific representations and [Security](/docs/json/security) for
input limits. Source code and contribution instructions are available at
[apache/fory](https://github.com/apache/fory).
+The [Kotlin JSON guide](/docs/json/kotlin) covers type mapping and
configuration; see [Custom Codecs](/docs/json/custom-codecs) for
application-specific representations and [Security](/docs/json/security) for
input limits. Source code and contribution instructions are available at
[apache/fory](https://github.com/apache/fory).
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-blog/2026-09-07-fory_kotlin_json.md
b/i18n/zh-CN/docusaurus-plugin-content-blog/2026-09-07-fory_kotlin_json.md
index 7a1c8dd52d3..b7e9fe0fc39 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-blog/2026-09-07-fory_kotlin_json.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-blog/2026-09-07-fory_kotlin_json.md
@@ -1,26 +1,24 @@
---
slug: fory_kotlin_json
title: "Apache Fory™ JSON：面向 Kotlin 的高性能 JSON 序列化"
-description: "Apache Fory JSON 为 Kotlin/JVM 数据类、值类和 sealed
层次结构提供高性能序列化，保留构造函数默认值与可空性。"
+description: "Apache Fory JSON 为 Kotlin/JVM 提供高性能序列化，支持数据类、值类和密封类型，并遵循 Kotlin
的构造函数默认值和可空性规则。"
authors: [chaokunyang]
tags: [fory, kotlin, java, json, serialization, performance]
---
-**摘要**：Apache Fory JSON 为 Kotlin/JVM 提供高性能 JSON 序列化。通过 String 和 UTF-8
API，可以直接使用数据类、构造函数默认值、可空属性、值类和 sealed 层次结构，无需依赖
`kotlin-reflect`。在涵盖小消息和大文档的基准测试中，Fory 的吞吐量高于 kotlinx.serialization、Moshi 和
Jackson Kotlin。
+**摘要**：Apache Fory JSON 为 Kotlin/JVM 提供高性能 JSON
序列化，支持数据类、值类和密封类型，并遵循模型中声明的默认值和可空性规则。在涵盖小消息和大文档的基准测试中，Fory 的吞吐量为
kotlinx.serialization、Moshi 和 Jackson Kotlin 的 **2.78–12.12 倍**。
<img src="/img/fory-logo-light.png" width="50%"/>
-## 让 JSON 遵循 Kotlin 模型的定义 {#kotlin-models-as-json-contracts}
+## Kotlin 应用中的 JSON 序列化 {#kotlin-models-as-json-contracts}
-Kotlin 应用经常用数据类描述 API 请求和响应。默认参数决定输入缺失时如何处理，可空类型明确哪些位置允许 null；值类区分账户 ID
等领域值，sealed 层次结构则表示不同支付方式这样的多种可能。
+Kotlin 应用经常需要接收 HTTP 请求、消费队列消息，或读取 JSON 文档。这些数据进入应用后，要转换成 Kotlin
对象；返回响应或写入存储时，又要转回 JSON。转换时需要遵循模型的类型和构造规则：正确传入参数、执行初始化逻辑，并在输出中保留还原对象所需的值。
-JSON
库在读写模型时也应遵循这些定义：为缺失属性使用默认值，检查集合内部的可空性，并在重建对象时执行构造函数中的初始化和校验。输出也应保留正确还原对象所需的值。
-
-Apache Fory JSON 直接支持这些 Kotlin 模型。它的 Kotlin/JVM 映射层保留模型的类型和构造规则，并使用 Fory 的高性能
JSON 引擎处理数据。应用可以用熟悉的 Kotlin 声明交换标准 JSON 文本或 UTF-8 字节，无需为每个数据类编写自定义适配器。
+对于需要处理大量消息或大文档的服务，序列化的 CPU 开销和临时内存分配也会影响性能。Apache Fory JSON 为 Kotlin
提供了专门的对象映射支持，负责处理 Kotlin 的类型信息和对象构造，底层沿用 Fory 的高性能 JSON
引擎完成解析和输出。它既支持字符串，也支持直接读写 UTF-8 字节。
## 快速开始 {#getting-started}
-在现有 Kotlin/JVM 项目中添加 Maven Central 上的模块，并确保所有 Fory 依赖使用相同版本：
+先在 Kotlin/JVM 项目中添加依赖。该模块已发布到 Maven Central，项目中的 Fory 依赖应使用相同版本：
```kotlin title="build.gradle.kts"
dependencies {
@@ -28,7 +26,7 @@ dependencies {
}
```
-创建运行时和模型的类型令牌。运行时是线程安全的；应保留这两个对象以便重复使用：
+接着创建 `json` 实例，并用 `jsonTypeRef<Account>()` 指定模型类型。`json` 是线程安全的，建议复用 `json` 和
`accountType`，避免每次读写都重新创建：
```kotlin
import org.apache.fory.json.kotlin.ForyJsonKotlin
@@ -53,9 +51,9 @@ fun main() {
}
```
-在标准 JVM 上，这个示例不需要模型注解或序列化编译器插件。`ForyJsonKotlin.builder()` 安装 Kotlin
模块，`jsonTypeRef<T>()` 描述要序列化或反序列化的类型，包括泛型参数和可空性。例如，列表允许包含 null 元素时使用
`jsonTypeRef<List<Account?>>()`，每个元素都必须是账户时则使用 `jsonTypeRef<List<Account>>()`。
+在标准 JVM 上，上面的示例无需给模型添加注解，也不需要序列化编译器插件。`ForyJsonKotlin.builder()` 会自动注册 Kotlin
模块。`jsonTypeRef<T>()` 提供完整的类型信息，包括泛型参数和可空性：`jsonTypeRef<List<Account?>>()`
允许列表包含 null 元素，`jsonTypeRef<List<Account>>()` 则要求所有元素非空。
-字节 API 直接读写 UTF-8。当 HTTP 客户端、消息传输或存储 API 已经使用字节交换数据时，可以避免将完整文档转换为中间 String。
+如果 HTTP 客户端、消息队列或存储接口本来就使用字节传递数据，可以直接调用字节 API 读写 UTF-8，省去将整份文档转换为字符串的开销。
## 构造函数默认值与可空性 {#constructor-defaults-and-nullability}
@@ -69,7 +67,7 @@ data class Request(
)
```
-Fory 自动选择主构造函数。成员缺失且存在默认值时，会使用编译器提供的默认值逻辑；对于显式 JSON null，则根据参数的可空性进行检查：
+Fory 会自动使用主构造函数创建 `Request`。JSON 中缺少某个字段时，如果对应参数有默认值，就使用该默认值；如果字段明确写为
null，则检查参数是否允许为 null：
| JSON 输入 | 结果 |
| --- | --- |
@@ -78,15 +76,15 @@ Fory 自动选择主构造函数。成员缺失且存在默认值时，会使用
| `{"label":"ready"}` | 拒绝：缺少必需参数 `id` |
| `{"id":1,"retries":null}` | 拒绝：`retries` 不可空 |
-可空性与默认值相互独立：没有默认值的可空参数仍要求 JSON 中存在对应成员。默认值仍是可执行的 Kotlin
表达式，在构造对象需要它时求值。初始化块和构造函数中的校验逻辑也会正常执行。
+参数可空，并不意味着这个字段可以省略。如果参数没有默认值，JSON 中仍必须提供该字段。需要使用默认值时，Fory 会在构造对象的过程中执行相应的
Kotlin 表达式。`init` 块和构造函数中的校验也会照常执行。
-这一差异同样影响序列化。如果 `label` 为 null，省略该成员会使读取方恢复出 `"new"`。因此，对于值为 null
的可空构造函数属性，Fory 会显式写出 null，使其在相同配置下往返转换后保留原值。
+序列化时也要区分 null 和字段缺失。例如，`label` 的值是 null，如果输出时省略了这个字段，再读取时就会得到默认值
`"new"`。因此，对于声明在构造函数中的可空属性，Fory 会把 null 值写入 JSON，确保在相同配置下序列化后再反序列化，得到的仍是原来的值。
-可空性检查会延伸到容器元素和嵌套泛型模型。关于次构造函数、显式创建器和类体中声明的属性，请参阅 [Kotlin
指南](/docs/json/kotlin#immutable-classes-and-compiler-defaults)。
+可空性检查也覆盖容器元素和嵌套泛型中的类型。如果需要使用次构造函数、通过 `JsonCreator` 指定构造函数或工厂方法，或处理类体中声明的属性，可参阅
[Kotlin 指南](/docs/json/kotlin#immutable-classes-and-compiler-defaults)。
## 值类与无符号类型 {#preserving-domain-types}
-值类可以在应用代码中区分不同的领域标识符，同时在 JSON 中保留标量表示。使用前面创建的运行时：
+用值类封装账户 ID，可以在 Kotlin 中把它与普通整数区分开来，而在 JSON 中仍然表示为一个数字。下面继续使用前面的 `json` 实例：
```kotlin
@JvmInline
@@ -101,15 +99,15 @@ val text = json.toJson(AccountId(42uL), idType) // 42
val restored = json.fromJson(text, idType)
```
-Fory 通过包含校验逻辑的构造操作重建 `AccountId`，因此 `require` 检查仍会执行。即使 JVM
将值类表示为基本类型，类型令牌也会保留其值类身份。
+反序列化 `AccountId` 时，Fory 会执行其构造和校验逻辑，包括 `require` 检查。即使 JVM 在底层用整数表示
`AccountId`，`jsonTypeRef<AccountId>()` 仍然保留了完整的值类类型信息。
-无符号整数保留其十进制表示，包括完整的 `ULong` 范围。如果 API 要求将 64 位整数表示为 JSON 字符串，可以通过
`ForyJsonKotlin.builder().writeLongAsString(true)` 创建运行时。该设置适用于 `Long` 和
`ULong`，也包括受支持的容器和值类；读取器同时接受带引号和不带引号的整数。
+无符号整数会按十进制数字写入 JSON，完整支持 `ULong` 的取值范围。如果 API 要求将 64 位整数写成 JSON 字符串，可以在创建实例时使用
`ForyJsonKotlin.builder().writeLongAsString(true)`。该设置适用于 `Long` 和
`ULong`，也适用于受支持的容器和值类中的这两种类型。反序列化时，整数带不带引号都可以读取。
-透明映射要求 null 的表示没有歧义。如果值类本身可空，且底层值也可空，两个不同状态就会对应同一个 JSON
null，因此这种情况需要使用带标签的自定义编解码器。其他 Kotlin
类型及其表示方式见[类型支持表](/docs/json/kotlin#supported-kotlin-types)。
+直接用底层值表示值类时，需要注意 null 的歧义。如果值类本身和它包装的值都允许为 null，就有两种不同情况：值类对象是
null，或者对象存在、内部的值是 null。两者都会变成 JSON null，因此需要用自定义编解码器添加标签，区分这两种状态。其他 Kotlin
类型如何映射到 JSON，见[类型支持表](/docs/json/kotlin#supported-kotlin-types)。
-## sealed 层次结构与注解 {#sealed-types-and-json-annotations}
+## 密封类型与注解 {#sealed-types-and-json-annotations}
-在 sealed 基类型上标注 `JsonSubTypes`，Fory 即可根据 Kotlin 元数据推导出具体子类型：
+在密封类或密封接口（`sealed`）上添加 `JsonSubTypes` 注解后，Fory 可以从 Kotlin 元数据中找出具体子类型：
```kotlin
import org.apache.fory.json.annotation.JsonSubTypes
@@ -126,9 +124,9 @@ val text = json.toJson(CardPayment("4242"), paymentType)
val decoded = json.fromJson(text, paymentType)
```
-声明类型 `Payment` 决定使用哪个子类型表。`kind` 成员包含子类型的逻辑名称，未知名称会被拒绝；输入不能指定任意 JVM
类。自动推导的名称取自源码类名。如果编码格式中的名称需要在源码重命名后保持稳定，应显式声明子类型表。相同的映射也适用于
`jsonTypeRef<List<Payment>>()`。
+Fory 根据声明的 `Payment` 类型确定可用的子类型，并用 `kind`
字段记录子类型名称。这里只接受映射中已有的名称，未知名称会被拒绝，JSON 输入无法任意指定 JVM 类。默认名称来自源码中的类名；如果希望重命名类后
JSON 中的名称不变，就需要显式配置子类型与名称的映射。列表中的 `Payment` 也适用这套规则，使用
`jsonTypeRef<List<Payment>>()` 即可。
-Kotlin 属性也可以使用 Fory 共用的 JSON 注解。显式指定注解目标，可以确定哪个 JVM 元素接收注解：
+Fory 的 JSON 注解同样适用于 Kotlin 属性。可以用 `@param:` 等注解目标明确指定注解作用的位置，例如下面的构造函数参数：
```kotlin
import org.apache.fory.json.annotation.JsonProperty
@@ -140,62 +138,62 @@ data class Profile(
)
```
-这里，`id` 映射为 `user_id`。命名、格式化、Mixin 和自定义编解码器均基于同一套注解体系；受支持的 Kotlin
注解目标见[注解指南](/docs/json/annotations#kotlin-use-site-targets)。
+这个注解把 Kotlin 中的 `id` 对应到 JSON 中的 `user_id`。属性命名、格式设置、Mixin 和自定义编解码器都沿用 Fory
的注解机制。支持哪些 Kotlin
注解目标，可参阅[注解指南](/docs/json/annotations#kotlin-use-site-targets)。
## Fory 如何高效映射 Kotlin 模型 {#how-fory-json-achieves-high-performance-in-kotlin}
-映射过程将 Kotlin 声明接入共用引擎：
+Fory 先从 Kotlin 类型中解析出构造函数和属性信息，再据此生成编解码器，调用底层 JSON 引擎完成读写：
```text
Kotlin 元数据 + 声明的根类型
- → 解析后的构造函数与属性模型
- → 生成的编解码器
- → 共用的 Fory JSON 运行时
+ → 构造函数和属性信息
+ → 按模型生成的编解码器
+ → Fory JSON 引擎
```
### 解析 Kotlin 元数据 {#preparing-kotlin-types-once}
-准备编解码器时，Kotlin 模块解析构造函数、属性访问器、泛型参数、可空性，以及具有编译器默认值的参数，将它们转换为 Fory
的对象模型。运行时在后续操作中复用该模型。
+准备编解码器时，Kotlin 模块会解析模型的构造函数、属性访问方式、泛型参数和可空性，并记录哪些参数有默认值。Fory
会将这些信息整理为内部对象模型，后续读写直接复用，无需重复解析。
-声明的根类型提供了类在某次具体使用中的类型信息。以 `Box<List<String?>>` 为例，类元数据描述 `Box<T>`，类型令牌则为 `T`
提供 `List<String?>`。两者结合后，映射器便能在对象内部执行正确的类型检查。
+只看类本身的元数据，还不足以确定泛型的实际类型。例如，`Box` 的元数据只能描述 `Box<T>`，而
`jsonTypeRef<Box<List<String?>>>()` 进一步指明了 `T` 是 `List<String?>`。结合这两部分信息，Fory
才能确定列表元素的类型，以及是否允许为 null。
-### 围绕构造函数生成代码 {#generating-code-for-the-declared-model}
+### 按模型生成读写代码 {#generating-code-for-the-declared-model}
-在标准 JDK 上，生成的读取器针对解析后的模型专门处理字段匹配与解码。对于 `Request`，读取器记录哪些参数已出现，拒绝缺少 `id`
的输入，并选择对应的构造函数调用。如果缺少 `label` 或 `retries`，默认参数掩码会告知 Kotlin
编译器生成的构造函数需要计算哪些表达式。显式传入 null 的 `label` 则不会触发默认值逻辑。
+在标准 JDK 上，Fory 会根据解析得到的模型生成 JSON 读取代码，直接完成字段匹配和解码。以 `Request` 为例，读取代码会记录 JSON
中提供了哪些参数，拒绝缺少 `id` 的输入，再选择相应的构造函数调用。缺少 `label` 或 `retries` 时，代码会通过默认参数掩码，告诉
Kotlin 编译器生成的构造函数需要计算哪些默认值。如果 `label` 明确传入了 null，就直接使用 null，不会触发默认值逻辑。
-生成的写入器同样使用已解析的访问器和字段类型，也遵守可空构造函数属性必须保留 null
的规则。复用这些编解码器可以省去反复解析模型的工作，同时在读取路径中保留正常的 Kotlin 构造和校验过程。无法在运行时编译的环境可以使用解释执行的映射路径。
+生成的写入代码使用已确定的属性访问方式和字段类型。对于构造函数中声明的可空属性，也会按前文的规则写出
null。模型解析完成后，编解码器可以反复使用；反序列化时，Kotlin 正常的构造和校验逻辑仍然会执行。不支持运行时编译的环境则通过解释执行完成映射。
-### 使用共用的 JSON 引擎 {#using-the-shared-json-engine}
+### 复用 Fory 的 JSON 引擎 {#using-the-shared-json-engine}
-这些编解码器使用 Fory 已有的数字编码器、文本处理逻辑、可复用缓冲区，以及直接 UTF-8 读取器和写入器。Kotlin 层提供类型和构造规则，引擎负责
JSON 输入与输出，无需构建中间 JSON 树。[Java JSON
文章](/blog/fory_json_fastest_java_json_framework)详细介绍了这些共用优化。
+这些编解码器沿用 Fory 已有的数字编码和文本处理实现，通过复用缓冲区减少临时分配，并支持直接读写 UTF-8 字节。Kotlin
模块负责类型规则和对象构造，JSON 引擎负责解析与输出，整个过程不需要先构建一棵 JSON 树。这些底层优化的具体实现，可参阅 [Java JSON
文章](/blog/fory_json_fastest_java_json_framework)。
## 性能 {#performance-on-kotlin-models}
-基准测试涵盖一条较小的结构化消息，以及两份约 1 MB 的文档，对比各库在 Kotlin 模型上的完整序列化与反序列化操作。
+基准测试分别使用一条较小的结构化消息和两份约 1 MB 的文档，对比各库将 Kotlin 对象转换为 JSON，以及从 JSON 还原对象的完整过程。
### 测试方法 {#benchmark-setup}
-两组基准测试均在 Apple M5 和 OpenJDK 25.0.3 上运行，对比 Fory JSON for Kotlin
1.7.1、kotlinx.serialization 1.11.0、使用生成式适配器的 Moshi 1.15.2，以及 Jackson Kotlin
2.22.1。
+两组基准测试都在 Apple M5 和 OpenJDK 25.0.3 上运行，参与对比的是 Fory JSON for Kotlin
1.7.1、kotlinx.serialization 1.11.0、Moshi 1.15.2（使用代码生成的适配器）和 Jackson Kotlin
2.22.1。
-同一负载下，各库处理相同的 Kotlin 模型和输入。正确性检查验证测试样本读取、往返转换和 JSON 输出等价性。String 操作不包含 UTF-8
转换。字节操作中，Fory 和 Jackson 使用直接字节数组 API，kotlinx.serialization 使用流 API，Moshi 使用
Okio 缓冲区；这些路径均不经过中间 String 转换。
+每个测试场景下，各库使用相同的 Kotlin 模型和输入数据。正确性测试会检查能否正确读取样本、序列化后能否还原原对象，以及各库输出的 JSON
是否等价。字符串测试不包含 UTF-8 编解码的开销。字节测试中，Fory 和 Jackson 使用字节数组
API，kotlinx.serialization 使用流 API，Moshi 使用 Okio 缓冲区；这些接口都直接处理字节，不会先把整份文档转成字符串。
-图中展示每秒操作数，数值越高越好，并标出 JMH
报告的误差。完整配置、输入哈希、原始测量数据和复现命令见[基准测试报告](https://github.com/chaokunyang/kotlin-json-benchmarks/blob/71399f45a9e6a55c07e127d240019ca9198446db/README.md)。
+图中的吞吐量以每秒操作数表示，越高越好；误差范围来自 JMH
报告。完整配置、输入数据的哈希值、原始测量结果和复现命令见[基准测试报告](https://github.com/chaokunyang/kotlin-json-benchmarks/blob/71399f45a9e6a55c07e127d240019ca9198446db/README.md)。
### MediaContent：结构化消息 {#mediacontent-structured-messages}
-Eishay MediaContent 测试样本包含一条媒体记录和图像，涉及字符串、数字、列表和枚举。其 Kotlin 模型包含必需构造函数参数、`val`
属性、可空成员和带编译器默认值的参数。各库的 null 与默认值输出配置保持一致。正确性测试覆盖成员缺失时使用默认值的行为；计时样本并未单独衡量这一行为。
+Eishay MediaContent 样本包含一条媒体记录及其图像信息，用到了字符串、数字、列表和枚举。对应的 Kotlin
模型包含必需的构造函数参数、`val` 属性、可空属性和带默认值的参数。各库使用一致的 null
和默认值输出设置。正确性测试也会检查字段缺失时是否使用默认值，但性能测试没有单独测量这一行为的开销。
-### 1 MB Users 和 Clients {#users-and-clients-larger-documents}
+### Users 和 Clients：约 1 MB 的大文档 {#users-and-clients-larger-documents}
-大文档测试将 `java-json-benchmark` 中的 Users 和 Clients Schema 移植为 Kotlin
数据类。确定性生成器持续追加完整记录，直到紧凑 UTF-8 输入至少达到 1,000,000 字节。每次操作处理一份完整文档。
+大文档测试沿用 `java-json-benchmark` 中 Users 和 Clients 的数据结构，并将它们改写为 Kotlin
数据类。生成器按固定规则逐条生成并追加完整记录，直到 JSON 文档以紧凑格式编码为 UTF-8 后达到至少 1,000,000
字节。每次序列化或反序列化都处理整份文档。
#### Users {#users}
-Users 包含文本字段、数值、标签和嵌套的朋友记录。文档包含 431 条记录，UTF-8 大小为 1,001,958 字节。
+Users 包含文本、数值、标签和嵌套的好友信息。测试文档共有 431 条记录，编码为 UTF-8 后占 1,001,958 字节。
@@ -203,9 +201,9 @@ Users 包含文本字段、数值、标签和嵌套的朋友记录。文档包
#### Clients {#clients}
-Clients 还包含 `UUID`、`BigDecimal`、`LocalDate` 和
`OffsetDateTime`，以及枚举、数组和嵌套的合作伙伴记录。文档包含 379 条记录，UTF-8 大小为 1,000,779 字节。
+Clients 还用到了 `UUID`、`BigDecimal`、`LocalDate` 和
`OffsetDateTime`，以及枚举、数组和嵌套的合作伙伴信息。测试文档共有 379 条记录，编码为 UTF-8 后占 1,000,779 字节。
-Fory 使用内置 JDK 编解码器。kotlinx.serialization 和 Moshi 使用显式适配器，将 UUID 和日期表示为字符串，将
`BigDecimal` 表示为不带引号的数字，并保留全部十进制精度。Jackson 注册 `JavaTimeModule`。检查会比较数组内容和完整的
`OffsetDateTime` 值，允许时间戳在小数秒末尾零的数量上存在差异，只要它们表示相同的值。
+Fory 使用内置的 JDK 类型编解码器。测试为 kotlinx.serialization 和 Moshi 配置了适配器，将 UUID
和日期写成字符串，将 `BigDecimal` 写成不带引号的数字，并保留完整的十进制精度。Jackson 则注册了
`JavaTimeModule`。正确性检查会比较数组中的元素和完整的 `OffsetDateTime`
值。时间戳中，秒的小数部分可以保留不同数量的末尾零，只要表示的值相同即可。
@@ -213,7 +211,7 @@ Fory 使用内置 JDK 编解码器。kotlinx.serialization 和 Moshi 使用显
### 结果解读 {#interpreting-the-results}
-在每种负载的四项操作中，Fory 均取得最高吞吐量。下表汇总了 String 和 UTF-8 序列化与反序列化操作中，Fory
相对于各库的吞吐量倍数范围，按未经四舍五入的原始分数计算：
+三个模型都分别测试了 String 和 UTF-8 的序列化与反序列化，Fory 在这些测试中的吞吐量都最高。下表列出每个模型四项测试中，Fory
相对于各库的吞吐量倍数范围，按未经四舍五入的原始结果计算：
| Kotlin 模型 | 相对 kotlinx.serialization | 相对 Moshi | 相对 Jackson Kotlin |
| --- | ---: | ---: | ---: |
@@ -221,16 +219,18 @@ Fory 使用内置 JDK 编解码器。kotlinx.serialization 和 Moshi 使用显
| Users | 3.50×–9.21× | 3.47×–5.53× | 2.78×–5.16× |
| Clients | 4.36×–9.45× | 4.83×–8.99× | 3.31×–9.75× |
-MediaContent 展示了映射一个通过构造函数创建的小模型并处理其 JSON 的综合开销。Users 和 Clients
则将比较扩展到更长的文档、嵌套集合和 JDK 值类型。这些结果衡量 Kotlin 映射层与 JSON 引擎共同运行时的性能，没有单独测量每项优化的贡献。
+MediaContent 反映了小对象的构造、类型映射和 JSON 处理的整体开销。Users 和 Clients 进一步考察大文档、嵌套集合及 JDK
类型的处理性能。这些结果衡量的是 Kotlin 映射层和 JSON 引擎的整体性能，没有单独测量各项优化带来的提升。
-这些测量对应一台机器上选定的模型和配置，未衡量值类、sealed 层次结构以及 Android、Native Image
上的性能。大文档数据集沿用上游的字段大小和数值范围，但使用自身的确定性生成序列，因此不能与独立运行的 Java 基准测试进行受控比较。
+以上结果来自同一台机器上的这些模型和配置，未测试值类、密封类型，也未测试 Android 或 Native Image
的性能。大文档数据沿用了上游的字段长度和数值范围，但具体记录由本测试按固定规则单独生成。因此，不能将这些结果与单独运行的 Java 基准测试直接比较。
## JVM、Android 与 GraalVM {#jvm-and-deployment-support}
-该模块面向 Kotlin/JVM，无需依赖 `kotlin-reflect`。运行时使用 Kotlin 2.3.20 构建，模型兼容性由 Kotlin
元数据读取器支持的版本决定。[安装指南](/docs/json/kotlin#installation)介绍了兼容性，[运行时指南](/docs/json/getting-started)则涵盖
JDK 25 及更高版本上建议开放的 `java.lang.invoke` 包。
+该模块可用于 Kotlin/JVM 项目，支持 Android 和 GraalVM Native Image，且不依赖
`kotlin-reflect`。兼容性说明见[安装指南](/docs/json/kotlin#installation)。使用 JDK 25
及更高版本时，建议按[运行时配置指南](/docs/json/getting-started)开放 `java.lang.invoke` 包的访问权限。
+
+在 Android API 26 及更高版本上，Fory 通过解释执行处理 JSON 映射。启用 R8 或 ProGuard 时，需要添加
`fory-json-kotlin-ksp`，并在需要序列化的源码模型上添加 `JsonType` 注解，以保留映射所需的信息。
-Android API 26 及更高版本使用解释执行的 JSON 映射。启用 R8 或 ProGuard 时，应添加
`fory-json-kotlin-ksp`，并为所需的源码模型标注 `JsonType`，以保留映射信息。GraalVM Native Image 通过
`ForyJsonProvider` 安装 Kotlin
模块，并选择可达模型进行代码生成。[平台指南](/docs/json/kotlin#graalvm-and-android)提供了这两种环境的配置方式。Kotlin/Native、Kotlin/JS
和 Kotlin/Wasm 不在此模块的支持范围内。
+在 GraalVM Native Image 中，通过 `ForyJsonProvider` 注册 Kotlin
模块，并为应用可访问到的模型配置代码生成。这两种环境的配置方法见[平台指南](/docs/json/kotlin#graalvm-and-android)。该模块不支持
Kotlin/Native、Kotlin/JS 和 Kotlin/Wasm。
-## 开始使用 {#learn-more}
+## 延伸阅读 {#learn-more}
-在应用中添加 `fory-json-kotlin`，选取一个 Kotlin 模型尝试往返转换。[Kotlin JSON
指南](/docs/json/kotlin)介绍了类型映射和配置；应用需要特定表示方式时，请参阅[自定义编解码器](/docs/json/custom-codecs)；输入限制见[安全指南](/docs/json/security)。源码和贡献说明位于
[apache/fory](https://github.com/apache/fory)。
+完整的类型映射与配置说明见 [Kotlin JSON 指南](/docs/json/kotlin)。需要自定义 JSON
表示时，可参考[自定义编解码器](/docs/json/custom-codecs)；输入限制的配置见[安全指南](/docs/json/security)。源码和贡献说明见
[apache/fory](https://github.com/apache/fory)。
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
