This is an automated email from the ASF dual-hosted git repository.
chaokunyang pushed a commit to branch fix-kotlin-blog-compatibility
in repository https://gitbox.apache.org/repos/asf/fory-site.git
The following commit(s) were added to refs/heads/fix-kotlin-blog-compatibility
by this push:
new bd00abb9bf4 Polish Chinese Kotlin JSON blog wording
bd00abb9bf4 is described below
commit bd00abb9bf43ff6114768e7350999767cf6c1954
Author: chaokunyang <[email protected]>
AuthorDate: Tue Sep 8 12:10:51 2026 +0800
Polish Chinese Kotlin JSON blog wording
---
.../2026-09-07-fory_kotlin_json.md | 98 +++++++++++-----------
1 file changed, 50 insertions(+), 48 deletions(-)
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 80e51232ac4..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,24 +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 序列化，支持数据类、值类和 sealed
层次结构，并保留构造函数默认值与可空性。在涵盖小消息和大文档的基准测试中，Fory 的吞吐量为 kotlinx.serialization、Moshi 和
Jackson Kotlin 的 **2.78–12.12 倍**。
+**摘要**：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%"/>
## Kotlin 应用中的 JSON 序列化 {#kotlin-models-as-json-contracts}
-Kotlin 应用通过 HTTP API、消息队列和存储的文档交换 JSON，而应用代码使用具有明确类型的模型，因此每次交换都涉及 JSON 与
Kotlin 对象之间的转换。读取文档时，需要用正确的参数构造对象，并执行初始化逻辑；写入时，则需要保留还原对象所需的值。
+Kotlin 应用经常需要接收 HTTP 请求、消费队列消息，或读取 JSON 文档。这些数据进入应用后，要转换成 Kotlin
对象；返回响应或写入存储时，又要转回 JSON。转换时需要遵循模型的类型和构造规则：正确传入参数、执行初始化逻辑，并在输出中保留还原对象所需的值。
-这些转换也会消耗 CPU 并产生临时内存分配，在处理大量消息或大文档的服务中尤其值得关注。Apache Fory JSON 将 Kotlin
对象映射与高性能 JSON 引擎结合起来：Kotlin 层遵循模型的类型和构造规则，引擎负责 JSON 解析与输出。String 和直接 UTF-8 API
均使用这套映射。
+对于需要处理大量消息或大文档的服务，序列化的 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 {
@@ -26,7 +26,7 @@ dependencies {
}
```
-创建运行时和模型的类型令牌。运行时是线程安全的；应保留这两个对象以便重复使用：
+接着创建 `json` 实例，并用 `jsonTypeRef<Account>()` 指定模型类型。`json` 是线程安全的，建议复用 `json` 和
`accountType`，避免每次读写都重新创建：
```kotlin
import org.apache.fory.json.kotlin.ForyJsonKotlin
@@ -51,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}
@@ -67,7 +67,7 @@ data class Request(
)
```
-Fory 自动选择主构造函数。成员缺失且存在默认值时，会使用编译器提供的默认值逻辑；对于显式 JSON null，则根据参数的可空性进行检查：
+Fory 会自动使用主构造函数创建 `Request`。JSON 中缺少某个字段时，如果对应参数有默认值，就使用该默认值；如果字段明确写为
null，则检查参数是否允许为 null：
| JSON 输入 | 结果 |
| --- | --- |
@@ -76,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
@@ -99,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
@@ -124,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
@@ -138,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 字节。
@@ -201,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`
值。时间戳中，秒的小数部分可以保留不同数量的末尾零，只要表示的值相同即可。
@@ -211,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 |
| --- | ---: | ---: | ---: |
@@ -219,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`。[安装指南](/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 及更高版本使用解释执行的 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 不在此模块的支持范围内。
+在 Android API 26 及更高版本上，Fory 通过解释执行处理 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。
## 延伸阅读 {#learn-more}
-[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]
