You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@fory.apache.org by ch...@apache.org on 2026/08/11 12:30:37 UTC

(fory-site) branch fory_json_blog updated (e0a02a71ee -> ea44120659)

This is an automated email from the ASF dual-hosted git repository.

chaokunyang pushed a change to branch fory_json_blog
in repository https://gitbox.apache.org/repos/asf/fory-site.git


    from e0a02a71ee docs: refine Fory JSON annotation sections
     new 9f03f43413 docs: clarify benchmark throughput wording
     new 4d2d7531e8 docs: add Chinese Fory JSON blog translation
     new 5ded0dff57 docs: simplify Fory JSON introduction
     new f2bddfd135 docs: polish Fory JSON blog narrative
     new ea44120659 docs: link Fory JSON custom codecs guide

The 5 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.


Summary of changes:
 .../translate-docs-zh/references/terminology.md    |   2 +
 ...08-11-fory_json_fastest_java_json_framework.md} |  58 ++--
 ...-08-11-fory_json_fastest_java_json_framework.md | 291 +++++++++++++++++++++
 .../img/blog/fory-json}/clients-throughput.png     | Bin
 .../img/blog/fory-json}/users-throughput.png       | Bin
 5 files changed, 321 insertions(+), 30 deletions(-)
 rename blog/{2026-08-11-fory-json/index.md => 2026-08-11-fory_json_fastest_java_json_framework.md} (68%)
 create mode 100644 i18n/zh-CN/docusaurus-plugin-content-blog/2026-08-11-fory_json_fastest_java_json_framework.md
 rename {blog/2026-08-11-fory-json => static/img/blog/fory-json}/clients-throughput.png (100%)
 rename {blog/2026-08-11-fory-json => static/img/blog/fory-json}/users-throughput.png (100%)


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@fory.apache.org
For additional commands, e-mail: commits-help@fory.apache.org


(fory-site) 03/05: docs: simplify Fory JSON introduction

Posted by ch...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

chaokunyang pushed a commit to branch fory_json_blog
in repository https://gitbox.apache.org/repos/asf/fory-site.git

commit 5ded0dff57f6d576bf0c2a22842723b60bf0e0bf
Author: chaokunyang <sh...@gmail.com>
AuthorDate: Tue Aug 11 20:21:52 2026 +0800

    docs: simplify Fory JSON introduction
---
 blog/2026-08-11-fory_json_fastest_java_json_framework.md                | 2 --
 .../2026-08-11-fory_json_fastest_java_json_framework.md                 | 2 --
 2 files changed, 4 deletions(-)

diff --git a/blog/2026-08-11-fory_json_fastest_java_json_framework.md b/blog/2026-08-11-fory_json_fastest_java_json_framework.md
index c392c53db4..c06a1f62f2 100644
--- a/blog/2026-08-11-fory_json_fastest_java_json_framework.md
+++ b/blog/2026-08-11-fory_json_fastest_java_json_framework.md
@@ -21,8 +21,6 @@ JSON is rarely the most interesting part of a Java service. It is simply everywh
 
 Fory already provides compact binary object serialization and a cross-language protocol. Fory JSON tackles a different job. It maps Java objects to ordinary JSON text and UTF-8 bytes, so the result remains readable by browsers, command-line tools, and any standards-compliant JSON implementation.
 
-There is no Fory-specific envelope and no binary metadata hidden in the document. This is standard JSON, built for Java applications that need to keep the wire format while spending less time converting it.
-
 ## Quick Start
 
 Fory JSON 1.6.0 is available from Maven Central:
diff --git a/i18n/zh-CN/docusaurus-plugin-content-blog/2026-08-11-fory_json_fastest_java_json_framework.md b/i18n/zh-CN/docusaurus-plugin-content-blog/2026-08-11-fory_json_fastest_java_json_framework.md
index dd5beaa118..8edc9094c0 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-blog/2026-08-11-fory_json_fastest_java_json_framework.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-blog/2026-08-11-fory_json_fastest_java_json_framework.md
@@ -21,8 +21,6 @@ JSON 很少是 Java 服务中最引人关注的部分,但它无处不在:HTT
 
 Fory 已经提供紧凑的二进制对象序列化和跨语言协议,Fory JSON 则解决另一类问题。它将 Java 对象映射为普通 JSON 文本或 UTF-8 字节,因此浏览器、命令行工具和任何符合标准的 JSON 实现都能读取结果。
 
-生成的 JSON 文档中没有 Fory 专属封装,也不隐藏任何二进制元数据。这就是标准 JSON,面向需要保留既有编码格式、同时减少转换开销的 Java 应用。
-
 ## 快速开始
 
 Fory JSON 1.6.0 已发布到 Maven Central:


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@fory.apache.org
For additional commands, e-mail: commits-help@fory.apache.org


(fory-site) 05/05: docs: link Fory JSON custom codecs guide

Posted by ch...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

chaokunyang pushed a commit to branch fory_json_blog
in repository https://gitbox.apache.org/repos/asf/fory-site.git

commit ea44120659a7e3309d975eb925afaa433e61e99a
Author: chaokunyang <sh...@gmail.com>
AuthorDate: Tue Aug 11 20:29:43 2026 +0800

    docs: link Fory JSON custom codecs guide
---
 blog/2026-08-11-fory_json_fastest_java_json_framework.md                | 2 +-
 .../2026-08-11-fory_json_fastest_java_json_framework.md                 | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/blog/2026-08-11-fory_json_fastest_java_json_framework.md b/blog/2026-08-11-fory_json_fastest_java_json_framework.md
index 1e9df85206..88adbd2ce4 100644
--- a/blog/2026-08-11-fory_json_fastest_java_json_framework.md
+++ b/blog/2026-08-11-fory_json_fastest_java_json_framework.md
@@ -210,7 +210,7 @@ ForyJson json =
         .build();
 ```
 
-When annotations are not enough, `JsonValueCodec<T>` handles one complete JSON value and streams it through Fory's reader and writer. Child codec selections can customize collection elements, optional contents, and map keys or values without replacing the surrounding container mapping.
+When built-in mapping and annotations are not enough, `JsonValueCodec<T>` can handle one complete JSON value and stream it through Fory's reader and writer. Child codec selections can customize collection elements, optional contents, and map keys or values without replacing the surrounding container mapping. See the [custom codecs guide](/docs/json/custom-codecs) for details.
 
 ## Closed-world polymorphism with `JsonSubTypes`
 
diff --git a/i18n/zh-CN/docusaurus-plugin-content-blog/2026-08-11-fory_json_fastest_java_json_framework.md b/i18n/zh-CN/docusaurus-plugin-content-blog/2026-08-11-fory_json_fastest_java_json_framework.md
index 760ac9131f..6c6a95bd8d 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-blog/2026-08-11-fory_json_fastest_java_json_framework.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-blog/2026-08-11-fory_json_fastest_java_json_framework.md
@@ -210,7 +210,7 @@ ForyJson json =
         .build();
 ```
 
-当注解仍不足以满足需求时,`JsonValueCodec<T>` 可以处理一个完整 JSON 值,并通过 Fory 的读取器和写入器进行流式处理。子 Codec 配置还可以定制集合元素、Optional 内容以及 Map 的键或值,而无需替换外围容器的映射逻辑。
+当内置映射和注解仍不足以满足需求时,`JsonValueCodec<T>` 可以处理一个完整 JSON 值,并通过 Fory 的读取器和写入器进行流式处理。子 Codec 配置还可以定制集合元素、Optional 内容以及 Map 的键或值,而无需替换外围容器的映射逻辑。详情请参阅 [自定义 Codec 指南](/docs/json/custom-codecs)。
 
 ## 使用 `JsonSubTypes` 实现封闭多态
 


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@fory.apache.org
For additional commands, e-mail: commits-help@fory.apache.org


(fory-site) 04/05: docs: polish Fory JSON blog narrative

Posted by ch...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

chaokunyang pushed a commit to branch fory_json_blog
in repository https://gitbox.apache.org/repos/asf/fory-site.git

commit f2bddfd135c8686d6b5338c501d4b78f7d046a9f
Author: chaokunyang <sh...@gmail.com>
AuthorDate: Tue Aug 11 20:28:20 2026 +0800

    docs: polish Fory JSON blog narrative
---
 ...-08-11-fory_json_fastest_java_json_framework.md | 48 +++++++++++-----------
 ...-08-11-fory_json_fastest_java_json_framework.md | 48 +++++++++++-----------
 2 files changed, 48 insertions(+), 48 deletions(-)

diff --git a/blog/2026-08-11-fory_json_fastest_java_json_framework.md b/blog/2026-08-11-fory_json_fastest_java_json_framework.md
index c06a1f62f2..1e9df85206 100644
--- a/blog/2026-08-11-fory_json_fastest_java_json_framework.md
+++ b/blog/2026-08-11-fory_json_fastest_java_json_framework.md
@@ -5,7 +5,7 @@ authors: [chaokunyang]
 tags: [fory, java, json, serialization, performance]
 ---
 
-**TL;DR**: Apache Fory JSON is a high-performance serialization framework that maps Java objects to and from standard JSON text and UTF-8 bytes. It supports ordinary Java models and runs on JDK 8+, Android, and GraalVM Native Image. In the published benchmark configurations below, Fory JSON is the fastest Java JSON serialization framework: up to **10.91× the throughput of Jackson and 10.89× the throughput of Gson** with 1000 KB payloads, and up to **5.55× the throughput of Jackson and 10 [...]
+**TL;DR**: Apache Fory JSON is a high-performance serialization framework that maps Java objects to and from standard JSON text and UTF-8 bytes. It supports common Java models and runs on JDK 8+, Android, and GraalVM Native Image. In the published benchmark configurations below, Fory JSON is the fastest Java JSON serialization framework: up to **10.91× the throughput of Jackson and 10.89× the throughput of Gson** with 1000 KB payloads, and up to **5.55× the throughput of Jackson and 10.0 [...]
 
 - GitHub: [apache/fory](https://github.com/apache/fory)
 - Documentation: [Fory JSON](/docs/json/)
@@ -17,9 +17,9 @@ tags: [fory, java, json, serialization, performance]
 
 ## Why JSON Performance Matters
 
-JSON is rarely the most interesting part of a Java service. It is simply everywhere: HTTP APIs, browser traffic, event envelopes, logs, configuration, and integrations with systems that do not share a binary protocol. That makes JSON processing a recurring CPU and allocation cost, often paid on every request.
+JSON sits on many Java service hot paths: HTTP APIs, browser traffic, event payloads, logs, configuration, and integrations with systems that do not share a binary protocol. Parsing and serialization costs recur across requests, consuming CPU and creating temporary objects.
 
-Fory already provides compact binary object serialization and a cross-language protocol. Fory JSON tackles a different job. It maps Java objects to ordinary JSON text and UTF-8 bytes, so the result remains readable by browsers, command-line tools, and any standards-compliant JSON implementation.
+Fory already provides compact binary object serialization and a cross-language protocol. Fory JSON serves a different use case by mapping Java objects to standard JSON text and UTF-8 bytes. The output remains readable by browsers, command-line tools, and any standards-compliant JSON implementation.
 
 ## Quick Start
 
@@ -69,11 +69,11 @@ public final class JsonExample {
 }
 ```
 
-String and byte-array APIs are both first-class. For generic roots, a `TypeRef<List<User>>` keeps the element type available on reads and declared writes. Fory JSON can also write a complete UTF-8 document to an `OutputStream` without taking ownership of the stream.
+Fory JSON directly supports both String and byte-array APIs. For generic roots, a `TypeRef<List<User>>` preserves the element type during deserialization and declared-type serialization. Fory JSON can also write a complete UTF-8 document to an `OutputStream` without taking ownership of the stream.
 
 ## How Fory JSON Achieves High Performance
 
-Four implementation choices do most of the work.
+Fory JSON's performance comes primarily from four implementation choices.
 
 **Minimal temporary allocation.** A `ForyJson` instance reuses prepared type metadata, execution state, and retained writer buffers. For most basic scalar values, the hot serialization path is effectively zero-allocation beyond the requested output: Fory writes the value directly into its output buffer instead of first converting it into a Java `String`. Returning a `String` or `byte[]` still creates that result, and buffer growth or a cold fallback can allocate.
 
@@ -83,17 +83,17 @@ Four implementation choices do most of the work.
 
 **Runtime code generation.** Fory JSON prepares a codec for each Java type it encounters. On a standard JDK, code generation and asynchronous compilation are enabled by default. Generated codecs specialize field access, property names, framing, and primitive operations for the target class instead of rediscovering the same property model on every call. An interpreted path remains available for restricted environments and diagnostics.
 
-The public API preserves those fast paths. A service that already needs network bytes can call `toJsonBytes` and `fromJson(byte[], type)` directly, while text-oriented code can stay on the String path. Custom codecs also stream through Fory's reader and writer instead of building an intermediate JSON tree.
+The public API preserves those fast paths. Applications that need UTF-8 output can call `toJsonBytes` and `fromJson(byte[], type)` directly, while text-oriented code can use the String APIs. Custom codecs also stream through Fory's reader and writer instead of building an intermediate JSON tree.
 
 ## Performance Benchmarks
 
-Any useful performance claim needs a workload. We use two views here: the three-thread `java-json-benchmark` run with one 1000 KB object per invocation, followed by the single-thread `jvm-serializers` MediaContent benchmark. Both report throughput in operations per second, so higher is better.
+The results below cover two workloads: a large-payload `java-json-benchmark` run and the smaller `jvm-serializers` MediaContent benchmark. Both report throughput in operations per second, so higher is better. Each subsection describes its configuration.
 
 The tables compare Fory JSON only with Jackson and Gson. For the wider large-payload matrix, exact payload setup, and the benchmark integration, see [java-json-benchmark](https://github.com/fabienrenaud/java-json-benchmark/pull/129).
 
 ### `java-json-benchmark`: 1000 KB payloads
 
-The 1000 KB suite asks what happens when each invocation has substantial parsing, traversal, and output work.
+The 1000 KB suite measures workloads in which each invocation performs substantial parsing, object traversal, and output work.
 
 The 1000 KB run used Fory JSON 1.6.0, Jackson Databind 2.17.1, and Gson 2.11.0 with the databind API. JMH ran two forks and three threads. Each fork used five 3-second warmup iterations and five 3-second measurement iterations. The Users and Clients payloads each contained one 1000 KB object per invocation.
 
@@ -108,11 +108,11 @@ The 1000 KB run used Fory JSON 1.6.0, Jackson Databind 2.17.1, and Gson 2.11.0 w
 | Clients | Serialization   | 11,895.269 ± 183.251  | 1,706.314 ± 36.263    | 1,298.288 ± 27.405    |       6.97× |    9.16× |
 | Clients | Deserialization | 6,442.262 ± 627.116   | 590.656 ± 10.849      | 591.350 ± 6.444       |      10.91× |   10.89× |
 
-Across these four large-payload cases, Fory JSON delivers 3.54× to 10.91× Jackson throughput and 5.65× to 10.89× Gson throughput.
+Across these four large-payload cases, Fory JSON delivers 3.54× to 10.91× the throughput of Jackson and 5.65× to 10.89× that of Gson.
 
 ### `jvm-serializers` MediaContent benchmark
 
-The second view uses the [`jvm-serializers` MediaContent model](https://github.com/eishay/jvm-serializers/blob/master/tpc/src/data/media/MediaContent.java), which contains a media object and a list of images. This benchmark covers much smaller objects than the 1000 KB suite and separates Java String APIs from UTF-8 byte-array APIs.
+The second benchmark uses the [`jvm-serializers` MediaContent model](https://github.com/eishay/jvm-serializers/blob/master/tpc/src/data/media/MediaContent.java), which contains a media object and a list of images. This benchmark covers much smaller objects than the 1000 KB suite and separates Java String APIs from UTF-8 byte-array APIs.
 
 The `jvm-serializers` benchmark ran on an Apple M4 Pro with JDK 26.0.1. It used one JMH fork and one thread, with three 2-second warmup iterations followed by five 2-second measurement iterations.
 
@@ -127,7 +127,7 @@ The `jvm-serializers` benchmark ran on an Apple M4 Pro with JDK 26.0.1. It used
 | UTF-8 bytes    | Serialize   |      10,375,498 |     1,868,614 |  1,037,211 |       5.55× |   10.00× |
 | UTF-8 bytes    | Deserialize |       3,077,158 |     1,268,397 |    933,079 |       2.43× |    3.30× |
 
-Fory JSON leads all four rows. Its largest advantage appears on UTF-8 serialization, where it passes 10 million operations per second and reaches 5.55× Jackson throughput and 10.00× Gson throughput.
+Fory JSON records the highest throughput in all four operations. Its largest advantage appears on UTF-8 serialization, where it exceeds 10 million operations per second and reaches 5.55× the throughput of Jackson and 10.00× that of Gson.
 
 The String and UTF-8 groups are deliberately separate. The String group excludes UTF-8 conversion. The byte group uses direct byte-array APIs where a library provides them; Gson includes its required String-to-byte and byte-to-String conversion.
 
@@ -135,23 +135,23 @@ Results vary by workload, but Fory JSON is the fastest framework in both benchma
 
 ## Java Object Mapping
 
-Performance would be much less useful if it required flattening every application model into hand-written transfer objects. Fory JSON maps the Java shapes developers already use:
+Fory JSON maps existing Java application models directly, without requiring hand-written transfer objects:
 
 - ordinary mutable classes and inherited fields;
 - Java records and immutable classes built through `JsonCreator`;
 - generic collections and maps through `TypeRef`;
 - Java time, optionals, atomics, UUIDs, paths, big numbers, enums, and common collection types;
-- natural `JsonObject` and `JsonArray` trees when the target type is dynamic.
+- `JsonObject` and `JsonArray` tree models for dynamic targets.
 
 Property discovery can combine fields with JavaBean getters and setters, or switch to field-only mode. A finite `JsonSubTypes` table handles declared polymorphic models without accepting arbitrary class names from input.
 
 ## Annotation-Based Object Mapping
 
-Fory JSON provides its own annotations in `org.apache.fory.json.annotation`. They cover explicit property names and ordering, ignored directions, immutable construction, date and time formats, Base64 byte arrays, raw or complete value representations, flattened objects, dynamic members, validation, and finite subtype tables.
+Fory JSON provides its own annotations in `org.apache.fory.json.annotation`. The annotation model will feel familiar to Jackson users, covering property names and ordering, creators, formatting, polymorphism, and validation. These are independent Fory JSON APIs, not Jackson-compatible annotations.
 
-The annotation model will feel familiar to Jackson users, covering property names and ordering, creators, formatting, polymorphism, and validation. These are independent Fory JSON APIs, not Jackson-compatible annotations. See the [Fory JSON annotations guide](/docs/json/annotations) for the complete reference.
+Additional annotations support ignoring properties only during serialization or deserialization, Base64 byte arrays, raw or complete value representations, flattened objects, and dynamic members. See the [Fory JSON annotations guide](/docs/json/annotations) for the complete reference.
 
-The annotations compose on an ordinary model. This event renames a fixed property, formats a date, flattens an owner, captures dynamic members, and validates the completed object after reading:
+The following model combines several annotations: it renames a fixed property, formats a date, flattens an owner, captures dynamic members, and validates the completed object after reading:
 
 ```java
 import java.time.LocalDate;
@@ -210,7 +210,7 @@ ForyJson json =
         .build();
 ```
 
-When annotations are not enough, `JsonValueCodec<T>` owns one complete JSON value and streams it through Fory's reader and writer. Child codec selections can customize collection elements, optional contents, and map keys or values without replacing the surrounding container mapping.
+When annotations are not enough, `JsonValueCodec<T>` handles one complete JSON value and streams it through Fory's reader and writer. Child codec selections can customize collection elements, optional contents, and map keys or values without replacing the surrounding container mapping.
 
 ## Closed-world polymorphism with `JsonSubTypes`
 
@@ -252,7 +252,7 @@ public final class PaymentExample {
 }
 ```
 
-The declared-type write tells Fory JSON to use `Payment`'s subtype table. During reading, `kind` must match `card` or `bank_transfer`; an unknown name is rejected. For containers, a `TypeRef<List<Payment>>` carries the same declared base type for every element. The [annotations guide](/docs/json/annotations) covers the alternative wrapper representations and complete validation rules.
+Serializing with the declared `Payment` type activates its subtype table. During reading, `kind` must match `card` or `bank_transfer`; an unknown name is rejected. For containers, a `TypeRef<List<Payment>>` carries the same declared base type for every element. The [annotations guide](/docs/json/annotations) covers the alternative wrapper representations and complete validation rules.
 
 ## JDK, Android, and GraalVM Native Image Support
 
@@ -260,9 +260,9 @@ The same `fory-json` artifact supports Java 8 and later. Java records require Ja
 
 On Android API level 26+, Fory JSON automatically uses interpreted object mapping because runtime compilation is unavailable. The Fory annotation processor can generate direct model access and exact R8 rules for `JsonType` classes and Mixins.
 
-GraalVM Native Image has its own build-time integration. Mark reachable models with `JsonType` for prepared access metadata. If a particular completed `ForyJson` configuration should use generated codecs in the native executable, expose it from a reachable `ForyJsonProvider`; other prepared configurations continue to work with interpreted codecs.
+GraalVM Native Image has its own build-time integration. Mark reachable models with `JsonType` so the build can prepare their access metadata. To use generated codecs for a specific `ForyJson` configuration in the native executable, expose that completed configuration from a reachable `ForyJsonProvider`. Other prepared configurations continue to use interpreted codecs.
 
-This gives applications one mapping model across a normal JVM, Android, and native executables without pretending those runtimes have the same code-generation capabilities.
+Applications can therefore use the same mapping model across the JVM, Android, and native executables, with execution adapted to each runtime's code-generation capabilities.
 
 ## Security controls for untrusted JSON
 
@@ -274,13 +274,13 @@ Those controls do not replace HTTP body limits, authentication, authorization, t
 
 ## Choosing Between Fory JSON and Binary Serialization
 
-Choose Fory JSON when the wire must remain ordinary JSON: public APIs, browser clients, configuration, logs, or an integration that already speaks JSON. You get the interoperability of the format with a Java implementation designed around generated codecs and reusable state.
+Choose Fory JSON when an application must exchange standard JSON: public APIs, browser clients, configuration, logs, or existing JSON integrations. This preserves format interoperability while using a Java implementation designed around generated codecs and reusable state.
 
-Choose Fory's binary object serialization when both sides can use a binary protocol and the application needs features JSON does not carry, such as cross-language schema metadata, shared-reference identity, or circular object graphs. The two formats solve different problems and can live in the same service.
+Choose Fory's binary object serialization when both sides can use a binary protocol and the application needs features JSON does not carry, such as cross-language schema metadata, shared-reference identity, or circular object graphs. The two formats solve different problems and can coexist within the same service.
 
 ## Learn More
 
-The fastest route to a useful evaluation is to replace one representative Jackson or Gson round trip, reuse a single `ForyJson` instance, and benchmark the application's real model and JDK settings. The published numbers show the available headroom; the application workload tells you how much of it matters.
+To evaluate Fory JSON, replace one representative Jackson or Gson round trip, reuse a single `ForyJson` instance, and benchmark the application's actual model and JDK settings. The published numbers show the available headroom; the application workload determines how much of it applies.
 
 - Read the [Fory JSON overview](/docs/json/).
 - Run the [Getting Started example](/docs/json/getting-started).
@@ -288,4 +288,4 @@ The fastest route to a useful evaluation is to replace one representative Jackso
 - Review the [1000 KB benchmark and broader matrix](https://github.com/fabienrenaud/java-json-benchmark/pull/129).
 - Join development at [apache/fory](https://github.com/apache/fory).
 
-Fory JSON keeps the format everyone already understands. The difference is how little time your Java service has to spend on it.
+Fory JSON preserves standard JSON interoperability while providing a high-performance implementation for Java services.
diff --git a/i18n/zh-CN/docusaurus-plugin-content-blog/2026-08-11-fory_json_fastest_java_json_framework.md b/i18n/zh-CN/docusaurus-plugin-content-blog/2026-08-11-fory_json_fastest_java_json_framework.md
index 8edc9094c0..760ac9131f 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-blog/2026-08-11-fory_json_fastest_java_json_framework.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-blog/2026-08-11-fory_json_fastest_java_json_framework.md
@@ -17,9 +17,9 @@ tags: [fory, java, json, serialization, performance]
 
 ## JSON 性能为何重要
 
-JSON 很少是 Java 服务中最引人关注的部分,但它无处不在:HTTP API、浏览器流量、事件封装、日志、配置,以及与不共享二进制协议的系统进行集成。因此,JSON 处理会持续消耗 CPU 并产生对象分配,而这项成本往往每个请求都要承担。
+JSON 位于许多 Java 服务的关键路径上:HTTP API、浏览器流量、事件载荷、日志、配置,以及与不共享二进制协议的系统集成。解析和序列化成本会随请求反复发生,消耗 CPU 并产生临时对象。
 
-Fory 已经提供紧凑的二进制对象序列化和跨语言协议,Fory JSON 则解决另一类问题。它将 Java 对象映射为普通 JSON 文本或 UTF-8 字节,因此浏览器、命令行工具和任何符合标准的 JSON 实现都能读取结果。
+Fory 已经提供紧凑的二进制对象序列化和跨语言协议,Fory JSON 则面向另一类使用场景,将 Java 对象映射为标准 JSON 文本或 UTF-8 字节。浏览器、命令行工具和任何符合标准的 JSON 实现都能读取输出结果。
 
 ## 快速开始
 
@@ -69,31 +69,31 @@ public final class JsonExample {
 }
 ```
 
-String 和字节数组均有原生 API 支持。对于泛型根类型,`TypeRef<List<User>>` 可在反序列化和按声明类型序列化时保留元素类型。Fory JSON 还可以将完整的 UTF-8 文档写入 `OutputStream`,且不会接管该流的所有权。
+Fory JSON 原生支持 String 和字节数组 API。对于泛型根类型,`TypeRef<List<User>>` 可在反序列化和按声明类型序列化时保留元素类型。Fory JSON 还可以将完整的 UTF-8 文档写入 `OutputStream`,且不会接管该流的所有权。
 
 ## Fory JSON 如何实现高性能
 
-高性能主要来自四项实现选择。
+Fory JSON 的高性能主要来自四项关键实现。
 
 **尽量减少临时对象分配。** `ForyJson` 实例会复用已经准备好的类型元数据、执行状态和保留的写入缓冲区。对于大多数基本标量值,除调用方要求的输出外,序列化热路径基本可以做到零分配:Fory 将值直接写入输出缓冲区,而不是先转换为 Java `String`。返回 `String` 或 `byte[]` 仍会创建结果对象,缓冲区扩容或冷路径回退也可能产生分配。
 
-**高度优化的基本类型写入。** 整数和长整数使用直接数字编码器;JDK 提供相应能力时,浮点数也通过直接格式化路径写入。布尔值、数值和带引号的字符串会直接进入当前的 String 或 UTF-8 写入器。热路径不需要为每个值执行一次 `String.valueOf(...)` 往返转换。
+**高度优化的基本类型写入。** 整数和长整数使用直接数字编码器;JDK 提供相应能力时,浮点数也通过直接格式化路径写入。布尔值、数值和带引号的字符串会直接进入当前使用的 String 或 UTF-8 写入器。热路径不需要为每个值执行一次 `String.valueOf(...)` 往返转换。
 
 **批量内存操作。** 常见的 Latin-1 和 ASCII 文本会以 8 字节或 16 字节为一组进行扫描和复制。生成的写入器还可以使用预打包的属性前缀和对象边界标记,从而减少逐字符分支和重复写入。
 
 **运行时代码生成。** Fory JSON 会为遇到的每种 Java 类型准备一个编解码器。在标准 JDK 上,代码生成和异步编译默认启用。生成的编解码器会针对目标类专门处理字段访问、属性名、对象边界和基本类型操作,而不必在每次调用时重新发现同一套属性模型。对于受限环境和诊断场景,仍可使用解释执行路径。
 
-公共 API 同样保留这些快速路径。需要直接生成网络字节的服务可以调用 `toJsonBytes` 和 `fromJson(byte[], type)`;面向文本的代码则可以继续使用 String 路径。自定义编解码器也直接通过 Fory 的读取器和写入器进行流式处理,无需构建中间 JSON 树。
+公共 API 同样保留这些快速路径。需要 UTF-8 输出的应用可以直接调用 `toJsonBytes` 和 `fromJson(byte[], type)`;面向文本的代码可以使用 String API。自定义编解码器也直接通过 Fory 的读取器和写入器进行流式处理,无需构建中间 JSON 树。
 
 ## 性能基准测试
 
-有意义的性能结论必须基于具体负载。这里展示两组结果:首先是三线程 `java-json-benchmark`,每次调用处理一个 1000 KB 对象;随后是单线程 `jvm-serializers` MediaContent 基准测试。两者都以每秒操作数报告吞吐量,因此数值越高越好。
+下面的结果覆盖两类负载:大载荷 `java-json-benchmark` 和对象较小的 `jvm-serializers` MediaContent 基准测试。两者都以每秒操作数报告吞吐量,因此数值越高越好。每个小节分别说明其测试配置。
 
 表格仅比较 Fory JSON、Jackson 和 Gson。更广泛的大载荷对比、完整的载荷设置以及基准测试集成方式,请参阅 [java-json-benchmark](https://github.com/fabienrenaud/java-json-benchmark/pull/129)。
 
 ### `java-json-benchmark`:1000 KB 载荷
 
-1000 KB 测试用于观察每次调用都需要完成大量解析、遍历和输出工作时的表现。
+1000 KB 测试衡量每次调用都需要完成大量解析、对象遍历和输出工作时的性能。
 
 该测试使用 Fory JSON 1.6.0、Jackson Databind 2.17.1 和 Gson 2.11.0,三者均采用数据绑定 API。JMH 运行两个 fork 和三个线程;每个 fork 包含五轮 3 秒预热迭代和五轮 3 秒测量迭代。Users 与 Clients 载荷每次调用都包含一个 1000 KB 对象。
 
@@ -112,7 +112,7 @@ String 和字节数组均有原生 API 支持。对于泛型根类型,`TypeRef
 
 ### `jvm-serializers` MediaContent 基准测试
 
-第二组结果使用 [`jvm-serializers` MediaContent 模型](https://github.com/eishay/jvm-serializers/blob/master/tpc/src/data/media/MediaContent.java)。该模型包含一个媒体对象和一个图像列表。与 1000 KB 测试相比,这项基准处理的对象要小得多,并分别测试 Java String API 与 UTF-8 字节数组 API。
+第二项基准测试使用 [`jvm-serializers` MediaContent 模型](https://github.com/eishay/jvm-serializers/blob/master/tpc/src/data/media/MediaContent.java)。该模型包含一个媒体对象和一个图像列表。与 1000 KB 测试相比,这项基准处理的对象要小得多,并分别测试 Java String API 与 UTF-8 字节数组 API。
 
 `jvm-serializers` 基准测试运行于搭载 JDK 26.0.1 的 Apple M4 Pro,使用一个 JMH fork 和一个线程,先执行三轮 2 秒预热迭代,再执行五轮 2 秒测量迭代。
 
@@ -135,23 +135,23 @@ String 与 UTF-8 两组测试有意分开。String 组不包含 UTF-8 转换;
 
 ## Java 对象映射
 
-如果高性能要求开发者把每个应用模型都改写成手写的传输对象,它的实用价值就会大打折扣。Fory JSON 可以映射开发者已经在使用的 Java 类型:
+Fory JSON 可以直接映射现有 Java 应用模型,无需手写传输对象:
 
 - 普通可变类和继承字段;
 - Java record,以及通过 `JsonCreator` 构建的不可变类;
 - 通过 `TypeRef` 表示的泛型集合和 Map;
 - Java 时间类型、Optional、原子类型、UUID、路径、大数、枚举和常用集合类型;
-- 目标类型为动态类型时,可自然使用 `JsonObject` 和 `JsonArray` 树。
+- 用于动态目标的 `JsonObject` 和 `JsonArray` 树模型。
 
 属性发现既可以组合字段与 JavaBean getter/setter,也可以切换为仅字段模式。有限的 `JsonSubTypes` 表可以处理应用声明的多态模型,同时不接受输入中的任意类名。
 
 ## 基于注解的对象映射
 
-Fory JSON 在 `org.apache.fory.json.annotation` 中提供自己的注解。这些注解覆盖显式属性名和顺序、按序列化或反序列化方向忽略属性、不可变对象构造、日期与时间格式、Base64 字节数组、原始值或完整值表示形式、对象展开、动态成员、校验以及有限子类型表。
+Fory JSON 在 `org.apache.fory.json.annotation` 中提供自己的注解。Jackson 用户会对这套注解模型感到熟悉:它涵盖属性命名和排序、构造器、格式化、多态和校验。不过,这些是独立的 Fory JSON API,并不兼容 Jackson 注解。
 
-Jackson 用户会对这套注解模型感到熟悉:它涵盖属性命名和排序、构造器、格式化、多态和校验。不过,这些是独立的 Fory JSON API,并不兼容 Jackson 注解。完整参考请参阅 [Fory JSON 注解指南](/docs/json/annotations)。
+其他注解还支持仅在序列化或反序列化时忽略属性、Base64 字节数组、原始值或完整值表示形式、对象展开和动态成员。完整参考请参阅 [Fory JSON 注解指南](/docs/json/annotations)。
 
-这些注解可以组合应用于普通模型。下面的事件模型会重命名固定属性、格式化日期、展开 owner 对象、捕获动态成员,并在读取完成后校验对象:
+下面的模型组合了多种注解:它会重命名固定属性、格式化日期、展开 owner 对象、捕获动态成员,并在读取完成后校验对象:
 
 ```java
 import java.time.LocalDate;
@@ -210,7 +210,7 @@ ForyJson json =
         .build();
 ```
 
-当注解仍不足以满足需求时,`JsonValueCodec<T>` 可以接管一个完整 JSON 值,并通过 Fory 的读取器和写入器进行流式处理。子 Codec 配置还可以定制集合元素、Optional 内容以及 Map 的键或值,而无需替换外围容器的映射逻辑。
+当注解仍不足以满足需求时,`JsonValueCodec<T>` 可以处理一个完整 JSON 值,并通过 Fory 的读取器和写入器进行流式处理。子 Codec 配置还可以定制集合元素、Optional 内容以及 Map 的键或值,而无需替换外围容器的映射逻辑。
 
 ## 使用 `JsonSubTypes` 实现封闭多态
 
@@ -252,7 +252,7 @@ public final class PaymentExample {
 }
 ```
 
-按声明类型写入会让 Fory JSON 使用 `Payment` 的子类型表。读取时,`kind` 必须匹配 `card` 或 `bank_transfer`,未知名称会被拒绝。对于容器,`TypeRef<List<Payment>>` 会为每个元素携带相同的声明基类型。[注解指南](/docs/json/annotations)还介绍了其他包装表示方式和完整校验规则。
+按声明的 `Payment` 类型序列化时,Fory JSON 会启用其子类型表。读取时,`kind` 必须匹配 `card` 或 `bank_transfer`,未知名称会被拒绝。对于容器,`TypeRef<List<Payment>>` 会为每个元素携带相同的声明基类型。[注解指南](/docs/json/annotations)还介绍了其他包装表示方式和完整校验规则。
 
 ## JDK、Android 与 GraalVM Native Image 支持
 
@@ -260,27 +260,27 @@ public final class PaymentExample {
 
 在 Android API 26+ 上,由于运行时编译不可用,Fory JSON 会自动使用解释执行的对象映射。Fory 注解处理器可以为 `JsonType` 类和 Mixin 生成直接模型访问代码以及精确的 R8 规则。
 
-GraalVM Native Image 提供独立的构建期集成。使用 `JsonType` 标记可达模型,以准备所需的访问元数据。如果某个构建完成的 `ForyJson` 配置需要在原生可执行文件中使用生成的编解码器,可通过一个可达的 `ForyJsonProvider` 暴露该配置;其他已准备的配置仍可使用解释执行编解码器。
+GraalVM Native Image 提供独立的构建期集成。使用 `JsonType` 标记可达模型后,构建过程可以准备其访问元数据。要让某个 `ForyJson` 配置在原生可执行文件中使用生成的编解码器,请通过一个可达的 `ForyJsonProvider` 暴露构建完成的配置。其他已准备的配置仍使用解释执行编解码器。
 
-因此,应用可以在标准 JVM、Android 和原生可执行文件中复用同一套映射模型,同时准确适配不同运行环境的代码生成能力。
+因此,应用可以在 JVM、Android 和原生可执行文件中复用同一套映射模型,并根据每种运行环境的代码生成能力选择执行方式。
 
 ## 面向不可信 JSON 的安全控制
 
-高性能解析器同样需要严格的类型边界。Fory JSON 只会反序列化为应用声明的类型;JSON 输入无法选择任意 Java 类。Fory JSON 采用封闭多态:`JsonSubTypes` 声明定义一组完整且有限的允许子类型,输入只能选择表中的逻辑名称。Fory JSON 还会始终应用固定的类型禁止列表,并提供 `JsonTypeChecker` 供应用定义允许列表。这些控制共同避免开放多态反序列化根据不可信 JSON 实例化任意类。
+高性能解析器同样需要严格的类型边界。Fory JSON 只会反序列化为应用声明的类型;JSON 输入无法选择任意 Java 类。Fory JSON 采用封闭多态:`JsonSubTypes` 声明定义一组完整且有限的允许子类型,输入只能选择表中的逻辑名称。Fory JSON 还会始终应用固定的类型禁止列表,并提供 `JsonTypeChecker` 供应用定义允许列表。这些控制共同避免开放多态反序列化根据不可信 JSON 选择并实例化任意类。
 
-输入深度默认为 20。另有一项独立的对象图内存限制,默认每次根读取为 128 MiB,用于估算数组、集合、Map、record 和应用对象所创建并保留的对象图。`JsonValidator` 方法可以在对象映射完成后执行领域规则校验。
+输入深度默认为 20。另有一项独立的对象图内存限制,默认每次根读取最多 128 MiB,用于估算数组、集合、Map、record 和应用对象所创建并保留的对象图。`JsonValidator` 方法可以在对象映射完成后执行领域规则校验。
 
 这些控制不能取代 HTTP 请求体大小限制、身份认证、授权、超时或端点专属校验。它们为 JSON 层提供清晰边界,以便与外部控制配合使用。[Fory JSON 安全指南](/docs/json/security)详细介绍了对象图计量模型和推荐的负向测试。
 
 ## Fory JSON 与二进制序列化如何选择
 
-如果编码格式必须保持为普通 JSON,例如用于公共 API、浏览器客户端、配置、日志或已经采用 JSON 的集成场景,应选择 Fory JSON。它在保持格式互操作性的同时,为 Java 提供基于生成编解码器和可复用状态设计的高性能实现。
+当应用必须交换标准 JSON,例如用于公共 API、浏览器客户端、配置、日志或现有 JSON 集成时,应选择 Fory JSON。它在保持格式互操作性的同时,为 Java 提供基于生成编解码器和可复用状态设计的高性能实现。
 
-如果通信双方都可以使用二进制协议,并且应用需要 JSON 无法表达的能力,例如跨语言 Schema 元数据、共享引用标识或循环对象图,则应选择 Fory 的二进制对象序列化。两种格式解决不同问题,也可以共存于同一服务中。
+如果通信双方都可以使用二进制协议,并且应用需要 JSON 无法表达的能力,例如跨语言 Schema 元数据、共享引用标识或循环对象图,则应选择 Fory 的二进制对象序列化。两种格式解决不同问题,也可以在同一服务中共存。
 
 ## 了解更多
 
-最有效的评估方式,是在真实模型和 JDK 配置下,将一条具有代表性的 Jackson 或 Gson 往返路径替换为 Fory JSON,并复用同一个 `ForyJson` 实例进行基准测试。公开结果展示了潜在的性能提升空间,应用自身的负载才能说明实际收益。
+评估 Fory JSON 时,可以在实际模型和 JDK 配置下,将一条具有代表性的 Jackson 或 Gson 往返路径替换为 Fory JSON,复用同一个 `ForyJson` 实例进行基准测试。公开结果展示了潜在的性能提升空间,应用自身的负载决定了其中有多少能够转化为实际收益。
 
 - 阅读 [Fory JSON 概览](/docs/json/)。
 - 运行 [快速开始示例](/docs/json/getting-started)。
@@ -288,4 +288,4 @@ GraalVM Native Image 提供独立的构建期集成。使用 `JsonType` 标记
 - 阅读 [1000 KB 基准测试及更广泛的对比矩阵](https://github.com/fabienrenaud/java-json-benchmark/pull/129)。
 - 在 [apache/fory](https://github.com/apache/fory) 参与开发。
 
-Fory JSON 保留了大家熟悉的格式;不同之处在于,Java 服务为此付出的时间可以大幅减少。
+Fory JSON 在保持标准 JSON 互操作性的同时,为 Java 服务提供高性能实现。


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@fory.apache.org
For additional commands, e-mail: commits-help@fory.apache.org


(fory-site) 02/05: docs: add Chinese Fory JSON blog translation

Posted by ch...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

chaokunyang pushed a commit to branch fory_json_blog
in repository https://gitbox.apache.org/repos/asf/fory-site.git

commit 4d2d7531e8153c2089210d9b6f4d16a432a6ec18
Author: chaokunyang <sh...@gmail.com>
AuthorDate: Tue Aug 11 20:21:08 2026 +0800

    docs: add Chinese Fory JSON blog translation
---
 .../translate-docs-zh/references/terminology.md    |   2 +
 ...08-11-fory_json_fastest_java_json_framework.md} |   8 +-
 ...-08-11-fory_json_fastest_java_json_framework.md | 293 +++++++++++++++++++++
 .../img/blog/fory-json}/clients-throughput.png     | Bin
 .../img/blog/fory-json}/users-throughput.png       | Bin
 5 files changed, 299 insertions(+), 4 deletions(-)

diff --git a/.claude/skills/translate-docs-zh/references/terminology.md b/.claude/skills/translate-docs-zh/references/terminology.md
index 059e263389..5abecbe841 100644
--- a/.claude/skills/translate-docs-zh/references/terminology.md
+++ b/.claude/skills/translate-docs-zh/references/terminology.md
@@ -36,6 +36,8 @@ Use these terms consistently across all translated docs.
 | payload              | 载荷              |                                                                                           |
 | runtime              | 运行时            |                                                                                           |
 | codegen              | 代码生成          |                                                                                           |
+| closed-world polymorphism | 封闭多态 | Use when input selects only from a complete, declared subtype set.                         |
+| open-world polymorphism | 开放多态   | Use for class-name-based or otherwise unrestricted subtype discovery.                     |
 | cross-language       | 跨语言            |                                                                                           |
 | object graph         | 对象图            | Use for graph-shaped data models with identity, shared refs, or cycles.                   |
 | domain object        | 领域对象          | Use for generated host-language models used directly in application code.                 |
diff --git a/blog/2026-08-11-fory-json/index.md b/blog/2026-08-11-fory_json_fastest_java_json_framework.md
similarity index 97%
rename from blog/2026-08-11-fory-json/index.md
rename to blog/2026-08-11-fory_json_fastest_java_json_framework.md
index ded43ab431..c392c53db4 100644
--- a/blog/2026-08-11-fory-json/index.md
+++ b/blog/2026-08-11-fory_json_fastest_java_json_framework.md
@@ -99,9 +99,9 @@ The 1000 KB suite asks what happens when each invocation has substantial parsing
 
 The 1000 KB run used Fory JSON 1.6.0, Jackson Databind 2.17.1, and Gson 2.11.0 with the databind API. JMH ran two forks and three threads. Each fork used five 3-second warmup iterations and five 3-second measurement iterations. The Users and Clients payloads each contained one 1000 KB object per invocation.
 
-![Fory JSON, Jackson, and Gson serialization and deserialization throughput for a 1000 KB Users payload](./users-throughput.png)
+![Fory JSON, Jackson, and Gson serialization and deserialization throughput for a 1000 KB Users payload](/img/blog/fory-json/users-throughput.png)
 
-![Fory JSON, Jackson, and Gson serialization and deserialization throughput for a 1000 KB Clients payload](./clients-throughput.png)
+![Fory JSON, Jackson, and Gson serialization and deserialization throughput for a 1000 KB Clients payload](/img/blog/fory-json/clients-throughput.png)
 
 | Payload | Operation       | Fory JSON ops/s       | Jackson ops/s         | Gson ops/s            | vs. Jackson | vs. Gson |
 | ------- | --------------- | --------------------: | --------------------: | --------------------: | ----------: | -------: |
@@ -118,9 +118,9 @@ The second view uses the [`jvm-serializers` MediaContent model](https://github.c
 
 The `jvm-serializers` benchmark ran on an Apple M4 Pro with JDK 26.0.1. It used one JMH fork and one thread, with three 2-second warmup iterations followed by five 2-second measurement iterations.
 
-![Java JSON String benchmark throughput](../../docs/benchmarks/json/java/string_throughput.png)
+![Java JSON String benchmark throughput](../docs/benchmarks/json/java/string_throughput.png)
 
-![Java JSON UTF-8 bytes benchmark throughput](../../docs/benchmarks/json/java/utf8_bytes_throughput.png)
+![Java JSON UTF-8 bytes benchmark throughput](../docs/benchmarks/json/java/utf8_bytes_throughput.png)
 
 | Representation | Operation   | Fory JSON ops/s | Jackson ops/s | Gson ops/s | vs. Jackson | vs. Gson |
 | -------------- | ----------- | --------------: | ------------: | ---------: | ----------: | -------: |
diff --git a/i18n/zh-CN/docusaurus-plugin-content-blog/2026-08-11-fory_json_fastest_java_json_framework.md b/i18n/zh-CN/docusaurus-plugin-content-blog/2026-08-11-fory_json_fastest_java_json_framework.md
new file mode 100644
index 0000000000..dd5beaa118
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-blog/2026-08-11-fory_json_fastest_java_json_framework.md
@@ -0,0 +1,293 @@
+---
+slug: fory_json_fastest_java_json_framework
+title: "Apache Fory™ JSON:面向 Java 的极速 JSON 序列化框架"
+authors: [chaokunyang]
+tags: [fory, java, json, serialization, performance]
+---
+
+**TL;DR**:Apache Fory JSON 是一款高性能序列化框架,可将 Java 对象与标准 JSON 文本或 UTF-8 字节相互转换。它支持常见 Java 模型,并可运行于 JDK 8+、Android 和 GraalVM Native Image。在下文展示的基准测试配置中,Fory JSON 是速度最快的 Java JSON 序列化框架:处理 1000 KB 载荷时,吞吐量最高可达 **Jackson 的 10.91 倍和 Gson 的 10.89 倍**;在 `jvm-serializers` MediaContent 基准测试中,最高可达 **Jackson 的 5.55 倍和 Gson 的 10.00 倍**。
+
+- GitHub:[apache/fory](https://github.com/apache/fory)
+- 文档:[Fory JSON](/docs/json/)
+- 更完整的 1000 KB 基准测试背景:[java-json-benchmark](https://github.com/fabienrenaud/java-json-benchmark/pull/129)
+
+<img src="/img/fory-logo-light.png" width="50%"/>
+
+---
+
+## JSON 性能为何重要
+
+JSON 很少是 Java 服务中最引人关注的部分,但它无处不在:HTTP API、浏览器流量、事件封装、日志、配置,以及与不共享二进制协议的系统进行集成。因此,JSON 处理会持续消耗 CPU 并产生对象分配,而这项成本往往每个请求都要承担。
+
+Fory 已经提供紧凑的二进制对象序列化和跨语言协议,Fory JSON 则解决另一类问题。它将 Java 对象映射为普通 JSON 文本或 UTF-8 字节,因此浏览器、命令行工具和任何符合标准的 JSON 实现都能读取结果。
+
+生成的 JSON 文档中没有 Fory 专属封装,也不隐藏任何二进制元数据。这就是标准 JSON,面向需要保留既有编码格式、同时减少转换开销的 Java 应用。
+
+## 快速开始
+
+Fory JSON 1.6.0 已发布到 Maven Central:
+
+```xml
+<dependency>
+  <groupId>org.apache.fory</groupId>
+  <artifactId>fory-json</artifactId>
+  <version>1.6.0</version>
+</dependency>
+```
+
+创建一个 `ForyJson` 实例并重复使用。构建完成的实例不可变且线程安全。
+
+```java
+import org.apache.fory.json.ForyJson;
+
+public final class JsonExample {
+  private static final ForyJson JSON = ForyJson.builder().build();
+
+  public static final class User {
+    public long id;
+    public String name;
+
+    public User() {}
+
+    User(long id, String name) {
+      this.id = id;
+      this.name = name;
+    }
+  }
+
+  public static void main(String[] args) {
+    User input = new User(7, "Alice");
+
+    String text = JSON.toJson(input);
+    byte[] utf8 = JSON.toJsonBytes(input);
+
+    User fromText = JSON.fromJson(text, User.class);
+    User fromUtf8 = JSON.fromJson(utf8, User.class);
+
+    System.out.println(text);              // {"id":7,"name":"Alice"}
+    System.out.println(fromText.name);      // Alice
+    System.out.println(fromUtf8.name);      // Alice
+  }
+}
+```
+
+String 和字节数组均有原生 API 支持。对于泛型根类型,`TypeRef<List<User>>` 可在反序列化和按声明类型序列化时保留元素类型。Fory JSON 还可以将完整的 UTF-8 文档写入 `OutputStream`,且不会接管该流的所有权。
+
+## Fory JSON 如何实现高性能
+
+高性能主要来自四项实现选择。
+
+**尽量减少临时对象分配。** `ForyJson` 实例会复用已经准备好的类型元数据、执行状态和保留的写入缓冲区。对于大多数基本标量值,除调用方要求的输出外,序列化热路径基本可以做到零分配:Fory 将值直接写入输出缓冲区,而不是先转换为 Java `String`。返回 `String` 或 `byte[]` 仍会创建结果对象,缓冲区扩容或冷路径回退也可能产生分配。
+
+**高度优化的基本类型写入。** 整数和长整数使用直接数字编码器;JDK 提供相应能力时,浮点数也通过直接格式化路径写入。布尔值、数值和带引号的字符串会直接进入当前的 String 或 UTF-8 写入器。热路径不需要为每个值执行一次 `String.valueOf(...)` 往返转换。
+
+**批量内存操作。** 常见的 Latin-1 和 ASCII 文本会以 8 字节或 16 字节为一组进行扫描和复制。生成的写入器还可以使用预打包的属性前缀和对象边界标记,从而减少逐字符分支和重复写入。
+
+**运行时代码生成。** Fory JSON 会为遇到的每种 Java 类型准备一个编解码器。在标准 JDK 上,代码生成和异步编译默认启用。生成的编解码器会针对目标类专门处理字段访问、属性名、对象边界和基本类型操作,而不必在每次调用时重新发现同一套属性模型。对于受限环境和诊断场景,仍可使用解释执行路径。
+
+公共 API 同样保留这些快速路径。需要直接生成网络字节的服务可以调用 `toJsonBytes` 和 `fromJson(byte[], type)`;面向文本的代码则可以继续使用 String 路径。自定义编解码器也直接通过 Fory 的读取器和写入器进行流式处理,无需构建中间 JSON 树。
+
+## 性能基准测试
+
+有意义的性能结论必须基于具体负载。这里展示两组结果:首先是三线程 `java-json-benchmark`,每次调用处理一个 1000 KB 对象;随后是单线程 `jvm-serializers` MediaContent 基准测试。两者都以每秒操作数报告吞吐量,因此数值越高越好。
+
+表格仅比较 Fory JSON、Jackson 和 Gson。更广泛的大载荷对比、完整的载荷设置以及基准测试集成方式,请参阅 [java-json-benchmark](https://github.com/fabienrenaud/java-json-benchmark/pull/129)。
+
+### `java-json-benchmark`:1000 KB 载荷
+
+1000 KB 测试用于观察每次调用都需要完成大量解析、遍历和输出工作时的表现。
+
+该测试使用 Fory JSON 1.6.0、Jackson Databind 2.17.1 和 Gson 2.11.0,三者均采用数据绑定 API。JMH 运行两个 fork 和三个线程;每个 fork 包含五轮 3 秒预热迭代和五轮 3 秒测量迭代。Users 与 Clients 载荷每次调用都包含一个 1000 KB 对象。
+
+![Fory JSON、Jackson 和 Gson 对 1000 KB Users 载荷进行序列化与反序列化时的吞吐量](/img/blog/fory-json/users-throughput.png)
+
+![Fory JSON、Jackson 和 Gson 对 1000 KB Clients 载荷进行序列化与反序列化时的吞吐量](/img/blog/fory-json/clients-throughput.png)
+
+| 载荷    | 操作       | Fory JSON ops/s      | Jackson ops/s        | Gson ops/s           | 相对 Jackson | 相对 Gson |
+| ------- | ---------- | -------------------: | -------------------: | -------------------: | -----------: | --------: |
+| Users   | 序列化     | 11,867.566 ± 136.846 | 2,225.296 ± 687.106  | 1,674.083 ± 12.558   |        5.33× |     7.09× |
+| Users   | 反序列化   | 6,872.876 ± 46.998   | 1,940.172 ± 58.242   | 1,217.513 ± 12.358   |        3.54× |     5.65× |
+| Clients | 序列化     | 11,895.269 ± 183.251 | 1,706.314 ± 36.263   | 1,298.288 ± 27.405   |        6.97× |     9.16× |
+| Clients | 反序列化   | 6,442.262 ± 627.116  | 590.656 ± 10.849     | 591.350 ± 6.444      |       10.91× |    10.89× |
+
+在这四项大载荷测试中,Fory JSON 的吞吐量达到 Jackson 的 3.54 至 10.91 倍、Gson 的 5.65 至 10.89 倍。
+
+### `jvm-serializers` MediaContent 基准测试
+
+第二组结果使用 [`jvm-serializers` MediaContent 模型](https://github.com/eishay/jvm-serializers/blob/master/tpc/src/data/media/MediaContent.java)。该模型包含一个媒体对象和一个图像列表。与 1000 KB 测试相比,这项基准处理的对象要小得多,并分别测试 Java String API 与 UTF-8 字节数组 API。
+
+`jvm-serializers` 基准测试运行于搭载 JDK 26.0.1 的 Apple M4 Pro,使用一个 JMH fork 和一个线程,先执行三轮 2 秒预热迭代,再执行五轮 2 秒测量迭代。
+
+![Java JSON String 基准测试吞吐量](../../../docs/benchmarks/json/java/string_throughput.png)
+
+![Java JSON UTF-8 字节基准测试吞吐量](../../../docs/benchmarks/json/java/utf8_bytes_throughput.png)
+
+| 表示形式   | 操作       | Fory JSON ops/s | Jackson ops/s | Gson ops/s | 相对 Jackson | 相对 Gson |
+| ---------- | ---------- | --------------: | ------------: | ---------: | -----------: | --------: |
+| String     | 序列化     |       7,387,465 |     2,049,368 |  1,084,042 |        3.60× |     6.81× |
+| String     | 反序列化   |       2,897,955 |     1,074,885 |    902,772 |        2.70× |     3.21× |
+| UTF-8 字节 | 序列化     |      10,375,498 |     1,868,614 |  1,037,211 |        5.55× |    10.00× |
+| UTF-8 字节 | 反序列化   |       3,077,158 |     1,268,397 |    933,079 |        2.43× |     3.30× |
+
+Fory JSON 的吞吐量在四项测试中均为最高。它在 UTF-8 序列化上的优势最大:每秒操作数超过 1000 万,吞吐量达到 Jackson 的 5.55 倍、Gson 的 10.00 倍。
+
+String 与 UTF-8 两组测试有意分开。String 组不包含 UTF-8 转换;字节组则在库提供直接字节数组 API 时使用该接口,Gson 的结果包含其必需的 String 与字节之间的转换。
+
+结果会随负载变化,但在这里展示的两组基准测试配置中,Fory JSON 都是速度最快的框架。
+
+## Java 对象映射
+
+如果高性能要求开发者把每个应用模型都改写成手写的传输对象,它的实用价值就会大打折扣。Fory JSON 可以映射开发者已经在使用的 Java 类型:
+
+- 普通可变类和继承字段;
+- Java record,以及通过 `JsonCreator` 构建的不可变类;
+- 通过 `TypeRef` 表示的泛型集合和 Map;
+- Java 时间类型、Optional、原子类型、UUID、路径、大数、枚举和常用集合类型;
+- 目标类型为动态类型时,可自然使用 `JsonObject` 和 `JsonArray` 树。
+
+属性发现既可以组合字段与 JavaBean getter/setter,也可以切换为仅字段模式。有限的 `JsonSubTypes` 表可以处理应用声明的多态模型,同时不接受输入中的任意类名。
+
+## 基于注解的对象映射
+
+Fory JSON 在 `org.apache.fory.json.annotation` 中提供自己的注解。这些注解覆盖显式属性名和顺序、按序列化或反序列化方向忽略属性、不可变对象构造、日期与时间格式、Base64 字节数组、原始值或完整值表示形式、对象展开、动态成员、校验以及有限子类型表。
+
+Jackson 用户会对这套注解模型感到熟悉:它涵盖属性命名和排序、构造器、格式化、多态和校验。不过,这些是独立的 Fory JSON API,并不兼容 Jackson 注解。完整参考请参阅 [Fory JSON 注解指南](/docs/json/annotations)。
+
+这些注解可以组合应用于普通模型。下面的事件模型会重命名固定属性、格式化日期、展开 owner 对象、捕获动态成员,并在读取完成后校验对象:
+
+```java
+import java.time.LocalDate;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import org.apache.fory.json.annotation.JsonAnyProperty;
+import org.apache.fory.json.annotation.JsonFormat;
+import org.apache.fory.json.annotation.JsonProperty;
+import org.apache.fory.json.annotation.JsonUnwrapped;
+import org.apache.fory.json.annotation.JsonValidator;
+
+public final class Event {
+  @JsonProperty("event_id")
+  public long id;
+
+  @JsonFormat(pattern = "dd/MM/uuuu")
+  public LocalDate day;
+
+  @JsonUnwrapped(prefix = "owner_")
+  public Owner owner;
+
+  @JsonAnyProperty
+  public Map<String, Object> attributes = new LinkedHashMap<>();
+
+  @JsonValidator
+  public void validate() {
+    if (id <= 0) {
+      throw new IllegalArgumentException("event_id must be positive");
+    }
+  }
+
+  public static final class Owner {
+    public String name;
+  }
+}
+```
+
+`JsonCreator` 支持不可变类,`JsonPropertyOrder` 可显式指定输出顺序。`JsonValue`、`JsonRawValue` 和 `JsonBase64` 可以处理特殊值表示形式,而无需改变对象其余部分的映射方式。
+
+对于无法直接添加注解的第三方类型,Mixin 可以在不修改或包装目标类的情况下应用同一套 Fory JSON 注解:
+
+```java
+import org.apache.fory.json.ForyJson;
+import org.apache.fory.json.annotation.JsonMixin;
+import org.apache.fory.json.annotation.JsonProperty;
+
+@JsonMixin(target = ThirdPartyUser.class)
+abstract class ThirdPartyUserMixin {
+  @JsonProperty("user_id")
+  long id;
+}
+
+ForyJson json =
+    ForyJson.builder()
+        .registerMixin(ThirdPartyUserMixin.class)
+        .build();
+```
+
+当注解仍不足以满足需求时,`JsonValueCodec<T>` 可以接管一个完整 JSON 值,并通过 Fory 的读取器和写入器进行流式处理。子 Codec 配置还可以定制集合元素、Optional 内容以及 Map 的键或值,而无需替换外围容器的映射逻辑。
+
+## 使用 `JsonSubTypes` 实现封闭多态
+
+`JsonSubTypes` 将声明的基类型映射到一组完整且有限的允许实现类及其逻辑名称。JSON 中的判别字段只能从这张表中选择类型,不会提供 Java 类名。
+
+```java
+import org.apache.fory.json.ForyJson;
+import org.apache.fory.json.annotation.JsonSubTypes;
+
+public final class PaymentExample {
+  @JsonSubTypes(
+      property = "kind",
+      value = {
+        @JsonSubTypes.Type(value = CardPayment.class, name = "card"),
+        @JsonSubTypes.Type(value = BankTransfer.class, name = "bank_transfer")
+      })
+  public interface Payment {}
+
+  public static final class CardPayment implements Payment {
+    public String lastFour;
+  }
+
+  public static final class BankTransfer implements Payment {
+    public String iban;
+  }
+
+  public static void main(String[] args) {
+    ForyJson json = ForyJson.builder().build();
+
+    CardPayment card = new CardPayment();
+    card.lastFour = "4242";
+
+    String text = json.toJson(card, Payment.class);
+    Payment copy = json.fromJson(text, Payment.class);
+
+    System.out.println(text);              // {"kind":"card","lastFour":"4242"}
+    System.out.println(copy.getClass());   // class PaymentExample$CardPayment
+  }
+}
+```
+
+按声明类型写入会让 Fory JSON 使用 `Payment` 的子类型表。读取时,`kind` 必须匹配 `card` 或 `bank_transfer`,未知名称会被拒绝。对于容器,`TypeRef<List<Payment>>` 会为每个元素携带相同的声明基类型。[注解指南](/docs/json/annotations)还介绍了其他包装表示方式和完整校验规则。
+
+## JDK、Android 与 GraalVM Native Image 支持
+
+同一个 `fory-json` artifact 支持 Java 8 及更高版本;Java record 需要 Java 17 或更高版本。
+
+在 Android API 26+ 上,由于运行时编译不可用,Fory JSON 会自动使用解释执行的对象映射。Fory 注解处理器可以为 `JsonType` 类和 Mixin 生成直接模型访问代码以及精确的 R8 规则。
+
+GraalVM Native Image 提供独立的构建期集成。使用 `JsonType` 标记可达模型,以准备所需的访问元数据。如果某个构建完成的 `ForyJson` 配置需要在原生可执行文件中使用生成的编解码器,可通过一个可达的 `ForyJsonProvider` 暴露该配置;其他已准备的配置仍可使用解释执行编解码器。
+
+因此,应用可以在标准 JVM、Android 和原生可执行文件中复用同一套映射模型,同时准确适配不同运行环境的代码生成能力。
+
+## 面向不可信 JSON 的安全控制
+
+高性能解析器同样需要严格的类型边界。Fory JSON 只会反序列化为应用声明的类型;JSON 输入无法选择任意 Java 类。Fory JSON 采用封闭多态:`JsonSubTypes` 声明定义一组完整且有限的允许子类型,输入只能选择表中的逻辑名称。Fory JSON 还会始终应用固定的类型禁止列表,并提供 `JsonTypeChecker` 供应用定义允许列表。这些控制共同避免开放多态反序列化根据不可信 JSON 实例化任意类。
+
+输入深度默认为 20。另有一项独立的对象图内存限制,默认每次根读取为 128 MiB,用于估算数组、集合、Map、record 和应用对象所创建并保留的对象图。`JsonValidator` 方法可以在对象映射完成后执行领域规则校验。
+
+这些控制不能取代 HTTP 请求体大小限制、身份认证、授权、超时或端点专属校验。它们为 JSON 层提供清晰边界,以便与外部控制配合使用。[Fory JSON 安全指南](/docs/json/security)详细介绍了对象图计量模型和推荐的负向测试。
+
+## Fory JSON 与二进制序列化如何选择
+
+如果编码格式必须保持为普通 JSON,例如用于公共 API、浏览器客户端、配置、日志或已经采用 JSON 的集成场景,应选择 Fory JSON。它在保持格式互操作性的同时,为 Java 提供基于生成编解码器和可复用状态设计的高性能实现。
+
+如果通信双方都可以使用二进制协议,并且应用需要 JSON 无法表达的能力,例如跨语言 Schema 元数据、共享引用标识或循环对象图,则应选择 Fory 的二进制对象序列化。两种格式解决不同问题,也可以共存于同一服务中。
+
+## 了解更多
+
+最有效的评估方式,是在真实模型和 JDK 配置下,将一条具有代表性的 Jackson 或 Gson 往返路径替换为 Fory JSON,并复用同一个 `ForyJson` 实例进行基准测试。公开结果展示了潜在的性能提升空间,应用自身的负载才能说明实际收益。
+
+- 阅读 [Fory JSON 概览](/docs/json/)。
+- 运行 [快速开始示例](/docs/json/getting-started)。
+- 查看 [完整的 `jvm-serializers` MediaContent 基准测试](/docs/benchmarks/json/java/)。
+- 阅读 [1000 KB 基准测试及更广泛的对比矩阵](https://github.com/fabienrenaud/java-json-benchmark/pull/129)。
+- 在 [apache/fory](https://github.com/apache/fory) 参与开发。
+
+Fory JSON 保留了大家熟悉的格式;不同之处在于,Java 服务为此付出的时间可以大幅减少。
diff --git a/blog/2026-08-11-fory-json/clients-throughput.png b/static/img/blog/fory-json/clients-throughput.png
similarity index 100%
rename from blog/2026-08-11-fory-json/clients-throughput.png
rename to static/img/blog/fory-json/clients-throughput.png
diff --git a/blog/2026-08-11-fory-json/users-throughput.png b/static/img/blog/fory-json/users-throughput.png
similarity index 100%
rename from blog/2026-08-11-fory-json/users-throughput.png
rename to static/img/blog/fory-json/users-throughput.png


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@fory.apache.org
For additional commands, e-mail: commits-help@fory.apache.org


(fory-site) 01/05: docs: clarify benchmark throughput wording

Posted by ch...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

chaokunyang pushed a commit to branch fory_json_blog
in repository https://gitbox.apache.org/repos/asf/fory-site.git

commit 9f03f43413029b54316d3a7ffff6cc3f171be264
Author: chaokunyang <sh...@gmail.com>
AuthorDate: Tue Aug 11 20:11:36 2026 +0800

    docs: clarify benchmark throughput wording
---
 blog/2026-08-11-fory-json/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/blog/2026-08-11-fory-json/index.md b/blog/2026-08-11-fory-json/index.md
index 2eeec815d6..ded43ab431 100644
--- a/blog/2026-08-11-fory-json/index.md
+++ b/blog/2026-08-11-fory-json/index.md
@@ -5,7 +5,7 @@ authors: [chaokunyang]
 tags: [fory, java, json, serialization, performance]
 ---
 
-**TL;DR**: Apache Fory JSON is a high-performance serialization framework that maps Java objects to and from standard JSON text and UTF-8 bytes. It supports ordinary Java models and runs on JDK 8+, Android, and GraalVM Native Image. In the published benchmark configurations below, Fory JSON is the fastest Java JSON serialization framework: up to **10.91× faster than Jackson and 10.89× faster than Gson** with 1000 KB payloads, and up to **5.55× faster than Jackson and 10.00× faster than G [...]
+**TL;DR**: Apache Fory JSON is a high-performance serialization framework that maps Java objects to and from standard JSON text and UTF-8 bytes. It supports ordinary Java models and runs on JDK 8+, Android, and GraalVM Native Image. In the published benchmark configurations below, Fory JSON is the fastest Java JSON serialization framework: up to **10.91× the throughput of Jackson and 10.89× the throughput of Gson** with 1000 KB payloads, and up to **5.55× the throughput of Jackson and 10 [...]
 
 - GitHub: [apache/fory](https://github.com/apache/fory)
 - Documentation: [Fory JSON](/docs/json/)


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@fory.apache.org
For additional commands, e-mail: commits-help@fory.apache.org