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/04/19 16:21:08 UTC
(fory-site) branch release_0.17.0 created (now 32d68f415)
This is an automated email from the ASF dual-hosted git repository.
chaokunyang pushed a change to branch release_0.17.0
in repository https://gitbox.apache.org/repos/asf/fory-site.git
at 32d68f415 update skill
This branch includes the following new commits:
new 8ff820d2e 0.17.0 release blog
new 9c02a59a9 Add release-major-version skill
new 4496fd3e3 Require user draft for release blog skill
new 60dec0908 Bump current docs to 0.17.0
new e4ca2b6bd Translate zh docs and blog for 0.17
new 0c9f74409 Complete zh docs and blog for 0.17
new 6f871be75 Create docs snapshot for 0.17
new e25838356 Sync stale zh docs for 0.17
new 32d68f415 update skill
The 9 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.
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@fory.apache.org
For additional commands, e-mail: commits-help@fory.apache.org
(fory-site) 05/09: Translate zh docs and blog for 0.17
Posted by ch...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
chaokunyang pushed a commit to branch release_0.17.0
in repository https://gitbox.apache.org/repos/asf/fory-site.git
commit e4ca2b6bdc88b67059ae5551878b267b9b5a2c0b
Author: 慕白 <ch...@antgroup.com>
AuthorDate: Sun Apr 19 23:05:31 2026 +0800
Translate zh docs and blog for 0.17
---
.../2026-04-19-fory_0_17_0_release.md | 230 +++++++++++++++++++++
.../current/guide/cpp/index.md | 87 +++++---
.../current/guide/csharp/index.md | 104 ++++++++++
.../current/guide/java/compression.md | 66 +++---
.../current/guide/kotlin/index.md | 36 ++--
.../current/guide/rust/index.md | 60 +++---
.../current/guide/scala/index.md | 40 ++--
.../current/guide/xlang/getting-started.md | 76 +++----
.../current/start/install.md | 46 ++---
9 files changed, 552 insertions(+), 193 deletions(-)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-blog/2026-04-19-fory_0_17_0_release.md b/i18n/zh-CN/docusaurus-plugin-content-blog/2026-04-19-fory_0_17_0_release.md
new file mode 100644
index 000000000..7a709c9c0
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-blog/2026-04-19-fory_0_17_0_release.md
@@ -0,0 +1,230 @@
+---
+slug: fory_0_17_0_release
+title: Fory v0.17.0 发布
+authors: [chaokunyang]
+tags: [fory, c#, swift, c++, java, python, compiler]
+---
+
+Apache Fory 团队很高兴宣布 0.17.0 版本正式发布。这是一个重要版本，包含来自 19 位贡献者的 [71 个 PR](https://github.com/apache/fory/compare/v0.16.0...v0.17.0)。请访问 [Install 页面](https://fory.apache.org/docs/start/install) 获取各平台安装方式。
+
+## JavaScript/NodeJS Serialization：首次发布
+
+Apache Fory 0.17.0 首次正式提供 JavaScript/NodeJS 文档、基准测试覆盖，以及对 TypeScript 友好的 IDL 代码生成支持。JavaScript 运行时面向现代 Node.js 服务和 TypeScript 代码库构建，同时保留了 Fory 的跨语言对象模型、Schema 驱动 API，以及可选的引用跟踪能力。
+
+**关键能力：**
+
+* 面向 Node.js 中 JavaScript 和 TypeScript 对象的高性能序列化
+* 支持与 Java、Python、Go、Rust、C#、Swift 和 Dart 的跨语言兼容
+* 通过 `Type.*` builder 与 TypeScript decorator 提供 Schema 驱动 API
+* 可选的引用跟踪，用于处理共享引用和循环引用对象图
+* 用于 Schema 演进的兼容模式
+* 可配置的深度、二进制大小和集合大小护栏
+* 在 Fory IDL/compiler 工作流中支持 JavaScript/TypeScript target
+* 为 Node.js 20+ 提供可选的 `@apache-fory/hps` 快速字符串路径
+
+### 快速开始
+
+```ts
+import Fory, { Type } from "@apache-fory/core";
+
+const userType = Type.struct(
+ { typeName: "example.user" },
+ {
+ id: Type.int64(),
+ name: Type.string(),
+ age: Type.int32(),
+ },
+);
+
+const fory = new Fory();
+const { serialize, deserialize } = fory.register(userType);
+
+const bytes = serialize({
+ id: 1n,
+ name: "Alice",
+ age: 30,
+});
+
+const user = deserialize(bytes);
+console.log(user);
+```
+
+* JavaScript 指南： https://fory.apache.org/docs/guide/javascript/
+* Compiler 文档： https://fory.apache.org/docs/compiler/
+
+### JavaScript 基准测试
+
+<img src="/img/blog/fory_0_17_0_release/javascript_throughput.png" width="90%"/>
+
+以下是代表性数据结构上的吞吐结果（ops/sec，越高越好），用于比较 Fory、Protocol Buffers 与 JSON。
+
+| Datatype | Operation | Fory TPS | Protobuf TPS | JSON TPS | Fastest |
+| ---------------- | ----------- | --------- | ------------ | --------- | ------- |
+| Struct | Serialize | 8,453,950 | 1,903,706 | 3,058,232 | fory |
+| Struct | Deserialize | 9,705,287 | 8,233,664 | 3,860,538 | fory |
+| Sample | Serialize | 1,498,391 | 422,620 | 744,790 | fory |
+| Sample | Deserialize | 1,918,162 | 819,010 | 762,048 | fory |
+| MediaContent | Serialize | 1,293,157 | 729,497 | 1,299,908 | json |
+| MediaContent | Deserialize | 1,638,086 | 1,209,140 | 921,191 | fory |
+| StructList | Serialize | 3,928,325 | 495,648 | 891,810 | fory |
+| StructList | Deserialize | 3,264,827 | 1,529,744 | 986,144 | fory |
+| SampleList | Serialize | 355,581 | 92,741 | 163,120 | fory |
+| SampleList | Deserialize | 424,916 | 163,253 | 162,520 | fory |
+| MediaContentList | Serialize | 286,053 | 148,977 | 282,445 | fory |
+| MediaContentList | Deserialize | 376,826 | 244,622 | 190,155 | fory |
+
+序列化数据大小（bytes）：
+
+| Datatype | Fory | Protobuf | JSON |
+| ---------------- | ---- | -------- | ---- |
+| Struct | 58 | 61 | 103 |
+| Sample | 446 | 377 | 724 |
+| MediaContent | 391 | 307 | 596 |
+| StructList | 184 | 315 | 537 |
+| SampleList | 1980 | 1900 | 3642 |
+| MediaContentList | 1665 | 1550 | 3009 |
+
+详细基准数据请参见： https://github.com/apache/fory/tree/v0.17.0/benchmarks/javascript
+
+## Dart Serialization：首次发布
+
+Apache Fory 0.17.0 也正式带来了 Dart serialization 的首次发布，提供官方文档、基准测试覆盖、重构后的运行时，以及 Dart IDL 支持。Dart 实现重点关注生成式 serializer、稳定的跨语言类型标识、Schema 演进，以及面向服务工作负载的可预测 API。
+
+**关键能力：**
+
+* 使用生成代码而非反射实现高性能 Dart serialization
+* 支持与 Java、Python、Go、Rust、C#、Swift 和 JavaScript 的跨语言兼容
+* 提供 `@ForyStruct` 和 `@ForyField` 注解，并结合 `build_runner` 进行代码生成
+* 用于跨版本 Schema 演进的兼容模式
+* 可选的引用跟踪，用于处理共享引用和循环引用对象图
+* 为高级或自定义类型提供手动 `Serializer<T>` 扩展点
+* 在 Fory IDL/compiler 工作流中支持 Dart target
+
+### 快速开始
+
+```dart
+import 'package:fory/fory.dart';
+
+part 'person.fory.dart';
+
+enum Color {
+ red,
+ blue,
+}
+
+@ForyStruct()
+class Person {
+ Person();
+
+ String name = '';
+ Int32 age = Int32(0);
+ Color favoriteColor = Color.red;
+}
+
+void main() {
+ final fory = Fory();
+ PersonFory.register(
+ fory,
+ Color,
+ namespace: 'example',
+ typeName: 'Color',
+ );
+ PersonFory.register(
+ fory,
+ Person,
+ namespace: 'example',
+ typeName: 'Person',
+ );
+
+ final bytes = fory.serialize(Person()
+ ..name = 'Ada'
+ ..age = Int32(36)
+ ..favoriteColor = Color.blue);
+ final roundTrip = fory.deserialize<Person>(bytes);
+ print(roundTrip.name);
+}
+```
+
+* Dart 指南： https://fory.apache.org/docs/guide/dart/
+* Compiler 文档： https://fory.apache.org/docs/compiler/
+
+### Dart 基准测试
+
+<img src="/img/blog/fory_0_17_0_release/dart_throughput.png" width="90%"/>
+
+以下是代表性数据结构上的吞吐结果（ops/sec，越高越好），用于比较 Fory 与 Protocol Buffers。
+
+| Datatype | Operation | Fory TPS | Protobuf TPS | Fastest |
+| ---------------- | ----------- | --------: | -----------: | ------------ |
+| Struct | Serialize | 3,989,432 | 1,884,653 | fory (2.12x) |
+| Struct | Deserialize | 5,828,197 | 4,199,680 | fory (1.39x) |
+| Sample | Serialize | 1,649,722 | 500,167 | fory (3.30x) |
+| Sample | Deserialize | 2,060,113 | 785,109 | fory (2.62x) |
+| MediaContent | Serialize | 800,876 | 391,235 | fory (2.05x) |
+| MediaContent | Deserialize | 1,315,115 | 683,533 | fory (1.92x) |
+| StructList | Serialize | 1,456,396 | 367,506 | fory (3.96x) |
+| StructList | Deserialize | 1,921,006 | 645,958 | fory (2.97x) |
+| SampleList | Serialize | 411,144 | 48,508 | fory (8.48x) |
+| SampleList | Deserialize | 464,273 | 103,558 | fory (4.48x) |
+| MediaContentList | Serialize | 186,870 | 77,029 | fory (2.43x) |
+| MediaContentList | Deserialize | 330,293 | 128,215 | fory (2.58x) |
+
+序列化数据大小（bytes）：
+
+| Datatype | Fory | Protobuf |
+| ---------------- | ---: | -------: |
+| Struct | 58 | 61 |
+| Sample | 446 | 377 |
+| MediaContent | 365 | 307 |
+| StructList | 184 | 315 |
+| SampleList | 1980 | 1900 |
+| MediaContentList | 1535 | 1550 |
+
+详细基准数据请参见： https://github.com/apache/fory/tree/v0.17.0/benchmarks/dart
+
+## 发布亮点
+* refactor(java): 重构 fory java serialization API，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3537
+* refactor(python): 重构 python serialization API，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3543
+* feat(java): 通过在 Fory 实例间共享来降低 java serializer 内存占用，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3546
+* feat(java): 从 fory java 中移除 guava 依赖，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3557
+* refactor(dart): 全新的 dart 实现，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3551
+
+## 功能特性
+* refactor(javascript): 将 apache-fory/fory 重命名为 apache-fory/core，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3489
+* feat(ci): 为 bazel 下载增加重试机制，作者 @BaldDemian，见 https://github.com/apache/fory/pull/3492
+* feat(go): 增加可配置的大小护栏，作者 @ayush00git，见 https://github.com/apache/fory/pull/3475
+* refactor(ci): 使用 setup-bazel 安装 Bazel，作者 @BaldDemian，见 https://github.com/apache/fory/pull/3494
+* perf(rust): 基于共享的 bench.proto 数据重写 Rust benchmark，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3497
+* feat(cpp): 为 c++ 增加 float16 支持，作者 @UninspiredCarrot，见 https://github.com/apache/fory/pull/3487
+* feat(java): 增加 float 支持，作者 @mengnankkkk，见 https://github.com/apache/fory/pull/3254
+* feat(java): 支持 java virtual threads，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3522
+* perf(java): 优化 java 中线程安全 fory 的性能，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3529
+* test(cpp): 为 ASAN 优化 float16 sign symmetry 测试，作者 @Geethapranay1，见 https://github.com/apache/fory/pull/3531
+* feat(java): 增加专用 exception serializer，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3536
+* refactor(java): 重构 fory java serialization API，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3537
+* refactor(python): 重构 python serialization API，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3543
+* feat(dart): 引入基于 id 的 enum serialization，作者 @yash-agarwa-l，见 https://github.com/apache/fory/pull/3482
+* feat(javascript): 增加可配置的大小护栏，作者 @ayush00git，见 https://github.com/apache/fory/pull/3539
+* feat(java): 通过在 Fory 实例间共享来降低 java serializer 内存占用，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3546
+* refactor(javascript): 将 serialization 运行时状态移动到 contexts 中，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3549
+* refactor(swift): 改进 swift API，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3554
+* feat(xlang): 改进 xlang API 与 enum serialization，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3555
+* feat(java): 从 fory java 中移除 guava 依赖，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3557
+* refactor(dart): 全新的 dart 实现，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3551
+* feat(compiler): 增加 JavaScript/TypeScript IDL 代码生成，作者 @miantalha45，见 https://github.com/apache/fory/pull/3394
+* perf(javascript): 增加 javascript benchmark，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3562
+* perf(dart): 使用直接分发代码生成为 struct 反序列化提速，作者 @yash-agarwa-l，见 https://github.com/apache/fory/pull/3563
+* feat(dart): 增加 dart IDL 支持，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3571
+* feat(python): 修复 python struct 跨语言引用跟踪错误，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3574
+* feat: 让生成的 enum 在编码格式中使用 id，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3576
+
+
+## Bug 修复
+* fix(java): 恢复 compact codec 定长优化，作者 @stevenschlansker，见 https://github.com/apache/fory/pull/3478
+* fix(rust): 处理 fuzz 发现的边界场景引发的 panic，作者 @utafrali，见 https://github.com/apache/fory/pull/3481
+* fix(rust): 为 std duration 增加错误处理逻辑，并支持 chrono duration，作者 @BaldDemian，见 https://github.com/apache/fory/pull/3490
+* fix(compiler): 校验 rpc request/response 类型，作者 @retryoos，见 https://github.com/apache/fory/pull/3493
+* fix(c++): 修复 UBSan 在 buffer.h 中检测到的未对齐地址访问错误，作者 @BaldDemian，见 https://github.com/apache/fory/pull/3479
+* fix(java): 在首次使用时固定 codegen config hash，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3495
+* fix(rust): 修复 cargo-fuzz 检测到的多个 panic，作者 @BaldDemian，见 https://github.com/apache/fory/pull/3483
+* fix(java): 处理 private final map 的代码生成，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3504
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/cpp/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/cpp/index.md
index cc2102a5e..12049c1a8 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/cpp/index.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/cpp/index.md
@@ -19,19 +19,19 @@ license: |
limitations under the License.
---
-**Apache Fory™** 是一个极速的多语言序列化框架，基于 **JIT 编译**和**零拷贝**技术，在保持易用性和安全性的同时提供**超高性能**。
+**Apache Fory™** 是一个高性能的多语言序列化框架，基于 **JIT 编译**与**零拷贝**技术，在保持易用性和安全性的同时提供出色性能。
-C++ 实现利用现代 C++17 特性和模板元编程，提供具有编译时类型安全的高性能序列化。
+C++ 实现基于现代 C++17 特性和模板元编程，提供具备编译时类型安全的高性能序列化能力。
## 为什么选择 Apache Fory™ C++？
-- **🔥 极速性能**：快速序列化和优化的二进制协议
-- **🌍 跨语言**：在 Java、Python、C++、Go、JavaScript 和 Rust 之间无缝序列化/反序列化数据
-- **🎯 类型安全**：基于宏的结构体注册实现编译时类型检查
-- **🔄 引用跟踪**：自动跟踪共享引用和循环引用
-- **📦 Schema 演化**：兼容模式支持独立的 schema 变更
-- **⚡ 双格式支持**：对象图序列化和零拷贝行格式
-- **🧵 线程安全**：同时提供单线程（最快）和线程安全两种变体
+- **高性能**：快速序列化与优化的二进制协议
+- **跨语言**：可在 Java、Python、C++、Go、JavaScript 和 Rust 之间无缝序列化与反序列化数据
+- **类型安全**：通过基于宏的结构体注册实现编译时类型检查
+- **引用跟踪**：自动跟踪共享引用和循环引用
+- **Schema 演进**：兼容模式支持独立的 Schema 变更
+- **双格式支持**：对象图序列化与零拷贝行格式
+- **线程安全**：同时提供单线程（最快）和线程安全两种变体
## 安装
@@ -40,11 +40,11 @@ C++ 实现同时支持 CMake 和 Bazel 构建系统。
### 前置条件
- CMake 3.16+（用于 CMake 构建）或 Bazel 8+（用于 Bazel 构建）
-- C++17 兼容的编译器（GCC 7+、Clang 5+、MSVC 2017+）
+- 支持 C++17 的编译器（GCC 7+、Clang 5+、MSVC 2017+）
### 使用 CMake（推荐）
-使用 CMake 的 `FetchContent` 模块是最简单的方式：
+最简单的集成方式是使用 CMake 的 `FetchContent` 模块：
```cmake
cmake_minimum_required(VERSION 3.16)
@@ -52,12 +52,14 @@ project(my_project LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
-
+if(MSVC)
+ add_compile_options(/Zc:preprocessor)
+endif()
include(FetchContent)
FetchContent_Declare(
fory
GIT_REPOSITORY https://github.com/apache/fory.git
- GIT_TAG v0.14.1
+ GIT_TAG v0.17.0
SOURCE_SUBDIR cpp
)
FetchContent_MakeAvailable(fory)
@@ -87,11 +89,11 @@ module(
bazel_dep(name = "rules_cc", version = "0.1.1")
-bazel_dep(name = "fory", version = "0.14.1")
+bazel_dep(name = "fory", version = "0.17.0")
git_override(
module_name = "fory",
remote = "https://github.com/apache/fory.git",
- commit = "v0.14.1", # 或使用特定的 commit hash 以确保可重现性
+ commit = "v0.17.0", # 或使用特定 commit hash 以确保可复现性
)
```
@@ -112,10 +114,10 @@ bazel build //:my_app
bazel run //:my_app
```
-对于本地开发，可以使用 `local_path_override`：
+对于本地开发，也可以改用 `local_path_override`：
```bazel
-bazel_dep(name = "fory", version = "0.14.1")
+bazel_dep(name = "fory", version = "0.17.0")
local_path_override(
module_name = "fory",
path = "/path/to/fory",
@@ -124,7 +126,7 @@ local_path_override(
### 示例
-请参阅 [examples/cpp](https://github.com/apache/fory/tree/main/examples/cpp) 目录获取完整的工作示例：
+完整可运行示例请参见 [examples/cpp](https://github.com/apache/fory/tree/main/examples/cpp) 目录：
- [hello_world](https://github.com/apache/fory/tree/main/examples/cpp/hello_world) - 对象图序列化
- [hello_row](https://github.com/apache/fory/tree/main/examples/cpp/hello_row) - 行格式编码
@@ -135,6 +137,8 @@ local_path_override(
```cpp
#include "fory/serialization/fory.h"
+#include <string>
+#include <vector>
using namespace fory::serialization;
@@ -148,8 +152,6 @@ struct Person {
return name == other.name && age == other.age && hobbies == other.hobbies;
}
};
-
-// 使用 Fory 注册结构体（必须在同一命名空间中）
FORY_STRUCT(Person, name, age, hobbies);
int main() {
@@ -159,7 +161,7 @@ int main() {
.track_ref(false) // 对简单类型禁用引用跟踪
.build();
- // 使用唯一 ID 注册类型
+ // 为类型注册唯一 ID
fory.register_struct<Person>(1);
// 创建对象
@@ -186,14 +188,30 @@ int main() {
}
```
+### 继承字段
+
+如果希望派生类型包含基类字段，请在 `FORY_STRUCT` 中写入 `FORY_BASE(Base)`。基类本身也必须定义自己的 `FORY_STRUCT`，这样其字段才能被引用。
+
+```cpp
+struct Base {
+ int32_t id;
+ FORY_STRUCT(Base, id);
+};
+
+struct Derived : Base {
+ std::string name;
+ FORY_STRUCT(Derived, FORY_BASE(Base), name);
+};
+```
+
## 线程安全
-Apache Fory™ C++ 为不同的线程需求提供两种变体：
+Apache Fory™ C++ 面向不同线程需求提供两种变体：
### 单线程（最快）
```cpp
-// 单线程 Fory - 最快，但非线程安全
+// 单线程 Fory：速度最快，但不是线程安全的
auto fory = Fory::builder()
.xlang(true)
.build();
@@ -202,12 +220,12 @@ auto fory = Fory::builder()
### 线程安全
```cpp
-// 线程安全 Fory - 使用上下文池
+// 线程安全 Fory：使用上下文池
auto fory = Fory::builder()
.xlang(true)
.build_thread_safe();
-// 可以从多个线程安全使用
+// 可安全用于多线程
std::thread t1([&]() {
auto result = fory.serialize(obj1);
});
@@ -216,30 +234,31 @@ std::thread t2([&]() {
});
```
-**提示：** 在生成线程之前完成类型注册，以确保每个工作线程看到相同的元数据。
+**提示：** 请在启动线程之前完成类型注册，以确保每个工作线程都能看到一致的元数据。
## 使用场景
### 对象序列化
-- 包含嵌套对象和引用的复杂数据结构
+- 含嵌套对象和引用的复杂数据结构
- 微服务中的跨语言通信
-- 具有完整类型安全的通用序列化
-- 使用兼容模式的 schema 演化
+- 具备完整类型安全的通用序列化
+- 使用兼容模式进行 Schema 演进
### 行格式序列化
-- 高吞吐量数据处理
-- 需要快速字段访问的分析工作负载
+- 高吞吐数据处理
+- 需要快速字段访问的分析型负载
- 内存受限环境
- 零拷贝场景
## 后续步骤
-- [配置](configuration.md) - 构建器选项和模式
+- [配置](configuration.md) - 构建器选项与模式
- [基础序列化](basic-serialization.md) - 对象图序列化
-- [Schema 演化](schema-evolution.md) - 兼容模式和 schema 变更
+- [Schema 演进](schema-evolution.md) - 兼容模式与 Schema 变更
- [类型注册](type-registration.md) - 注册类型
-- [支持的类型](supported-types.md) - 所有支持的类型
+- [字段配置](field-configuration.md) - 字段级元数据（可空、引用跟踪）
+- [支持的类型](supported-types.md) - 全部支持的类型
- [跨语言](cross-language.md) - XLANG 模式
- [行格式](row-format.md) - 零拷贝行格式
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/index.md
new file mode 100644
index 000000000..4cd2780ce
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/index.md
@@ -0,0 +1,104 @@
+---
+title: C# 序列化指南
+sidebar_position: 0
+id: serialization_index
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Apache Fory™ C# 是面向 .NET 的高性能跨语言序列化运行时。它提供对象图序列化、Schema 演进、泛型对象载荷支持，以及面向并发负载的线程安全封装。
+
+## 为什么选择 Fory C#？
+
+- 面向 .NET 8+ 的高性能二进制序列化
+- 与 Java、Python、C++、Go、Rust 和 JavaScript 中的 Fory 实现保持跨语言兼容
+- 基于 source generator 的 `[ForyObject]` 类型序列化器
+- 可选引用跟踪，支持共享对象图和循环对象图
+- 面向 Schema 演进的兼容模式
+- 面向多线程服务的线程安全运行时 `ThreadSafeFory`
+
+## 快速开始
+
+### 要求
+
+- .NET SDK 8.0+
+- C# 语言版本 12+
+
+### 从 NuGet 安装
+
+引用单个 `Apache.Fory` 包即可。它同时包含运行时和 `[ForyObject]` 类型所需的 source generator。
+
+```xml
+<ItemGroup>
+ <PackageReference Include="Apache.Fory" Version="0.17.0" />
+</ItemGroup>
+```
+
+### 基础示例
+
+```csharp
+using Apache.Fory;
+
+[ForyObject]
+public sealed class User
+{
+ public long Id { get; set; }
+ public string Name { get; set; } = string.Empty;
+ public string? Email { get; set; }
+}
+
+Fory fory = Fory.Builder().Build();
+fory.Register<User>(1);
+
+User user = new()
+{
+ Id = 1,
+ Name = "Alice",
+ Email = "alice@example.com",
+};
+
+byte[] payload = fory.Serialize(user);
+User decoded = fory.Deserialize<User>(payload);
+```
+
+## 核心 API
+
+- `Serialize<T>(in T value)` / `Deserialize<T>(...)`
+- `Serialize<object?>(...)` / `Deserialize<object?>(...)`，用于动态载荷
+- `Register<T>(uint typeId)` 以及基于命名空间和名称的注册 API
+- `Register<T, TSerializer>(...)`，用于自定义序列化器
+
+## 文档
+
+| 主题 | 说明 |
+| --------------------------------------------- | ---------------------------------- |
+| [配置](configuration.md) | 构建器选项与运行时模式 |
+| [基础序列化](basic-serialization.md) | 强类型和动态序列化 API |
+| [类型注册](type-registration.md) | 注册用户类型和自定义序列化器 |
+| [自定义序列化器](custom-serializers.md) | 实现 `Serializer<T>` |
+| [字段配置](field-configuration.md) | `[Field]` 特性与整数编码选项 |
+| [引用](references.md) | 共享引用与循环引用处理 |
+| [Schema 演进](schema-evolution.md) | 兼容模式行为 |
+| [跨语言](cross-language.md) | 互操作性指导 |
+| [支持的类型](supported-types.md) | 内置类型与生成类型支持 |
+| [线程安全](thread-safety.md) | `Fory` 与 `ThreadSafeFory` 的用法 |
+| [故障排查](troubleshooting.md) | 常见错误与调试步骤 |
+
+## 相关资源
+
+- [跨语言序列化规范](../../specification/xlang_serialization_spec.md)
+- [跨语言指南](../xlang/index.md)
+- [C# 源码目录](https://github.com/apache/fory/tree/main/csharp)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/compression.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/compression.md
index 3594eee55..5447dd9ed 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/compression.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/compression.md
@@ -1,6 +1,6 @@
---
title: 压缩
-sidebar_position: 6
+sidebar_position: 7
id: compression
license: |
Licensed to the Apache Software Foundation (ASF) under one or more
@@ -19,49 +19,49 @@ license: |
limitations under the License.
---
-本页介绍用于减少序列化数据大小的压缩选项。
+本页介绍用于减小序列化数据体积的压缩选项。
## 整数压缩
-`ForyBuilder#withIntCompressed`/`ForyBuilder#withLongCompressed` 可用于压缩 int/long 以获得更小的大小。通常压缩 int 就足够了。
+可使用 `ForyBuilder#withIntCompressed` / `ForyBuilder#withLongCompressed` 对 int / long 进行压缩以减小体积。通常压缩 int 就足够了。
-这两个压缩选项默认都是启用的。如果序列化大小不重要（例如，你之前使用 FlatBuffers 进行序列化，它不压缩任何东西），那么你应该禁用压缩。如果你的数据全是数字，压缩可能会带来 80% 的性能回退。
+这两个压缩选项默认都已启用。如果序列化体积并不重要，例如你之前使用的是不会做压缩的 FlatBuffers，那么应考虑关闭压缩。如果你的数据几乎全是数字，压缩可能带来 80% 的性能回退。
### Int 压缩
-对于 int 压缩，Fory 使用 1~5 个字节进行编码。每个字节中的第一位表示是否有下一个字节。如果设置了第一位，则将读取下一个字节，直到下一个字节的第一位未设置。
+对于 int 压缩，Fory 使用 1 到 5 个字节进行编码。每个字节的第一位表示后面是否还有下一个字节。如果第一位被置位，就继续读取下一个字节，直到某个字节的第一位未置位为止。
### Long 压缩
-对于 long 压缩，Fory 支持两种编码：
+对于 long 压缩，Fory 支持两种编码方式：
-#### SLI（Small Long as Int）编码（默认）
+#### SLI（Small Long as Int）编码，默认
-- 如果 long 在 `[-1073741824, 1073741823]` 范围内，编码为 4 字节 int：`| little-endian: ((int) value) << 1 |`
-- 否则写为 9 字节：`| 0b1 | little-endian 8bytes long |`
+- 如果 long 落在 `[-1073741824, 1073741823]` 范围内，则按 4 字节 int 编码：`| little-endian: ((int) value) << 1 |`
+- 否则写成 9 字节：`| 0b1 | little-endian 8bytes long |`
#### PVL（Progressive Variable-length Long）编码
-- 每个字节中的第一位表示是否有下一个字节。如果设置了第一位，则将读取下一个字节，直到下一个字节的第一位未设置。
-- 负数将通过 `(v << 1) ^ (v >> 63)` 转换为正数，以减少小负数的成本。
+- 每个字节的第一位表示后面是否还有下一个字节。如果第一位被置位，就继续读取下一个字节，直到某个字节的第一位未置位为止。
+- 负数会通过 `(v << 1) ^ (v >> 63)` 转换为正数，以降低小负数的编码成本。
-如果数字是 `long` 类型，但大多数情况下不能用较小的字节表示，压缩不会得到足够好的结果——与性能成本相比不值得。如果你发现它没有带来太多空间节省，也许你应该尝试禁用 long 压缩。
+如果一个数字虽然是 `long` 类型，但多数情况下并不能用更小字节数表示，那么压缩效果就不会理想，不值得承担对应的性能成本。如果你发现它没有带来明显的空间收益，可以考虑关闭 long 压缩。
## 数组压缩
-当数组值可以适配较小的数据类型时，Fory 支持原始数组（`int[]` 和 `long[]`）的 SIMD 加速压缩。此功能在 Java 16+ 上可用，并使用 Vector API 以获得最佳性能。
+当原始数组（`int[]` 和 `long[]`）中的值可以放入更小的数据类型时，Fory 支持使用 SIMD 加速的数组压缩。该特性要求 Java 16+，并借助 Vector API 获得最佳性能。
-### 数组压缩工作原理
+### 数组压缩如何工作
-数组压缩分析数组以确定值是否可以使用更少的字节存储：
+数组压缩会分析数组，判断这些值是否可以用更少字节存储：
-- **`int[]` → `byte[]`**：当所有值都在范围 [-128, 127] 内时（减少 75% 大小）
-- **`int[]` → `short[]`**：当所有值都在范围 [-32768, 32767] 内时（减少 50% 大小）
-- **`long[]` → `int[]`**：当所有值都适合整数范围时（减少 50% 大小）
+- **`int[]` → `byte[]`**：当所有值都落在 [-128, 127] 范围内时，体积减少 75%
+- **`int[]` → `short[]`**：当所有值都落在 [-32768, 32767] 范围内时，体积减少 50%
+- **`long[]` → `int[]`**：当所有值都可落入 int 范围时，体积减少 50%
-### 配置和注册
+### 配置与注册
-要启用数组压缩，你必须显式注册序列化器：
+要启用数组压缩，你必须显式注册对应的序列化器：
```java
Fory fory = Fory.builder()
@@ -76,7 +76,7 @@ Fory fory = Fory.builder()
CompressedArraySerializers.registerSerializers(fory);
```
-**注意**：必须在依赖项中包含 `fory-simd` 模块，压缩数组序列化器才可用。
+**注意**：要让压缩数组序列化器可用，依赖中必须包含 `fory-simd` 模块。
### Maven 依赖
@@ -84,13 +84,13 @@ CompressedArraySerializers.registerSerializers(fory);
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-simd</artifactId>
- <version>0.14.1</version>
+ <version>0.17.0</version>
</dependency>
```
## 字符串压缩
-字符串压缩可以通过 `ForyBuilder#withStringCompressed(true)` 启用。这默认是禁用的。
+字符串压缩可通过 `ForyBuilder#withStringCompressed(true)` 启用。该选项默认关闭。
## 配置摘要
@@ -98,28 +98,28 @@ CompressedArraySerializers.registerSerializers(fory);
| ------------------- | ----------------------------------- | ------- |
| `compressInt` | 启用 int 压缩 | `true` |
| `compressLong` | 启用 long 压缩 | `true` |
-| `compressIntArray` | 启用 SIMD int 数组压缩（Java 16+） | `true` |
-| `compressLongArray` | 启用 SIMD long 数组压缩（Java 16+） | `true` |
+| `compressIntArray` | 启用 SIMD int 数组压缩（Java 16+） | `false` |
+| `compressLongArray` | 启用 SIMD long 数组压缩（Java 16+） | `false` |
| `compressString` | 启用字符串压缩 | `false` |
-## 性能考虑
+## 性能注意事项
-1. **对数字密集型数据禁用压缩**：如果你的数据主要是数字，压缩开销可能不值得
-2. **数组压缩需要 Java 16+**：使用 Vector API 进行 SIMD 加速
-3. **Long 压缩可能对大值无用**：如果大多数 long 不能适配较小的表示，请禁用它
-4. **字符串压缩有开销**：仅在字符串高度可压缩时启用
+1. **数字密集型数据建议关闭压缩**：如果你的数据大多是数字，压缩开销可能并不划算。
+2. **数组压缩要求 Java 16+**：它依赖 Vector API 实现 SIMD 加速。
+3. **Long 压缩未必适合大数值**：如果多数 long 无法放进更小表示，请关闭它。
+4. **字符串压缩存在开销**：仅在字符串高度可压缩时启用。
## 示例配置
```java
-// 对于主要是数字的数据 - 禁用压缩
+// 主要是数字的数据：关闭压缩
Fory fory = Fory.builder()
.withLanguage(Language.JAVA)
.withIntCompressed(false)
.withLongCompressed(false)
.build();
-// 对于包含数组的混合数据 - 启用数组压缩
+// 包含数组的混合数据：启用数组压缩
Fory fory = Fory.builder()
.withLanguage(Language.JAVA)
.withIntCompressed(true)
@@ -132,5 +132,5 @@ CompressedArraySerializers.registerSerializers(fory);
## 相关主题
-- [配置选项](configuration.md) - 所有 ForyBuilder 选项
+- [配置](configuration.md) - 所有 ForyBuilder 选项
- [高级特性](advanced-features.md) - 内存管理
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/kotlin/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/kotlin/index.md
index 64841805c..2ef27d3f1 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/kotlin/index.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/kotlin/index.md
@@ -19,7 +19,7 @@ license: |
limitations under the License.
---
-Apache Fory™ Kotlin 基于 Fory Java 构建，为 Kotlin 类型提供了优化的序列化器。大多数标准 Kotlin 类型可以直接使用默认的 Fory Java 实现，而 Fory Kotlin 则为 Kotlin 特有的类型提供了额外的支持。
+Apache Fory™ Kotlin 基于 Fory Java 构建，为 Kotlin 类型提供优化的序列化器。大多数标准 Kotlin 类型都可以直接使用默认的 Fory Java 实现，而 Fory Kotlin 则为 Kotlin 特有类型补充了额外支持。
支持的类型包括：
@@ -27,20 +27,20 @@ Apache Fory™ Kotlin 基于 Fory Java 构建，为 Kotlin 类型提供了优化
- 无符号原始类型：`UByte`、`UShort`、`UInt`、`ULong`
- 无符号数组：`UByteArray`、`UShortArray`、`UIntArray`、`ULongArray`
- 标准库类型：`Pair`、`Triple`、`Result`
-- 范围：`IntRange`、`LongRange`、`CharRange` 以及等差数列
+- 范围：`IntRange`、`LongRange`、`CharRange` 以及各种 progression
- 集合：`ArrayDeque`、空集合（`emptyList`、`emptyMap`、`emptySet`）
- `kotlin.time.Duration`、`kotlin.text.Regex`、`kotlin.uuid.Uuid`
## 特性
-Fory Kotlin 继承了 Fory Java 的所有特性，并增加了 Kotlin 特定的优化：
+Fory Kotlin 继承了 Fory Java 的全部特性，并增加了 Kotlin 特定优化：
-- **高性能**：JIT 代码生成、零拷贝，比传统序列化快 20-170 倍
-- **Kotlin 类型支持**：为数据类、无符号类型、范围和标准库类型提供优化的序列化器
-- **默认值支持**：在 schema 演化期间自动处理 Kotlin 数据类的默认参数
-- **Schema 演化**：支持类 schema 变更的前向/后向兼容性
+- **高性能**：JIT 代码生成、零拷贝，性能可比传统序列化快 20 到 170 倍
+- **Kotlin 类型支持**：为数据类、无符号类型、范围和标准库类型提供优化序列化器
+- **默认值支持**：在 Schema 演进期间自动处理 Kotlin 数据类的默认参数
+- **Schema 演进**：支持类 Schema 变更时的前向和后向兼容
-完整特性列表请参阅 [Java 特性](../java/index.md#features)。
+完整特性列表请参见 [Java 特性](../java/index.md#features)。
## 安装
@@ -50,14 +50,14 @@ Fory Kotlin 继承了 Fory Java 的所有特性，并增加了 Kotlin 特定的
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-kotlin</artifactId>
- <version>0.14.1</version>
+ <version>0.17.0</version>
</dependency>
```
### Gradle
```kotlin
-implementation("org.apache.fory:fory-kotlin:0.14.1")
+implementation("org.apache.fory:fory-kotlin:0.17.0")
```
## 快速开始
@@ -71,7 +71,7 @@ data class Person(val name: String, val id: Long, val github: String)
data class Point(val x: Int, val y: Int, val z: Int)
fun main() {
- // 创建 Fory 实例（应该重用）
+ // 创建 Fory 实例（应复用）
val fory: ThreadSafeFory = Fory.builder()
.requireClassRegistration(true)
.buildThreadSafeFory()
@@ -91,18 +91,18 @@ fun main() {
## 基于 Fory Java 构建
-Fory Kotlin 基于 Fory Java 构建。Fory Java 的大多数配置选项、特性和概念直接适用于 Kotlin。请参阅 Java 文档了解：
+Fory Kotlin 基于 Fory Java 构建。Fory Java 中的大多数配置选项、特性和概念都可直接应用于 Kotlin。可参考 Java 文档了解：
-- [配置选项](../java/configuration.md) - 所有 ForyBuilder 选项
-- [基础序列化](../java/basic-serialization.md) - 序列化模式和 API
-- [类型注册](../java/type-registration.md) - 类注册和安全性
-- [Schema 演化](../java/schema-evolution.md) - 前向/后向兼容性
+- [配置](../java/configuration.md) - 所有 ForyBuilder 选项
+- [基础序列化](../java/basic-serialization.md) - 序列化模式与 API
+- [类型注册](../java/type-registration.md) - 类注册与安全性
+- [Schema 演进](../java/schema-evolution.md) - 前向和后向兼容
- [自定义序列化器](../java/custom-serializers.md) - 实现自定义序列化器
- [压缩](../java/compression.md) - Int、long 和字符串压缩
-- [故障排除](../java/troubleshooting.md) - 常见问题和解决方案
+- [故障排查](../java/troubleshooting.md) - 常见问题与解决方案
## Kotlin 特定文档
- [Fory 创建](fory-creation.md) - Kotlin 特定的 Fory 设置要求
-- [类型序列化](type-serialization.md) - 序列化 Kotlin 类型
+- [类型序列化](type-serialization.md) - Kotlin 类型的序列化
- [默认值](default-values.md) - Kotlin 数据类默认值支持
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/rust/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/rust/index.md
index 008da460b..c4893979c 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/rust/index.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/rust/index.md
@@ -19,27 +19,27 @@ license: |
limitations under the License.
---
-**Apache Fory™** 是一个极速的多语言序列化框架，基于 **JIT 编译**和**零拷贝**技术，在保持易用性和安全性的同时提供**超高性能**。
+**Apache Fory™** 是一个高性能的多语言序列化框架，基于 **JIT 编译**与**零拷贝**技术，在保持易用性和安全性的同时提供出色性能。
-Rust 实现提供多功能的高性能序列化，具有自动内存管理和编译时类型安全。
+Rust 实现提供灵活而高性能的序列化能力，具备自动内存管理与编译时类型安全。
## 为什么选择 Apache Fory™ Rust？
-- **🔥 极速性能**：零拷贝反序列化和优化的二进制协议
-- **🌍 跨语言**：在 Java、Python、C++、Go、JavaScript 和 Rust 之间无缝序列化/反序列化数据
-- **🎯 类型安全**：使用 derive macro 实现编译时类型检查
-- **🔄 循环引用**：使用 `Rc`/`Arc` 和弱指针自动跟踪共享引用和循环引用
-- **🧬 多态支持**：使用 `Box<dyn Trait>`、`Rc<dyn Trait>` 和 `Arc<dyn Trait>` 序列化 trait 对象
-- **📦 Schema 演化**：兼容模式支持独立的 schema 变更
-- **⚡ 双格式支持**：对象图序列化和零拷贝行格式
+- **高性能**：零拷贝反序列化与优化的二进制协议
+- **跨语言**：可在 Java、Python、C++、Go、JavaScript 和 Rust 之间无缝序列化与反序列化数据
+- **类型安全**：通过 derive macro 实现编译时类型检查
+- **循环引用**：借助 `Rc` / `Arc` 与弱指针自动跟踪共享引用和循环引用
+- **多态支持**：支持序列化 `Box<dyn Trait>`、`Rc<dyn Trait>` 和 `Arc<dyn Trait>` 等 trait 对象
+- **Schema 演进**：兼容模式支持独立的 Schema 变更
+- **双格式支持**：对象图序列化与零拷贝行格式
-## Crate 列表
+## Crate
-| Crate | 描述 | 版本 |
-| --------------------------------------------------------------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------- |
-| [`fory`](https://github.com/apache/fory/blob/main/rust/fory) | 带有 derive macro 的高级 API | [](https://crates.io/crates/fory) |
-| [`fory-core`](https://github.com/apache/fory/blob/main/rust/fory-core/) | 核心序列化引擎 | [](https://crates.io/crates/fory-core) |
-| [`fory-derive`](https://github.com/apache/fory/blob/main/rust/fory-derive/) | 过程宏 | [](https://crates.io/crates/fory-derive) |
+| Crate | 说明 | 版本 |
+| --------------------------------------------------------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------- |
+| [`fory`](https://github.com/apache/fory/blob/main/rust/fory) | 带 derive macro 的高级 API | [](https://crates.io/crates/fory) |
+| [`fory-core`](https://github.com/apache/fory/blob/main/rust/fory-core/) | 核心序列化引擎 | [](https://crates.io/crates/fory-core) |
+| [`fory-derive`](https://github.com/apache/fory/blob/main/rust/fory-derive/) | 过程宏 | [](https://crates.io/crates/fory-derive) |
## 快速开始
@@ -47,7 +47,7 @@ Rust 实现提供多功能的高性能序列化，具有自动内存管理和编
```toml
[dependencies]
-fory = "0.14"
+fory = "0.17.0"
```
### 基础示例
@@ -92,7 +92,7 @@ fn main() -> Result<(), Error> {
## 线程安全
-Apache Fory™ Rust 是完全线程安全的：`Fory` 同时实现了 `Send` 和 `Sync`，因此一个配置好的实例可以在多个线程之间共享以进行并发工作。内部的读/写上下文池是使用线程安全原语延迟初始化的，让工作线程可以重用缓冲区而无需协调。
+Apache Fory™ Rust 完全线程安全：`Fory` 同时实现了 `Send` 和 `Sync`，因此一个配置好的实例可以在线程之间共享并发使用。内部读写上下文池通过线程安全原语延迟初始化，使工作线程无需额外协调即可复用缓冲区。
```rust
use fory::{Fory, Error};
@@ -130,22 +130,22 @@ fn main() -> Result<(), Error> {
}
```
-**提示：** 在生成线程之前执行注册操作（例如 `fory.register::<T>(id)`），以便每个工作线程看到相同的元数据。配置完成后，将实例包装在 `Arc` 中就足以安全地分发序列化和反序列化任务。
+**提示：** 请在启动线程之前完成注册操作，例如 `fory.register::<T>(id)`，确保每个工作线程看到一致的元数据。配置完成后，将实例包在 `Arc` 中即可安全地分发序列化和反序列化任务。
## 架构
Rust 实现由三个主要 crate 组成：
-```
+```text
fory/ # 高级 API
├── src/lib.rs # 公共 API 导出
fory-core/ # 核心序列化引擎
├── src/
-│ ├── fory.rs # 主序列化入口点
+│ ├── fory.rs # 主序列化入口
│ ├── buffer.rs # 二进制缓冲区管理
│ ├── serializer/ # 类型特定序列化器
-│ ├── resolver/ # 类型解析和元数据
+│ ├── resolver/ # 类型解析与元数据
│ ├── meta/ # 元字符串压缩
│ ├── row/ # 行格式实现
│ └── types.rs # 类型定义
@@ -153,32 +153,32 @@ fory-core/ # 核心序列化引擎
fory-derive/ # 过程宏
├── src/
│ ├── object/ # ForyObject 宏
-│ └── fory_row.rs # ForyRow 宏
+│ └── fory_row.rs # ForyRow 宏
```
## 使用场景
### 对象序列化
-- 包含嵌套对象和引用的复杂数据结构
+- 含嵌套对象和引用的复杂数据结构
- 微服务中的跨语言通信
-- 具有完整类型安全的通用序列化
-- 使用兼容模式的 schema 演化
-- 具有循环引用的图形数据结构
+- 具备完整类型安全的通用序列化
+- 使用兼容模式进行 Schema 演进
+- 带循环引用的图状数据结构
### 行格式序列化
-- 高吞吐量数据处理
-- 需要快速字段访问的分析工作负载
+- 高吞吐数据处理
+- 需要快速字段访问的分析型负载
- 内存受限环境
- 实时数据流应用
- 零拷贝场景
## 后续步骤
-- [配置](configuration.md) - Fory 构建器选项和模式
+- [配置](configuration.md) - Fory 构建器选项与模式
- [基础序列化](basic-serialization.md) - 对象图序列化
-- [引用](references.md) - 共享引用和循环引用
+- [引用](references.md) - 共享引用与循环引用
- [多态](polymorphism.md) - Trait 对象序列化
- [跨语言](cross-language.md) - XLANG 模式
- [行格式](row-format.md) - 零拷贝行格式
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/scala/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/scala/index.md
index 3ca3b3fc5..036470ce2 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/scala/index.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/scala/index.md
@@ -19,36 +19,36 @@ license: |
limitations under the License.
---
-Apache Fory™ Scala 为 Scala 类型提供优化的序列化器，构建在 Fory Java 之上。它支持所有 Scala 对象序列化：
+Apache Fory™ Scala 基于 Fory Java 构建，为 Scala 类型提供优化的序列化器。它支持完整的 Scala 对象序列化，包括：
- `case` 类序列化
- `pojo/bean` 类序列化
- `object` 单例序列化
- `collection` 序列化（Seq、List、Map 等）
-- `tuple` 和 `either` 类型
+- `tuple` 与 `either` 类型
- `Option` 类型
-- Scala 2 和 3 枚举
+- Scala 2 和 Scala 3 枚举
同时支持 Scala 2 和 Scala 3。
## 特性
-Fory Scala 继承了 Fory Java 的所有特性，并增加了 Scala 特定的优化：
+Fory Scala 继承了 Fory Java 的全部特性，并增加了 Scala 特定优化：
-- **高性能**：JIT 代码生成、零拷贝、比传统序列化快 20-170 倍
-- **Scala 类型支持**：为 case 类、单例、集合、元组、Option、Either 提供优化的序列化器
-- **默认值支持**：在 schema 演化期间自动处理 Scala 类的默认参数
-- **单例保持**：`object` 单例在反序列化后保持引用相等性
-- **Schema 演化**：支持类 schema 变更的前向/后向兼容性
+- **高性能**：JIT 代码生成、零拷贝，性能可比传统序列化快 20 到 170 倍
+- **Scala 类型支持**：为 case 类、单例、集合、tuple、Option、Either 提供优化序列化器
+- **默认值支持**：在 Schema 演进期间自动处理 Scala 类的默认参数
+- **单例保持**：`object` 单例在反序列化后仍保持引用相等性
+- **Schema 演进**：支持类 Schema 变更时的前向和后向兼容
-查看 [Java 特性](../java/index.md#features)获取完整特性列表。
+完整特性列表请参见 [Java 特性](../java/index.md#features)。
## 安装
使用 sbt 添加依赖：
```sbt
-libraryDependencies += "org.apache.fory" %% "fory-scala" % "0.14.1"
+libraryDependencies += "org.apache.fory" %% "fory-scala" % "0.17.0"
```
## 快速开始
@@ -81,20 +81,20 @@ object ScalaExample {
}
```
-## 构建于 Fory Java 之上
+## 基于 Fory Java 构建
-Fory Scala 构建在 Fory Java 之上。大多数配置选项、特性和概念都直接适用于 Scala。请参考 Java 文档：
+Fory Scala 基于 Fory Java 构建。Fory Java 中的大多数配置选项、特性和概念都可直接应用于 Scala。可参考 Java 文档了解：
-- [配置选项](../java/configuration.md) - 所有 ForyBuilder 选项
-- [基础序列化](../java/basic-serialization.md) - 序列化模式和 API
-- [类型注册](../java/type-registration.md) - 类注册和安全性
-- [Schema 演化](../java/schema-evolution.md) - 前向/后向兼容性
+- [配置](../java/configuration.md) - 所有 ForyBuilder 选项
+- [基础序列化](../java/basic-serialization.md) - 序列化模式与 API
+- [类型注册](../java/type-registration.md) - 类注册与安全性
+- [Schema 演进](../java/schema-evolution.md) - 前向和后向兼容
- [自定义序列化器](../java/custom-serializers.md) - 实现自定义序列化器
-- [压缩](../java/compression.md) - Int、long 和 string 压缩
-- [故障排查](../java/troubleshooting.md) - 常见问题和解决方案
+- [压缩](../java/compression.md) - Int、long 和字符串压缩
+- [故障排查](../java/troubleshooting.md) - 常见问题与解决方案
## Scala 特定文档
- [Fory 创建](fory-creation.md) - Scala 特定的 Fory 设置要求
-- [类型序列化](type-serialization.md) - 序列化 Scala 类型
+- [类型序列化](type-serialization.md) - Scala 类型的序列化
- [默认值](default-values.md) - Scala 类默认值支持
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/xlang/getting-started.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/xlang/getting-started.md
index 3a708f1d2..a93f386c4 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/xlang/getting-started.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/xlang/getting-started.md
@@ -1,7 +1,7 @@
---
title: 入门指南
-sidebar_position: 1
-id: xlang_getting_started
+sidebar_position: 10
+id: getting_started
license: |
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
@@ -19,7 +19,7 @@ license: |
limitations under the License.
---
-本指南涵盖了所有支持语言的跨语言序列化安装和基本设置。
+本指南介绍所有受支持语言中跨语言序列化的安装与基础设置。
## 安装
@@ -31,14 +31,14 @@ license: |
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-core</artifactId>
- <version>0.14.1</version>
+ <version>0.17.0</version>
</dependency>
```
**Gradle：**
```gradle
-implementation 'org.apache.fory:fory-core:0.14.1'
+implementation 'org.apache.fory:fory-core:0.17.0'
```
### Python
@@ -57,7 +57,7 @@ go get github.com/apache/fory/go/fory
```toml
[dependencies]
-fory = "0.14"
+fory = "0.17.0"
```
### JavaScript
@@ -68,11 +68,11 @@ npm install @apache-fory/fory
### C++
-使用 Bazel 或 CMake 从源代码构建。有关详细信息，请参阅 [C++ 指南](../cpp/index.md)。
+使用 Bazel 或 CMake 从源码构建。详见 [C++ 指南](../cpp/index.md)。
## 启用跨语言模式
-每种语言都需要启用 xlang 模式以确保跨语言的二进制兼容性。
+每种语言都需要启用 xlang 模式，以确保跨语言之间的二进制兼容性。
### Java
@@ -91,11 +91,11 @@ Fory fory = Fory.builder()
```python
import pyfory
-# xlang 模式默认启用
-fory = pyfory.Fory()
+# 必须显式启用跨语言模式
+fory = pyfory.Fory(xlang=True)
-# 显式配置
-fory = pyfory.Fory(ref_tracking=True)
+# 需要时启用引用跟踪
+fory = pyfory.Fory(xlang=True, ref=True)
```
### Go
@@ -103,9 +103,9 @@ fory = pyfory.Fory(ref_tracking=True)
```go
import forygo "github.com/apache/fory/go/fory"
-fory := forygo.NewFory()
+fory := forygo.NewFory(forygo.WithXlang(true))
// 或启用引用跟踪
-fory := forygo.NewFory(true)
+fory := forygo.NewFory(forygo.WithXlang(true), forygo.WithTrackRef(true))
```
### Rust
@@ -113,7 +113,7 @@ fory := forygo.NewFory(true)
```rust
use fory::Fory;
-let fory = Fory::default();
+let fory = Fory::default().xlang(true);
```
### JavaScript
@@ -138,11 +138,11 @@ auto fory = Fory::builder()
## 类型注册
-自定义类型必须在所有语言中使用一致的名称或 ID 进行注册。
+自定义类型必须在所有语言中使用一致的名称或 ID 注册。
### 按名称注册（推荐）
-使用字符串名称更灵活，不易产生冲突：
+使用字符串名称更灵活，也更不容易发生冲突：
**Java：**
@@ -159,18 +159,24 @@ fory.register_type(Person, typename="example.Person")
**Go：**
```go
-fory.RegisterNamedType(Person{}, "example.Person")
+fory.RegisterNamedStruct(Person{}, "example.Person")
```
**Rust：**
```rust
-#[derive(Fory)]
-#[tag("example.Person")]
+use fory::{Fory, ForyObject};
+
+#[derive(ForyObject)]
struct Person {
name: String,
age: i32,
}
+
+let mut fory = Fory::default().xlang(true);
+fory
+ .register_by_namespace::<Person>("example", "Person")
+ .expect("register Person");
```
**JavaScript：**
@@ -193,7 +199,7 @@ fory.register_struct<Person>("example.Person");
### 按 ID 注册
-使用数字 ID 更快，生成的二进制输出更小：
+使用数字 ID 速度更快，并且生成的二进制输出更小：
**Java：**
@@ -210,7 +216,7 @@ fory.register_type(Person, type_id=100)
**Go：**
```go
-fory.Register(Person{}, 100)
+fory.RegisterStruct(Person{}, 100)
```
**C++：**
@@ -223,9 +229,9 @@ fory.register_struct<Person>(100);
## Hello World 示例
-一个完整的示例，展示了在 Java 中序列化并在 Python 中反序列化：
+下面给出一个完整示例，展示如何在 Java 中序列化、在 Python 中反序列化：
-### Java（序列化器）
+### Java（序列化端）
```java
import org.apache.fory.*;
@@ -255,7 +261,7 @@ public class HelloWorld {
}
```
-### Python（反序列化器）
+### Python（反序列化端）
```python
import pyfory
@@ -266,7 +272,7 @@ class Person:
name: str
age: pyfory.Int32Type
-fory = pyfory.Fory()
+fory = pyfory.Fory(xlang=True)
fory.register_type(Person, typename="example.Person")
with open("person.bin", "rb") as f:
@@ -274,19 +280,19 @@ with open("person.bin", "rb") as f:
person = fory.deserialize(data)
print(f"Name: {person.name}, Age: {person.age}")
-# 输出: Name: Alice, Age: 30
+# Output: Name: Alice, Age: 30
```
## 最佳实践
-1. **使用一致的类型名称**：确保所有语言使用相同的类型名称或 ID
-2. **启用引用跟踪**：如果数据包含循环引用或共享引用
-3. **重用 Fory 实例**：创建 Fory 的成本较高；应重用实例
-4. **使用类型注解**：在 Python 中，使用 `pyfory.Int32Type` 等进行精确类型映射
-5. **测试跨语言**：验证序列化在所有目标语言中都能正常工作
+1. **使用一致的类型名**：确保所有语言使用相同的类型名或 ID。
+2. **启用引用跟踪**：如果你的数据包含循环引用或共享引用。
+3. **复用 Fory 实例**：创建 Fory 的成本较高，应尽量复用实例。
+4. **使用类型注解**：在 Python 中使用 `pyfory.Int32Type` 等精确类型映射。
+5. **测试跨语言链路**：验证序列化结果在所有目标语言之间都能正确工作。
## 后续步骤
-- [类型映射](https://fory.apache.org/docs/specification/xlang_type_mapping) - 跨语言类型映射参考
-- [序列化](serialization.md) - 详细的序列化示例
-- [故障排查](troubleshooting.md) - 常见问题及解决方案
+- [类型映射](../../specification/xlang_type_mapping.md) - 跨语言类型映射参考
+- [序列化](serialization.md) - 更详细的序列化示例
+- [故障排查](troubleshooting.md) - 常见问题与解决方案
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/install.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/install.md
index 2adeffddb..2a6c85ced 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/install.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/install.md
@@ -1,6 +1,6 @@
---
id: install
-title: 安装 Apache Fory™
+title: 安装
sidebar_position: 0
---
@@ -16,22 +16,22 @@ Apache Fory™ 同时提供源码发布物和各语言对应的软件包。
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-core</artifactId>
- <version>0.16.0</version>
+ <version>0.17.0</version>
</dependency>
-<!-- 可选：row format 支持 -->
+<!-- 可选的 row format 支持 -->
<!--
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-format</artifactId>
- <version>0.16.0</version>
+ <version>0.17.0</version>
</dependency>
-->
-<!-- 可选：数组压缩 SIMD 加速（Java 16+） -->
+<!-- 用于数组压缩的 SIMD 加速（Java 16+） -->
<!--
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-simd</artifactId>
- <version>0.16.0</version>
+ <version>0.17.0</version>
</dependency>
-->
```
@@ -44,7 +44,7 @@ Scala 2.13 的 Maven 依赖：
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-scala_2.13</artifactId>
- <version>0.16.0</version>
+ <version>0.17.0</version>
</dependency>
```
@@ -54,20 +54,20 @@ Scala 3 的 Maven 依赖：
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-scala_3</artifactId>
- <version>0.16.0</version>
+ <version>0.17.0</version>
</dependency>
```
Scala 2.13 的 sbt 依赖：
```sbt
-libraryDependencies += "org.apache.fory" % "fory-scala_2.13" % "0.16.0"
+libraryDependencies += "org.apache.fory" % "fory-scala_2.13" % "0.17.0"
```
Scala 3 的 sbt 依赖：
```sbt
-libraryDependencies += "org.apache.fory" % "fory-scala_3" % "0.16.0"
+libraryDependencies += "org.apache.fory" % "fory-scala_3" % "0.17.0"
```
## Kotlin
@@ -78,7 +78,7 @@ libraryDependencies += "org.apache.fory" % "fory-scala_3" % "0.16.0"
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-kotlin</artifactId>
- <version>0.16.0</version>
+ <version>0.17.0</version>
</dependency>
```
@@ -86,7 +86,7 @@ libraryDependencies += "org.apache.fory" % "fory-scala_3" % "0.16.0"
```bash
python -m pip install --upgrade pip
-pip install pyfory==0.16.0
+pip install pyfory==0.17.0
```
## Go
@@ -94,27 +94,27 @@ pip install pyfory==0.16.0
请使用完整的 Go 模块路径 `github.com/apache/fory/go/fory`：
```bash
-go get github.com/apache/fory/go/fory@v0.16.0
+go get github.com/apache/fory/go/fory@v0.17.0
```
-如果你的 Go proxy 还没有同步到新的子模块 tag，可以稍后重试，或者临时使用 `GOPROXY=direct`。
+如果你的 Go proxy 还没有同步新的子模块 tag，请稍后重试，或者临时使用 `GOPROXY=direct`。
## Rust
```toml
[dependencies]
-fory = "0.16.0"
+fory = "0.17.0"
```
或者使用 `cargo add`：
```bash
-cargo add fory@0.16.0
+cargo add fory@0.17.0
```
## JavaScript
-Apache Fory 的 JavaScript 包目前还没有发布到 npm。
+JavaScript 包尚未发布到 npm。
目前请先从源码安装并构建：
@@ -125,9 +125,9 @@ npm install
npm run build
```
-完成源码构建后，再在你的项目或 workspace 中使用 `@apache-fory/core`，并按需启用 `@apache-fory/hps`。
+完成源码构建后，再在你的项目或 workspace 配置中使用 `@apache-fory/core`，并按需启用 `@apache-fory/hps`。
-可选的原生加速模块需要 Node.js 20+：
+可选的原生加速需要 Node.js 20+：
```bash
cd packages/hps
@@ -136,15 +136,15 @@ npm run build
## C\#
-安装 `Apache.Fory` NuGet 包。它同时包含运行时和 `[ForyObject]` 类型所需的源代码生成器。
+安装 `Apache.Fory` NuGet 包。它同时包含运行时以及 `[ForyObject]` 类型所需的源代码生成器。
```bash
-dotnet add package Apache.Fory --version 0.16.0
+dotnet add package Apache.Fory --version 0.17.0
```
```xml
<ItemGroup>
- <PackageReference Include="Apache.Fory" Version="0.16.0" />
+ <PackageReference Include="Apache.Fory" Version="0.17.0" />
</ItemGroup>
```
@@ -154,7 +154,7 @@ dotnet add package Apache.Fory --version 0.16.0
```swift
dependencies: [
- .package(url: "https://github.com/apache/fory.git", exact: "0.16.0")
+ .package(url: "https://github.com/apache/fory.git", exact: "0.17.0")
],
targets: [
.target(
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@fory.apache.org
For additional commands, e-mail: commits-help@fory.apache.org
(fory-site) 07/09: Create docs snapshot for 0.17
Posted by ch...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
chaokunyang pushed a commit to branch release_0.17.0
in repository https://gitbox.apache.org/repos/asf/fory-site.git
commit 6f871be75db9b7e7d51bc6619570cc8bdedc5343
Author: 慕白 <ch...@antgroup.com>
AuthorDate: Sun Apr 19 23:29:47 2026 +0800
Create docs snapshot for 0.17
---
docusaurus.config.ts | 3 +-
.../version-0.17/.keep | 0
.../version-0.17/benchmarks/cpp/README.md | 60 +
.../version-0.17/benchmarks/cpp/REPORT.md | 116 ++
.../version-0.17/benchmarks/cpp/mediacontent.png | Bin 0 -> 51863 bytes
.../benchmarks/cpp/mediacontentlist.png | Bin 0 -> 54504 bytes
.../version-0.17/benchmarks/cpp/sample.png | Bin 0 -> 48714 bytes
.../version-0.17/benchmarks/cpp/samplelist.png | Bin 0 -> 51686 bytes
.../version-0.17/benchmarks/cpp/struct.png | Bin 0 -> 47309 bytes
.../version-0.17/benchmarks/cpp/structlist.png | Bin 0 -> 48428 bytes
.../version-0.17/benchmarks/cpp/throughput.png | Bin 0 -> 73763 bytes
.../version-0.17/benchmarks/csharp/README.md | 129 ++
.../benchmarks/csharp/mediacontent.png | Bin 0 -> 53148 bytes
.../benchmarks/csharp/mediacontentlist.png | Bin 0 -> 52044 bytes
.../version-0.17/benchmarks/csharp/sample.png | Bin 0 -> 51280 bytes
.../version-0.17/benchmarks/csharp/samplelist.png | Bin 0 -> 55993 bytes
.../version-0.17/benchmarks/csharp/struct.png | Bin 0 -> 53639 bytes
.../version-0.17/benchmarks/csharp/structlist.png | Bin 0 -> 47081 bytes
.../version-0.17/benchmarks/csharp/throughput.png | Bin 0 -> 77537 bytes
.../version-0.17/benchmarks/dart/README.md | 73 +
.../version-0.17/benchmarks/dart/mediacontent.png | Bin 0 -> 52584 bytes
.../benchmarks/dart/mediacontentlist.png | Bin 0 -> 55357 bytes
.../version-0.17/benchmarks/dart/sample.png | Bin 0 -> 42105 bytes
.../version-0.17/benchmarks/dart/samplelist.png | Bin 0 -> 51598 bytes
.../version-0.17/benchmarks/dart/struct.png | Bin 0 -> 38645 bytes
.../version-0.17/benchmarks/dart/structlist.png | Bin 0 -> 44541 bytes
.../version-0.17/benchmarks/dart/throughput.png | Bin 0 -> 89092 bytes
.../version-0.17/benchmarks/go/README.md | 58 +
.../benchmarks/go/benchmark_combined.png | Bin 0 -> 193421 bytes
.../benchmarks/go/benchmark_mediacontent.png | Bin 0 -> 63179 bytes
.../benchmarks/go/benchmark_mediacontentlist.png | Bin 0 -> 75245 bytes
.../version-0.17/benchmarks/go/benchmark_report.md | 84 ++
.../benchmarks/go/benchmark_results.json | 184 +++
.../benchmarks/go/benchmark_results.txt | 326 +++++
.../benchmarks/go/benchmark_sample.png | Bin 0 -> 64836 bytes
.../benchmarks/go/benchmark_samplelist.png | Bin 0 -> 70519 bytes
.../benchmarks/go/benchmark_struct.png | Bin 0 -> 65532 bytes
.../benchmarks/go/benchmark_structlist.png | Bin 0 -> 63835 bytes
.../benchmarks/go/serialized_sizes.txt | 27 +
.../version-0.17/benchmarks/java/README.md | 239 ++++
.../java/data/jmh-jdk-11-deserialization.csv | 153 ++
.../java/data/jmh-jdk-11-serialization.csv | 153 ++
.../benchmarks/java/data/jmh-jdk-11-zerocopy.csv | 73 +
.../java/java_heap_deserialize_compatible.png | Bin 0 -> 99247 bytes
.../java/java_heap_deserialize_consistent.png | Bin 0 -> 107832 bytes
.../java/java_heap_serialize_compatible.png | Bin 0 -> 108196 bytes
.../java/java_heap_serialize_consistent.png | Bin 0 -> 106382 bytes
.../java/java_offheap_deserialize_compatible.png | Bin 0 -> 104602 bytes
.../java/java_offheap_deserialize_consistent.png | Bin 0 -> 108056 bytes
.../java/java_offheap_serialize_compatible.png | Bin 0 -> 119826 bytes
.../java/java_offheap_serialize_consistent.png | Bin 0 -> 121717 bytes
.../java/java_repo_deserialization_throughput.png | Bin 0 -> 116455 bytes
.../java/java_repo_serialization_throughput.png | Bin 0 -> 124190 bytes
.../benchmarks/java/java_zero_copy_deserialize.png | Bin 0 -> 98312 bytes
.../benchmarks/java/java_zero_copy_serialize.png | Bin 0 -> 98680 bytes
.../version-0.17/benchmarks/javascript/README.md | 104 ++
.../benchmarks/javascript/mediacontent.png | Bin 0 -> 55168 bytes
.../benchmarks/javascript/mediacontentlist.png | Bin 0 -> 56815 bytes
.../version-0.17/benchmarks/javascript/sample.png | Bin 0 -> 57185 bytes
.../benchmarks/javascript/samplelist.png | Bin 0 -> 57215 bytes
.../version-0.17/benchmarks/javascript/struct.png | Bin 0 -> 50777 bytes
.../benchmarks/javascript/structlist.png | Bin 0 -> 54735 bytes
.../benchmarks/javascript/throughput.png | Bin 0 -> 81947 bytes
.../version-0.17/benchmarks/python/README.md | 127 ++
.../benchmarks/python/mediacontent.png | Bin 0 -> 49948 bytes
.../benchmarks/python/mediacontentlist.png | Bin 0 -> 57263 bytes
.../version-0.17/benchmarks/python/sample.png | Bin 0 -> 53682 bytes
.../version-0.17/benchmarks/python/samplelist.png | Bin 0 -> 60171 bytes
.../version-0.17/benchmarks/python/struct.png | Bin 0 -> 54218 bytes
.../version-0.17/benchmarks/python/structlist.png | Bin 0 -> 52290 bytes
.../version-0.17/benchmarks/python/throughput.png | Bin 0 -> 79016 bytes
.../version-0.17/benchmarks/rust/README.md | 104 ++
.../version-0.17/benchmarks/rust/company.png | Bin 0 -> 44643 bytes
.../benchmarks/rust/ecommerce_data.png | Bin 0 -> 44956 bytes
.../version-0.17/benchmarks/rust/mediacontent.png | Bin 0 -> 54130 bytes
.../benchmarks/rust/mediacontentlist.png | Bin 0 -> 54154 bytes
.../version-0.17/benchmarks/rust/person.png | Bin 0 -> 40224 bytes
.../version-0.17/benchmarks/rust/sample.png | Bin 0 -> 44641 bytes
.../version-0.17/benchmarks/rust/samplelist.png | Bin 0 -> 46992 bytes
.../version-0.17/benchmarks/rust/simple_list.png | Bin 0 -> 39423 bytes
.../version-0.17/benchmarks/rust/simple_map.png | Bin 0 -> 45555 bytes
.../version-0.17/benchmarks/rust/simple_struct.png | Bin 0 -> 43007 bytes
.../version-0.17/benchmarks/rust/struct.png | Bin 0 -> 49558 bytes
.../version-0.17/benchmarks/rust/structlist.png | Bin 0 -> 45987 bytes
.../version-0.17/benchmarks/rust/system_data.png | Bin 0 -> 41417 bytes
.../version-0.17/benchmarks/rust/throughput.png | Bin 0 -> 75422 bytes
.../version-0.17/benchmarks/swift/README.md | 46 +
.../version-0.17/benchmarks/swift/throughput.png | Bin 0 -> 84759 bytes
.../version-0.17/community/community.md | 85 ++
.../community/how_to_join_community.md | 108 ++
.../version-0.17/community/how_to_release.md | 431 ++++++
.../version-0.17/community/how_to_verify.md | 119 ++
.../version-0.17/compiler/_category_.json | 6 +
.../version-0.17/compiler/compiler-guide.md | 655 +++++++++
.../version-0.17/compiler/flatbuffers-idl.md | 183 +++
.../version-0.17/compiler/generated-code.md | 714 ++++++++++
.../version-0.17/compiler/index.md | 212 +++
.../version-0.17/compiler/protobuf-idl.md | 321 +++++
.../version-0.17/compiler/schema-idl.md | 737 ++++++++++
.../version-0.17/guide/DEVELOPMENT.md | 146 ++
.../version-0.17/guide/_category_.json | 1 +
.../version-0.17/guide/cpp/_category_.json | 6 +
.../version-0.17/guide/cpp/basic-serialization.md | 238 ++++
.../version-0.17/guide/cpp/configuration.md | 189 +++
.../version-0.17/guide/cpp/cross-language.md | 271 ++++
.../version-0.17/guide/cpp/custom-serializers.md | 371 +++++
.../version-0.17/guide/cpp/field-configuration.md | 504 +++++++
.../version-0.17/guide/cpp/index.md | 264 ++++
.../version-0.17/guide/cpp/polymorphism.md | 480 +++++++
.../version-0.17/guide/cpp/row-format.md | 516 +++++++
.../version-0.17/guide/cpp/schema-evolution.md | 404 ++++++
.../version-0.17/guide/cpp/supported-types.md | 277 ++++
.../version-0.17/guide/cpp/type-registration.md | 225 +++
.../version-0.17/guide/csharp/index.md | 104 ++
.../version-0.17/guide/dart/_category_.json | 6 +
.../version-0.17/guide/dart/basic-serialization.md | 144 ++
.../version-0.17/guide/dart/code-generation.md | 113 ++
.../version-0.17/guide/dart/configuration.md | 121 ++
.../version-0.17/guide/dart/cross-language.md | 193 +++
.../version-0.17/guide/dart/custom-serializers.md | 139 ++
.../version-0.17/guide/dart/field-configuration.md | 127 ++
.../version-0.17/guide/dart/index.md | 141 ++
.../version-0.17/guide/dart/schema-evolution.md | 92 ++
.../version-0.17/guide/dart/supported-types.md | 102 ++
.../version-0.17/guide/dart/troubleshooting.md | 103 ++
.../version-0.17/guide/dart/type-registration.md | 98 ++
.../version-0.17/guide/go/_category_.json | 6 +
.../version-0.17/guide/go/basic-serialization.md | 404 ++++++
.../version-0.17/guide/go/codegen.md | 420 ++++++
.../version-0.17/guide/go/configuration.md | 339 +++++
.../version-0.17/guide/go/cross-language.md | 280 ++++
.../version-0.17/guide/go/custom-serializers.md | 285 ++++
.../version-0.17/guide/go/index.md | 164 +++
.../version-0.17/guide/go/references.md | 356 +++++
.../version-0.17/guide/go/schema-evolution.md | 340 +++++
.../version-0.17/guide/go/struct-tags.md | 335 +++++
.../version-0.17/guide/go/supported-types.md | 369 +++++
.../version-0.17/guide/go/thread-safety.md | 347 +++++
.../version-0.17/guide/go/troubleshooting.md | 448 ++++++
.../version-0.17/guide/go/type-registration.md | 260 ++++
.../version-0.17/guide/graalvm_guide.md | 318 +++++
.../version-0.17/guide/java/_category_.json | 6 +
.../version-0.17/guide/java/advanced-features.md | 208 +++
.../version-0.17/guide/java/basic-serialization.md | 137 ++
.../version-0.17/guide/java/compression.md | 136 ++
.../version-0.17/guide/java/configuration.md | 77 +
.../version-0.17/guide/java/cross-language.md | 231 +++
.../version-0.17/guide/java/custom-serializers.md | 659 +++++++++
.../version-0.17/guide/java/enum-configuration.md | 104 ++
.../version-0.17/guide/java/field-configuration.md | 605 ++++++++
.../version-0.17/guide/java/index.md | 193 +++
.../version-0.17/guide/java/migration.md | 120 ++
.../version-0.17/guide/java/row-format.md | 183 +++
.../version-0.17/guide/java/schema-evolution.md | 215 +++
.../version-0.17/guide/java/troubleshooting.md | 213 +++
.../version-0.17/guide/java/type-registration.md | 112 ++
.../version-0.17/guide/java/virtual-threads.md | 114 ++
.../version-0.17/guide/javascript/_category_.json | 6 +
.../guide/javascript/basic-serialization.md | 219 +++
.../guide/javascript/cross-language.md | 128 ++
.../version-0.17/guide/javascript/index.md | 141 ++
.../version-0.17/guide/javascript/references.md | 111 ++
.../guide/javascript/schema-evolution.md | 99 ++
.../guide/javascript/supported-types.md | 177 +++
.../guide/javascript/troubleshooting.md | 105 ++
.../guide/javascript/type-registration.md | 200 +++
.../version-0.17/guide/kotlin/_category_.json | 6 +
.../version-0.17/guide/kotlin/default-values.md | 137 ++
.../version-0.17/guide/kotlin/fory-creation.md | 116 ++
.../version-0.17/guide/kotlin/index.md | 108 ++
.../guide/kotlin/type-serialization.md | 184 +++
.../version-0.17/guide/python/_category_.json | 6 +
.../guide/python/basic-serialization.md | 145 ++
.../version-0.17/guide/python/configuration.md | 181 +++
.../version-0.17/guide/python/cross-language.md | 140 ++
.../guide/python/custom-serializers.md | 146 ++
.../guide/python/field-configuration.md | 492 +++++++
.../version-0.17/guide/python/index.md | 160 +++
.../version-0.17/guide/python/migration.md | 85 ++
.../version-0.17/guide/python/numpy-integration.md | 103 ++
.../version-0.17/guide/python/out-of-band.md | 179 +++
.../version-0.17/guide/python/python-native.md | 205 +++
.../version-0.17/guide/python/row-format.md | 169 +++
.../version-0.17/guide/python/schema-evolution.md | 77 +
.../version-0.17/guide/python/security.md | 150 ++
.../version-0.17/guide/python/troubleshooting.md | 186 +++
.../version-0.17/guide/python/type-registration.md | 146 ++
.../version-0.17/guide/rust/_category_.json | 6 +
.../version-0.17/guide/rust/basic-serialization.md | 166 +++
.../version-0.17/guide/rust/configuration.md | 125 ++
.../version-0.17/guide/rust/cross-language.md | 165 +++
.../version-0.17/guide/rust/custom-serializers.md | 147 ++
.../version-0.17/guide/rust/field-configuration.md | 460 ++++++
.../version-0.17/guide/rust/index.md | 184 +++
.../version-0.17/guide/rust/polymorphism.md | 232 +++
.../version-0.17/guide/rust/references.md | 213 +++
.../version-0.17/guide/rust/row-format.md | 126 ++
.../version-0.17/guide/rust/schema-evolution.md | 204 +++
.../version-0.17/guide/rust/troubleshooting.md | 164 +++
.../version-0.17/guide/rust/type-registration.md | 126 ++
.../version-0.17/guide/scala/_category_.json | 6 +
.../version-0.17/guide/scala/default-values.md | 186 +++
.../version-0.17/guide/scala/fory-creation.md | 139 ++
.../version-0.17/guide/scala/index.md | 100 ++
.../version-0.17/guide/scala/type-serialization.md | 171 +++
.../version-0.17/guide/xlang/_category_.json | 6 +
.../version-0.17/guide/xlang/field-nullability.md | 251 ++++
.../guide/xlang/field-reference-tracking.md | 260 ++++
.../version-0.17/guide/xlang/field-type-meta.md | 301 ++++
.../version-0.17/guide/xlang/getting-started.md | 298 ++++
.../version-0.17/guide/xlang/index.md | 125 ++
.../version-0.17/guide/xlang/row_format.md | 190 +++
.../version-0.17/guide/xlang/serialization.md | 542 +++++++
.../version-0.17/guide/xlang/troubleshooting.md | 321 +++++
.../version-0.17/guide/xlang/type-mapping.md | 113 ++
.../version-0.17/guide/xlang/zero-copy.md | 207 +++
.../version-0.17/introduction/_category_.json | 1 +
.../version-0.17/introduction/benchmark.md | 90 ++
.../version-0.17/introduction/features.md | 210 +++
.../version-0.17/introduction/overview.md | 200 +++
.../version-0.17/start/_category_.json | 1 +
.../version-0.17/start/install.md | 167 +++
.../version-0.17/start/usage.md | 595 ++++++++
.../version-0.17/benchmarks/cpp/README.md | 104 ++
.../version-0.17/benchmarks/cpp/REPORT.md | 116 ++
.../version-0.17/benchmarks/cpp/mediacontent.png | Bin 0 -> 52226 bytes
.../benchmarks/cpp/mediacontentlist.png | Bin 0 -> 57111 bytes
.../version-0.17/benchmarks/cpp/sample.png | Bin 0 -> 55251 bytes
.../version-0.17/benchmarks/cpp/samplelist.png | Bin 0 -> 53909 bytes
.../version-0.17/benchmarks/cpp/struct.png | Bin 0 -> 51352 bytes
.../version-0.17/benchmarks/cpp/structlist.png | Bin 0 -> 53820 bytes
.../version-0.17/benchmarks/cpp/throughput.png | Bin 0 -> 78902 bytes
.../version-0.17/benchmarks/csharp/README.md | 115 ++
.../benchmarks/csharp/mediacontent.png | Bin 0 -> 53148 bytes
.../benchmarks/csharp/mediacontentlist.png | Bin 0 -> 52044 bytes
.../version-0.17/benchmarks/csharp/sample.png | Bin 0 -> 51280 bytes
.../version-0.17/benchmarks/csharp/samplelist.png | Bin 0 -> 55993 bytes
.../version-0.17/benchmarks/csharp/struct.png | Bin 0 -> 53639 bytes
.../version-0.17/benchmarks/csharp/structlist.png | Bin 0 -> 47081 bytes
.../version-0.17/benchmarks/csharp/throughput.png | Bin 0 -> 77537 bytes
.../version-0.17/benchmarks/dart/README.md | 73 +
.../version-0.17/benchmarks/dart/mediacontent.png | Bin 0 -> 52584 bytes
.../benchmarks/dart/mediacontentlist.png | Bin 0 -> 55357 bytes
.../version-0.17/benchmarks/dart/sample.png | Bin 0 -> 42105 bytes
.../version-0.17/benchmarks/dart/samplelist.png | Bin 0 -> 51598 bytes
.../version-0.17/benchmarks/dart/struct.png | Bin 0 -> 38645 bytes
.../version-0.17/benchmarks/dart/structlist.png | Bin 0 -> 44541 bytes
.../version-0.17/benchmarks/dart/throughput.png | Bin 0 -> 89092 bytes
.../version-0.17/benchmarks/go/README.md | 58 +
.../benchmarks/go/benchmark_combined.png | Bin 0 -> 193421 bytes
.../benchmarks/go/benchmark_mediacontent.png | Bin 0 -> 63179 bytes
.../benchmarks/go/benchmark_mediacontentlist.png | Bin 0 -> 75245 bytes
.../benchmarks/go/benchmark_results.txt | 326 +++++
.../benchmarks/go/benchmark_sample.png | Bin 0 -> 64836 bytes
.../benchmarks/go/benchmark_samplelist.png | Bin 0 -> 70519 bytes
.../benchmarks/go/benchmark_struct.png | Bin 0 -> 65532 bytes
.../benchmarks/go/benchmark_structlist.png | Bin 0 -> 63835 bytes
.../benchmarks/go/serialized_sizes.txt | 27 +
.../version-0.17/benchmarks/java/README.md | 239 ++++
.../java/data/jmh-jdk-11-deserialization.csv | 153 ++
.../java/data/jmh-jdk-11-serialization.csv | 153 ++
.../benchmarks/java/data/jmh-jdk-11-zerocopy.csv | 73 +
.../java/java_heap_deserialize_compatible.png | Bin 0 -> 95479 bytes
.../java/java_heap_deserialize_consistent.png | Bin 0 -> 104022 bytes
.../java/java_heap_serialize_compatible.png | Bin 0 -> 104969 bytes
.../java/java_heap_serialize_consistent.png | Bin 0 -> 102858 bytes
.../java/java_offheap_deserialize_compatible.png | Bin 0 -> 100158 bytes
.../java/java_offheap_deserialize_consistent.png | Bin 0 -> 104245 bytes
.../java/java_offheap_serialize_compatible.png | Bin 0 -> 115647 bytes
.../java/java_offheap_serialize_consistent.png | Bin 0 -> 117336 bytes
.../java/java_repo_deserialization_throughput.png | Bin 0 -> 112116 bytes
.../java/java_repo_serialization_throughput.png | Bin 0 -> 120005 bytes
.../benchmarks/java/java_zero_copy_deserialize.png | Bin 0 -> 93509 bytes
.../benchmarks/java/java_zero_copy_serialize.png | Bin 0 -> 94327 bytes
.../version-0.17/benchmarks/javascript/README.md | 104 ++
.../benchmarks/javascript/mediacontent.png | Bin 0 -> 55168 bytes
.../benchmarks/javascript/mediacontentlist.png | Bin 0 -> 56815 bytes
.../version-0.17/benchmarks/javascript/sample.png | Bin 0 -> 57185 bytes
.../benchmarks/javascript/samplelist.png | Bin 0 -> 57215 bytes
.../version-0.17/benchmarks/javascript/struct.png | Bin 0 -> 50777 bytes
.../benchmarks/javascript/structlist.png | Bin 0 -> 54735 bytes
.../benchmarks/javascript/throughput.png | Bin 0 -> 81947 bytes
.../version-0.17/benchmarks/python/README.md | 113 ++
.../benchmarks/python/mediacontent.png | Bin 0 -> 51723 bytes
.../benchmarks/python/mediacontentlist.png | Bin 0 -> 56440 bytes
.../version-0.17/benchmarks/python/sample.png | Bin 0 -> 47563 bytes
.../version-0.17/benchmarks/python/samplelist.png | Bin 0 -> 48300 bytes
.../version-0.17/benchmarks/python/struct.png | Bin 0 -> 53286 bytes
.../version-0.17/benchmarks/python/structlist.png | Bin 0 -> 50022 bytes
.../version-0.17/benchmarks/python/throughput.png | Bin 0 -> 74287 bytes
.../version-0.17/benchmarks/rust/README.md | 103 ++
.../version-0.17/benchmarks/rust/company.png | Bin 0 -> 44643 bytes
.../benchmarks/rust/ecommerce_data.png | Bin 0 -> 44956 bytes
.../version-0.17/benchmarks/rust/mediacontent.png | Bin 0 -> 54130 bytes
.../benchmarks/rust/mediacontentlist.png | Bin 0 -> 54154 bytes
.../version-0.17/benchmarks/rust/person.png | Bin 0 -> 40224 bytes
.../version-0.17/benchmarks/rust/sample.png | Bin 0 -> 44641 bytes
.../version-0.17/benchmarks/rust/samplelist.png | Bin 0 -> 46992 bytes
.../version-0.17/benchmarks/rust/simple_list.png | Bin 0 -> 39423 bytes
.../version-0.17/benchmarks/rust/simple_map.png | Bin 0 -> 45555 bytes
.../version-0.17/benchmarks/rust/simple_struct.png | Bin 0 -> 43007 bytes
.../version-0.17/benchmarks/rust/struct.png | Bin 0 -> 49558 bytes
.../version-0.17/benchmarks/rust/structlist.png | Bin 0 -> 45987 bytes
.../version-0.17/benchmarks/rust/system_data.png | Bin 0 -> 41417 bytes
.../version-0.17/benchmarks/rust/throughput.png | Bin 0 -> 75422 bytes
.../version-0.17/benchmarks/swift/README.md | 44 +
.../version-0.17/benchmarks/swift/throughput.png | Bin 0 -> 84759 bytes
versioned_docs/version-0.17/community/community.md | 90 ++
.../community/how_to_join_community.md | 105 ++
.../version-0.17/community/how_to_release.md | 645 +++++++++
.../version-0.17/community/how_to_verify.md | 125 ++
.../version-0.17/compiler/_category_.json | 6 +
.../version-0.17/compiler/compiler-guide.md | 805 +++++++++++
.../version-0.17/compiler/flatbuffers-idl.md | 199 +++
.../version-0.17/compiler/generated-code.md | 1040 ++++++++++++++
versioned_docs/version-0.17/compiler/index.md | 217 +++
.../version-0.17/compiler/protobuf-idl.md | 336 +++++
versioned_docs/version-0.17/compiler/schema-idl.md | 1492 ++++++++++++++++++++
versioned_docs/version-0.17/guide/DEVELOPMENT.md | 131 ++
versioned_docs/version-0.17/guide/_category_.json | 4 +
.../version-0.17/guide/cpp/_category_.json | 6 +
.../version-0.17/guide/cpp/basic-serialization.md | 305 ++++
.../version-0.17/guide/cpp/configuration.md | 189 +++
.../version-0.17/guide/cpp/cross-language.md | 271 ++++
.../version-0.17/guide/cpp/custom-serializers.md | 371 +++++
.../version-0.17/guide/cpp/field-configuration.md | 568 ++++++++
versioned_docs/version-0.17/guide/cpp/index.md | 266 ++++
.../version-0.17/guide/cpp/polymorphism.md | 480 +++++++
.../version-0.17/guide/cpp/row-format.md | 512 +++++++
.../version-0.17/guide/cpp/schema-evolution.md | 416 ++++++
.../version-0.17/guide/cpp/supported-types.md | 278 ++++
.../version-0.17/guide/cpp/type-registration.md | 226 +++
.../version-0.17/guide/csharp/_category_.json | 6 +
.../guide/csharp/basic-serialization.md | 131 ++
.../version-0.17/guide/csharp/configuration.md | 125 ++
.../version-0.17/guide/csharp/cross-language.md | 107 ++
.../guide/csharp/custom-serializers.md | 84 ++
.../guide/csharp/field-configuration.md | 75 +
versioned_docs/version-0.17/guide/csharp/index.md | 104 ++
.../version-0.17/guide/csharp/references.md | 72 +
.../version-0.17/guide/csharp/schema-evolution.md | 90 ++
.../version-0.17/guide/csharp/supported-types.md | 97 ++
.../version-0.17/guide/csharp/thread-safety.md | 73 +
.../version-0.17/guide/csharp/troubleshooting.md | 94 ++
.../version-0.17/guide/csharp/type-registration.md | 82 ++
.../version-0.17/guide/dart/_category_.json | 6 +
.../version-0.17/guide/dart/basic-serialization.md | 144 ++
.../version-0.17/guide/dart/code-generation.md | 113 ++
.../version-0.17/guide/dart/configuration.md | 121 ++
.../version-0.17/guide/dart/cross-language.md | 193 +++
.../version-0.17/guide/dart/custom-serializers.md | 139 ++
.../version-0.17/guide/dart/field-configuration.md | 127 ++
versioned_docs/version-0.17/guide/dart/index.md | 141 ++
.../version-0.17/guide/dart/schema-evolution.md | 92 ++
.../version-0.17/guide/dart/supported-types.md | 102 ++
.../version-0.17/guide/dart/troubleshooting.md | 103 ++
.../version-0.17/guide/dart/type-registration.md | 98 ++
.../version-0.17/guide/go/_category_.json | 6 +
.../version-0.17/guide/go/basic-serialization.md | 404 ++++++
versioned_docs/version-0.17/guide/go/codegen.md | 430 ++++++
.../version-0.17/guide/go/configuration.md | 344 +++++
.../version-0.17/guide/go/cross-language.md | 282 ++++
.../version-0.17/guide/go/custom-serializers.md | 285 ++++
versioned_docs/version-0.17/guide/go/index.md | 157 ++
versioned_docs/version-0.17/guide/go/references.md | 356 +++++
.../version-0.17/guide/go/schema-evolution.md | 354 +++++
.../version-0.17/guide/go/struct-tags.md | 373 +++++
.../version-0.17/guide/go/supported-types.md | 369 +++++
.../version-0.17/guide/go/thread-safety.md | 347 +++++
.../version-0.17/guide/go/troubleshooting.md | 448 ++++++
.../version-0.17/guide/go/type-registration.md | 264 ++++
versioned_docs/version-0.17/guide/graalvm_guide.md | 329 +++++
.../version-0.17/guide/java/_category_.json | 6 +
.../version-0.17/guide/java/advanced-features.md | 209 +++
.../version-0.17/guide/java/basic-serialization.md | 127 ++
.../version-0.17/guide/java/compression.md | 136 ++
.../version-0.17/guide/java/configuration.md | 79 ++
.../version-0.17/guide/java/cross-language.md | 231 +++
.../version-0.17/guide/java/custom-serializers.md | 227 +++
.../version-0.17/guide/java/enum-configuration.md | 111 ++
.../version-0.17/guide/java/field-configuration.md | 607 ++++++++
versioned_docs/version-0.17/guide/java/index.md | 210 +++
.../version-0.17/guide/java/migration.md | 120 ++
.../version-0.17/guide/java/row-format.md | 181 +++
.../version-0.17/guide/java/schema-evolution.md | 231 +++
.../version-0.17/guide/java/troubleshooting.md | 203 +++
.../version-0.17/guide/java/type-registration.md | 117 ++
.../version-0.17/guide/java/virtual-threads.md | 127 ++
.../version-0.17/guide/javascript/_category_.json | 6 +
.../guide/javascript/basic-serialization.md | 244 ++++
.../guide/javascript/cross-language.md | 128 ++
.../version-0.17/guide/javascript/index.md | 141 ++
.../version-0.17/guide/javascript/references.md | 111 ++
.../guide/javascript/schema-evolution.md | 99 ++
.../guide/javascript/supported-types.md | 177 +++
.../guide/javascript/troubleshooting.md | 105 ++
.../guide/javascript/type-registration.md | 200 +++
.../version-0.17/guide/kotlin/_category_.json | 6 +
.../version-0.17/guide/kotlin/default-values.md | 137 ++
.../version-0.17/guide/kotlin/fory-creation.md | 112 ++
versioned_docs/version-0.17/guide/kotlin/index.md | 108 ++
.../guide/kotlin/type-serialization.md | 184 +++
.../version-0.17/guide/python/_category_.json | 6 +
.../guide/python/basic-serialization.md | 145 ++
.../version-0.17/guide/python/configuration.md | 183 +++
.../version-0.17/guide/python/cross-language.md | 140 ++
.../guide/python/custom-serializers.md | 138 ++
.../guide/python/field-configuration.md | 492 +++++++
versioned_docs/version-0.17/guide/python/index.md | 160 +++
.../version-0.17/guide/python/migration.md | 85 ++
.../version-0.17/guide/python/numpy-integration.md | 103 ++
.../version-0.17/guide/python/out-of-band.md | 179 +++
.../version-0.17/guide/python/python-native.md | 205 +++
.../version-0.17/guide/python/row-format.md | 167 +++
.../version-0.17/guide/python/schema-evolution.md | 98 ++
.../version-0.17/guide/python/security.md | 150 ++
.../version-0.17/guide/python/troubleshooting.md | 186 +++
.../version-0.17/guide/python/type-registration.md | 146 ++
.../version-0.17/guide/rust/_category_.json | 6 +
.../version-0.17/guide/rust/basic-serialization.md | 166 +++
.../version-0.17/guide/rust/configuration.md | 125 ++
.../version-0.17/guide/rust/cross-language.md | 165 +++
.../version-0.17/guide/rust/custom-serializers.md | 153 ++
.../version-0.17/guide/rust/field-configuration.md | 460 ++++++
versioned_docs/version-0.17/guide/rust/index.md | 184 +++
.../version-0.17/guide/rust/polymorphism.md | 232 +++
.../version-0.17/guide/rust/references.md | 213 +++
.../version-0.17/guide/rust/row-format.md | 126 ++
.../version-0.17/guide/rust/schema-evolution.md | 218 +++
.../version-0.17/guide/rust/troubleshooting.md | 164 +++
.../version-0.17/guide/rust/type-registration.md | 126 ++
.../version-0.17/guide/scala/_category_.json | 6 +
.../version-0.17/guide/scala/default-values.md | 186 +++
.../version-0.17/guide/scala/fory-creation.md | 136 ++
versioned_docs/version-0.17/guide/scala/index.md | 100 ++
.../version-0.17/guide/scala/type-serialization.md | 171 +++
.../version-0.17/guide/swift/_category_.json | 6 +
.../guide/swift/basic-serialization.md | 114 ++
.../version-0.17/guide/swift/configuration.md | 100 ++
.../version-0.17/guide/swift/cross-language.md | 97 ++
.../version-0.17/guide/swift/custom-serializers.md | 84 ++
.../guide/swift/field-configuration.md | 92 ++
versioned_docs/version-0.17/guide/swift/index.md | 84 ++
.../version-0.17/guide/swift/polymorphism.md | 80 ++
.../version-0.17/guide/swift/references.md | 111 ++
.../version-0.17/guide/swift/row-format.md | 38 +
.../version-0.17/guide/swift/schema-evolution.md | 77 +
.../version-0.17/guide/swift/troubleshooting.md | 92 ++
.../version-0.17/guide/swift/type-registration.md | 76 +
.../version-0.17/guide/xlang/_category_.json | 6 +
.../version-0.17/guide/xlang/field-nullability.md | 250 ++++
.../guide/xlang/field-reference-tracking.md | 264 ++++
.../version-0.17/guide/xlang/field-type-meta.md | 301 ++++
.../version-0.17/guide/xlang/getting-started.md | 298 ++++
versioned_docs/version-0.17/guide/xlang/index.md | 162 +++
.../version-0.17/guide/xlang/row_format.md | 190 +++
.../version-0.17/guide/xlang/serialization.md | 548 +++++++
.../version-0.17/guide/xlang/troubleshooting.md | 302 ++++
.../version-0.17/guide/xlang/zero-copy.md | 209 +++
.../version-0.17/introduction/_category_.json | 4 +
.../version-0.17/introduction/benchmark.md | 96 ++
.../version-0.17/introduction/features.md | 210 +++
.../version-0.17/introduction/overview.md | 200 +++
.../specification/java_serialization_spec.md | 485 +++++++
.../version-0.17/specification/row_format_spec.md | 540 +++++++
.../specification/xlang_implementation_guide.md | 439 ++++++
.../specification/xlang_serialization_spec.md | 1464 +++++++++++++++++++
.../specification/xlang_type_mapping.md | 145 ++
versioned_docs/version-0.17/start/_category_.json | 4 +
versioned_docs/version-0.17/start/install.md | 167 +++
versioned_docs/version-0.17/start/usage.md | 595 ++++++++
versioned_sidebars/version-0.17-sidebars.json | 64 +
versions.json | 1 +
473 files changed, 66438 insertions(+), 2 deletions(-)
diff --git a/docusaurus.config.ts b/docusaurus.config.ts
index 970d8d0fc..4eacdbdfd 100644
--- a/docusaurus.config.ts
+++ b/docusaurus.config.ts
@@ -38,7 +38,7 @@ const config: Config = {
{
docs: {
sidebarCollapsible: true,
- lastVersion: '0.16',
+ lastVersion: '0.17',
versions: {
current: {
label: 'dev',
@@ -279,4 +279,3 @@ const config: Config = {
};
export default config;
-
diff --git a/i18n/en-US/docusaurus-plugin-content-docs/version-0.17/.keep b/i18n/en-US/docusaurus-plugin-content-docs/version-0.17/.keep
new file mode 100644
index 000000000..e69de29bb
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/cpp/README.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/cpp/README.md
new file mode 100644
index 000000000..a2be4452e
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/cpp/README.md
@@ -0,0 +1,60 @@
+# C++ 基准性能报告
+
+_生成时间：2025-12-15 23:03:06_
+
+## 如何生成本报告
+
+```bash
+cd benchmarks/cpp_benchmark/build
+./fory_benchmark --benchmark_format=json --benchmark_out=benchmark_results.json
+cd ..
+python benchmark_report.py --json-file build/benchmark_results.json --output-dir report
+```
+
+## 硬件与系统信息
+
+| Key | Value |
+| -------------------------- | ------------------------- |
+| OS | Darwin 24.6.0 |
+| Machine | arm64 |
+| Processor | arm |
+| CPU Cores (Physical) | 12 |
+| CPU Cores (Logical) | 12 |
+| Total RAM (GB) | 48.0 |
+| Benchmark Date | 2025-12-15T23:02:49+08:00 |
+| CPU Cores (from benchmark) | 12 |
+
+## 基准图表
+
+
+
+## 基准结果
+
+### 耗时结果（纳秒）
+
+| Datatype | Operation | Fory (ns) | Protobuf (ns) | Faster |
+| ------------ | ----------- | --------- | ------------- | ----------- |
+| Mediacontent | Serialize | 443.5 | 1982.5 | Fory (4.5x) |
+| Mediacontent | Deserialize | 1349.0 | 2525.2 | Fory (1.9x) |
+| Sample | Serialize | 235.4 | 309.7 | Fory (1.3x) |
+| Sample | Deserialize | 1068.7 | 1397.0 | Fory (1.3x) |
+| Struct | Serialize | 109.4 | 170.0 | Fory (1.6x) |
+| Struct | Deserialize | 129.1 | 161.2 | Fory (1.2x) |
+
+### 吞吐结果（ops/sec）
+
+| Datatype | Operation | Fory TPS | Protobuf TPS | Faster |
+| ------------ | ----------- | --------- | ------------ | ----------- |
+| Mediacontent | Serialize | 2,254,915 | 504,410 | Fory (4.5x) |
+| Mediacontent | Deserialize | 741,303 | 396,013 | Fory (1.9x) |
+| Sample | Serialize | 4,248,973 | 3,229,102 | Fory (1.3x) |
+| Sample | Deserialize | 935,709 | 715,837 | Fory (1.3x) |
+| Struct | Serialize | 9,143,618 | 5,881,005 | Fory (1.6x) |
+| Struct | Deserialize | 7,746,787 | 6,202,164 | Fory (1.2x) |
+
+### 序列化数据大小（字节）
+
+| Datatype | Fory | Protobuf |
+| -------- | ---- | -------- |
+| Struct | 32 | 61 |
+| Sample | 384 | 375 |
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/cpp/REPORT.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/cpp/REPORT.md
new file mode 100644
index 000000000..cb2ed0a96
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/cpp/REPORT.md
@@ -0,0 +1,116 @@
+# C++ 基准性能报告
+
+_生成时间：2026-02-06 20:01:02_
+
+## 如何生成本报告
+
+```bash
+cd benchmarks/cpp_benchmark/build
+./fory_benchmark --benchmark_format=json --benchmark_out=benchmark_results.json
+cd ..
+python benchmark_report.py --json-file build/benchmark_results.json --output-dir report
+```
+
+## 硬件与系统信息
+
+| Key | Value |
+| -------------------------- | ------------------------- |
+| OS | Darwin 24.6.0 |
+| Machine | arm64 |
+| Processor | arm |
+| CPU Cores (Physical) | 12 |
+| CPU Cores (Logical) | 12 |
+| Total RAM (GB) | 48.0 |
+| Benchmark Date | 2026-02-06T20:00:20+08:00 |
+| CPU Cores (from benchmark) | 12 |
+
+## 基准图表
+
+### Mediacontent
+
+<p align="center">
+<img src="mediacontent.png" width="90%" />
+</p>
+
+### Mediacontentlist
+
+<p align="center">
+<img src="mediacontentlist.png" width="90%" />
+</p>
+
+### Sample
+
+<p align="center">
+<img src="sample.png" width="90%" />
+</p>
+
+### Samplelist
+
+<p align="center">
+<img src="samplelist.png" width="90%" />
+</p>
+
+### Struct
+
+<p align="center">
+<img src="struct.png" width="90%" />
+</p>
+
+### Structlist
+
+<p align="center">
+<img src="structlist.png" width="90%" />
+</p>
+
+### Throughput
+
+<p align="center">
+<img src="throughput.png" width="90%" />
+</p>
+
+## 基准结果
+
+### 耗时结果（纳秒）
+
+| Datatype | Operation | Fory (ns) | Protobuf (ns) | Faster |
+| ---------------- | ----------- | --------- | ------------- | ------------ |
+| Mediacontent | Serialize | 512.0 | 1990.9 | Fory (3.9x) |
+| Mediacontent | Deserialize | 1674.1 | 2516.6 | Fory (1.5x) |
+| Mediacontentlist | Serialize | 2261.0 | 10804.2 | Fory (4.8x) |
+| Mediacontentlist | Deserialize | 6943.5 | 13375.9 | Fory (1.9x) |
+| Sample | Serialize | 241.7 | 309.4 | Fory (1.3x) |
+| Sample | Deserialize | 1055.8 | 1361.5 | Fory (1.3x) |
+| Samplelist | Serialize | 963.2 | 11716.7 | Fory (12.2x) |
+| Samplelist | Deserialize | 5295.9 | 12162.2 | Fory (2.3x) |
+| Struct | Serialize | 117.1 | 169.6 | Fory (1.4x) |
+| Struct | Deserialize | 138.6 | 156.2 | Fory (1.1x) |
+| Structlist | Serialize | 308.4 | 1299.4 | Fory (4.2x) |
+| Structlist | Deserialize | 706.2 | 1188.0 | Fory (1.7x) |
+
+### 吞吐结果（ops/sec）
+
+| Datatype | Operation | Fory TPS | Protobuf TPS | Faster |
+| ---------------- | ----------- | --------- | ------------ | ------------ |
+| Mediacontent | Serialize | 1,952,940 | 502,295 | Fory (3.9x) |
+| Mediacontent | Deserialize | 597,343 | 397,356 | Fory (1.5x) |
+| Mediacontentlist | Serialize | 442,277 | 92,557 | Fory (4.8x) |
+| Mediacontentlist | Deserialize | 144,020 | 74,761 | Fory (1.9x) |
+| Sample | Serialize | 4,138,037 | 3,232,073 | Fory (1.3x) |
+| Sample | Deserialize | 947,188 | 734,472 | Fory (1.3x) |
+| Samplelist | Serialize | 1,038,236 | 85,348 | Fory (12.2x) |
+| Samplelist | Deserialize | 188,825 | 82,222 | Fory (2.3x) |
+| Struct | Serialize | 8,542,313 | 5,896,325 | Fory (1.4x) |
+| Struct | Deserialize | 7,217,541 | 6,403,969 | Fory (1.1x) |
+| Structlist | Serialize | 3,242,105 | 769,562 | Fory (4.2x) |
+| Structlist | Deserialize | 1,416,005 | 841,739 | Fory (1.7x) |
+
+### 序列化数据大小（字节）
+
+| Datatype | Fory | Protobuf |
+| ---------------- | ---- | -------- |
+| Struct | 58 | 61 |
+| Sample | 446 | 375 |
+| MediaContent | 365 | 301 |
+| StructList | 184 | 315 |
+| SampleList | 1980 | 1890 |
+| MediaContentList | 1535 | 1520 |
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/cpp/mediacontent.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/cpp/mediacontent.png
new file mode 100644
index 000000000..3c42b14f3
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/cpp/mediacontent.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/cpp/mediacontentlist.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/cpp/mediacontentlist.png
new file mode 100644
index 000000000..604663b68
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/cpp/mediacontentlist.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/cpp/sample.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/cpp/sample.png
new file mode 100644
index 000000000..2932de24b
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/cpp/sample.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/cpp/samplelist.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/cpp/samplelist.png
new file mode 100644
index 000000000..6d903f53c
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/cpp/samplelist.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/cpp/struct.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/cpp/struct.png
new file mode 100644
index 000000000..94209b375
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/cpp/struct.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/cpp/structlist.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/cpp/structlist.png
new file mode 100644
index 000000000..fe2dca4ca
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/cpp/structlist.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/cpp/throughput.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/cpp/throughput.png
new file mode 100644
index 000000000..1aa86b16b
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/cpp/throughput.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/csharp/README.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/csharp/README.md
new file mode 100644
index 000000000..d613c04eb
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/csharp/README.md
@@ -0,0 +1,129 @@
+# C# 基准性能报告
+
+_生成于 2026-03-11 02:14:01_
+
+## 如何生成本报告
+
+```bash
+cd benchmarks/csharp
+dotnet run -c Release --project ./Fory.CSharpBenchmark.csproj -- --output build/benchmark_results.json
+python3 benchmark_report.py --json-file build/benchmark_results.json --output-dir report
+```
+
+## 硬件与操作系统信息
+
+| 键 | 值 |
+| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| 操作系统 | Darwin 24.6.0 Darwin Kernel Version 24.6.0: Wed Oct 15 21:12:15 PDT 2025; root:xnu-11417.140.69.703.14~1/RELEASE_ARM64_T6041 |
+| 系统架构 | Arm64 |
+| 机器架构 | Arm64 |
+| 运行时版本 | 8.0.24 |
+| 基准日期（UTC） | 2026-03-10T18:14:00.0852460Z |
+| 预热秒数 | 1 |
+| 持续秒数 | 3 |
+| CPU 逻辑核心数（基准采集） | 12 |
+| CPU 核心数（物理） | 12 |
+| CPU 核心数（逻辑） | 12 |
+| 总内存（GB） | 48.0 |
+
+## 基准覆盖范围
+
+| 键 | 值 |
+| ------------------- | ---------------------------------------------------------------------- |
+| 输入 JSON 中的用例 | 36 / 36 |
+| 序列化器 | fory, msgpack, protobuf |
+| 数据类型 | struct, sample, mediacontent, structlist, samplelist, mediacontentlist |
+| 操作 | serialize, deserialize |
+
+## 基准图表
+
+下列各类图表均展示吞吐量（ops/sec）。
+
+### 总吞吐量
+
+<p align="center">
+<img src="throughput.png" width="90%" />
+</p>
+
+### `MediaContent` 基准
+
+<p align="center">
+<img src="mediacontent.png" width="90%" />
+</p>
+
+### `MediaContentList` 基准
+
+<p align="center">
+<img src="mediacontentlist.png" width="90%" />
+</p>
+
+### Sample
+
+<p align="center">
+<img src="sample.png" width="90%" />
+</p>
+
+### Samplelist
+
+<p align="center">
+<img src="samplelist.png" width="90%" />
+</p>
+
+### Struct
+
+<p align="center">
+<img src="struct.png" width="90%" />
+</p>
+
+### Structlist
+
+<p align="center">
+<img src="structlist.png" width="90%" />
+</p>
+
+## 基准结果
+
+### 延迟结果（纳秒）
+
+| 数据类型 | 操作 | fory (ns) | protobuf (ns) | msgpack (ns) | 最快 |
+| ---------------- | ----------- | --------- | ------------- | ------------ | ------- |
+| Struct | Serialize | 39.2 | 121.5 | 66.0 | fory |
+| Struct | Deserialize | 58.3 | 180.1 | 102.6 | fory |
+| Sample | Serialize | 269.2 | 562.6 | 339.6 | fory |
+| Sample | Deserialize | 175.6 | 1084.9 | 531.8 | fory |
+| MediaContent | Serialize | 306.3 | 434.7 | 351.5 | fory |
+| MediaContent | Deserialize | 379.4 | 718.8 | 676.9 | fory |
+| StructList | Serialize | 136.1 | 468.5 | 266.9 | fory |
+| StructList | Deserialize | 221.1 | 687.0 | 488.5 | fory |
+| SampleList | Serialize | 1198.9 | 2811.9 | 1635.7 | fory |
+| SampleList | Deserialize | 791.5 | 5174.5 | 2629.2 | fory |
+| MediaContentList | Serialize | 1393.9 | 2199.4 | 1710.9 | fory |
+| MediaContentList | Deserialize | 1719.5 | 3373.1 | 3401.2 | fory |
+
+### 吞吐结果（ops/sec）
+
+| 数据类型 | 操作 | fory TPS | protobuf TPS | msgpack TPS | 最快 |
+| ---------------- | ----------- | ---------- | ------------ | ----------- | ------- |
+| Struct | Serialize | 25,535,535 | 8,233,006 | 15,153,903 | fory |
+| Struct | Deserialize | 17,164,793 | 5,553,220 | 9,745,096 | fory |
+| Sample | Serialize | 3,715,302 | 1,777,405 | 2,944,981 | fory |
+| Sample | Deserialize | 5,696,108 | 921,760 | 1,880,420 | fory |
+| MediaContent | Serialize | 3,264,890 | 2,300,297 | 2,845,038 | fory |
+| MediaContent | Deserialize | 2,635,449 | 1,391,138 | 1,477,346 | fory |
+| StructList | Serialize | 7,347,503 | 2,134,576 | 3,746,866 | fory |
+| StructList | Deserialize | 4,522,114 | 1,455,557 | 2,046,988 | fory |
+| SampleList | Serialize | 834,086 | 355,633 | 611,365 | fory |
+| SampleList | Deserialize | 1,263,450 | 193,254 | 380,338 | fory |
+| MediaContentList | Serialize | 717,408 | 454,670 | 584,497 | fory |
+| MediaContentList | Deserialize | 581,554 | 296,459 | 294,015 | fory |
+
+### 序列化数据大小（字节）
+
+| 数据类型 | fory | protobuf | msgpack |
+| ---------------- | ---- | -------- | ------- |
+| Struct | 58 | 61 | 55 |
+| Sample | 446 | 460 | 562 |
+| MediaContent | 365 | 307 | 479 |
+| StructList | 184 | 315 | 284 |
+| SampleList | 1980 | 2315 | 2819 |
+| MediaContentList | 1535 | 1550 | 2404 |
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/csharp/mediacontent.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/csharp/mediacontent.png
new file mode 100644
index 000000000..052229ba8
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/csharp/mediacontent.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/csharp/mediacontentlist.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/csharp/mediacontentlist.png
new file mode 100644
index 000000000..81854b876
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/csharp/mediacontentlist.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/csharp/sample.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/csharp/sample.png
new file mode 100644
index 000000000..77ccabc0c
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/csharp/sample.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/csharp/samplelist.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/csharp/samplelist.png
new file mode 100644
index 000000000..93a9c5018
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/csharp/samplelist.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/csharp/struct.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/csharp/struct.png
new file mode 100644
index 000000000..39e32751b
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/csharp/struct.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/csharp/structlist.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/csharp/structlist.png
new file mode 100644
index 000000000..792559337
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/csharp/structlist.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/csharp/throughput.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/csharp/throughput.png
new file mode 100644
index 000000000..77b696c9b
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/csharp/throughput.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/dart/README.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/dart/README.md
new file mode 100644
index 000000000..090c930bf
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/dart/README.md
@@ -0,0 +1,73 @@
+# Fory Dart Benchmark
+
+This benchmark compares serialization and deserialization throughput for Apache Fory and Protocol Buffers in Dart.
+
+## Hardware and Runtime Info
+
+| Key | Value |
+| --------------------- | ---------------------------------------------------------------- |
+| Timestamp | 2026-04-13T21:55:28.456625Z |
+| OS | Version 26.2 (Build 25C56) |
+| Host | Macbook-Air.local |
+| CPU Cores (Logical) | 8 |
+| Memory (GB) | 8.00 |
+| Dart | 3.10.4 (stable) (Tue Dec 9 00:01:55 2025 -0800) on "macos_arm64" |
+| Samples per case | 5 |
+| Warmup per case (s) | 1.0 |
+| Duration per case (s) | 1.5 |
+
+## Throughput Results
+
+
+
+| Datatype | Operation | Fory TPS | Protobuf TPS | Fastest |
+| ---------------- | ----------- | --------: | -----------: | ------------ |
+| Struct | Serialize | 3,989,432 | 1,884,653 | fory (2.12x) |
+| Struct | Deserialize | 5,828,197 | 4,199,680 | fory (1.39x) |
+| Sample | Serialize | 1,649,722 | 500,167 | fory (3.30x) |
+| Sample | Deserialize | 2,060,113 | 785,109 | fory (2.62x) |
+| MediaContent | Serialize | 800,876 | 391,235 | fory (2.05x) |
+| MediaContent | Deserialize | 1,315,115 | 683,533 | fory (1.92x) |
+| StructList | Serialize | 1,456,396 | 367,506 | fory (3.96x) |
+| StructList | Deserialize | 1,921,006 | 645,958 | fory (2.97x) |
+| SampleList | Serialize | 411,144 | 48,508 | fory (8.48x) |
+| SampleList | Deserialize | 464,273 | 103,558 | fory (4.48x) |
+| MediaContentList | Serialize | 186,870 | 77,029 | fory (2.43x) |
+| MediaContentList | Deserialize | 330,293 | 128,215 | fory (2.58x) |
+
+## Serialized Size (bytes)
+
+| Datatype | Fory | Protobuf |
+| ---------------- | ---: | -------: |
+| Struct | 58 | 61 |
+| Sample | 446 | 377 |
+| MediaContent | 365 | 307 |
+| StructList | 184 | 315 |
+| SampleList | 1980 | 1900 |
+| MediaContentList | 1535 | 1550 |
+
+## Per-workload Plots
+
+### Struct
+
+
+
+### Sample
+
+
+
+### MediaContent
+
+
+
+### StructList
+
+
+
+### SampleList
+
+
+
+### MediaContentList
+
+
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/dart/mediacontent.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/dart/mediacontent.png
new file mode 100644
index 000000000..17bd33a9b
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/dart/mediacontent.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/dart/mediacontentlist.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/dart/mediacontentlist.png
new file mode 100644
index 000000000..a0d404e06
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/dart/mediacontentlist.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/dart/sample.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/dart/sample.png
new file mode 100644
index 000000000..11f2d7743
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/dart/sample.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/dart/samplelist.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/dart/samplelist.png
new file mode 100644
index 000000000..a4b8cb1c0
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/dart/samplelist.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/dart/struct.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/dart/struct.png
new file mode 100644
index 000000000..7d616cbed
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/dart/struct.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/dart/structlist.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/dart/structlist.png
new file mode 100644
index 000000000..01484cfe9
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/dart/structlist.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/dart/throughput.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/dart/throughput.png
new file mode 100644
index 000000000..f0c4d91d8
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/dart/throughput.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/go/README.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/go/README.md
new file mode 100644
index 000000000..7227dc092
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/go/README.md
@@ -0,0 +1,58 @@
+# Go 序列化基准报告
+
+生成时间：2026-02-06 11:26:58
+
+## 系统信息
+
+- **OS**: Darwin 24.6.0
+- **Architecture**: arm64
+- **Python**: 3.10.8
+
+## 性能图表
+
+
+
+## 性能汇总
+
+| Data Type | Operation | Fory (ops/s) | Protobuf (ops/s) | Msgpack (ops/s) | Fory vs PB | Fory vs MP |
+| ---------------- | ----------- | ------------ | ---------------- | --------------- | ---------- | ---------- |
+| Struct | Serialize | 15.16M | 10.23M | 5.41M | 1.48x | 2.80x |
+| Struct | Deserialize | 12.10M | 11.01M | 3.23M | 1.10x | 3.75x |
+| Structlist | Serialize | 1.58M | 561K | 299K | 2.82x | 5.28x |
+| Structlist | Deserialize | 1.10M | 529K | 175K | 2.09x | 6.30x |
+| Sample | Serialize | 7.28M | 2.72M | 670K | 2.68x | 10.87x |
+| Sample | Deserialize | 3.79M | 2.37M | 376K | 1.60x | 10.09x |
+| Samplelist | Serialize | 510K | 141K | 38K | 3.61x | 13.34x |
+| Samplelist | Deserialize | 236K | 107K | 19K | 2.20x | 12.66x |
+| Mediacontent | Serialize | 3.72M | 2.12M | 1.29M | 1.75x | 2.88x |
+| Mediacontent | Deserialize | 2.34M | 1.81M | 698K | 1.30x | 3.35x |
+| Mediacontentlist | Serialize | 268K | 110K | 72K | 2.44x | 3.72x |
+| Mediacontentlist | Deserialize | 138K | 87K | 36K | 1.58x | 3.86x |
+
+## 详细耗时（ns/op）
+
+| Data Type | Operation | Fory | Protobuf | Msgpack |
+| ---------------- | ----------- | ------ | -------- | ------- |
+| Struct | Serialize | 66.0 | 97.8 | 184.9 |
+| Struct | Deserialize | 82.7 | 90.9 | 309.6 |
+| Structlist | Serialize | 632.8 | 1783.0 | 3340.0 |
+| Structlist | Deserialize | 906.4 | 1891.0 | 5709.0 |
+| Sample | Serialize | 137.3 | 367.3 | 1492.0 |
+| Sample | Deserialize | 263.6 | 422.2 | 2661.0 |
+| Samplelist | Serialize | 1962.0 | 7087.0 | 26169.0 |
+| Samplelist | Deserialize | 4234.0 | 9321.0 | 53615.0 |
+| Mediacontent | Serialize | 268.8 | 471.1 | 773.7 |
+| Mediacontent | Deserialize | 426.9 | 553.1 | 1432.0 |
+| Mediacontentlist | Serialize | 3736.0 | 9107.0 | 13911.0 |
+| Mediacontentlist | Deserialize | 7247.0 | 11435.0 | 27975.0 |
+
+### 序列化数据大小（字节）
+
+| Data Type | Fory | Protobuf | Msgpack |
+| ---------------- | ---- | -------- | ------- |
+| Struct | 58 | 61 | 57 |
+| Sample | 446 | 375 | 524 |
+| MediaContent | 342 | 301 | 400 |
+| StructList | 560 | 1260 | 1146 |
+| SampleList | 7600 | 7560 | 10486 |
+| MediaContentList | 5776 | 6080 | 8006 |
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/go/benchmark_combined.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/go/benchmark_combined.png
new file mode 100644
index 000000000..fe3ede6c2
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/go/benchmark_combined.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/go/benchmark_mediacontent.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/go/benchmark_mediacontent.png
new file mode 100644
index 000000000..dd914fc25
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/go/benchmark_mediacontent.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/go/benchmark_mediacontentlist.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/go/benchmark_mediacontentlist.png
new file mode 100644
index 000000000..8c10cb933
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/go/benchmark_mediacontentlist.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/go/benchmark_report.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/go/benchmark_report.md
new file mode 100644
index 000000000..f73aacf0a
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/go/benchmark_report.md
@@ -0,0 +1,84 @@
+# Go 序列化基准报告
+
+生成时间：2026-02-06 11:50:36
+
+## 系统信息
+
+- **操作系统**: Darwin 24.6.0
+- **架构**: arm64
+- **Python**: 3.9.6
+
+## 性能摘要
+
+| 数据类型 | 操作 | Fory (ops/s) | Protobuf (ops/s) | Msgpack (ops/s) | Fory vs PB | Fory vs MP |
+| ---------------- | -------- | ------------ | ---------------- | --------------- | ---------- | ---------- |
+| Struct | 序列化 | 15.16M | 10.23M | 5.41M | 1.48x | 2.80x |
+| Struct | 反序列化 | 12.10M | 11.01M | 3.23M | 1.10x | 3.75x |
+| Structlist | 序列化 | 1.58M | 561K | 299K | 2.82x | 5.28x |
+| Structlist | 反序列化 | 1.10M | 529K | 175K | 2.09x | 6.30x |
+| Sample | 序列化 | 7.28M | 2.72M | 670K | 2.68x | 10.87x |
+| Sample | 反序列化 | 3.79M | 2.37M | 376K | 1.60x | 10.09x |
+| Samplelist | 序列化 | 510K | 141K | 38K | 3.61x | 13.34x |
+| Samplelist | 反序列化 | 236K | 107K | 19K | 2.20x | 12.66x |
+| Mediacontent | 序列化 | 3.72M | 2.12M | 1.29M | 1.75x | 2.88x |
+| Mediacontent | 反序列化 | 2.34M | 1.81M | 698K | 1.30x | 3.35x |
+| Mediacontentlist | 序列化 | 268K | 110K | 72K | 2.44x | 3.72x |
+| Mediacontentlist | 反序列化 | 138K | 87K | 36K | 1.58x | 3.86x |
+
+## 详细耗时（ns/op）
+
+| 数据类型 | 操作 | Fory | Protobuf | Msgpack |
+| ---------------- | -------- | ------ | -------- | ------- |
+| Struct | 序列化 | 66.0 | 97.8 | 184.9 |
+| Struct | 反序列化 | 82.7 | 90.9 | 309.6 |
+| Structlist | 序列化 | 632.8 | 1783.0 | 3340.0 |
+| Structlist | 反序列化 | 906.4 | 1891.0 | 5709.0 |
+| Sample | 序列化 | 137.3 | 367.3 | 1492.0 |
+| Sample | 反序列化 | 263.6 | 422.2 | 2661.0 |
+| Samplelist | 序列化 | 1962.0 | 7087.0 | 26169.0 |
+| Samplelist | 反序列化 | 4234.0 | 9321.0 | 53615.0 |
+| Mediacontent | 序列化 | 268.8 | 471.1 | 773.7 |
+| Mediacontent | 反序列化 | 426.9 | 553.1 | 1432.0 |
+| Mediacontentlist | 序列化 | 3736.0 | 9107.0 | 13911.0 |
+| Mediacontentlist | 反序列化 | 7247.0 | 11435.0 | 27975.0 |
+
+### 序列化后数据大小（字节）
+
+| 数据类型 | Fory | Protobuf | Msgpack |
+| ---------------- | ---- | -------- | ------- |
+| Struct | 58 | 61 | 57 |
+| Sample | 446 | 375 | 524 |
+| MediaContent | 342 | 301 | 400 |
+| StructList | 560 | 1260 | 1146 |
+| SampleList | 7600 | 7560 | 10486 |
+| MediaContentList | 5776 | 6080 | 8006 |
+
+## 性能图表
+
+### 综合概览
+
+
+
+### Struct
+
+
+
+### Structlist
+
+
+
+### Sample
+
+
+
+### Samplelist
+
+
+
+### Mediacontent
+
+
+
+### Mediacontentlist
+
+
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/go/benchmark_results.json b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/go/benchmark_results.json
new file mode 100644
index 000000000..a56018d44
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/go/benchmark_results.json
@@ -0,0 +1,184 @@
+{"Time":"2026-02-06T11:26:00.8242+08:00","Action":"start","Package":"github.com/apache/fory/benchmarks/go_benchmark"}
+{"Time":"2026-02-06T11:26:02.038023+08:00","Action":"run","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"TestPrintSerializedSizes"}
+{"Time":"2026-02-06T11:26:02.038063+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"TestPrintSerializedSizes","Output":"=== RUN TestPrintSerializedSizes\n"}
+{"Time":"2026-02-06T11:26:02.039886+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"TestPrintSerializedSizes","Output":"============================================\n"}
+{"Time":"2026-02-06T11:26:02.039942+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"TestPrintSerializedSizes","Output":"Serialized Sizes (bytes):\n"}
+{"Time":"2026-02-06T11:26:02.03996+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"TestPrintSerializedSizes","Output":"============================================\n"}
+{"Time":"2026-02-06T11:26:02.039966+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"TestPrintSerializedSizes","Output":"NumericStruct:\n"}
+{"Time":"2026-02-06T11:26:02.039976+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"TestPrintSerializedSizes","Output":" Fory: 58 bytes\n"}
+{"Time":"2026-02-06T11:26:02.03998+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"TestPrintSerializedSizes","Output":" Protobuf: 61 bytes\n"}
+{"Time":"2026-02-06T11:26:02.039984+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"TestPrintSerializedSizes","Output":" Msgpack: 57 bytes\n"}
+{"Time":"2026-02-06T11:26:02.039988+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"TestPrintSerializedSizes","Output":"Sample:\n"}
+{"Time":"2026-02-06T11:26:02.039999+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"TestPrintSerializedSizes","Output":" Fory: 446 bytes\n"}
+{"Time":"2026-02-06T11:26:02.040004+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"TestPrintSerializedSizes","Output":" Protobuf: 375 bytes\n"}
+{"Time":"2026-02-06T11:26:02.040008+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"TestPrintSerializedSizes","Output":" Msgpack: 524 bytes\n"}
+{"Time":"2026-02-06T11:26:02.040011+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"TestPrintSerializedSizes","Output":"MediaContent:\n"}
+{"Time":"2026-02-06T11:26:02.040015+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"TestPrintSerializedSizes","Output":" Fory: 342 bytes\n"}
+{"Time":"2026-02-06T11:26:02.040018+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"TestPrintSerializedSizes","Output":" Protobuf: 301 bytes\n"}
+{"Time":"2026-02-06T11:26:02.040022+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"TestPrintSerializedSizes","Output":" Msgpack: 400 bytes\n"}
+{"Time":"2026-02-06T11:26:02.040025+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"TestPrintSerializedSizes","Output":"StructList:\n"}
+{"Time":"2026-02-06T11:26:02.040029+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"TestPrintSerializedSizes","Output":" Fory: 560 bytes\n"}
+{"Time":"2026-02-06T11:26:02.040034+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"TestPrintSerializedSizes","Output":" Protobuf: 1260 bytes\n"}
+{"Time":"2026-02-06T11:26:02.040038+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"TestPrintSerializedSizes","Output":" Msgpack: 1146 bytes\n"}
+{"Time":"2026-02-06T11:26:02.040042+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"TestPrintSerializedSizes","Output":"SampleList:\n"}
+{"Time":"2026-02-06T11:26:02.040058+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"TestPrintSerializedSizes","Output":" Fory: 7600 bytes\n"}
+{"Time":"2026-02-06T11:26:02.040061+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"TestPrintSerializedSizes","Output":" Protobuf: 7560 bytes\n"}
+{"Time":"2026-02-06T11:26:02.040065+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"TestPrintSerializedSizes","Output":" Msgpack: 10486 bytes\n"}
+{"Time":"2026-02-06T11:26:02.040069+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"TestPrintSerializedSizes","Output":"MediaContentList:\n"}
+{"Time":"2026-02-06T11:26:02.040072+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"TestPrintSerializedSizes","Output":" Fory: 5776 bytes\n"}
+{"Time":"2026-02-06T11:26:02.040076+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"TestPrintSerializedSizes","Output":" Protobuf: 6080 bytes\n"}
+{"Time":"2026-02-06T11:26:02.040079+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"TestPrintSerializedSizes","Output":" Msgpack: 8006 bytes\n"}
+{"Time":"2026-02-06T11:26:02.040083+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"TestPrintSerializedSizes","Output":"============================================\n"}
+{"Time":"2026-02-06T11:26:02.040096+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"TestPrintSerializedSizes","Output":"--- PASS: TestPrintSerializedSizes (0.00s)\n"}
+{"Time":"2026-02-06T11:26:02.0401+08:00","Action":"pass","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"TestPrintSerializedSizes","Elapsed":0}
+{"Time":"2026-02-06T11:26:02.040221+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Output":"goos: darwin\n"}
+{"Time":"2026-02-06T11:26:02.040245+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Output":"goarch: arm64\n"}
+{"Time":"2026-02-06T11:26:02.040254+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Output":"pkg: github.com/apache/fory/benchmarks/go_benchmark\n"}
+{"Time":"2026-02-06T11:26:02.04026+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Output":"cpu: Apple M4 Pro\n"}
+{"Time":"2026-02-06T11:26:02.040266+08:00","Action":"run","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_Struct_Serialize"}
+{"Time":"2026-02-06T11:26:02.040271+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_Struct_Serialize","Output":"=== RUN BenchmarkFory_Struct_Serialize\n"}
+{"Time":"2026-02-06T11:26:02.040276+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_Struct_Serialize","Output":"BenchmarkFory_Struct_Serialize\n"}
+{"Time":"2026-02-06T11:26:03.350214+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_Struct_Serialize","Output":"BenchmarkFory_Struct_Serialize-12 \t18143846\t 68.43 ns/op\t 0 B/op\t 0 allocs/op\n"}
+{"Time":"2026-02-06T11:26:03.350303+08:00","Action":"run","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_Struct_Serialize"}
+{"Time":"2026-02-06T11:26:03.350311+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_Struct_Serialize","Output":"=== RUN BenchmarkProtobuf_Struct_Serialize\n"}
+{"Time":"2026-02-06T11:26:03.350316+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_Struct_Serialize","Output":"BenchmarkProtobuf_Struct_Serialize\n"}
+{"Time":"2026-02-06T11:26:04.625572+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_Struct_Serialize","Output":"BenchmarkProtobuf_Struct_Serialize-12 \t11706260\t 99.94 ns/op\t 144 B/op\t 2 allocs/op\n"}
+{"Time":"2026-02-06T11:26:04.62562+08:00","Action":"run","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_Struct_Serialize"}
+{"Time":"2026-02-06T11:26:04.625628+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_Struct_Serialize","Output":"=== RUN BenchmarkMsgpack_Struct_Serialize\n"}
+{"Time":"2026-02-06T11:26:04.625634+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_Struct_Serialize","Output":"BenchmarkMsgpack_Struct_Serialize\n"}
+{"Time":"2026-02-06T11:26:06.017238+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_Struct_Serialize","Output":"BenchmarkMsgpack_Struct_Serialize-12 \t 6927219\t 175.4 ns/op\t 112 B/op\t 2 allocs/op\n"}
+{"Time":"2026-02-06T11:26:06.017297+08:00","Action":"run","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_Struct_Deserialize"}
+{"Time":"2026-02-06T11:26:06.017305+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_Struct_Deserialize","Output":"=== RUN BenchmarkFory_Struct_Deserialize\n"}
+{"Time":"2026-02-06T11:26:06.017311+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_Struct_Deserialize","Output":"BenchmarkFory_Struct_Deserialize\n"}
+{"Time":"2026-02-06T11:26:07.293915+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_Struct_Deserialize","Output":"BenchmarkFory_Struct_Deserialize-12 \t13959790\t 85.11 ns/op\t 32 B/op\t 1 allocs/op\n"}
+{"Time":"2026-02-06T11:26:07.293975+08:00","Action":"run","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_Struct_Deserialize"}
+{"Time":"2026-02-06T11:26:07.293986+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_Struct_Deserialize","Output":"=== RUN BenchmarkProtobuf_Struct_Deserialize\n"}
+{"Time":"2026-02-06T11:26:07.294004+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_Struct_Deserialize","Output":"BenchmarkProtobuf_Struct_Deserialize\n"}
+{"Time":"2026-02-06T11:26:09.620474+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_Struct_Deserialize","Output":"BenchmarkProtobuf_Struct_Deserialize-12 \t13299274\t 91.61 ns/op\t 80 B/op\t 1 allocs/op\n"}
+{"Time":"2026-02-06T11:26:09.620532+08:00","Action":"run","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_Struct_Deserialize"}
+{"Time":"2026-02-06T11:26:09.620541+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_Struct_Deserialize","Output":"=== RUN BenchmarkMsgpack_Struct_Deserialize\n"}
+{"Time":"2026-02-06T11:26:09.620555+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_Struct_Deserialize","Output":"BenchmarkMsgpack_Struct_Deserialize\n"}
+{"Time":"2026-02-06T11:26:11.125057+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_Struct_Deserialize","Output":"BenchmarkMsgpack_Struct_Deserialize-12 \t 3930746\t 304.0 ns/op\t 80 B/op\t 2 allocs/op\n"}
+{"Time":"2026-02-06T11:26:11.125134+08:00","Action":"run","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_StructList_Serialize"}
+{"Time":"2026-02-06T11:26:11.125155+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_StructList_Serialize","Output":"=== RUN BenchmarkFory_StructList_Serialize\n"}
+{"Time":"2026-02-06T11:26:11.125162+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_StructList_Serialize","Output":"BenchmarkFory_StructList_Serialize\n"}
+{"Time":"2026-02-06T11:26:12.963363+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_StructList_Serialize","Output":"BenchmarkFory_StructList_Serialize-12 \t 1823836\t 642.7 ns/op\t 0 B/op\t 0 allocs/op\n"}
+{"Time":"2026-02-06T11:26:12.963407+08:00","Action":"run","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_StructList_Serialize"}
+{"Time":"2026-02-06T11:26:12.963415+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_StructList_Serialize","Output":"=== RUN BenchmarkProtobuf_StructList_Serialize\n"}
+{"Time":"2026-02-06T11:26:12.963424+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_StructList_Serialize","Output":"BenchmarkProtobuf_StructList_Serialize\n"}
+{"Time":"2026-02-06T11:26:14.186362+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_StructList_Serialize","Output":"BenchmarkProtobuf_StructList_Serialize-12 \t 674140\t 1786 ns/op\t 3104 B/op\t 23 allocs/op\n"}
+{"Time":"2026-02-06T11:26:14.186414+08:00","Action":"run","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_StructList_Serialize"}
+{"Time":"2026-02-06T11:26:14.186422+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_StructList_Serialize","Output":"=== RUN BenchmarkMsgpack_StructList_Serialize\n"}
+{"Time":"2026-02-06T11:26:14.186447+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_StructList_Serialize","Output":"BenchmarkMsgpack_StructList_Serialize\n"}
+{"Time":"2026-02-06T11:26:15.426174+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_StructList_Serialize","Output":"BenchmarkMsgpack_StructList_Serialize-12 \t 359842\t 3349 ns/op\t 4106 B/op\t 8 allocs/op\n"}
+{"Time":"2026-02-06T11:26:15.426251+08:00","Action":"run","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_StructList_Deserialize"}
+{"Time":"2026-02-06T11:26:15.426263+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_StructList_Deserialize","Output":"=== RUN BenchmarkFory_StructList_Deserialize\n"}
+{"Time":"2026-02-06T11:26:15.426381+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_StructList_Deserialize","Output":"BenchmarkFory_StructList_Deserialize\n"}
+{"Time":"2026-02-06T11:26:17.519761+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_StructList_Deserialize","Output":"BenchmarkFory_StructList_Deserialize-12 \t 1330341\t 887.2 ns/op\t 688 B/op\t 3 allocs/op\n"}
+{"Time":"2026-02-06T11:26:17.519837+08:00","Action":"run","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_StructList_Deserialize"}
+{"Time":"2026-02-06T11:26:17.519846+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_StructList_Deserialize","Output":"=== RUN BenchmarkProtobuf_StructList_Deserialize\n"}
+{"Time":"2026-02-06T11:26:17.519853+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_StructList_Deserialize","Output":"BenchmarkProtobuf_StructList_Deserialize\n"}
+{"Time":"2026-02-06T11:26:18.731978+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_StructList_Deserialize","Output":"BenchmarkProtobuf_StructList_Deserialize-12 \t 617972\t 1928 ns/op\t 2808 B/op\t 28 allocs/op\n"}
+{"Time":"2026-02-06T11:26:18.732042+08:00","Action":"run","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_StructList_Deserialize"}
+{"Time":"2026-02-06T11:26:18.732051+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_StructList_Deserialize","Output":"=== RUN BenchmarkMsgpack_StructList_Deserialize\n"}
+{"Time":"2026-02-06T11:26:18.732057+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_StructList_Deserialize","Output":"BenchmarkMsgpack_StructList_Deserialize\n"}
+{"Time":"2026-02-06T11:26:20.02287+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_StructList_Deserialize","Output":"BenchmarkMsgpack_StructList_Deserialize-12 \t 210877\t 5843 ns/op\t 1424 B/op\t 7 allocs/op\n"}
+{"Time":"2026-02-06T11:26:20.022923+08:00","Action":"run","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_Sample_Serialize"}
+{"Time":"2026-02-06T11:26:20.022931+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_Sample_Serialize","Output":"=== RUN BenchmarkFory_Sample_Serialize\n"}
+{"Time":"2026-02-06T11:26:20.022937+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_Sample_Serialize","Output":"BenchmarkFory_Sample_Serialize\n"}
+{"Time":"2026-02-06T11:26:21.394325+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_Sample_Serialize","Output":"BenchmarkFory_Sample_Serialize-12 \t 8677500\t 141.8 ns/op\t 0 B/op\t 0 allocs/op\n"}
+{"Time":"2026-02-06T11:26:21.394387+08:00","Action":"run","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_Sample_Serialize"}
+{"Time":"2026-02-06T11:26:21.394395+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_Sample_Serialize","Output":"=== RUN BenchmarkProtobuf_Sample_Serialize\n"}
+{"Time":"2026-02-06T11:26:21.394401+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_Sample_Serialize","Output":"BenchmarkProtobuf_Sample_Serialize\n"}
+{"Time":"2026-02-06T11:26:22.980131+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_Sample_Serialize","Output":"BenchmarkProtobuf_Sample_Serialize-12 \t 3224515\t 374.8 ns/op\t 704 B/op\t 2 allocs/op\n"}
+{"Time":"2026-02-06T11:26:22.980196+08:00","Action":"run","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_Sample_Serialize"}
+{"Time":"2026-02-06T11:26:22.980223+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_Sample_Serialize","Output":"=== RUN BenchmarkMsgpack_Sample_Serialize\n"}
+{"Time":"2026-02-06T11:26:22.980231+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_Sample_Serialize","Output":"BenchmarkMsgpack_Sample_Serialize\n"}
+{"Time":"2026-02-06T11:26:24.170678+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_Sample_Serialize","Output":"BenchmarkMsgpack_Sample_Serialize-12 \t 794436\t 1478 ns/op\t 2321 B/op\t 7 allocs/op\n"}
+{"Time":"2026-02-06T11:26:24.170768+08:00","Action":"run","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_Sample_Deserialize"}
+{"Time":"2026-02-06T11:26:24.170805+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_Sample_Deserialize","Output":"=== RUN BenchmarkFory_Sample_Deserialize\n"}
+{"Time":"2026-02-06T11:26:24.170825+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_Sample_Deserialize","Output":"BenchmarkFory_Sample_Deserialize\n"}
+{"Time":"2026-02-06T11:26:25.63715+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_Sample_Deserialize","Output":"BenchmarkFory_Sample_Deserialize-12 \t 4500349\t 265.5 ns/op\t 676 B/op\t 9 allocs/op\n"}
+{"Time":"2026-02-06T11:26:25.637205+08:00","Action":"run","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_Sample_Deserialize"}
+{"Time":"2026-02-06T11:26:25.637214+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_Sample_Deserialize","Output":"=== RUN BenchmarkProtobuf_Sample_Deserialize\n"}
+{"Time":"2026-02-06T11:26:25.63722+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_Sample_Deserialize","Output":"BenchmarkProtobuf_Sample_Deserialize\n"}
+{"Time":"2026-02-06T11:26:27.316964+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_Sample_Deserialize","Output":"BenchmarkProtobuf_Sample_Deserialize-12 \t 2784835\t 446.3 ns/op\t 708 B/op\t 9 allocs/op\n"}
+{"Time":"2026-02-06T11:26:27.317031+08:00","Action":"run","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_Sample_Deserialize"}
+{"Time":"2026-02-06T11:26:27.317044+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_Sample_Deserialize","Output":"=== RUN BenchmarkMsgpack_Sample_Deserialize\n"}
+{"Time":"2026-02-06T11:26:27.317052+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_Sample_Deserialize","Output":"BenchmarkMsgpack_Sample_Deserialize\n"}
+{"Time":"2026-02-06T11:26:28.448747+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_Sample_Deserialize","Output":"BenchmarkMsgpack_Sample_Deserialize-12 \t 395234\t 2783 ns/op\t 1576 B/op\t 38 allocs/op\n"}
+{"Time":"2026-02-06T11:26:28.448797+08:00","Action":"run","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_SampleList_Serialize"}
+{"Time":"2026-02-06T11:26:28.448807+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_SampleList_Serialize","Output":"=== RUN BenchmarkFory_SampleList_Serialize\n"}
+{"Time":"2026-02-06T11:26:28.448816+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_SampleList_Serialize","Output":"BenchmarkFory_SampleList_Serialize\n"}
+{"Time":"2026-02-06T11:26:29.669329+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_SampleList_Serialize","Output":"BenchmarkFory_SampleList_Serialize-12 \t 601761\t 1992 ns/op\t 0 B/op\t 0 allocs/op\n"}
+{"Time":"2026-02-06T11:26:29.669593+08:00","Action":"run","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_SampleList_Serialize"}
+{"Time":"2026-02-06T11:26:29.669609+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_SampleList_Serialize","Output":"=== RUN BenchmarkProtobuf_SampleList_Serialize\n"}
+{"Time":"2026-02-06T11:26:29.669618+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_SampleList_Serialize","Output":"BenchmarkProtobuf_SampleList_Serialize\n"}
+{"Time":"2026-02-06T11:26:30.912786+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_SampleList_Serialize","Output":"BenchmarkProtobuf_SampleList_Serialize-12 \t 160716\t 7260 ns/op\t 14816 B/op\t 23 allocs/op\n"}
+{"Time":"2026-02-06T11:26:30.912848+08:00","Action":"run","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_SampleList_Serialize"}
+{"Time":"2026-02-06T11:26:30.912856+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_SampleList_Serialize","Output":"=== RUN BenchmarkMsgpack_SampleList_Serialize\n"}
+{"Time":"2026-02-06T11:26:30.912863+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_SampleList_Serialize","Output":"BenchmarkMsgpack_SampleList_Serialize\n"}
+{"Time":"2026-02-06T11:26:32.378762+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_SampleList_Serialize","Output":"BenchmarkMsgpack_SampleList_Serialize-12 \t 46688\t 25815 ns/op\t 32793 B/op\t 11 allocs/op\n"}
+{"Time":"2026-02-06T11:26:32.378867+08:00","Action":"run","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_SampleList_Deserialize"}
+{"Time":"2026-02-06T11:26:32.378877+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_SampleList_Deserialize","Output":"=== RUN BenchmarkFory_SampleList_Deserialize\n"}
+{"Time":"2026-02-06T11:26:32.378884+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_SampleList_Deserialize","Output":"BenchmarkFory_SampleList_Deserialize\n"}
+{"Time":"2026-02-06T11:26:33.650206+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_SampleList_Deserialize","Output":"BenchmarkFory_SampleList_Deserialize-12 \t 293077\t 4192 ns/op\t 13952 B/op\t 163 allocs/op\n"}
+{"Time":"2026-02-06T11:26:33.650336+08:00","Action":"run","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_SampleList_Deserialize"}
+{"Time":"2026-02-06T11:26:33.650344+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_SampleList_Deserialize","Output":"=== RUN BenchmarkProtobuf_SampleList_Deserialize\n"}
+{"Time":"2026-02-06T11:26:33.650351+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_SampleList_Deserialize","Output":"BenchmarkProtobuf_SampleList_Deserialize\n"}
+{"Time":"2026-02-06T11:26:34.926961+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_SampleList_Deserialize","Output":"BenchmarkProtobuf_SampleList_Deserialize-12 \t 130516\t 9062 ns/op\t 20872 B/op\t 188 allocs/op\n"}
+{"Time":"2026-02-06T11:26:34.927018+08:00","Action":"run","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_SampleList_Deserialize"}
+{"Time":"2026-02-06T11:26:34.927027+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_SampleList_Deserialize","Output":"=== RUN BenchmarkMsgpack_SampleList_Deserialize\n"}
+{"Time":"2026-02-06T11:26:34.927033+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_SampleList_Deserialize","Output":"BenchmarkMsgpack_SampleList_Deserialize\n"}
+{"Time":"2026-02-06T11:26:36.678928+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_SampleList_Deserialize","Output":"BenchmarkMsgpack_SampleList_Deserialize-12 \t 22149\t 54329 ns/op\t 37251 B/op\t 727 allocs/op\n"}
+{"Time":"2026-02-06T11:26:36.678975+08:00","Action":"run","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_MediaContent_Serialize"}
+{"Time":"2026-02-06T11:26:36.678983+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_MediaContent_Serialize","Output":"=== RUN BenchmarkFory_MediaContent_Serialize\n"}
+{"Time":"2026-02-06T11:26:36.678999+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_MediaContent_Serialize","Output":"BenchmarkFory_MediaContent_Serialize\n"}
+{"Time":"2026-02-06T11:26:38.138388+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_MediaContent_Serialize","Output":"BenchmarkFory_MediaContent_Serialize-12 \t 4465790\t 265.7 ns/op\t 0 B/op\t 0 allocs/op\n"}
+{"Time":"2026-02-06T11:26:38.1385+08:00","Action":"run","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_MediaContent_Serialize"}
+{"Time":"2026-02-06T11:26:38.138526+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_MediaContent_Serialize","Output":"=== RUN BenchmarkProtobuf_MediaContent_Serialize\n"}
+{"Time":"2026-02-06T11:26:38.138534+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_MediaContent_Serialize","Output":"BenchmarkProtobuf_MediaContent_Serialize\n"}
+{"Time":"2026-02-06T11:26:39.849873+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_MediaContent_Serialize","Output":"BenchmarkProtobuf_MediaContent_Serialize-12 \t 2525698\t 486.9 ns/op\t 1144 B/op\t 11 allocs/op\n"}
+{"Time":"2026-02-06T11:26:39.849916+08:00","Action":"run","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_MediaContent_Serialize"}
+{"Time":"2026-02-06T11:26:39.849924+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_MediaContent_Serialize","Output":"=== RUN BenchmarkMsgpack_MediaContent_Serialize\n"}
+{"Time":"2026-02-06T11:26:39.849948+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_MediaContent_Serialize","Output":"BenchmarkMsgpack_MediaContent_Serialize\n"}
+{"Time":"2026-02-06T11:26:41.859429+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_MediaContent_Serialize","Output":"BenchmarkMsgpack_MediaContent_Serialize-12 \t 1442941\t 809.6 ns/op\t 1168 B/op\t 6 allocs/op\n"}
+{"Time":"2026-02-06T11:26:41.859487+08:00","Action":"run","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_MediaContent_Deserialize"}
+{"Time":"2026-02-06T11:26:41.859496+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_MediaContent_Deserialize","Output":"=== RUN BenchmarkFory_MediaContent_Deserialize\n"}
+{"Time":"2026-02-06T11:26:41.859502+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_MediaContent_Deserialize","Output":"BenchmarkFory_MediaContent_Deserialize\n"}
+{"Time":"2026-02-06T11:26:43.498623+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_MediaContent_Deserialize","Output":"BenchmarkFory_MediaContent_Deserialize-12 \t 2758138\t 434.2 ns/op\t 656 B/op\t 13 allocs/op\n"}
+{"Time":"2026-02-06T11:26:43.498681+08:00","Action":"run","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_MediaContent_Deserialize"}
+{"Time":"2026-02-06T11:26:43.498691+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_MediaContent_Deserialize","Output":"=== RUN BenchmarkProtobuf_MediaContent_Deserialize\n"}
+{"Time":"2026-02-06T11:26:43.498698+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_MediaContent_Deserialize","Output":"BenchmarkProtobuf_MediaContent_Deserialize\n"}
+{"Time":"2026-02-06T11:26:45.267858+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_MediaContent_Deserialize","Output":"BenchmarkProtobuf_MediaContent_Deserialize-12 \t 2056162\t 573.1 ns/op\t 1088 B/op\t 21 allocs/op\n"}
+{"Time":"2026-02-06T11:26:45.267907+08:00","Action":"run","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_MediaContent_Deserialize"}
+{"Time":"2026-02-06T11:26:45.267915+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_MediaContent_Deserialize","Output":"=== RUN BenchmarkMsgpack_MediaContent_Deserialize\n"}
+{"Time":"2026-02-06T11:26:45.267922+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_MediaContent_Deserialize","Output":"BenchmarkMsgpack_MediaContent_Deserialize\n"}
+{"Time":"2026-02-06T11:26:46.474309+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_MediaContent_Deserialize","Output":"BenchmarkMsgpack_MediaContent_Deserialize-12 \t 849342\t 1402 ns/op\t 896 B/op\t 17 allocs/op\n"}
+{"Time":"2026-02-06T11:26:46.474373+08:00","Action":"run","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_MediaContentList_Serialize"}
+{"Time":"2026-02-06T11:26:46.474382+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_MediaContentList_Serialize","Output":"=== RUN BenchmarkFory_MediaContentList_Serialize\n"}
+{"Time":"2026-02-06T11:26:46.474389+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_MediaContentList_Serialize","Output":"BenchmarkFory_MediaContentList_Serialize\n"}
+{"Time":"2026-02-06T11:26:48.716644+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_MediaContentList_Serialize","Output":"BenchmarkFory_MediaContentList_Serialize-12 \t 322346\t 3749 ns/op\t 0 B/op\t 0 allocs/op\n"}
+{"Time":"2026-02-06T11:26:48.716695+08:00","Action":"run","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_MediaContentList_Serialize"}
+{"Time":"2026-02-06T11:26:48.716704+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_MediaContentList_Serialize","Output":"=== RUN BenchmarkProtobuf_MediaContentList_Serialize\n"}
+{"Time":"2026-02-06T11:26:48.716725+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_MediaContentList_Serialize","Output":"BenchmarkProtobuf_MediaContentList_Serialize\n"}
+{"Time":"2026-02-06T11:26:50.020984+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_MediaContentList_Serialize","Output":"BenchmarkProtobuf_MediaContentList_Serialize-12 \t 134098\t 9044 ns/op\t 22848 B/op\t 203 allocs/op\n"}
+{"Time":"2026-02-06T11:26:50.021029+08:00","Action":"run","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_MediaContentList_Serialize"}
+{"Time":"2026-02-06T11:26:50.021036+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_MediaContentList_Serialize","Output":"=== RUN BenchmarkMsgpack_MediaContentList_Serialize\n"}
+{"Time":"2026-02-06T11:26:50.021054+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_MediaContentList_Serialize","Output":"BenchmarkMsgpack_MediaContentList_Serialize\n"}
+{"Time":"2026-02-06T11:26:51.345052+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_MediaContentList_Serialize","Output":"BenchmarkMsgpack_MediaContentList_Serialize-12 \t 83294\t 14136 ns/op\t 16880 B/op\t 30 allocs/op\n"}
+{"Time":"2026-02-06T11:26:51.345103+08:00","Action":"run","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_MediaContentList_Deserialize"}
+{"Time":"2026-02-06T11:26:51.345122+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_MediaContentList_Deserialize","Output":"=== RUN BenchmarkFory_MediaContentList_Deserialize\n"}
+{"Time":"2026-02-06T11:26:51.345129+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_MediaContentList_Deserialize","Output":"BenchmarkFory_MediaContentList_Deserialize\n"}
+{"Time":"2026-02-06T11:26:52.630153+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkFory_MediaContentList_Deserialize","Output":"BenchmarkFory_MediaContentList_Deserialize-12 \t 164211\t 7367 ns/op\t 13040 B/op\t 243 allocs/op\n"}
+{"Time":"2026-02-06T11:26:52.630211+08:00","Action":"run","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_MediaContentList_Deserialize"}
+{"Time":"2026-02-06T11:26:52.630219+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_MediaContentList_Deserialize","Output":"=== RUN BenchmarkProtobuf_MediaContentList_Deserialize\n"}
+{"Time":"2026-02-06T11:26:52.630226+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_MediaContentList_Deserialize","Output":"BenchmarkProtobuf_MediaContentList_Deserialize\n"}
+{"Time":"2026-02-06T11:26:53.956031+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkProtobuf_MediaContentList_Deserialize","Output":"BenchmarkProtobuf_MediaContentList_Deserialize-12 \t 104497\t 11566 ns/op\t 25400 B/op\t 428 allocs/op\n"}
+{"Time":"2026-02-06T11:26:53.956078+08:00","Action":"run","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_MediaContentList_Deserialize"}
+{"Time":"2026-02-06T11:26:53.956087+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_MediaContentList_Deserialize","Output":"=== RUN BenchmarkMsgpack_MediaContentList_Deserialize\n"}
+{"Time":"2026-02-06T11:26:53.956093+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_MediaContentList_Deserialize","Output":"BenchmarkMsgpack_MediaContentList_Deserialize\n"}
+{"Time":"2026-02-06T11:26:55.436967+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Test":"BenchmarkMsgpack_MediaContentList_Deserialize","Output":"BenchmarkMsgpack_MediaContentList_Deserialize-12 \t 42306\t 28194 ns/op\t 20058 B/op\t 307 allocs/op\n"}
+{"Time":"2026-02-06T11:26:55.437027+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Output":"PASS\n"}
+{"Time":"2026-02-06T11:26:55.438151+08:00","Action":"output","Package":"github.com/apache/fory/benchmarks/go_benchmark","Output":"ok \tgithub.com/apache/fory/benchmarks/go_benchmark\t54.613s\n"}
+{"Time":"2026-02-06T11:26:55.438171+08:00","Action":"pass","Package":"github.com/apache/fory/benchmarks/go_benchmark","Elapsed":54.614}
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/go/benchmark_results.txt b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/go/benchmark_results.txt
new file mode 100644
index 000000000..516dc0387
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/go/benchmark_results.txt
@@ -0,0 +1,326 @@
+============================================
+Serialized Sizes (bytes):
+============================================
+NumericStruct:
+ Fory: 58 bytes
+ Protobuf: 61 bytes
+ Msgpack: 57 bytes
+Sample:
+ Fory: 446 bytes
+ Protobuf: 375 bytes
+ Msgpack: 524 bytes
+MediaContent:
+ Fory: 342 bytes
+ Protobuf: 301 bytes
+ Msgpack: 400 bytes
+StructList:
+ Fory: 560 bytes
+ Protobuf: 1260 bytes
+ Msgpack: 1146 bytes
+SampleList:
+ Fory: 7600 bytes
+ Protobuf: 7560 bytes
+ Msgpack: 10486 bytes
+MediaContentList:
+ Fory: 5776 bytes
+ Protobuf: 6080 bytes
+ Msgpack: 8006 bytes
+============================================
+============================================
+Serialized Sizes (bytes):
+============================================
+NumericStruct:
+ Fory: 58 bytes
+ Protobuf: 61 bytes
+ Msgpack: 57 bytes
+Sample:
+ Fory: 446 bytes
+ Protobuf: 375 bytes
+ Msgpack: 524 bytes
+MediaContent:
+ Fory: 342 bytes
+ Protobuf: 301 bytes
+ Msgpack: 400 bytes
+StructList:
+ Fory: 560 bytes
+ Protobuf: 1260 bytes
+ Msgpack: 1146 bytes
+SampleList:
+ Fory: 7600 bytes
+ Protobuf: 7560 bytes
+ Msgpack: 10486 bytes
+MediaContentList:
+ Fory: 5776 bytes
+ Protobuf: 6080 bytes
+ Msgpack: 8006 bytes
+============================================
+============================================
+Serialized Sizes (bytes):
+============================================
+NumericStruct:
+ Fory: 58 bytes
+ Protobuf: 61 bytes
+ Msgpack: 57 bytes
+Sample:
+ Fory: 446 bytes
+ Protobuf: 375 bytes
+ Msgpack: 524 bytes
+MediaContent:
+ Fory: 342 bytes
+ Protobuf: 301 bytes
+ Msgpack: 400 bytes
+StructList:
+ Fory: 560 bytes
+ Protobuf: 1260 bytes
+ Msgpack: 1146 bytes
+SampleList:
+ Fory: 7600 bytes
+ Protobuf: 7560 bytes
+ Msgpack: 10486 bytes
+MediaContentList:
+ Fory: 5776 bytes
+ Protobuf: 6080 bytes
+ Msgpack: 8006 bytes
+============================================
+============================================
+Serialized Sizes (bytes):
+============================================
+NumericStruct:
+ Fory: 58 bytes
+ Protobuf: 61 bytes
+ Msgpack: 57 bytes
+Sample:
+ Fory: 446 bytes
+ Protobuf: 375 bytes
+ Msgpack: 524 bytes
+MediaContent:
+ Fory: 342 bytes
+ Protobuf: 301 bytes
+ Msgpack: 400 bytes
+StructList:
+ Fory: 560 bytes
+ Protobuf: 1260 bytes
+ Msgpack: 1146 bytes
+SampleList:
+ Fory: 7600 bytes
+ Protobuf: 7560 bytes
+ Msgpack: 10486 bytes
+MediaContentList:
+ Fory: 5776 bytes
+ Protobuf: 6080 bytes
+ Msgpack: 8006 bytes
+============================================
+============================================
+Serialized Sizes (bytes):
+============================================
+NumericStruct:
+ Fory: 58 bytes
+ Protobuf: 61 bytes
+ Msgpack: 57 bytes
+Sample:
+ Fory: 446 bytes
+ Protobuf: 375 bytes
+ Msgpack: 524 bytes
+MediaContent:
+ Fory: 342 bytes
+ Protobuf: 301 bytes
+ Msgpack: 400 bytes
+StructList:
+ Fory: 560 bytes
+ Protobuf: 1260 bytes
+ Msgpack: 1146 bytes
+SampleList:
+ Fory: 7600 bytes
+ Protobuf: 7560 bytes
+ Msgpack: 10486 bytes
+MediaContentList:
+ Fory: 5776 bytes
+ Protobuf: 6080 bytes
+ Msgpack: 8006 bytes
+============================================
+goos: darwin
+goarch: arm64
+pkg: github.com/apache/fory/benchmarks/go_benchmark
+cpu: Apple M4 Pro
+BenchmarkFory_Struct_Serialize-12 18441836 65.29 ns/op 0 B/op 0 allocs/op
+BenchmarkFory_Struct_Serialize-12 18408471 65.41 ns/op 0 B/op 0 allocs/op
+BenchmarkFory_Struct_Serialize-12 17736544 65.19 ns/op 0 B/op 0 allocs/op
+BenchmarkFory_Struct_Serialize-12 18385110 65.37 ns/op 0 B/op 0 allocs/op
+BenchmarkFory_Struct_Serialize-12 18366690 65.95 ns/op 0 B/op 0 allocs/op
+BenchmarkProtobuf_Struct_Serialize-12 11775620 100.3 ns/op 144 B/op 2 allocs/op
+BenchmarkProtobuf_Struct_Serialize-12 12272547 97.80 ns/op 144 B/op 2 allocs/op
+BenchmarkProtobuf_Struct_Serialize-12 12371797 97.68 ns/op 144 B/op 2 allocs/op
+BenchmarkProtobuf_Struct_Serialize-12 12184240 97.62 ns/op 144 B/op 2 allocs/op
+BenchmarkProtobuf_Struct_Serialize-12 12216723 97.78 ns/op 144 B/op 2 allocs/op
+BenchmarkMsgpack_Struct_Serialize-12 7076667 171.4 ns/op 112 B/op 2 allocs/op
+BenchmarkMsgpack_Struct_Serialize-12 6900595 173.6 ns/op 112 B/op 2 allocs/op
+BenchmarkMsgpack_Struct_Serialize-12 6820158 184.8 ns/op 112 B/op 2 allocs/op
+BenchmarkMsgpack_Struct_Serialize-12 6626666 176.1 ns/op 112 B/op 2 allocs/op
+BenchmarkMsgpack_Struct_Serialize-12 6930025 184.9 ns/op 112 B/op 2 allocs/op
+BenchmarkFory_Struct_Deserialize-12 12602647 85.48 ns/op 32 B/op 1 allocs/op
+BenchmarkFory_Struct_Deserialize-12 14198599 82.69 ns/op 32 B/op 1 allocs/op
+BenchmarkFory_Struct_Deserialize-12 12750420 85.79 ns/op 32 B/op 1 allocs/op
+BenchmarkFory_Struct_Deserialize-12 13704170 83.80 ns/op 32 B/op 1 allocs/op
+BenchmarkFory_Struct_Deserialize-12 14302634 82.66 ns/op 32 B/op 1 allocs/op
+BenchmarkProtobuf_Struct_Deserialize-12 13726815 87.92 ns/op 80 B/op 1 allocs/op
+BenchmarkProtobuf_Struct_Deserialize-12 13350038 87.81 ns/op 80 B/op 1 allocs/op
+BenchmarkProtobuf_Struct_Deserialize-12 13771383 88.75 ns/op 80 B/op 1 allocs/op
+BenchmarkProtobuf_Struct_Deserialize-12 13840743 90.58 ns/op 80 B/op 1 allocs/op
+BenchmarkProtobuf_Struct_Deserialize-12 13009616 90.86 ns/op 80 B/op 1 allocs/op
+BenchmarkMsgpack_Struct_Deserialize-12 3796537 304.3 ns/op 80 B/op 2 allocs/op
+BenchmarkMsgpack_Struct_Deserialize-12 3963567 305.9 ns/op 80 B/op 2 allocs/op
+BenchmarkMsgpack_Struct_Deserialize-12 3949239 305.3 ns/op 80 B/op 2 allocs/op
+BenchmarkMsgpack_Struct_Deserialize-12 3842962 307.7 ns/op 80 B/op 2 allocs/op
+BenchmarkMsgpack_Struct_Deserialize-12 3946874 309.6 ns/op 80 B/op 2 allocs/op
+BenchmarkFory_StructList_Serialize-12 1887151 654.7 ns/op 0 B/op 0 allocs/op
+BenchmarkFory_StructList_Serialize-12 1836488 635.3 ns/op 0 B/op 0 allocs/op
+BenchmarkFory_StructList_Serialize-12 1863346 647.0 ns/op 0 B/op 0 allocs/op
+BenchmarkFory_StructList_Serialize-12 1913204 627.8 ns/op 0 B/op 0 allocs/op
+BenchmarkFory_StructList_Serialize-12 1887578 632.8 ns/op 0 B/op 0 allocs/op
+BenchmarkProtobuf_StructList_Serialize-12 664448 1773 ns/op 3104 B/op 23 allocs/op
+BenchmarkProtobuf_StructList_Serialize-12 684133 1794 ns/op 3104 B/op 23 allocs/op
+BenchmarkProtobuf_StructList_Serialize-12 642586 1784 ns/op 3104 B/op 23 allocs/op
+BenchmarkProtobuf_StructList_Serialize-12 674518 1768 ns/op 3104 B/op 23 allocs/op
+BenchmarkProtobuf_StructList_Serialize-12 668338 1783 ns/op 3104 B/op 23 allocs/op
+BenchmarkMsgpack_StructList_Serialize-12 350497 3433 ns/op 4106 B/op 8 allocs/op
+BenchmarkMsgpack_StructList_Serialize-12 351436 3409 ns/op 4106 B/op 8 allocs/op
+BenchmarkMsgpack_StructList_Serialize-12 344049 3398 ns/op 4106 B/op 8 allocs/op
+BenchmarkMsgpack_StructList_Serialize-12 357286 3361 ns/op 4106 B/op 8 allocs/op
+BenchmarkMsgpack_StructList_Serialize-12 358231 3340 ns/op 4106 B/op 8 allocs/op
+BenchmarkFory_StructList_Deserialize-12 1335152 901.9 ns/op 688 B/op 3 allocs/op
+BenchmarkFory_StructList_Deserialize-12 1295712 878.2 ns/op 688 B/op 3 allocs/op
+BenchmarkFory_StructList_Deserialize-12 1351540 889.7 ns/op 688 B/op 3 allocs/op
+BenchmarkFory_StructList_Deserialize-12 1327351 896.7 ns/op 688 B/op 3 allocs/op
+BenchmarkFory_StructList_Deserialize-12 1326216 906.4 ns/op 688 B/op 3 allocs/op
+BenchmarkProtobuf_StructList_Deserialize-12 618871 1914 ns/op 2808 B/op 28 allocs/op
+BenchmarkProtobuf_StructList_Deserialize-12 552850 1867 ns/op 2808 B/op 28 allocs/op
+BenchmarkProtobuf_StructList_Deserialize-12 621386 1887 ns/op 2808 B/op 28 allocs/op
+BenchmarkProtobuf_StructList_Deserialize-12 626301 1916 ns/op 2808 B/op 28 allocs/op
+BenchmarkProtobuf_StructList_Deserialize-12 619466 1891 ns/op 2808 B/op 28 allocs/op
+BenchmarkMsgpack_StructList_Deserialize-12 209462 5707 ns/op 1424 B/op 7 allocs/op
+BenchmarkMsgpack_StructList_Deserialize-12 205341 5680 ns/op 1424 B/op 7 allocs/op
+BenchmarkMsgpack_StructList_Deserialize-12 212827 5715 ns/op 1424 B/op 7 allocs/op
+BenchmarkMsgpack_StructList_Deserialize-12 212240 5742 ns/op 1424 B/op 7 allocs/op
+BenchmarkMsgpack_StructList_Deserialize-12 214522 5709 ns/op 1424 B/op 7 allocs/op
+BenchmarkFory_Sample_Serialize-12 8722086 137.8 ns/op 0 B/op 0 allocs/op
+BenchmarkFory_Sample_Serialize-12 8074246 137.2 ns/op 0 B/op 0 allocs/op
+BenchmarkFory_Sample_Serialize-12 8734982 137.3 ns/op 0 B/op 0 allocs/op
+BenchmarkFory_Sample_Serialize-12 8774318 137.3 ns/op 0 B/op 0 allocs/op
+BenchmarkFory_Sample_Serialize-12 8791104 137.3 ns/op 0 B/op 0 allocs/op
+BenchmarkProtobuf_Sample_Serialize-12 3474804 339.3 ns/op 704 B/op 2 allocs/op
+BenchmarkProtobuf_Sample_Serialize-12 3353059 350.9 ns/op 704 B/op 2 allocs/op
+BenchmarkProtobuf_Sample_Serialize-12 3485572 359.7 ns/op 704 B/op 2 allocs/op
+BenchmarkProtobuf_Sample_Serialize-12 3293542 364.4 ns/op 704 B/op 2 allocs/op
+BenchmarkProtobuf_Sample_Serialize-12 3304266 367.3 ns/op 704 B/op 2 allocs/op
+BenchmarkMsgpack_Sample_Serialize-12 815510 1454 ns/op 2321 B/op 7 allocs/op
+BenchmarkMsgpack_Sample_Serialize-12 814988 1474 ns/op 2321 B/op 7 allocs/op
+BenchmarkMsgpack_Sample_Serialize-12 819774 1441 ns/op 2321 B/op 7 allocs/op
+BenchmarkMsgpack_Sample_Serialize-12 806146 1448 ns/op 2321 B/op 7 allocs/op
+BenchmarkMsgpack_Sample_Serialize-12 806767 1492 ns/op 2321 B/op 7 allocs/op
+BenchmarkFory_Sample_Deserialize-12 4371154 260.9 ns/op 676 B/op 9 allocs/op
+BenchmarkFory_Sample_Deserialize-12 4748262 256.2 ns/op 676 B/op 9 allocs/op
+BenchmarkFory_Sample_Deserialize-12 4563691 259.0 ns/op 676 B/op 9 allocs/op
+BenchmarkFory_Sample_Deserialize-12 4679144 257.7 ns/op 676 B/op 9 allocs/op
+BenchmarkFory_Sample_Deserialize-12 4577006 263.6 ns/op 676 B/op 9 allocs/op
+BenchmarkProtobuf_Sample_Deserialize-12 2827587 426.9 ns/op 708 B/op 9 allocs/op
+BenchmarkProtobuf_Sample_Deserialize-12 2790972 424.5 ns/op 708 B/op 9 allocs/op
+BenchmarkProtobuf_Sample_Deserialize-12 2761682 436.8 ns/op 708 B/op 9 allocs/op
+BenchmarkProtobuf_Sample_Deserialize-12 2730283 432.4 ns/op 708 B/op 9 allocs/op
+BenchmarkProtobuf_Sample_Deserialize-12 2829603 422.2 ns/op 708 B/op 9 allocs/op
+BenchmarkMsgpack_Sample_Deserialize-12 445099 2801 ns/op 1576 B/op 38 allocs/op
+BenchmarkMsgpack_Sample_Deserialize-12 437914 2686 ns/op 1576 B/op 38 allocs/op
+BenchmarkMsgpack_Sample_Deserialize-12 416235 2660 ns/op 1576 B/op 38 allocs/op
+BenchmarkMsgpack_Sample_Deserialize-12 448528 2650 ns/op 1576 B/op 38 allocs/op
+BenchmarkMsgpack_Sample_Deserialize-12 447135 2661 ns/op 1576 B/op 38 allocs/op
+BenchmarkFory_SampleList_Serialize-12 609176 1948 ns/op 0 B/op 0 allocs/op
+BenchmarkFory_SampleList_Serialize-12 612290 1958 ns/op 0 B/op 0 allocs/op
+BenchmarkFory_SampleList_Serialize-12 605318 1950 ns/op 0 B/op 0 allocs/op
+BenchmarkFory_SampleList_Serialize-12 610993 1945 ns/op 0 B/op 0 allocs/op
+BenchmarkFory_SampleList_Serialize-12 612297 1962 ns/op 0 B/op 0 allocs/op
+BenchmarkProtobuf_SampleList_Serialize-12 167353 6748 ns/op 14816 B/op 23 allocs/op
+BenchmarkProtobuf_SampleList_Serialize-12 170196 6906 ns/op 14816 B/op 23 allocs/op
+BenchmarkProtobuf_SampleList_Serialize-12 170259 7246 ns/op 14816 B/op 23 allocs/op
+BenchmarkProtobuf_SampleList_Serialize-12 170742 7127 ns/op 14816 B/op 23 allocs/op
+BenchmarkProtobuf_SampleList_Serialize-12 167684 7087 ns/op 14816 B/op 23 allocs/op
+BenchmarkMsgpack_SampleList_Serialize-12 46962 25632 ns/op 32793 B/op 11 allocs/op
+BenchmarkMsgpack_SampleList_Serialize-12 47451 25432 ns/op 32793 B/op 11 allocs/op
+BenchmarkMsgpack_SampleList_Serialize-12 44647 26471 ns/op 32793 B/op 11 allocs/op
+BenchmarkMsgpack_SampleList_Serialize-12 46993 25869 ns/op 32793 B/op 11 allocs/op
+BenchmarkMsgpack_SampleList_Serialize-12 46513 26169 ns/op 32792 B/op 11 allocs/op
+BenchmarkFory_SampleList_Deserialize-12 269730 4251 ns/op 13952 B/op 163 allocs/op
+BenchmarkFory_SampleList_Deserialize-12 287401 4202 ns/op 13952 B/op 163 allocs/op
+BenchmarkFory_SampleList_Deserialize-12 283461 4176 ns/op 13952 B/op 163 allocs/op
+BenchmarkFory_SampleList_Deserialize-12 278598 4257 ns/op 13952 B/op 163 allocs/op
+BenchmarkFory_SampleList_Deserialize-12 285021 4234 ns/op 13952 B/op 163 allocs/op
+BenchmarkProtobuf_SampleList_Deserialize-12 130734 9285 ns/op 20872 B/op 188 allocs/op
+BenchmarkProtobuf_SampleList_Deserialize-12 132328 9157 ns/op 20872 B/op 188 allocs/op
+BenchmarkProtobuf_SampleList_Deserialize-12 132595 9258 ns/op 20872 B/op 188 allocs/op
+BenchmarkProtobuf_SampleList_Deserialize-12 128911 9332 ns/op 20872 B/op 188 allocs/op
+BenchmarkProtobuf_SampleList_Deserialize-12 124810 9321 ns/op 20872 B/op 188 allocs/op
+BenchmarkMsgpack_SampleList_Deserialize-12 22225 53384 ns/op 37251 B/op 727 allocs/op
+BenchmarkMsgpack_SampleList_Deserialize-12 22498 54968 ns/op 37251 B/op 727 allocs/op
+BenchmarkMsgpack_SampleList_Deserialize-12 21262 54571 ns/op 37251 B/op 727 allocs/op
+BenchmarkMsgpack_SampleList_Deserialize-12 21877 54363 ns/op 37251 B/op 727 allocs/op
+BenchmarkMsgpack_SampleList_Deserialize-12 21978 53615 ns/op 37251 B/op 727 allocs/op
+BenchmarkFory_MediaContent_Serialize-12 4530111 265.7 ns/op 0 B/op 0 allocs/op
+BenchmarkFory_MediaContent_Serialize-12 4538586 267.6 ns/op 0 B/op 0 allocs/op
+BenchmarkFory_MediaContent_Serialize-12 4477569 264.6 ns/op 0 B/op 0 allocs/op
+BenchmarkFory_MediaContent_Serialize-12 4504632 270.4 ns/op 0 B/op 0 allocs/op
+BenchmarkFory_MediaContent_Serialize-12 4519728 268.8 ns/op 0 B/op 0 allocs/op
+BenchmarkProtobuf_MediaContent_Serialize-12 2446335 486.8 ns/op 1144 B/op 11 allocs/op
+BenchmarkProtobuf_MediaContent_Serialize-12 2468845 489.5 ns/op 1144 B/op 11 allocs/op
+BenchmarkProtobuf_MediaContent_Serialize-12 2463714 468.9 ns/op 1144 B/op 11 allocs/op
+BenchmarkProtobuf_MediaContent_Serialize-12 2605141 467.7 ns/op 1144 B/op 11 allocs/op
+BenchmarkProtobuf_MediaContent_Serialize-12 2586032 471.1 ns/op 1144 B/op 11 allocs/op
+BenchmarkMsgpack_MediaContent_Serialize-12 1496350 787.2 ns/op 1168 B/op 6 allocs/op
+BenchmarkMsgpack_MediaContent_Serialize-12 1533099 794.6 ns/op 1168 B/op 6 allocs/op
+BenchmarkMsgpack_MediaContent_Serialize-12 1533223 786.9 ns/op 1168 B/op 6 allocs/op
+BenchmarkMsgpack_MediaContent_Serialize-12 1558996 778.9 ns/op 1168 B/op 6 allocs/op
+BenchmarkMsgpack_MediaContent_Serialize-12 1535682 773.7 ns/op 1168 B/op 6 allocs/op
+BenchmarkFory_MediaContent_Deserialize-12 2840757 421.6 ns/op 656 B/op 13 allocs/op
+BenchmarkFory_MediaContent_Deserialize-12 2805544 429.2 ns/op 656 B/op 13 allocs/op
+BenchmarkFory_MediaContent_Deserialize-12 2819227 433.5 ns/op 656 B/op 13 allocs/op
+BenchmarkFory_MediaContent_Deserialize-12 2805493 426.6 ns/op 656 B/op 13 allocs/op
+BenchmarkFory_MediaContent_Deserialize-12 2828582 426.9 ns/op 656 B/op 13 allocs/op
+BenchmarkProtobuf_MediaContent_Deserialize-12 2141352 569.0 ns/op 1088 B/op 21 allocs/op
+BenchmarkProtobuf_MediaContent_Deserialize-12 2052590 559.8 ns/op 1088 B/op 21 allocs/op
+BenchmarkProtobuf_MediaContent_Deserialize-12 2134398 550.8 ns/op 1088 B/op 21 allocs/op
+BenchmarkProtobuf_MediaContent_Deserialize-12 2151742 567.4 ns/op 1088 B/op 21 allocs/op
+BenchmarkProtobuf_MediaContent_Deserialize-12 2155804 553.1 ns/op 1088 B/op 21 allocs/op
+BenchmarkMsgpack_MediaContent_Deserialize-12 838147 1376 ns/op 896 B/op 17 allocs/op
+BenchmarkMsgpack_MediaContent_Deserialize-12 824925 1392 ns/op 896 B/op 17 allocs/op
+BenchmarkMsgpack_MediaContent_Deserialize-12 814362 1414 ns/op 896 B/op 17 allocs/op
+BenchmarkMsgpack_MediaContent_Deserialize-12 837973 1399 ns/op 896 B/op 17 allocs/op
+BenchmarkMsgpack_MediaContent_Deserialize-12 850816 1432 ns/op 896 B/op 17 allocs/op
+BenchmarkFory_MediaContentList_Serialize-12 320854 3724 ns/op 0 B/op 0 allocs/op
+BenchmarkFory_MediaContentList_Serialize-12 323788 3725 ns/op 0 B/op 0 allocs/op
+BenchmarkFory_MediaContentList_Serialize-12 323928 3688 ns/op 0 B/op 0 allocs/op
+BenchmarkFory_MediaContentList_Serialize-12 320772 3652 ns/op 0 B/op 0 allocs/op
+BenchmarkFory_MediaContentList_Serialize-12 325976 3736 ns/op 0 B/op 0 allocs/op
+BenchmarkProtobuf_MediaContentList_Serialize-12 128820 9015 ns/op 22848 B/op 203 allocs/op
+BenchmarkProtobuf_MediaContentList_Serialize-12 133196 9049 ns/op 22848 B/op 203 allocs/op
+BenchmarkProtobuf_MediaContentList_Serialize-12 133237 9152 ns/op 22848 B/op 203 allocs/op
+BenchmarkProtobuf_MediaContentList_Serialize-12 131954 8952 ns/op 22848 B/op 203 allocs/op
+BenchmarkProtobuf_MediaContentList_Serialize-12 132843 9107 ns/op 22848 B/op 203 allocs/op
+BenchmarkMsgpack_MediaContentList_Serialize-12 86242 13984 ns/op 16880 B/op 30 allocs/op
+BenchmarkMsgpack_MediaContentList_Serialize-12 84384 14032 ns/op 16880 B/op 30 allocs/op
+BenchmarkMsgpack_MediaContentList_Serialize-12 83804 14321 ns/op 16880 B/op 30 allocs/op
+BenchmarkMsgpack_MediaContentList_Serialize-12 87357 14185 ns/op 16880 B/op 30 allocs/op
+BenchmarkMsgpack_MediaContentList_Serialize-12 85074 13911 ns/op 16880 B/op 30 allocs/op
+BenchmarkFory_MediaContentList_Deserialize-12 158547 7564 ns/op 13040 B/op 243 allocs/op
+BenchmarkFory_MediaContentList_Deserialize-12 159993 7508 ns/op 13040 B/op 243 allocs/op
+BenchmarkFory_MediaContentList_Deserialize-12 159046 7447 ns/op 13040 B/op 243 allocs/op
+BenchmarkFory_MediaContentList_Deserialize-12 163632 7268 ns/op 13040 B/op 243 allocs/op
+BenchmarkFory_MediaContentList_Deserialize-12 163434 7247 ns/op 13040 B/op 243 allocs/op
+BenchmarkProtobuf_MediaContentList_Deserialize-12 92965 11322 ns/op 25400 B/op 428 allocs/op
+BenchmarkProtobuf_MediaContentList_Deserialize-12 105206 11297 ns/op 25400 B/op 428 allocs/op
+BenchmarkProtobuf_MediaContentList_Deserialize-12 104979 11205 ns/op 25400 B/op 428 allocs/op
+BenchmarkProtobuf_MediaContentList_Deserialize-12 105859 11327 ns/op 25400 B/op 428 allocs/op
+BenchmarkProtobuf_MediaContentList_Deserialize-12 105524 11435 ns/op 25400 B/op 428 allocs/op
+BenchmarkMsgpack_MediaContentList_Deserialize-12 43263 27244 ns/op 20058 B/op 307 allocs/op
+BenchmarkMsgpack_MediaContentList_Deserialize-12 44388 27167 ns/op 20058 B/op 307 allocs/op
+BenchmarkMsgpack_MediaContentList_Deserialize-12 44185 27271 ns/op 20058 B/op 307 allocs/op
+BenchmarkMsgpack_MediaContentList_Deserialize-12 43345 27499 ns/op 20058 B/op 307 allocs/op
+BenchmarkMsgpack_MediaContentList_Deserialize-12 43718 27975 ns/op 20058 B/op 307 allocs/op
+PASS
+ok github.com/apache/fory/benchmarks/go_benchmark 256.707s
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/go/benchmark_sample.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/go/benchmark_sample.png
new file mode 100644
index 000000000..7984bae39
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/go/benchmark_sample.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/go/benchmark_samplelist.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/go/benchmark_samplelist.png
new file mode 100644
index 000000000..0f8877114
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/go/benchmark_samplelist.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/go/benchmark_struct.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/go/benchmark_struct.png
new file mode 100644
index 000000000..e07c004ce
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/go/benchmark_struct.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/go/benchmark_structlist.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/go/benchmark_structlist.png
new file mode 100644
index 000000000..5a97780ac
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/go/benchmark_structlist.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/go/serialized_sizes.txt b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/go/serialized_sizes.txt
new file mode 100644
index 000000000..5a54edec6
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/go/serialized_sizes.txt
@@ -0,0 +1,27 @@
+Serialized Sizes (bytes):
+============================================
+NumericStruct:
+ Fory: 58 bytes
+ Protobuf: 61 bytes
+ Msgpack: 57 bytes
+Sample:
+ Fory: 446 bytes
+ Protobuf: 375 bytes
+ Msgpack: 524 bytes
+MediaContent:
+ Fory: 342 bytes
+ Protobuf: 301 bytes
+ Msgpack: 400 bytes
+StructList:
+ Fory: 560 bytes
+ Protobuf: 1260 bytes
+ Msgpack: 1146 bytes
+SampleList:
+ Fory: 7600 bytes
+ Protobuf: 7560 bytes
+ Msgpack: 10486 bytes
+MediaContentList:
+ Fory: 5776 bytes
+ Protobuf: 6080 bytes
+ Msgpack: 8006 bytes
+============================================
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/README.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/README.md
new file mode 100644
index 000000000..72cc3feb7
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/README.md
@@ -0,0 +1,239 @@
+# Java 基准测试
+
+## 系统环境
+
+- Operation System：4.9.151-015.x86_64
+- CPU：Intel(R) Xeon(R) Platinum 8163 CPU @ 2.50GHz
+- Byte Order：Little Endian
+- L1d cache： 32K
+- L1i cache：32K
+- L2 cache： 1024K
+- L3 cache： 33792K
+
+## JMH 参数
+
+不要跳过 **warm up**，否则结果不准确。
+
+```bash
+ -f 1 -wi 3 -i 3 -t 1 -w 2s -r 2s -rf cs
+```
+
+## 基准数据
+
+### Struct
+
+Struct 是一个包含 100 个基础类型字段的类：
+
+```java
+public class Struct {
+ public int f1;
+ public long f2;
+ public float f3;
+ public double f4;
+ // ...
+ public double f99;
+}
+```
+
+### Struct2
+
+Struct2 是一个包含 100 个装箱类型字段的类：
+
+```java
+public class Struct {
+ public Integer f1;
+ public Long f2;
+ public Float f3;
+ public Double f4;
+ // ...
+ public Double f99;
+}
+```
+
+### MediaContent
+
+MEDIA_CONTENT 来自 [jvm-serializers](https://github.com/eishay/jvm-serializers/blob/master/tpc/src/data/media/MediaContent.java).
+
+### Sample
+
+SAMPLE 来自 [kryo benchmark](https://github.com/EsotericSoftware/kryo/blob/master/benchmarks/src/main/java/com/esotericsoftware/kryo/benchmarks/data/Sample.java)
+
+## 基准图表
+
+### 序列化到堆内缓冲区
+
+将数据序列化到 Java 字节数组。
+
+#### Java schema 一致性序列化
+
+反序列化端必须与序列化端使用相同的类定义。
+该模式不支持类的前向/后向兼容。
+
+
+
+#### Java schema 兼容模式序列化
+
+反序列化端可以与序列化端使用不同的类定义。
+该模式支持类的前向/后向兼容。
+
+
+
+#### Java schema 一致性反序列化
+
+反序列化端必须与序列化端使用相同的类定义。
+该模式不支持类的前向/后向兼容。
+
+
+
+#### Java schema 兼容模式反序列化
+
+反序列化端可以与序列化端使用不同的类定义。
+该模式支持类的前向/后向兼容。
+
+
+
+### 堆外序列化
+
+将数据序列化到堆外内存。
+
+#### Java schema 一致性序列化
+
+反序列化端必须与序列化端使用相同的类定义。
+该模式不支持类的前向/后向兼容。
+
+
+
+#### Java schema 兼容模式序列化
+
+反序列化端可以与序列化端使用不同的类定义。
+该模式支持类的前向/后向兼容。
+
+
+
+#### Java schema 一致性反序列化
+
+反序列化端必须与序列化端使用相同的类定义。
+该模式不支持类的前向/后向兼容。
+
+
+
+#### Java schema 兼容模式反序列化
+
+反序列化端可以与序列化端使用不同的类定义。
+该模式支持类的前向/后向兼容。
+
+
+
+### 零拷贝序列化
+
+注意：零拷贝序列化只是在序列化阶段避免拷贝；如果将数据发送到其他机器，仍可能发生拷贝。
+
+但如果在同一节点进程间序列化并使用共享内存，且数据在序列化前已位于堆外，那么其他进程可无拷贝读取该缓冲区。
+
+#### Java 零拷贝序列化到堆内缓冲区
+
+
+
+#### Java 零拷贝序列化到直接缓冲区
+
+
+
+## 基准数据
+
+### Java Serialization
+
+| Benchmark | objectType | bufferType | references | Fory | ForyMetaShared | Kryo | Fst | Hession | Jdk | Protostuff |
+| ---------------------- | ------------- | ------------ | ---------- | -------------- | --------------- | -------------- | ------------- | ------------- | ------------- | ------------- |
+| serialize | STRUCT | array | False | 7501415.567260 | | 558194.100861 | 882178.995727 | 258233.998931 | 155908.244240 | 330975.350403 |
+| serialize | STRUCT | array | True | 6264439.154428 | | 557542.628765 | 757753.756691 | 260845.209485 | 151258.539369 | |
+| serialize | STRUCT | directBuffer | False | 9834223.243204 | | 1078046.011115 | 807847.663261 | 266481.009225 | 154875.908438 | 340262.650047 |
+| serialize | STRUCT | directBuffer | True | 7551780.823133 | | 853350.408656 | 762088.935404 | 261762.594966 | 156404.686214 | |
+| serialize | STRUCT2 | array | False | 3586126.623874 | | 325172.969175 | 371762.982661 | 56056.080075 | 36846.049162 | 322563.440433 |
+| serialize | STRUCT2 | array | True | 3306474.506382 | | 259863.332448 | 380638.700267 | 60038.879790 | 38183.705811 | |
+| serialize | STRUCT2 | directBuffer | False | 2643155.135327 | | 355688.882786 | 365317.705376 | 55924.319442 | 37444.967981 | 325093.716261 |
+| serialize | STRUCT2 | directBuffer | True | 2391110.083108 | | 338960.426033 | 370851.880711 | 56674.065604 | 35798.679246 | |
+| serialize | MEDIA_CONTENT | array | False | 3031642.924542 | | 730792.521676 | 751892.023189 | 367782.358049 | 137989.198821 | 780618.761219 |
+| serialize | MEDIA_CONTENT | array | True | 2250384.600246 | | 445251.084327 | 583859.907758 | 329427.470680 | 140260.668888 | |
+| serialize | MEDIA_CONTENT | directBuffer | False | 2479862.129632 | | 608972.517580 | 728001.080250 | 372477.138150 | 138567.623369 | 805941.345157 |
+| serialize | MEDIA_CONTENT | directBuffer | True | 1938527.588331 | | 359875.473951 | 595679.580108 | 353376.085025 | 140158.673910 | |
+| serialize | SAMPLE | array | False | 3570966.469087 | | 1105365.931217 | 915907.574306 | 220386.502846 | 118374.836631 | 663272.710783 |
+| serialize | SAMPLE | array | True | 1767693.835090 | | 734215.482291 | 731869.156376 | 192414.014211 | 119858.140625 | |
+| serialize | SAMPLE | directBuffer | False | 3684487.760591 | | 1376560.302168 | 902302.261168 | 220981.308085 | 118273.584257 | 693641.589806 |
+| serialize | SAMPLE | directBuffer | True | 1826456.709478 | | 932887.968348 | 723614.066770 | 211949.960255 | 108263.040839 | |
+| serialize_compatible | STRUCT | array | False | 3530406.108869 | 9204444.777172 | 145964.199559 | | 258650.663523 | | |
+| serialize_compatible | STRUCT | array | True | 3293059.098127 | 7064625.291374 | 136180.832879 | | 263564.913879 | | |
+| serialize_compatible | STRUCT | directBuffer | False | 2653169.568374 | 11650229.648715 | 106695.800225 | | 249221.452137 | | |
+| serialize_compatible | STRUCT | directBuffer | True | 2393817.762938 | 8702412.752357 | 106458.212005 | | 263623.143601 | | |
+| serialize_compatible | STRUCT2 | array | False | 2773368.997680 | 2575824.143864 | 125807.748004 | | 58509.125342 | | |
+| serialize_compatible | STRUCT2 | array | True | 2564174.550276 | 3543082.528217 | 114983.546343 | | 55552.977735 | | |
+| serialize_compatible | STRUCT2 | directBuffer | False | 1912402.937879 | 2714748.572248 | 92130.672361 | | 58908.567439 | | |
+| serialize_compatible | STRUCT2 | directBuffer | True | 1848338.968058 | 1866073.031851 | 88989.724768 | | 55524.373547 | | |
+| serialize_compatible | MEDIA_CONTENT | array | False | 1679272.036223 | 2992288.235281 | 188911.259146 | | 377195.903772 | | |
+| serialize_compatible | MEDIA_CONTENT | array | True | 1406736.538716 | 2058738.716953 | 145782.916427 | | 351657.879556 | | |
+| serialize_compatible | MEDIA_CONTENT | directBuffer | False | 1710680.937387 | 2291443.556971 | 185363.714829 | | 371729.727192 | | |
+| serialize_compatible | MEDIA_CONTENT | directBuffer | True | 1149999.473994 | 1804349.244125 | 142836.961878 | | 343834.954942 | | |
+| serialize_compatible | SAMPLE | array | False | 3604596.465625 | 4409055.687063 | 378907.663184 | | 234454.975158 | | |
+| serialize_compatible | SAMPLE | array | True | 1619648.337293 | 1840705.439334 | 320815.567701 | | 206174.173039 | | |
+| serialize_compatible | SAMPLE | directBuffer | False | 3484533.218305 | 5043538.364886 | 296102.615094 | | 194761.224263 | | |
+| serialize_compatible | SAMPLE | directBuffer | True | 1730822.630648 | 1859289.705838 | 276757.392449 | | 212840.483308 | | |
+| deserialize | STRUCT | array | False | 4595230.434552 | | 607750.343557 | 357887.235311 | 84709.108821 | 29603.066599 | 517381.168594 |
+| deserialize | STRUCT | array | True | 4634753.596131 | | 552802.227807 | 353480.554035 | 91050.370224 | 29727.744196 | |
+| deserialize | STRUCT | directBuffer | False | 5012002.859236 | | 910534.169114 | 352441.597147 | 91151.633583 | 28717.004518 | 538922.947147 |
+| deserialize | STRUCT | directBuffer | True | 4864329.316938 | | 914404.107564 | 334574.303484 | 91037.205901 | 29549.998286 | |
+| deserialize | STRUCT2 | array | False | 1126298.359550 | | 275984.042401 | 280131.091068 | 69758.767783 | 14888.805111 | 416212.973861 |
+| deserialize | STRUCT2 | array | True | 1046649.083082 | | 222710.554833 | 260649.308016 | 68616.029248 | 14034.100664 | |
+| deserialize | STRUCT2 | directBuffer | False | 1117586.457565 | | 319247.256793 | 262519.858810 | 66866.108653 | 14652.043788 | 425523.315814 |
+| deserialize | STRUCT2 | directBuffer | True | 1018277.848128 | | 249105.828416 | 234973.637096 | 65338.345185 | 14425.886048 | |
+| deserialize | MEDIA_CONTENT | array | False | 2054066.903469 | | 577631.234369 | 363455.785182 | 118156.072284 | 38536.250402 | 951662.019963 |
+| deserialize | MEDIA_CONTENT | array | True | 1507767.206603 | | 365530.417232 | 304371.728638 | 120016.594171 | 38957.191090 | |
+| deserialize | MEDIA_CONTENT | directBuffer | False | 1502746.028159 | | 389473.174523 | 311691.658687 | 111067.942626 | 40512.632076 | 964664.641598 |
+| deserialize | MEDIA_CONTENT | directBuffer | True | 1290593.975753 | | 306995.220799 | 251820.171513 | 121820.821260 | 37030.594632 | |
+| deserialize | SAMPLE | array | False | 2069988.624415 | | 979173.981159 | 473409.796491 | 119471.518388 | 29309.573998 | 619338.385412 |
+| deserialize | SAMPLE | array | True | 1797942.442313 | | 716438.884369 | 428315.502365 | 121106.002978 | 27466.003923 | |
+| deserialize | SAMPLE | directBuffer | False | 2229791.078395 | | 983538.936801 | 441027.550809 | 117806.916589 | 28128.457935 | 624804.978534 |
+| deserialize | SAMPLE | directBuffer | True | 1958815.397807 | | 762889.302732 | 420523.770904 | 121940.783597 | 28221.014735 | |
+| deserialize_compatible | STRUCT | array | False | 2110335.039275 | 4978833.206806 | 78771.635309 | | 88617.486795 | | |
+| deserialize_compatible | STRUCT | array | True | 2135681.982674 | 4807963.882520 | 72805.937649 | | 90206.654212 | | |
+| deserialize_compatible | STRUCT | directBuffer | False | 1596464.248141 | 5149070.657830 | 58574.904225 | | 89580.561575 | | |
+| deserialize_compatible | STRUCT | directBuffer | True | 1684681.074242 | 5137500.621288 | 60685.320299 | | 84407.472531 | | |
+| deserialize_compatible | STRUCT2 | array | False | 849507.176263 | 1201998.142474 | 60602.285743 | | 63703.763814 | | |
+| deserialize_compatible | STRUCT2 | array | True | 815120.319155 | 1058423.614156 | 62729.908347 | | 69521.573119 | | |
+| deserialize_compatible | STRUCT2 | directBuffer | False | 784036.589363 | 1131212.586953 | 54637.329134 | | 69342.030965 | | |
+| deserialize_compatible | STRUCT2 | directBuffer | True | 782679.662083 | 1089162.408165 | 51761.569591 | | 68542.055543 | | |
+| deserialize_compatible | MEDIA_CONTENT | array | False | 1441671.706320 | 2279742.810882 | 180882.860363 | | 121619.090797 | | |
+| deserialize_compatible | MEDIA_CONTENT | array | True | 1121136.039627 | 1623938.202345 | 154311.211540 | | 119994.104050 | | |
+| deserialize_compatible | MEDIA_CONTENT | directBuffer | False | 1256034.732514 | 1718098.363961 | 134485.160300 | | 107594.474890 | | |
+| deserialize_compatible | MEDIA_CONTENT | directBuffer | True | 1054942.751816 | 1333345.536684 | 119311.787329 | | 116531.023438 | | |
+| deserialize_compatible | SAMPLE | array | False | 2296046.895861 | 2485564.396196 | 255086.928308 | | 121898.105768 | | |
+| deserialize_compatible | SAMPLE | array | True | 1834139.395757 | 2002938.794909 | 238811.995510 | | 121297.485903 | | |
+| deserialize_compatible | SAMPLE | directBuffer | False | 2308111.633661 | 2289261.533644 | 201993.787890 | | 124044.417439 | | |
+| deserialize_compatible | SAMPLE | directBuffer | True | 1820490.585648 | 1927548.827586 | 174534.710870 | | 120276.449497 | | |
+
+### Java 零拷贝
+
+| Benchmark | array_size | bufferType | dataType | Fory | Kryo | Fst |
+| ----------- | ---------- | ------------ | --------------- | -------------- | -------------- | -------------- |
+| serialize | 200 | array | BUFFER | 5123572.914045 | 1985187.977633 | 2400193.220466 |
+| serialize | 200 | array | PRIMITIVE_ARRAY | 8297232.942927 | 147342.606262 | 313986.053417 |
+| serialize | 200 | directBuffer | BUFFER | 5400346.890126 | 1739454.519770 | 2282550.111756 |
+| serialize | 200 | directBuffer | PRIMITIVE_ARRAY | 8335248.350301 | 972683.763633 | 294132.218623 |
+| serialize | 1000 | array | BUFFER | 4979590.929127 | 1616159.671230 | 1805557.477810 |
+| serialize | 1000 | array | PRIMITIVE_ARRAY | 8772856.921028 | 31395.721514 | 67209.107012 |
+| serialize | 1000 | directBuffer | BUFFER | 5376191.775007 | 1377272.568510 | 1644789.427010 |
+| serialize | 1000 | directBuffer | PRIMITIVE_ARRAY | 8207563.785251 | 209183.090868 | 66108.014322 |
+| serialize | 5000 | array | BUFFER | 5018916.322770 | 711287.533377 | 811029.402136 |
+| serialize | 5000 | array | PRIMITIVE_ARRAY | 8027439.580226 | 6248.006967 | 14997.400124 |
+| serialize | 5000 | directBuffer | BUFFER | 5330897.682960 | 707092.956534 | 477148.540850 |
+| serialize | 5000 | directBuffer | PRIMITIVE_ARRAY | 7695981.988316 | 43565.678616 | 15000.378818 |
+| deserialize | 200 | array | BUFFER | 3302149.383135 | 1296284.787720 | 657754.887247 |
+| deserialize | 200 | array | PRIMITIVE_ARRAY | 986136.067809 | 146675.360652 | 219333.990504 |
+| deserialize | 200 | directBuffer | BUFFER | 3113115.471758 | 1004844.498712 | 598421.278941 |
+| deserialize | 200 | directBuffer | PRIMITIVE_ARRAY | 991807.969328 | 518713.299422 | 179604.045774 |
+| deserialize | 1000 | array | BUFFER | 2831942.848999 | 721266.541130 | 422147.154601 |
+| deserialize | 1000 | array | PRIMITIVE_ARRAY | 205671.992736 | 30409.835023 | 53100.903684 |
+| deserialize | 1000 | directBuffer | BUFFER | 3397690.327371 | 592972.713203 | 298929.116572 |
+| deserialize | 1000 | directBuffer | PRIMITIVE_ARRAY | 202275.242341 | 112132.004609 | 38572.001768 |
+| deserialize | 5000 | array | BUFFER | 3296658.120035 | 147251.846111 | 136934.604328 |
+| deserialize | 5000 | array | PRIMITIVE_ARRAY | 40312.590172 | 6122.351228 | 10672.872798 |
+| deserialize | 5000 | directBuffer | BUFFER | 3284441.570594 | 148614.476829 | 77950.612503 |
+| deserialize | 5000 | directBuffer | PRIMITIVE_ARRAY | 40413.743717 | 21826.040410 | 8561.694533 |
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/data/jmh-jdk-11-deserialization.csv b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/data/jmh-jdk-11-deserialization.csv
new file mode 100644
index 000000000..98760a472
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/data/jmh-jdk-11-deserialization.csv
@@ -0,0 +1,153 @@
+"Benchmark","Mode","Threads","Samples","Score","Score Error (99.9%)","Unit","Param: bufferType","Param: objectType","Param: references"
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fst_deserialize","thrpt",1,3,473409.796491,250793.361170,"ops/s",array,SAMPLE,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fst_deserialize","thrpt",1,3,428315.502365,191770.682411,"ops/s",array,SAMPLE,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fst_deserialize","thrpt",1,3,363455.785182,44717.666948,"ops/s",array,MEDIA_CONTENT,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fst_deserialize","thrpt",1,3,304371.728638,74831.791688,"ops/s",array,MEDIA_CONTENT,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fst_deserialize","thrpt",1,3,357887.235311,218092.594151,"ops/s",array,STRUCT,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fst_deserialize","thrpt",1,3,353480.554035,229239.505256,"ops/s",array,STRUCT,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fst_deserialize","thrpt",1,3,280131.091068,89472.347221,"ops/s",array,STRUCT2,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fst_deserialize","thrpt",1,3,260649.308016,165597.762734,"ops/s",array,STRUCT2,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fst_deserialize","thrpt",1,3,441027.550809,321712.847983,"ops/s",directBuffer,SAMPLE,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fst_deserialize","thrpt",1,3,420523.770904,122531.658151,"ops/s",directBuffer,SAMPLE,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fst_deserialize","thrpt",1,3,311691.658687,185300.664992,"ops/s",directBuffer,MEDIA_CONTENT,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fst_deserialize","thrpt",1,3,251820.171513,894743.730727,"ops/s",directBuffer,MEDIA_CONTENT,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fst_deserialize","thrpt",1,3,352441.597147,109488.413174,"ops/s",directBuffer,STRUCT,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fst_deserialize","thrpt",1,3,334574.303484,89858.329407,"ops/s",directBuffer,STRUCT,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fst_deserialize","thrpt",1,3,262519.858810,138990.948859,"ops/s",directBuffer,STRUCT2,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fst_deserialize","thrpt",1,3,234973.637096,568162.582389,"ops/s",directBuffer,STRUCT2,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fory_deserialize","thrpt",1,3,2069988.624415,1501625.089719,"ops/s",array,SAMPLE,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fory_deserialize","thrpt",1,3,1797942.442313,3541577.357052,"ops/s",array,SAMPLE,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fory_deserialize","thrpt",1,3,2054066.903469,3314161.094630,"ops/s",array,MEDIA_CONTENT,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fory_deserialize","thrpt",1,3,1507767.206603,1662320.958961,"ops/s",array,MEDIA_CONTENT,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fory_deserialize","thrpt",1,3,4595230.434552,678411.427346,"ops/s",array,STRUCT,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fory_deserialize","thrpt",1,3,4634753.596131,582102.492158,"ops/s",array,STRUCT,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fory_deserialize","thrpt",1,3,1126298.359550,856691.704987,"ops/s",array,STRUCT2,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fory_deserialize","thrpt",1,3,1046649.083082,1816153.563648,"ops/s",array,STRUCT2,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fory_deserialize","thrpt",1,3,2229791.078395,2950833.975767,"ops/s",directBuffer,SAMPLE,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fory_deserialize","thrpt",1,3,1958815.397807,381903.427430,"ops/s",directBuffer,SAMPLE,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fory_deserialize","thrpt",1,3,1502746.028159,1759759.267183,"ops/s",directBuffer,MEDIA_CONTENT,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fory_deserialize","thrpt",1,3,1290593.975753,246089.810346,"ops/s",directBuffer,MEDIA_CONTENT,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fory_deserialize","thrpt",1,3,5012002.859236,3360944.705659,"ops/s",directBuffer,STRUCT,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fory_deserialize","thrpt",1,3,4864329.316938,4357833.300692,"ops/s",directBuffer,STRUCT,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fory_deserialize","thrpt",1,3,1117586.457565,323438.118804,"ops/s",directBuffer,STRUCT2,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fory_deserialize","thrpt",1,3,1018277.848128,1141314.435153,"ops/s",directBuffer,STRUCT2,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fory_deserialize_compatible","thrpt",1,3,2296046.895861,2532372.600048,"ops/s",array,SAMPLE,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fory_deserialize_compatible","thrpt",1,3,1834139.395757,1021897.505849,"ops/s",array,SAMPLE,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fory_deserialize_compatible","thrpt",1,3,1441671.706320,317052.609754,"ops/s",array,MEDIA_CONTENT,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fory_deserialize_compatible","thrpt",1,3,1121136.039627,979316.642796,"ops/s",array,MEDIA_CONTENT,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fory_deserialize_compatible","thrpt",1,3,2110335.039275,389404.889706,"ops/s",array,STRUCT,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fory_deserialize_compatible","thrpt",1,3,2135681.982674,1140328.709799,"ops/s",array,STRUCT,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fory_deserialize_compatible","thrpt",1,3,849507.176263,77466.989680,"ops/s",array,STRUCT2,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fory_deserialize_compatible","thrpt",1,3,815120.319155,110547.743648,"ops/s",array,STRUCT2,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fory_deserialize_compatible","thrpt",1,3,2308111.633661,1699117.497565,"ops/s",directBuffer,SAMPLE,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fory_deserialize_compatible","thrpt",1,3,1820490.585648,244290.391445,"ops/s",directBuffer,SAMPLE,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fory_deserialize_compatible","thrpt",1,3,1256034.732514,811833.294307,"ops/s",directBuffer,MEDIA_CONTENT,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fory_deserialize_compatible","thrpt",1,3,1054942.751816,180122.424477,"ops/s",directBuffer,MEDIA_CONTENT,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fory_deserialize_compatible","thrpt",1,3,1596464.248141,1624412.248391,"ops/s",directBuffer,STRUCT,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fory_deserialize_compatible","thrpt",1,3,1684681.074242,865262.572050,"ops/s",directBuffer,STRUCT,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fory_deserialize_compatible","thrpt",1,3,784036.589363,189745.805570,"ops/s",directBuffer,STRUCT2,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.fory_deserialize_compatible","thrpt",1,3,782679.662083,232459.929272,"ops/s",directBuffer,STRUCT2,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.forymetashared_deserialize_compatible","thrpt",1,3,2485564.396196,404678.689647,"ops/s",array,SAMPLE,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.forymetashared_deserialize_compatible","thrpt",1,3,2002938.794909,254819.284313,"ops/s",array,SAMPLE,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.forymetashared_deserialize_compatible","thrpt",1,3,2279742.810882,1984221.778254,"ops/s",array,MEDIA_CONTENT,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.forymetashared_deserialize_compatible","thrpt",1,3,1623938.202345,902985.831204,"ops/s",array,MEDIA_CONTENT,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.forymetashared_deserialize_compatible","thrpt",1,3,4978833.206806,1201415.339844,"ops/s",array,STRUCT,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.forymetashared_deserialize_compatible","thrpt",1,3,4807963.882520,981981.561987,"ops/s",array,STRUCT,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.forymetashared_deserialize_compatible","thrpt",1,3,1201998.142474,446807.356524,"ops/s",array,STRUCT2,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.forymetashared_deserialize_compatible","thrpt",1,3,1058423.614156,2254684.330438,"ops/s",array,STRUCT2,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.forymetashared_deserialize_compatible","thrpt",1,3,2289261.533644,330913.304260,"ops/s",directBuffer,SAMPLE,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.forymetashared_deserialize_compatible","thrpt",1,3,1927548.827586,2169684.221478,"ops/s",directBuffer,SAMPLE,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.forymetashared_deserialize_compatible","thrpt",1,3,1718098.363961,1096276.962216,"ops/s",directBuffer,MEDIA_CONTENT,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.forymetashared_deserialize_compatible","thrpt",1,3,1333345.536684,1110700.750020,"ops/s",directBuffer,MEDIA_CONTENT,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.forymetashared_deserialize_compatible","thrpt",1,3,5149070.657830,3249519.880480,"ops/s",directBuffer,STRUCT,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.forymetashared_deserialize_compatible","thrpt",1,3,5137500.621288,3988987.937014,"ops/s",directBuffer,STRUCT,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.forymetashared_deserialize_compatible","thrpt",1,3,1131212.586953,240674.468318,"ops/s",directBuffer,STRUCT2,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.forymetashared_deserialize_compatible","thrpt",1,3,1089162.408165,294119.059967,"ops/s",directBuffer,STRUCT2,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.hession_deserialize","thrpt",1,3,119471.518388,29846.632785,"ops/s",array,SAMPLE,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.hession_deserialize","thrpt",1,3,121106.002978,27710.578092,"ops/s",array,SAMPLE,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.hession_deserialize","thrpt",1,3,118156.072284,4767.841380,"ops/s",array,MEDIA_CONTENT,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.hession_deserialize","thrpt",1,3,120016.594171,41255.986380,"ops/s",array,MEDIA_CONTENT,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.hession_deserialize","thrpt",1,3,84709.108821,132894.355932,"ops/s",array,STRUCT,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.hession_deserialize","thrpt",1,3,91050.370224,17939.461828,"ops/s",array,STRUCT,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.hession_deserialize","thrpt",1,3,69758.767783,10886.276794,"ops/s",array,STRUCT2,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.hession_deserialize","thrpt",1,3,68616.029248,13625.851120,"ops/s",array,STRUCT2,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.hession_deserialize","thrpt",1,3,117806.916589,35449.535259,"ops/s",directBuffer,SAMPLE,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.hession_deserialize","thrpt",1,3,121940.783597,54381.355274,"ops/s",directBuffer,SAMPLE,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.hession_deserialize","thrpt",1,3,111067.942626,136178.034974,"ops/s",directBuffer,MEDIA_CONTENT,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.hession_deserialize","thrpt",1,3,121820.821260,36972.450957,"ops/s",directBuffer,MEDIA_CONTENT,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.hession_deserialize","thrpt",1,3,91151.633583,18401.579776,"ops/s",directBuffer,STRUCT,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.hession_deserialize","thrpt",1,3,91037.205901,58868.732797,"ops/s",directBuffer,STRUCT,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.hession_deserialize","thrpt",1,3,66866.108653,38522.707093,"ops/s",directBuffer,STRUCT2,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.hession_deserialize","thrpt",1,3,65338.345185,56556.914062,"ops/s",directBuffer,STRUCT2,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.hession_deserialize_compatible","thrpt",1,3,121898.105768,55415.594537,"ops/s",array,SAMPLE,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.hession_deserialize_compatible","thrpt",1,3,121297.485903,33990.621079,"ops/s",array,SAMPLE,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.hession_deserialize_compatible","thrpt",1,3,121619.090797,6094.683470,"ops/s",array,MEDIA_CONTENT,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.hession_deserialize_compatible","thrpt",1,3,119994.104050,24538.128667,"ops/s",array,MEDIA_CONTENT,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.hession_deserialize_compatible","thrpt",1,3,88617.486795,40076.835119,"ops/s",array,STRUCT,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.hession_deserialize_compatible","thrpt",1,3,90206.654212,19313.248466,"ops/s",array,STRUCT,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.hession_deserialize_compatible","thrpt",1,3,63703.763814,132184.298414,"ops/s",array,STRUCT2,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.hession_deserialize_compatible","thrpt",1,3,69521.573119,8875.645591,"ops/s",array,STRUCT2,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.hession_deserialize_compatible","thrpt",1,3,124044.417439,41135.181705,"ops/s",directBuffer,SAMPLE,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.hession_deserialize_compatible","thrpt",1,3,120276.449497,87827.771405,"ops/s",directBuffer,SAMPLE,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.hession_deserialize_compatible","thrpt",1,3,107594.474890,81084.454215,"ops/s",directBuffer,MEDIA_CONTENT,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.hession_deserialize_compatible","thrpt",1,3,116531.023438,141591.979641,"ops/s",directBuffer,MEDIA_CONTENT,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.hession_deserialize_compatible","thrpt",1,3,89580.561575,23464.095972,"ops/s",directBuffer,STRUCT,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.hession_deserialize_compatible","thrpt",1,3,84407.472531,46007.731889,"ops/s",directBuffer,STRUCT,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.hession_deserialize_compatible","thrpt",1,3,69342.030965,17706.784671,"ops/s",directBuffer,STRUCT2,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.hession_deserialize_compatible","thrpt",1,3,68542.055543,31793.805138,"ops/s",directBuffer,STRUCT2,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.jdk_deserialize","thrpt",1,3,29309.573998,765.998843,"ops/s",array,SAMPLE,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.jdk_deserialize","thrpt",1,3,27466.003923,14896.452629,"ops/s",array,SAMPLE,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.jdk_deserialize","thrpt",1,3,38536.250402,28217.590983,"ops/s",array,MEDIA_CONTENT,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.jdk_deserialize","thrpt",1,3,38957.191090,23931.545367,"ops/s",array,MEDIA_CONTENT,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.jdk_deserialize","thrpt",1,3,29603.066599,10373.666720,"ops/s",array,STRUCT,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.jdk_deserialize","thrpt",1,3,29727.744196,15820.774882,"ops/s",array,STRUCT,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.jdk_deserialize","thrpt",1,3,14888.805111,842.165916,"ops/s",array,STRUCT2,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.jdk_deserialize","thrpt",1,3,14034.100664,13936.787605,"ops/s",array,STRUCT2,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.jdk_deserialize","thrpt",1,3,28128.457935,5385.055284,"ops/s",directBuffer,SAMPLE,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.jdk_deserialize","thrpt",1,3,28221.014735,15281.277719,"ops/s",directBuffer,SAMPLE,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.jdk_deserialize","thrpt",1,3,40512.632076,8592.454839,"ops/s",directBuffer,MEDIA_CONTENT,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.jdk_deserialize","thrpt",1,3,37030.594632,9683.316145,"ops/s",directBuffer,MEDIA_CONTENT,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.jdk_deserialize","thrpt",1,3,28717.004518,17023.663871,"ops/s",directBuffer,STRUCT,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.jdk_deserialize","thrpt",1,3,29549.998286,13823.854047,"ops/s",directBuffer,STRUCT,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.jdk_deserialize","thrpt",1,3,14652.043788,2419.900104,"ops/s",directBuffer,STRUCT2,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.jdk_deserialize","thrpt",1,3,14425.886048,8723.095052,"ops/s",directBuffer,STRUCT2,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.kryo_deserialize","thrpt",1,3,979173.981159,178146.966897,"ops/s",array,SAMPLE,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.kryo_deserialize","thrpt",1,3,716438.884369,623966.984928,"ops/s",array,SAMPLE,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.kryo_deserialize","thrpt",1,3,577631.234369,221011.018380,"ops/s",array,MEDIA_CONTENT,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.kryo_deserialize","thrpt",1,3,365530.417232,214946.853015,"ops/s",array,MEDIA_CONTENT,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.kryo_deserialize","thrpt",1,3,607750.343557,99638.164976,"ops/s",array,STRUCT,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.kryo_deserialize","thrpt",1,3,552802.227807,126286.013177,"ops/s",array,STRUCT,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.kryo_deserialize","thrpt",1,3,275984.042401,9405.143983,"ops/s",array,STRUCT2,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.kryo_deserialize","thrpt",1,3,222710.554833,45168.519253,"ops/s",array,STRUCT2,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.kryo_deserialize","thrpt",1,3,983538.936801,1112062.949472,"ops/s",directBuffer,SAMPLE,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.kryo_deserialize","thrpt",1,3,762889.302732,279678.610328,"ops/s",directBuffer,SAMPLE,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.kryo_deserialize","thrpt",1,3,389473.174523,43058.395501,"ops/s",directBuffer,MEDIA_CONTENT,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.kryo_deserialize","thrpt",1,3,306995.220799,57411.579647,"ops/s",directBuffer,MEDIA_CONTENT,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.kryo_deserialize","thrpt",1,3,910534.169114,1888677.766640,"ops/s",directBuffer,STRUCT,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.kryo_deserialize","thrpt",1,3,914404.107564,357717.816934,"ops/s",directBuffer,STRUCT,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.kryo_deserialize","thrpt",1,3,319247.256793,217674.935649,"ops/s",directBuffer,STRUCT2,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.kryo_deserialize","thrpt",1,3,249105.828416,131690.474985,"ops/s",directBuffer,STRUCT2,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.kryo_deserialize_compatible","thrpt",1,3,255086.928308,23672.392381,"ops/s",array,SAMPLE,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.kryo_deserialize_compatible","thrpt",1,3,238811.995510,18059.118666,"ops/s",array,SAMPLE,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.kryo_deserialize_compatible","thrpt",1,3,180882.860363,69339.581545,"ops/s",array,MEDIA_CONTENT,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.kryo_deserialize_compatible","thrpt",1,3,154311.211540,23065.912064,"ops/s",array,MEDIA_CONTENT,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.kryo_deserialize_compatible","thrpt",1,3,78771.635309,45155.641241,"ops/s",array,STRUCT,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.kryo_deserialize_compatible","thrpt",1,3,72805.937649,16849.888437,"ops/s",array,STRUCT,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.kryo_deserialize_compatible","thrpt",1,3,60602.285743,61404.274046,"ops/s",array,STRUCT2,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.kryo_deserialize_compatible","thrpt",1,3,62729.908347,32805.651539,"ops/s",array,STRUCT2,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.kryo_deserialize_compatible","thrpt",1,3,201993.787890,41567.224827,"ops/s",directBuffer,SAMPLE,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.kryo_deserialize_compatible","thrpt",1,3,174534.710870,96357.498949,"ops/s",directBuffer,SAMPLE,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.kryo_deserialize_compatible","thrpt",1,3,134485.160300,104898.991148,"ops/s",directBuffer,MEDIA_CONTENT,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.kryo_deserialize_compatible","thrpt",1,3,119311.787329,66580.856795,"ops/s",directBuffer,MEDIA_CONTENT,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.kryo_deserialize_compatible","thrpt",1,3,58574.904225,140682.248378,"ops/s",directBuffer,STRUCT,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.kryo_deserialize_compatible","thrpt",1,3,60685.320299,24159.853451,"ops/s",directBuffer,STRUCT,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.kryo_deserialize_compatible","thrpt",1,3,54637.329134,14011.283798,"ops/s",directBuffer,STRUCT2,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.kryo_deserialize_compatible","thrpt",1,3,51761.569591,61030.640534,"ops/s",directBuffer,STRUCT2,true
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.protostuff_deserialize","thrpt",1,3,619338.385412,275705.847169,"ops/s",array,SAMPLE,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.protostuff_deserialize","thrpt",1,3,951662.019963,165160.853007,"ops/s",array,MEDIA_CONTENT,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.protostuff_deserialize","thrpt",1,3,517381.168594,313746.662696,"ops/s",array,STRUCT,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.protostuff_deserialize","thrpt",1,3,416212.973861,119393.345217,"ops/s",array,STRUCT2,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.protostuff_deserialize","thrpt",1,3,624804.978534,147685.682690,"ops/s",directBuffer,SAMPLE,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.protostuff_deserialize","thrpt",1,3,964664.641598,218386.902856,"ops/s",directBuffer,MEDIA_CONTENT,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.protostuff_deserialize","thrpt",1,3,538922.947147,59168.303230,"ops/s",directBuffer,STRUCT,false
+"org.apache.fory.benchmark.UserTypeDeserializeSuite.protostuff_deserialize","thrpt",1,3,425523.315814,179264.359952,"ops/s",directBuffer,STRUCT2,false
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/data/jmh-jdk-11-serialization.csv b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/data/jmh-jdk-11-serialization.csv
new file mode 100644
index 000000000..2e985751a
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/data/jmh-jdk-11-serialization.csv
@@ -0,0 +1,153 @@
+"Benchmark","Mode","Threads","Samples","Score","Score Error (99.9%)","Unit","Param: bufferType","Param: objectType","Param: references"
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fst_serialize","thrpt",1,3,915907.574306,87627.907529,"ops/s",array,SAMPLE,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fst_serialize","thrpt",1,3,731869.156376,37845.555465,"ops/s",array,SAMPLE,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fst_serialize","thrpt",1,3,751892.023189,174327.010719,"ops/s",array,MEDIA_CONTENT,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fst_serialize","thrpt",1,3,583859.907758,320047.618377,"ops/s",array,MEDIA_CONTENT,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fst_serialize","thrpt",1,3,882178.995727,294884.724923,"ops/s",array,STRUCT,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fst_serialize","thrpt",1,3,757753.756691,605180.489112,"ops/s",array,STRUCT,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fst_serialize","thrpt",1,3,371762.982661,80513.482138,"ops/s",array,STRUCT2,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fst_serialize","thrpt",1,3,380638.700267,101974.434105,"ops/s",array,STRUCT2,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fst_serialize","thrpt",1,3,902302.261168,474054.277143,"ops/s",directBuffer,SAMPLE,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fst_serialize","thrpt",1,3,723614.066770,77429.645491,"ops/s",directBuffer,SAMPLE,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fst_serialize","thrpt",1,3,728001.080250,75699.111305,"ops/s",directBuffer,MEDIA_CONTENT,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fst_serialize","thrpt",1,3,595679.580108,117269.848918,"ops/s",directBuffer,MEDIA_CONTENT,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fst_serialize","thrpt",1,3,807847.663261,67842.801069,"ops/s",directBuffer,STRUCT,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fst_serialize","thrpt",1,3,762088.935404,575559.070335,"ops/s",directBuffer,STRUCT,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fst_serialize","thrpt",1,3,365317.705376,138313.634773,"ops/s",directBuffer,STRUCT2,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fst_serialize","thrpt",1,3,370851.880711,66834.323719,"ops/s",directBuffer,STRUCT2,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fory_serialize","thrpt",1,3,3570966.469087,152949.902180,"ops/s",array,SAMPLE,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fory_serialize","thrpt",1,3,1767693.835090,263146.035836,"ops/s",array,SAMPLE,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fory_serialize","thrpt",1,3,3031642.924542,567213.986117,"ops/s",array,MEDIA_CONTENT,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fory_serialize","thrpt",1,3,2250384.600246,529709.299207,"ops/s",array,MEDIA_CONTENT,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fory_serialize","thrpt",1,3,7501415.567260,6672023.542025,"ops/s",array,STRUCT,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fory_serialize","thrpt",1,3,6264439.154428,976363.317001,"ops/s",array,STRUCT,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fory_serialize","thrpt",1,3,3586126.623874,1966282.728305,"ops/s",array,STRUCT2,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fory_serialize","thrpt",1,3,3306474.506382,869558.338568,"ops/s",array,STRUCT2,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fory_serialize","thrpt",1,3,3684487.760591,882227.920611,"ops/s",directBuffer,SAMPLE,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fory_serialize","thrpt",1,3,1826456.709478,1377648.673630,"ops/s",directBuffer,SAMPLE,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fory_serialize","thrpt",1,3,2479862.129632,1498299.302699,"ops/s",directBuffer,MEDIA_CONTENT,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fory_serialize","thrpt",1,3,1938527.588331,148125.034055,"ops/s",directBuffer,MEDIA_CONTENT,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fory_serialize","thrpt",1,3,9834223.243204,5284494.290641,"ops/s",directBuffer,STRUCT,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fory_serialize","thrpt",1,3,7551780.823133,744016.111639,"ops/s",directBuffer,STRUCT,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fory_serialize","thrpt",1,3,2643155.135327,200764.008652,"ops/s",directBuffer,STRUCT2,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fory_serialize","thrpt",1,3,2391110.083108,2608567.411194,"ops/s",directBuffer,STRUCT2,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fory_serialize_compatible","thrpt",1,3,3604596.465625,1232634.245435,"ops/s",array,SAMPLE,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fory_serialize_compatible","thrpt",1,3,1619648.337293,212055.067245,"ops/s",array,SAMPLE,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fory_serialize_compatible","thrpt",1,3,1679272.036223,788041.322785,"ops/s",array,MEDIA_CONTENT,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fory_serialize_compatible","thrpt",1,3,1406736.538716,263608.222325,"ops/s",array,MEDIA_CONTENT,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fory_serialize_compatible","thrpt",1,3,3530406.108869,3125642.741982,"ops/s",array,STRUCT,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fory_serialize_compatible","thrpt",1,3,3293059.098127,96940.669016,"ops/s",array,STRUCT,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fory_serialize_compatible","thrpt",1,3,2773368.997680,503239.905176,"ops/s",array,STRUCT2,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fory_serialize_compatible","thrpt",1,3,2564174.550276,978139.792610,"ops/s",array,STRUCT2,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fory_serialize_compatible","thrpt",1,3,3484533.218305,476583.192148,"ops/s",directBuffer,SAMPLE,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fory_serialize_compatible","thrpt",1,3,1730822.630648,410016.597939,"ops/s",directBuffer,SAMPLE,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fory_serialize_compatible","thrpt",1,3,1710680.937387,307207.222026,"ops/s",directBuffer,MEDIA_CONTENT,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fory_serialize_compatible","thrpt",1,3,1149999.473994,140915.968294,"ops/s",directBuffer,MEDIA_CONTENT,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fory_serialize_compatible","thrpt",1,3,2653169.568374,535312.987476,"ops/s",directBuffer,STRUCT,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fory_serialize_compatible","thrpt",1,3,2393817.762938,380997.375838,"ops/s",directBuffer,STRUCT,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fory_serialize_compatible","thrpt",1,3,1912402.937879,284090.793301,"ops/s",directBuffer,STRUCT2,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.fory_serialize_compatible","thrpt",1,3,1848338.968058,108311.846780,"ops/s",directBuffer,STRUCT2,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.forymetashared_serialize_compatible","thrpt",1,3,4409055.687063,112740.443049,"ops/s",array,SAMPLE,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.forymetashared_serialize_compatible","thrpt",1,3,1840705.439334,516764.580627,"ops/s",array,SAMPLE,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.forymetashared_serialize_compatible","thrpt",1,3,2992288.235281,867622.163323,"ops/s",array,MEDIA_CONTENT,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.forymetashared_serialize_compatible","thrpt",1,3,2058738.716953,2388681.798594,"ops/s",array,MEDIA_CONTENT,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.forymetashared_serialize_compatible","thrpt",1,3,9204444.777172,1526628.258403,"ops/s",array,STRUCT,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.forymetashared_serialize_compatible","thrpt",1,3,7064625.291374,2655795.498346,"ops/s",array,STRUCT,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.forymetashared_serialize_compatible","thrpt",1,3,2575824.143864,2216634.295140,"ops/s",array,STRUCT2,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.forymetashared_serialize_compatible","thrpt",1,3,3543082.528217,393858.603613,"ops/s",array,STRUCT2,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.forymetashared_serialize_compatible","thrpt",1,3,5043538.364886,2797987.191909,"ops/s",directBuffer,SAMPLE,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.forymetashared_serialize_compatible","thrpt",1,3,1859289.705838,366893.710607,"ops/s",directBuffer,SAMPLE,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.forymetashared_serialize_compatible","thrpt",1,3,2291443.556971,3167882.958411,"ops/s",directBuffer,MEDIA_CONTENT,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.forymetashared_serialize_compatible","thrpt",1,3,1804349.244125,481995.792041,"ops/s",directBuffer,MEDIA_CONTENT,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.forymetashared_serialize_compatible","thrpt",1,3,11650229.648715,1101289.207239,"ops/s",directBuffer,STRUCT,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.forymetashared_serialize_compatible","thrpt",1,3,8702412.752357,1116617.972427,"ops/s",directBuffer,STRUCT,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.forymetashared_serialize_compatible","thrpt",1,3,2714748.572248,284462.787825,"ops/s",directBuffer,STRUCT2,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.forymetashared_serialize_compatible","thrpt",1,3,1866073.031851,1521156.537508,"ops/s",directBuffer,STRUCT2,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.hession_serialize","thrpt",1,3,220386.502846,60892.430853,"ops/s",array,SAMPLE,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.hession_serialize","thrpt",1,3,192414.014211,34217.359956,"ops/s",array,SAMPLE,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.hession_serialize","thrpt",1,3,367782.358049,54538.846197,"ops/s",array,MEDIA_CONTENT,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.hession_serialize","thrpt",1,3,329427.470680,530871.650379,"ops/s",array,MEDIA_CONTENT,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.hession_serialize","thrpt",1,3,258233.998931,145299.453488,"ops/s",array,STRUCT,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.hession_serialize","thrpt",1,3,260845.209485,90601.426407,"ops/s",array,STRUCT,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.hession_serialize","thrpt",1,3,56056.080075,3919.171009,"ops/s",array,STRUCT2,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.hession_serialize","thrpt",1,3,60038.879790,6808.083631,"ops/s",array,STRUCT2,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.hession_serialize","thrpt",1,3,220981.308085,153633.380796,"ops/s",directBuffer,SAMPLE,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.hession_serialize","thrpt",1,3,211949.960255,231322.136517,"ops/s",directBuffer,SAMPLE,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.hession_serialize","thrpt",1,3,372477.138150,39349.725456,"ops/s",directBuffer,MEDIA_CONTENT,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.hession_serialize","thrpt",1,3,353376.085025,11334.885856,"ops/s",directBuffer,MEDIA_CONTENT,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.hession_serialize","thrpt",1,3,266481.009225,113518.076189,"ops/s",directBuffer,STRUCT,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.hession_serialize","thrpt",1,3,261762.594966,64652.028148,"ops/s",directBuffer,STRUCT,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.hession_serialize","thrpt",1,3,55924.319442,28173.043405,"ops/s",directBuffer,STRUCT2,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.hession_serialize","thrpt",1,3,56674.065604,2667.957614,"ops/s",directBuffer,STRUCT2,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.hession_serialize_compatible","thrpt",1,3,234454.975158,5232.236462,"ops/s",array,SAMPLE,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.hession_serialize_compatible","thrpt",1,3,206174.173039,54217.176504,"ops/s",array,SAMPLE,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.hession_serialize_compatible","thrpt",1,3,377195.903772,33297.468886,"ops/s",array,MEDIA_CONTENT,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.hession_serialize_compatible","thrpt",1,3,351657.879556,10762.766962,"ops/s",array,MEDIA_CONTENT,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.hession_serialize_compatible","thrpt",1,3,258650.663523,64158.329095,"ops/s",array,STRUCT,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.hession_serialize_compatible","thrpt",1,3,263564.913879,101476.568014,"ops/s",array,STRUCT,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.hession_serialize_compatible","thrpt",1,3,58509.125342,10836.872797,"ops/s",array,STRUCT2,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.hession_serialize_compatible","thrpt",1,3,55552.977735,37802.538138,"ops/s",array,STRUCT2,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.hession_serialize_compatible","thrpt",1,3,194761.224263,8828.274695,"ops/s",directBuffer,SAMPLE,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.hession_serialize_compatible","thrpt",1,3,212840.483308,50730.019909,"ops/s",directBuffer,SAMPLE,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.hession_serialize_compatible","thrpt",1,3,371729.727192,136063.629978,"ops/s",directBuffer,MEDIA_CONTENT,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.hession_serialize_compatible","thrpt",1,3,343834.954942,13355.085558,"ops/s",directBuffer,MEDIA_CONTENT,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.hession_serialize_compatible","thrpt",1,3,249221.452137,261034.656030,"ops/s",directBuffer,STRUCT,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.hession_serialize_compatible","thrpt",1,3,263623.143601,32854.227410,"ops/s",directBuffer,STRUCT,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.hession_serialize_compatible","thrpt",1,3,58908.567439,4137.470432,"ops/s",directBuffer,STRUCT2,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.hession_serialize_compatible","thrpt",1,3,55524.373547,668.406873,"ops/s",directBuffer,STRUCT2,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.jdk_serialize","thrpt",1,3,118374.836631,34704.407553,"ops/s",array,SAMPLE,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.jdk_serialize","thrpt",1,3,119858.140625,49308.850176,"ops/s",array,SAMPLE,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.jdk_serialize","thrpt",1,3,137989.198821,40017.148924,"ops/s",array,MEDIA_CONTENT,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.jdk_serialize","thrpt",1,3,140260.668888,57308.595910,"ops/s",array,MEDIA_CONTENT,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.jdk_serialize","thrpt",1,3,155908.244240,20385.278504,"ops/s",array,STRUCT,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.jdk_serialize","thrpt",1,3,151258.539369,12676.385578,"ops/s",array,STRUCT,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.jdk_serialize","thrpt",1,3,36846.049162,5491.880967,"ops/s",array,STRUCT2,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.jdk_serialize","thrpt",1,3,38183.705811,14778.659439,"ops/s",array,STRUCT2,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.jdk_serialize","thrpt",1,3,118273.584257,18950.629048,"ops/s",directBuffer,SAMPLE,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.jdk_serialize","thrpt",1,3,108263.040839,14982.910444,"ops/s",directBuffer,SAMPLE,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.jdk_serialize","thrpt",1,3,138567.623369,24365.255940,"ops/s",directBuffer,MEDIA_CONTENT,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.jdk_serialize","thrpt",1,3,140158.673910,54416.908878,"ops/s",directBuffer,MEDIA_CONTENT,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.jdk_serialize","thrpt",1,3,154875.908438,11984.781345,"ops/s",directBuffer,STRUCT,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.jdk_serialize","thrpt",1,3,156404.686214,58131.602098,"ops/s",directBuffer,STRUCT,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.jdk_serialize","thrpt",1,3,37444.967981,14948.012339,"ops/s",directBuffer,STRUCT2,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.jdk_serialize","thrpt",1,3,35798.679246,36641.428549,"ops/s",directBuffer,STRUCT2,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.kryo_serialize","thrpt",1,3,1105365.931217,162251.803619,"ops/s",array,SAMPLE,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.kryo_serialize","thrpt",1,3,734215.482291,79297.387490,"ops/s",array,SAMPLE,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.kryo_serialize","thrpt",1,3,730792.521676,678674.266715,"ops/s",array,MEDIA_CONTENT,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.kryo_serialize","thrpt",1,3,445251.084327,85646.179264,"ops/s",array,MEDIA_CONTENT,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.kryo_serialize","thrpt",1,3,558194.100861,257156.321315,"ops/s",array,STRUCT,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.kryo_serialize","thrpt",1,3,557542.628765,63084.390134,"ops/s",array,STRUCT,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.kryo_serialize","thrpt",1,3,325172.969175,20774.334333,"ops/s",array,STRUCT2,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.kryo_serialize","thrpt",1,3,259863.332448,86373.633851,"ops/s",array,STRUCT2,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.kryo_serialize","thrpt",1,3,1376560.302168,147424.342310,"ops/s",directBuffer,SAMPLE,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.kryo_serialize","thrpt",1,3,932887.968348,249800.928765,"ops/s",directBuffer,SAMPLE,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.kryo_serialize","thrpt",1,3,608972.517580,249598.971835,"ops/s",directBuffer,MEDIA_CONTENT,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.kryo_serialize","thrpt",1,3,359875.473951,274870.064607,"ops/s",directBuffer,MEDIA_CONTENT,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.kryo_serialize","thrpt",1,3,1078046.011115,249527.480472,"ops/s",directBuffer,STRUCT,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.kryo_serialize","thrpt",1,3,853350.408656,126642.692106,"ops/s",directBuffer,STRUCT,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.kryo_serialize","thrpt",1,3,355688.882786,37587.645927,"ops/s",directBuffer,STRUCT2,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.kryo_serialize","thrpt",1,3,338960.426033,36185.446014,"ops/s",directBuffer,STRUCT2,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.kryo_serialize_compatible","thrpt",1,3,378907.663184,280309.649766,"ops/s",array,SAMPLE,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.kryo_serialize_compatible","thrpt",1,3,320815.567701,455179.720989,"ops/s",array,SAMPLE,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.kryo_serialize_compatible","thrpt",1,3,188911.259146,97827.317807,"ops/s",array,MEDIA_CONTENT,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.kryo_serialize_compatible","thrpt",1,3,145782.916427,81270.905462,"ops/s",array,MEDIA_CONTENT,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.kryo_serialize_compatible","thrpt",1,3,145964.199559,88578.667153,"ops/s",array,STRUCT,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.kryo_serialize_compatible","thrpt",1,3,136180.832879,167433.069232,"ops/s",array,STRUCT,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.kryo_serialize_compatible","thrpt",1,3,125807.748004,23178.451287,"ops/s",array,STRUCT2,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.kryo_serialize_compatible","thrpt",1,3,114983.546343,7341.380140,"ops/s",array,STRUCT2,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.kryo_serialize_compatible","thrpt",1,3,296102.615094,18485.738321,"ops/s",directBuffer,SAMPLE,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.kryo_serialize_compatible","thrpt",1,3,276757.392449,61173.636852,"ops/s",directBuffer,SAMPLE,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.kryo_serialize_compatible","thrpt",1,3,185363.714829,121440.885632,"ops/s",directBuffer,MEDIA_CONTENT,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.kryo_serialize_compatible","thrpt",1,3,142836.961878,12450.918452,"ops/s",directBuffer,MEDIA_CONTENT,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.kryo_serialize_compatible","thrpt",1,3,106695.800225,13463.570576,"ops/s",directBuffer,STRUCT,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.kryo_serialize_compatible","thrpt",1,3,106458.212005,2994.065295,"ops/s",directBuffer,STRUCT,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.kryo_serialize_compatible","thrpt",1,3,92130.672361,9515.661170,"ops/s",directBuffer,STRUCT2,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.kryo_serialize_compatible","thrpt",1,3,88989.724768,9379.338279,"ops/s",directBuffer,STRUCT2,true
+"org.apache.fory.benchmark.UserTypeSerializeSuite.protostuff_serialize","thrpt",1,3,663272.710783,522116.492895,"ops/s",array,SAMPLE,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.protostuff_serialize","thrpt",1,3,780618.761219,406063.945348,"ops/s",array,MEDIA_CONTENT,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.protostuff_serialize","thrpt",1,3,330975.350403,196475.862643,"ops/s",array,STRUCT,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.protostuff_serialize","thrpt",1,3,322563.440433,201276.713653,"ops/s",array,STRUCT2,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.protostuff_serialize","thrpt",1,3,693641.589806,43883.803566,"ops/s",directBuffer,SAMPLE,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.protostuff_serialize","thrpt",1,3,805941.345157,91281.699006,"ops/s",directBuffer,MEDIA_CONTENT,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.protostuff_serialize","thrpt",1,3,340262.650047,152117.387028,"ops/s",directBuffer,STRUCT,false
+"org.apache.fory.benchmark.UserTypeSerializeSuite.protostuff_serialize","thrpt",1,3,325093.716261,56485.972228,"ops/s",directBuffer,STRUCT2,false
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/data/jmh-jdk-11-zerocopy.csv b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/data/jmh-jdk-11-zerocopy.csv
new file mode 100644
index 000000000..503298291
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/data/jmh-jdk-11-zerocopy.csv
@@ -0,0 +1,73 @@
+"Benchmark","Mode","Threads","Samples","Score","Score Error (99.9%)","Unit","Param: array_size","Param: bufferType","Param: dataType","Param: references"
+"org.apache.fory.benchmark.ZeroCopySuite.fst_deserialize","thrpt",1,3,219333.990504,40075.312705,"ops/s",200,array,PRIMITIVE_ARRAY,false
+"org.apache.fory.benchmark.ZeroCopySuite.fst_deserialize","thrpt",1,3,657754.887247,408901.031753,"ops/s",200,array,BUFFER,false
+"org.apache.fory.benchmark.ZeroCopySuite.fst_deserialize","thrpt",1,3,179604.045774,45387.509931,"ops/s",200,directBuffer,PRIMITIVE_ARRAY,false
+"org.apache.fory.benchmark.ZeroCopySuite.fst_deserialize","thrpt",1,3,598421.278941,135411.381215,"ops/s",200,directBuffer,BUFFER,false
+"org.apache.fory.benchmark.ZeroCopySuite.fst_deserialize","thrpt",1,3,53100.903684,17709.358858,"ops/s",1000,array,PRIMITIVE_ARRAY,false
+"org.apache.fory.benchmark.ZeroCopySuite.fst_deserialize","thrpt",1,3,422147.154601,528539.529166,"ops/s",1000,array,BUFFER,false
+"org.apache.fory.benchmark.ZeroCopySuite.fst_deserialize","thrpt",1,3,38572.001768,24685.893533,"ops/s",1000,directBuffer,PRIMITIVE_ARRAY,false
+"org.apache.fory.benchmark.ZeroCopySuite.fst_deserialize","thrpt",1,3,298929.116572,135040.133488,"ops/s",1000,directBuffer,BUFFER,false
+"org.apache.fory.benchmark.ZeroCopySuite.fst_deserialize","thrpt",1,3,10672.872798,11519.184075,"ops/s",5000,array,PRIMITIVE_ARRAY,false
+"org.apache.fory.benchmark.ZeroCopySuite.fst_deserialize","thrpt",1,3,136934.604328,19269.032565,"ops/s",5000,array,BUFFER,false
+"org.apache.fory.benchmark.ZeroCopySuite.fst_deserialize","thrpt",1,3,8561.694533,2137.867210,"ops/s",5000,directBuffer,PRIMITIVE_ARRAY,false
+"org.apache.fory.benchmark.ZeroCopySuite.fst_deserialize","thrpt",1,3,77950.612503,83587.484192,"ops/s",5000,directBuffer,BUFFER,false
+"org.apache.fory.benchmark.ZeroCopySuite.fst_serialize","thrpt",1,3,313986.053417,29311.641179,"ops/s",200,array,PRIMITIVE_ARRAY,false
+"org.apache.fory.benchmark.ZeroCopySuite.fst_serialize","thrpt",1,3,2400193.220466,242732.420524,"ops/s",200,array,BUFFER,false
+"org.apache.fory.benchmark.ZeroCopySuite.fst_serialize","thrpt",1,3,294132.218623,60640.778775,"ops/s",200,directBuffer,PRIMITIVE_ARRAY,false
+"org.apache.fory.benchmark.ZeroCopySuite.fst_serialize","thrpt",1,3,2282550.111756,93004.652618,"ops/s",200,directBuffer,BUFFER,false
+"org.apache.fory.benchmark.ZeroCopySuite.fst_serialize","thrpt",1,3,67209.107012,5947.935958,"ops/s",1000,array,PRIMITIVE_ARRAY,false
+"org.apache.fory.benchmark.ZeroCopySuite.fst_serialize","thrpt",1,3,1805557.477810,5232839.112456,"ops/s",1000,array,BUFFER,false
+"org.apache.fory.benchmark.ZeroCopySuite.fst_serialize","thrpt",1,3,66108.014322,16869.542536,"ops/s",1000,directBuffer,PRIMITIVE_ARRAY,false
+"org.apache.fory.benchmark.ZeroCopySuite.fst_serialize","thrpt",1,3,1644789.427010,54907.475118,"ops/s",1000,directBuffer,BUFFER,false
+"org.apache.fory.benchmark.ZeroCopySuite.fst_serialize","thrpt",1,3,14997.400124,12425.308762,"ops/s",5000,array,PRIMITIVE_ARRAY,false
+"org.apache.fory.benchmark.ZeroCopySuite.fst_serialize","thrpt",1,3,811029.402136,39593.863849,"ops/s",5000,array,BUFFER,false
+"org.apache.fory.benchmark.ZeroCopySuite.fst_serialize","thrpt",1,3,15000.378818,2219.583522,"ops/s",5000,directBuffer,PRIMITIVE_ARRAY,false
+"org.apache.fory.benchmark.ZeroCopySuite.fst_serialize","thrpt",1,3,477148.540850,34970.176073,"ops/s",5000,directBuffer,BUFFER,false
+"org.apache.fory.benchmark.ZeroCopySuite.fory_deserialize","thrpt",1,3,986136.067809,274606.792449,"ops/s",200,array,PRIMITIVE_ARRAY,false
+"org.apache.fory.benchmark.ZeroCopySuite.fory_deserialize","thrpt",1,3,3302149.383135,3166455.521704,"ops/s",200,array,BUFFER,false
+"org.apache.fory.benchmark.ZeroCopySuite.fory_deserialize","thrpt",1,3,991807.969328,296490.837932,"ops/s",200,directBuffer,PRIMITIVE_ARRAY,false
+"org.apache.fory.benchmark.ZeroCopySuite.fory_deserialize","thrpt",1,3,3113115.471758,4861106.592529,"ops/s",200,directBuffer,BUFFER,false
+"org.apache.fory.benchmark.ZeroCopySuite.fory_deserialize","thrpt",1,3,205671.992736,127494.951753,"ops/s",1000,array,PRIMITIVE_ARRAY,false
+"org.apache.fory.benchmark.ZeroCopySuite.fory_deserialize","thrpt",1,3,2831942.848999,1720214.698856,"ops/s",1000,array,BUFFER,false
+"org.apache.fory.benchmark.ZeroCopySuite.fory_deserialize","thrpt",1,3,202275.242341,56270.238293,"ops/s",1000,directBuffer,PRIMITIVE_ARRAY,false
+"org.apache.fory.benchmark.ZeroCopySuite.fory_deserialize","thrpt",1,3,3397690.327371,146058.097383,"ops/s",1000,directBuffer,BUFFER,false
+"org.apache.fory.benchmark.ZeroCopySuite.fory_deserialize","thrpt",1,3,40312.590172,11836.614114,"ops/s",5000,array,PRIMITIVE_ARRAY,false
+"org.apache.fory.benchmark.ZeroCopySuite.fory_deserialize","thrpt",1,3,3296658.120035,2199676.238015,"ops/s",5000,array,BUFFER,false
+"org.apache.fory.benchmark.ZeroCopySuite.fory_deserialize","thrpt",1,3,40413.743717,9893.735875,"ops/s",5000,directBuffer,PRIMITIVE_ARRAY,false
+"org.apache.fory.benchmark.ZeroCopySuite.fory_deserialize","thrpt",1,3,3284441.570594,998247.999163,"ops/s",5000,directBuffer,BUFFER,false
+"org.apache.fory.benchmark.ZeroCopySuite.fory_serialize","thrpt",1,3,8297232.942927,6613235.386482,"ops/s",200,array,PRIMITIVE_ARRAY,false
+"org.apache.fory.benchmark.ZeroCopySuite.fory_serialize","thrpt",1,3,5123572.914045,9342104.794019,"ops/s",200,array,BUFFER,false
+"org.apache.fory.benchmark.ZeroCopySuite.fory_serialize","thrpt",1,3,8335248.350301,2796789.944593,"ops/s",200,directBuffer,PRIMITIVE_ARRAY,false
+"org.apache.fory.benchmark.ZeroCopySuite.fory_serialize","thrpt",1,3,5400346.890126,7654935.504676,"ops/s",200,directBuffer,BUFFER,false
+"org.apache.fory.benchmark.ZeroCopySuite.fory_serialize","thrpt",1,3,8772856.921028,1984208.178343,"ops/s",1000,array,PRIMITIVE_ARRAY,false
+"org.apache.fory.benchmark.ZeroCopySuite.fory_serialize","thrpt",1,3,4979590.929127,5568756.926202,"ops/s",1000,array,BUFFER,false
+"org.apache.fory.benchmark.ZeroCopySuite.fory_serialize","thrpt",1,3,8207563.785251,4153794.222735,"ops/s",1000,directBuffer,PRIMITIVE_ARRAY,false
+"org.apache.fory.benchmark.ZeroCopySuite.fory_serialize","thrpt",1,3,5376191.775007,9167580.616022,"ops/s",1000,directBuffer,BUFFER,false
+"org.apache.fory.benchmark.ZeroCopySuite.fory_serialize","thrpt",1,3,8027439.580226,6148996.477681,"ops/s",5000,array,PRIMITIVE_ARRAY,false
+"org.apache.fory.benchmark.ZeroCopySuite.fory_serialize","thrpt",1,3,5018916.322770,1424045.598203,"ops/s",5000,array,BUFFER,false
+"org.apache.fory.benchmark.ZeroCopySuite.fory_serialize","thrpt",1,3,7695981.988316,578662.201123,"ops/s",5000,directBuffer,PRIMITIVE_ARRAY,false
+"org.apache.fory.benchmark.ZeroCopySuite.fory_serialize","thrpt",1,3,5330897.682960,8055585.038901,"ops/s",5000,directBuffer,BUFFER,false
+"org.apache.fory.benchmark.ZeroCopySuite.kryo_deserialize","thrpt",1,3,146675.360652,23502.675233,"ops/s",200,array,PRIMITIVE_ARRAY,false
+"org.apache.fory.benchmark.ZeroCopySuite.kryo_deserialize","thrpt",1,3,1296284.787720,297204.673569,"ops/s",200,array,BUFFER,false
+"org.apache.fory.benchmark.ZeroCopySuite.kryo_deserialize","thrpt",1,3,518713.299422,600548.228171,"ops/s",200,directBuffer,PRIMITIVE_ARRAY,false
+"org.apache.fory.benchmark.ZeroCopySuite.kryo_deserialize","thrpt",1,3,1004844.498712,552313.083272,"ops/s",200,directBuffer,BUFFER,false
+"org.apache.fory.benchmark.ZeroCopySuite.kryo_deserialize","thrpt",1,3,30409.835023,9562.322209,"ops/s",1000,array,PRIMITIVE_ARRAY,false
+"org.apache.fory.benchmark.ZeroCopySuite.kryo_deserialize","thrpt",1,3,721266.541130,62426.822891,"ops/s",1000,array,BUFFER,false
+"org.apache.fory.benchmark.ZeroCopySuite.kryo_deserialize","thrpt",1,3,112132.004609,6625.327605,"ops/s",1000,directBuffer,PRIMITIVE_ARRAY,false
+"org.apache.fory.benchmark.ZeroCopySuite.kryo_deserialize","thrpt",1,3,592972.713203,511777.226637,"ops/s",1000,directBuffer,BUFFER,false
+"org.apache.fory.benchmark.ZeroCopySuite.kryo_deserialize","thrpt",1,3,6122.351228,3021.683209,"ops/s",5000,array,PRIMITIVE_ARRAY,false
+"org.apache.fory.benchmark.ZeroCopySuite.kryo_deserialize","thrpt",1,3,147251.846111,278375.379465,"ops/s",5000,array,BUFFER,false
+"org.apache.fory.benchmark.ZeroCopySuite.kryo_deserialize","thrpt",1,3,21826.040410,2246.004993,"ops/s",5000,directBuffer,PRIMITIVE_ARRAY,false
+"org.apache.fory.benchmark.ZeroCopySuite.kryo_deserialize","thrpt",1,3,148614.476829,87146.409451,"ops/s",5000,directBuffer,BUFFER,false
+"org.apache.fory.benchmark.ZeroCopySuite.kryo_serialize","thrpt",1,3,147342.606262,138864.952435,"ops/s",200,array,PRIMITIVE_ARRAY,false
+"org.apache.fory.benchmark.ZeroCopySuite.kryo_serialize","thrpt",1,3,1985187.977633,70426.638387,"ops/s",200,array,BUFFER,false
+"org.apache.fory.benchmark.ZeroCopySuite.kryo_serialize","thrpt",1,3,972683.763633,604464.052899,"ops/s",200,directBuffer,PRIMITIVE_ARRAY,false
+"org.apache.fory.benchmark.ZeroCopySuite.kryo_serialize","thrpt",1,3,1739454.519770,1053963.541481,"ops/s",200,directBuffer,BUFFER,false
+"org.apache.fory.benchmark.ZeroCopySuite.kryo_serialize","thrpt",1,3,31395.721514,3652.506399,"ops/s",1000,array,PRIMITIVE_ARRAY,false
+"org.apache.fory.benchmark.ZeroCopySuite.kryo_serialize","thrpt",1,3,1616159.671230,2722436.839807,"ops/s",1000,array,BUFFER,false
+"org.apache.fory.benchmark.ZeroCopySuite.kryo_serialize","thrpt",1,3,209183.090868,25323.702489,"ops/s",1000,directBuffer,PRIMITIVE_ARRAY,false
+"org.apache.fory.benchmark.ZeroCopySuite.kryo_serialize","thrpt",1,3,1377272.568510,203974.331559,"ops/s",1000,directBuffer,BUFFER,false
+"org.apache.fory.benchmark.ZeroCopySuite.kryo_serialize","thrpt",1,3,6248.006967,783.226602,"ops/s",5000,array,PRIMITIVE_ARRAY,false
+"org.apache.fory.benchmark.ZeroCopySuite.kryo_serialize","thrpt",1,3,711287.533377,86363.201941,"ops/s",5000,array,BUFFER,false
+"org.apache.fory.benchmark.ZeroCopySuite.kryo_serialize","thrpt",1,3,43565.678616,4221.267495,"ops/s",5000,directBuffer,PRIMITIVE_ARRAY,false
+"org.apache.fory.benchmark.ZeroCopySuite.kryo_serialize","thrpt",1,3,707092.956534,298737.951680,"ops/s",5000,directBuffer,BUFFER,false
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/java_heap_deserialize_compatible.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/java_heap_deserialize_compatible.png
new file mode 100644
index 000000000..2865473dd
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/java_heap_deserialize_compatible.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/java_heap_deserialize_consistent.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/java_heap_deserialize_consistent.png
new file mode 100644
index 000000000..fff332e47
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/java_heap_deserialize_consistent.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/java_heap_serialize_compatible.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/java_heap_serialize_compatible.png
new file mode 100644
index 000000000..d9e3db675
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/java_heap_serialize_compatible.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/java_heap_serialize_consistent.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/java_heap_serialize_consistent.png
new file mode 100644
index 000000000..065907ddb
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/java_heap_serialize_consistent.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/java_offheap_deserialize_compatible.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/java_offheap_deserialize_compatible.png
new file mode 100644
index 000000000..e7258a923
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/java_offheap_deserialize_compatible.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/java_offheap_deserialize_consistent.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/java_offheap_deserialize_consistent.png
new file mode 100644
index 000000000..b84e279e3
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/java_offheap_deserialize_consistent.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/java_offheap_serialize_compatible.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/java_offheap_serialize_compatible.png
new file mode 100644
index 000000000..3f1f5821c
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/java_offheap_serialize_compatible.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/java_offheap_serialize_consistent.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/java_offheap_serialize_consistent.png
new file mode 100644
index 000000000..98d0582af
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/java_offheap_serialize_consistent.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/java_repo_deserialization_throughput.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/java_repo_deserialization_throughput.png
new file mode 100644
index 000000000..21bf2b45d
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/java_repo_deserialization_throughput.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/java_repo_serialization_throughput.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/java_repo_serialization_throughput.png
new file mode 100644
index 000000000..dfff16eec
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/java_repo_serialization_throughput.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/java_zero_copy_deserialize.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/java_zero_copy_deserialize.png
new file mode 100644
index 000000000..03acaa38b
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/java_zero_copy_deserialize.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/java_zero_copy_serialize.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/java_zero_copy_serialize.png
new file mode 100644
index 000000000..e1be0893b
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/java/java_zero_copy_serialize.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/javascript/README.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/javascript/README.md
new file mode 100644
index 000000000..f51899233
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/javascript/README.md
@@ -0,0 +1,104 @@
+# JavaScript Benchmark Performance Report
+
+_Generated on 2026-04-14 17:11:43_
+
+## How to Generate This Report
+
+```bash
+cd benchmarks/javascript
+./run.sh
+```
+
+## Hardware & OS Info
+
+| Key | Value |
+| -------------------------- | ------------------------ |
+| OS | Darwin 24.6.0 |
+| Machine | arm64 |
+| Processor | arm |
+| CPU Cores (Physical) | 12 |
+| CPU Cores (Logical) | 12 |
+| Total RAM (GB) | 48.0 |
+| Benchmark Date | 2026-04-14T09:09:51.959Z |
+| CPU Cores (from benchmark) | 12 |
+| Node.js | v22.20.0 |
+| V8 | 12.4.254.21-node.33 |
+
+## Benchmark Plots
+
+All class-level plots below show throughput (ops/sec).
+
+### Throughput
+
+
+
+### MediaContent
+
+
+
+### MediaContentList
+
+
+
+### Sample
+
+
+
+### SampleList
+
+
+
+### Struct
+
+
+
+### StructList
+
+
+
+## Benchmark Results
+
+### Timing Results (nanoseconds)
+
+| Datatype | Operation | fory (ns) | protobuf (ns) | json (ns) | Fastest |
+| ---------------- | ----------- | --------- | ------------- | --------- | ------- |
+| Struct | Serialize | 118.3 | 525.3 | 327.0 | fory |
+| Struct | Deserialize | 103.0 | 121.5 | 259.0 | fory |
+| Sample | Serialize | 667.4 | 2366.2 | 1342.7 | fory |
+| Sample | Deserialize | 521.3 | 1221.0 | 1312.3 | fory |
+| MediaContent | Serialize | 773.3 | 1370.8 | 769.3 | json |
+| MediaContent | Deserialize | 610.5 | 827.0 | 1085.6 | fory |
+| StructList | Serialize | 254.6 | 2017.6 | 1121.3 | fory |
+| StructList | Deserialize | 306.3 | 653.7 | 1014.1 | fory |
+| SampleList | Serialize | 2812.3 | 10782.7 | 6130.4 | fory |
+| SampleList | Deserialize | 2353.4 | 6125.5 | 6153.1 | fory |
+| MediaContentList | Serialize | 3495.9 | 6712.4 | 3540.5 | fory |
+| MediaContentList | Deserialize | 2653.7 | 4087.9 | 5258.9 | fory |
+
+### Throughput Results (ops/sec)
+
+| Datatype | Operation | fory TPS | protobuf TPS | json TPS | Fastest |
+| ---------------- | ----------- | --------- | ------------ | --------- | ------- |
+| Struct | Serialize | 8,453,950 | 1,903,706 | 3,058,232 | fory |
+| Struct | Deserialize | 9,705,287 | 8,233,664 | 3,860,538 | fory |
+| Sample | Serialize | 1,498,391 | 422,620 | 744,790 | fory |
+| Sample | Deserialize | 1,918,162 | 819,010 | 762,048 | fory |
+| MediaContent | Serialize | 1,293,157 | 729,497 | 1,299,908 | json |
+| MediaContent | Deserialize | 1,638,086 | 1,209,140 | 921,191 | fory |
+| StructList | Serialize | 3,928,325 | 495,648 | 891,810 | fory |
+| StructList | Deserialize | 3,264,827 | 1,529,744 | 986,144 | fory |
+| SampleList | Serialize | 355,581 | 92,741 | 163,120 | fory |
+| SampleList | Deserialize | 424,916 | 163,253 | 162,520 | fory |
+| MediaContentList | Serialize | 286,053 | 148,977 | 282,445 | fory |
+| MediaContentList | Deserialize | 376,826 | 244,622 | 190,155 | fory |
+
+### Serialized Data Sizes (bytes)
+
+| Datatype | fory | protobuf | json |
+| ---------------- | ---- | -------- | ---- |
+| Struct | 58 | 61 | 103 |
+| Sample | 446 | 377 | 724 |
+| MediaContent | 391 | 307 | 596 |
+| StructList | 184 | 315 | 537 |
+| SampleList | 1980 | 1900 | 3642 |
+| MediaContentList | 1665 | 1550 | 3009 |
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/javascript/mediacontent.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/javascript/mediacontent.png
new file mode 100644
index 000000000..45d2c34db
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/javascript/mediacontent.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/javascript/mediacontentlist.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/javascript/mediacontentlist.png
new file mode 100644
index 000000000..a5763d069
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/javascript/mediacontentlist.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/javascript/sample.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/javascript/sample.png
new file mode 100644
index 000000000..57c619b33
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/javascript/sample.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/javascript/samplelist.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/javascript/samplelist.png
new file mode 100644
index 000000000..6e66a0a11
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/javascript/samplelist.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/javascript/struct.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/javascript/struct.png
new file mode 100644
index 000000000..e78a56967
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/javascript/struct.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/javascript/structlist.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/javascript/structlist.png
new file mode 100644
index 000000000..cae684ed2
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/javascript/structlist.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/javascript/throughput.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/javascript/throughput.png
new file mode 100644
index 000000000..fffd41c47
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/javascript/throughput.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/python/README.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/python/README.md
new file mode 100644
index 000000000..0cf659028
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/python/README.md
@@ -0,0 +1,127 @@
+# Python 基准性能报告
+
+_生成于 2026-03-03 13:42:38_
+
+## 如何生成本报告
+
+```bash
+cd benchmarks/python
+./run.sh
+```
+
+## 硬件与操作系统信息
+
+| 键 | 值 |
+| --------------------- | ---------------------------- |
+| 操作系统 | Darwin 24.6.0 |
+| 机器架构 | arm64 |
+| 处理器 | arm |
+| Python | 3.10.8 |
+| CPU 核心数（物理） | 12 |
+| CPU 核心数（逻辑） | 12 |
+| 总内存（GB） | 48.0 |
+| Python 实现 | CPython |
+| 基准平台 | macOS-15.7.2-arm64-arm-64bit |
+
+## 基准配置
+
+| 键 | 值 |
+| ---------- | ----- |
+| warmup | 3 |
+| iterations | 15 |
+| repeat | 5 |
+| number | 1000 |
+| list_size | 5 |
+
+## 基准图表
+
+所有图表均展示吞吐量（ops/sec）；数值越高越好。
+
+### 总吞吐量
+
+<p align="center">
+<img src="throughput.png" width="90%" />
+</p>
+
+### `MediaContent` 基准
+
+<p align="center">
+<img src="mediacontent.png" width="90%" />
+</p>
+
+### `MediaContentList` 基准
+
+<p align="center">
+<img src="mediacontentlist.png" width="90%" />
+</p>
+
+### Sample
+
+<p align="center">
+<img src="sample.png" width="90%" />
+</p>
+
+### Samplelist
+
+<p align="center">
+<img src="samplelist.png" width="90%" />
+</p>
+
+### Struct
+
+<p align="center">
+<img src="struct.png" width="90%" />
+</p>
+
+### Structlist
+
+<p align="center">
+<img src="structlist.png" width="90%" />
+</p>
+
+## 基准结果
+
+### 延迟结果（纳秒）
+
+| 数据类型 | 操作 | fory (ns) | pickle (ns) | protobuf (ns) | 最快 |
+| ---------------- | ----------- | --------- | ----------- | ------------- | ------- |
+| Struct | Serialize | 417.9 | 868.9 | 548.9 | fory |
+| Struct | Deserialize | 516.1 | 910.6 | 742.4 | fory |
+| Sample | Serialize | 828.1 | 1663.5 | 2383.7 | fory |
+| Sample | Deserialize | 1282.4 | 2296.3 | 3992.7 | fory |
+| MediaContent | Serialize | 1139.9 | 2859.7 | 2867.1 | fory |
+| MediaContent | Deserialize | 1719.5 | 2854.3 | 3236.1 | fory |
+| StructList | Serialize | 1009.1 | 2630.6 | 3281.6 | fory |
+| StructList | Deserialize | 1387.2 | 2651.9 | 3547.9 | fory |
+| SampleList | Serialize | 2828.3 | 5541.0 | 15256.6 | fory |
+| SampleList | Deserialize | 5043.4 | 8144.7 | 18912.5 | fory |
+| MediaContentList | Serialize | 3417.9 | 9341.9 | 15853.2 | fory |
+| MediaContentList | Deserialize | 6138.7 | 8435.3 | 16442.6 | fory |
+
+### 吞吐结果（ops/sec）
+
+| 数据类型 | 操作 | fory TPS | pickle TPS | protobuf TPS | 最快 |
+| ---------------- | ----------- | --------- | ---------- | ------------ | ------- |
+| Struct | Serialize | 2,393,086 | 1,150,946 | 1,821,982 | fory |
+| Struct | Deserialize | 1,937,707 | 1,098,170 | 1,346,915 | fory |
+| Sample | Serialize | 1,207,542 | 601,144 | 419,511 | fory |
+| Sample | Deserialize | 779,789 | 435,489 | 250,460 | fory |
+| MediaContent | Serialize | 877,300 | 349,688 | 348,780 | fory |
+| MediaContent | Deserialize | 581,563 | 350,354 | 309,018 | fory |
+| StructList | Serialize | 991,017 | 380,145 | 304,732 | fory |
+| StructList | Deserialize | 720,901 | 377,081 | 281,855 | fory |
+| SampleList | Serialize | 353,574 | 180,473 | 65,545 | fory |
+| SampleList | Deserialize | 198,280 | 122,780 | 52,875 | fory |
+| MediaContentList | Serialize | 292,578 | 107,045 | 63,079 | fory |
+| MediaContentList | Deserialize | 162,902 | 118,550 | 60,818 | fory |
+
+### 序列化数据大小（字节）
+
+| 数据类型 | fory | pickle | protobuf |
+| ---------------- | ---- | ------ | -------- |
+| Struct | 72 | 126 | 61 |
+| Sample | 517 | 793 | 375 |
+| MediaContent | 470 | 586 | 301 |
+| StructList | 205 | 420 | 315 |
+| SampleList | 1810 | 2539 | 1890 |
+| MediaContentList | 1756 | 1377 | 1520 |
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/python/mediacontent.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/python/mediacontent.png
new file mode 100644
index 000000000..05b28cd20
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/python/mediacontent.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/python/mediacontentlist.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/python/mediacontentlist.png
new file mode 100644
index 000000000..6ca7b1814
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/python/mediacontentlist.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/python/sample.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/python/sample.png
new file mode 100644
index 000000000..eb318e1ab
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/python/sample.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/python/samplelist.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/python/samplelist.png
new file mode 100644
index 000000000..94896bcab
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/python/samplelist.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/python/struct.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/python/struct.png
new file mode 100644
index 000000000..c8fe09cfe
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/python/struct.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/python/structlist.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/python/structlist.png
new file mode 100644
index 000000000..e421b1738
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/python/structlist.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/python/throughput.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/python/throughput.png
new file mode 100644
index 000000000..c750a9ffb
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/python/throughput.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/README.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/README.md
new file mode 100644
index 000000000..fdaa812b8
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/README.md
@@ -0,0 +1,104 @@
+## 性能对比报告
+
+_生成时间：2025-10-26 18:36:41_
+
+如何生成性能报告：
+
+```bash
+cd benchmarks/rust_benchmark
+cargo bench 2>&1 | tee cargo_bench.log
+python benchmark_report.py --log-file cargo_bench.log --output-dir=report_output
+```
+
+### 硬件与系统信息
+
+| Key | Value |
+| -------------------- | ------------- |
+| OS | Darwin 24.5.0 |
+| Machine | arm64 |
+| Processor | arm |
+| CPU Cores (Physical) | 12 |
+| CPU Cores (Logical) | 12 |
+| Total RAM (GB) | 48.0 |
+
+### 基准图表
+
+**company**
+
+
+
+**ecommerce_data**
+
+
+
+**person**
+
+
+
+**simple_list**
+
+
+
+**simple_map**
+
+
+
+**simple_struct**
+
+
+
+**system_data**
+
+
+
+### 序列化结果
+
+| Datatype | Size | Operation | Fory TPS | JSON TPS | Protobuf TPS | Fastest |
+| -------------- | ------ | --------- | ---------- | ---------- | ------------ | ------- |
+| company | small | serialize | 10,063,906 | 761,673 | 896,620 | fory |
+| company | medium | serialize | 412,507 | 33,835 | 37,590 | fory |
+| company | large | serialize | 9,183 | 793 | 880 | fory |
+| ecommerce_data | small | serialize | 2,350,729 | 206,262 | 256,970 | fory |
+| ecommerce_data | medium | serialize | 59,977 | 4,699 | 5,242 | fory |
+| ecommerce_data | large | serialize | 3,727 | 266 | 295 | fory |
+| person | small | serialize | 13,632,522 | 1,345,189 | 1,475,035 | fory |
+| person | medium | serialize | 3,839,656 | 337,610 | 369,031 | fory |
+| person | large | serialize | 907,853 | 79,631 | 91,408 | fory |
+| simple_list | small | serialize | 27,726,945 | 4,874,957 | 4,643,172 | fory |
+| simple_list | medium | serialize | 4,770,765 | 401,558 | 397,551 | fory |
+| simple_list | large | serialize | 606,061 | 41,061 | 44,565 | fory |
+| simple_map | small | serialize | 22,862,369 | 3,888,025 | 2,695,999 | fory |
+| simple_map | medium | serialize | 2,128,973 | 204,319 | 193,132 | fory |
+| simple_map | large | serialize | 177,847 | 18,419 | 18,668 | fory |
+| simple_struct | small | serialize | 35,729,598 | 10,167,045 | 8,633,342 | fory |
+| simple_struct | medium | serialize | 34,988,279 | 9,737,098 | 6,433,350 | fory |
+| simple_struct | large | serialize | 31,801,558 | 4,545,041 | 7,420,049 | fory |
+| system_data | small | serialize | 5,382,131 | 468,033 | 569,930 | fory |
+| system_data | medium | serialize | 174,240 | 11,896 | 14,753 | fory |
+| system_data | large | serialize | 10,671 | 876 | 1,040 | fory |
+
+### 反序列化结果
+
+| Datatype | Size | Operation | Fory TPS | JSON TPS | Protobuf TPS | Fastest |
+| -------------- | ------ | ----------- | ---------- | ---------- | ------------ | ------- |
+| company | small | deserialize | 1,145,593 | 718,597 | 917,431 | fory |
+| company | medium | deserialize | 35,195 | 24,474 | 25,057 | fory |
+| company | large | deserialize | 836 | 623 | 623 | fory |
+| ecommerce_data | small | deserialize | 278,427 | 183,237 | 241,109 | fory |
+| ecommerce_data | medium | deserialize | 5,622 | 3,820 | 4,249 | fory |
+| ecommerce_data | large | deserialize | 298 | 204 | 217 | fory |
+| person | small | deserialize | 1,924,372 | 1,214,388 | 1,675,631 | fory |
+| person | medium | deserialize | 371,016 | 265,280 | 266,333 | fory |
+| person | large | deserialize | 84,839 | 63,975 | 61,820 | fory |
+| simple_list | small | deserialize | 6,129,329 | 3,599,582 | 4,429,286 | fory |
+| simple_list | medium | deserialize | 460,745 | 305,409 | 337,336 | fory |
+| simple_list | large | deserialize | 54,348 | 33,962 | 38,776 | fory |
+| simple_map | small | deserialize | 3,686,364 | 3,090,426 | 3,477,051 | fory |
+| simple_map | medium | deserialize | 171,774 | 126,638 | 119,323 | fory |
+| simple_map | large | deserialize | 16,501 | 10,920 | 10,853 | fory |
+| simple_struct | small | deserialize | 31,476,235 | 12,948,168 | 28,280,543 | fory |
+| simple_struct | medium | deserialize | 30,077,902 | 10,431,118 | 23,012,841 | fory |
+| simple_struct | large | deserialize | 28,201,585 | 8,955,759 | 23,528,858 | fory |
+| system_data | small | deserialize | 644,870 | 421,106 | 549,209 | fory |
+| system_data | medium | deserialize | 14,322 | 9,205 | 10,565 | fory |
+| system_data | large | deserialize | 961 | 634 | 706 | fory |
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/company.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/company.png
new file mode 100644
index 000000000..eee9de23f
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/company.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/ecommerce_data.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/ecommerce_data.png
new file mode 100644
index 000000000..11a507329
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/ecommerce_data.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/mediacontent.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/mediacontent.png
new file mode 100644
index 000000000..8d026ef4b
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/mediacontent.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/mediacontentlist.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/mediacontentlist.png
new file mode 100644
index 000000000..f2bf6b721
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/mediacontentlist.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/person.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/person.png
new file mode 100644
index 000000000..d31e0d030
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/person.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/sample.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/sample.png
new file mode 100644
index 000000000..e63ebcbad
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/sample.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/samplelist.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/samplelist.png
new file mode 100644
index 000000000..b7ba75b72
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/samplelist.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/simple_list.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/simple_list.png
new file mode 100644
index 000000000..00c5b7d4e
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/simple_list.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/simple_map.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/simple_map.png
new file mode 100644
index 000000000..1142bb3fb
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/simple_map.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/simple_struct.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/simple_struct.png
new file mode 100644
index 000000000..973fa35e8
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/simple_struct.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/struct.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/struct.png
new file mode 100644
index 000000000..e12c6a332
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/struct.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/structlist.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/structlist.png
new file mode 100644
index 000000000..e030cf45f
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/structlist.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/system_data.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/system_data.png
new file mode 100644
index 000000000..330aa6b52
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/system_data.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/throughput.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/throughput.png
new file mode 100644
index 000000000..be89782fb
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/throughput.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/swift/README.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/swift/README.md
new file mode 100644
index 000000000..543e891f9
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/swift/README.md
@@ -0,0 +1,46 @@
+# Fory Swift 基准
+
+该基准用于比较 Apache Fory、Protocol Buffers 和 MessagePack 在 Swift 中的序列化与反序列化吞吐量。
+
+## 硬件与运行时信息
+
+| 键 | 值 |
+| --------------------- | ----------------------------- |
+| 时间戳 | 2026-03-10T06:25:16Z |
+| 操作系统 | Version 15.7.2 (Build 24G325) |
+| 主机 | macbook-pro.local |
+| CPU 核心数（逻辑） | 12 |
+| 内存（GB） | 48.00 |
+| 每个用例持续时间（秒）| 3 |
+
+## 吞吐结果
+
+<p align="center">
+<img src="throughput.png" width="95%" />
+</p>
+
+| 数据类型 | 操作 | Fory TPS | Protobuf TPS | Msgpack TPS | 最快 |
+| ---------------- | ----------- | ---------: | -----------: | ----------: | ------------ |
+| Struct | Serialize | 9,727,950 | 6,572,406 | 141,248 | fory (1.48x) |
+| Struct | Deserialize | 11,889,570 | 8,584,510 | 99,792 | fory (1.39x) |
+| Sample | Serialize | 3,496,305 | 1,281,983 | 17,188 | fory (2.73x) |
+| Sample | Deserialize | 1,045,018 | 765,706 | 12,767 | fory (1.36x) |
+| MediaContent | Serialize | 1,425,354 | 678,542 | 29,048 | fory (2.10x) |
+| MediaContent | Deserialize | 614,447 | 478,298 | 12,711 | fory (1.28x) |
+| StructList | Serialize | 3,307,962 | 1,028,210 | 24,781 | fory (3.22x) |
+| StructList | Deserialize | 2,788,200 | 708,596 | 8,160 | fory (3.93x) |
+| SampleList | Serialize | 715,734 | 205,380 | 3,361 | fory (3.48x) |
+| SampleList | Deserialize | 199,317 | 133,425 | 1,498 | fory (1.49x) |
+| MediaContentList | Serialize | 364,097 | 103,721 | 5,538 | fory (3.51x) |
+| MediaContentList | Deserialize | 103,421 | 86,331 | 1,529 | fory (1.20x) |
+
+## 序列化大小（字节）
+
+| 数据类型 | Fory | Protobuf | Msgpack |
+| ---------------- | ---: | -------: | ------: |
+| MediaContent | 365 | 301 | 524 |
+| MediaContentList | 1535 | 1520 | 2639 |
+| Sample | 446 | 375 | 737 |
+| SampleList | 1980 | 1890 | 3698 |
+| Struct | 58 | 61 | 65 |
+| StructList | 184 | 315 | 338 |
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/swift/throughput.png b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/swift/throughput.png
new file mode 100644
index 000000000..291dc8145
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/swift/throughput.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/community/community.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/community/community.md
new file mode 100644
index 000000000..25b8db402
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/community/community.md
@@ -0,0 +1,85 @@
+---
+title: 社区
+sidebar_position: 0
+id: community
+---
+
+Apache Fory™ 是一个由社区驱动的开源项目，项目的蓬勃发展得益于社区贡献。
+我们邀请您根据自己的意愿尽可能地参与项目。以下是几种贡献方式：
+
+- 使用 Apache Fory™ 并分享使用体验和反馈问题；
+- 为项目提供最佳实践示例；
+- 报告错误并修复；
+- 贡献代码和参与文档建设。
+
+## 邮件列表
+
+| 邮件列表 | 描述 | 订阅 | 取消订阅 | 发送邮件 | 活动 |
+| ----------------------- | ------------------ | ------------------------------------------------ | ------------------------------------------------------ | -------------------------------------- | -------------------------------------------------------------------------- |
+| dev@fory.apache.org | 开发相关讨论 | [订阅](mailto:dev-subscribe@fory.apache.org) | [取消订阅](mailto:dev-unsubscribe@fory.apache.org) | [发送邮件](mailto:dev@fory.apache.org) | [邮件列表活动](https://lists.apache.org/list.html?dev@fory.apache.org) |
+| commits@fory.apache.org | 仓库的所有 commits | [订阅](mailto:commits-subscribe@fory.apache.org) | [取消订阅](mailto:commits-unsubscribe@fory.apache.org) | 只读的邮件列表 | [邮件列表活动](https://lists.apache.org/list.html?commits@fory.apache.org) |
+
+在尝试发送邮件之前，请确保订阅上述的邮件列表。
+
+**如果您没有订阅邮件列表，您的邮件将被拒绝或不会收到回复。**
+
+### 如何订阅邮件列表
+
+要发送邮件至邮件列表，请先通过以下方式订阅：
+
+1. 发送电子邮件至 listname-subscribe@fory.apache.org，并相应替换 `listname`；
+2. 回复您将收到的确认电子邮件，保持邮件主题行完整；
+3. 然后您将收到一封欢迎的电子邮件，订阅成功。
+
+在讨论电子邮件中的代码片段时，请确保：
+
+- 您不要链接到外部服务中的文件，因为此类文件可能会更改、被删除或链接可能会中断，从而使存档的电子邮件线程变得无用；
+- 您粘贴文本而不是文本屏幕截图；
+- 粘贴代码时保持格式，以保持代码可读；
+- 有足够的导入语句以避免产生代码歧义。
+
+## Slack
+
+您可以加入[Slack 上的 Apache Fory™ 社区](https://join.slack.com/t/fory-project/shared_invite/zt-1u8soj4qc-ieYEu7ciHOqA2mo47llS8A)。
+
+这里有一些社区规则：
+
+- 保持尊重和友善；
+- 所有重要的决定和结论都必须反映到邮件列表中。 “如果这没有在邮件列表中有相关的讨论记录，则代表它不生效” ；
+- [The Apache Way](https://theapacheway.com/on-list/)；
+- 使用 Slack 线程来防止并行对话淹没当前的对话频道；
+- 请不要直接向邮件列表发送 Bug fix、Issue 分配和 Code Review 消息。这些内容应该被社区贡献者自愿处理并分配。
+
+## Issue 跟踪
+
+我们使用 GitHub Issues 来跟踪所有 Issues：
+
+- 代码相关问题：https://github.com/apache/fory/issues
+- 网站相关问题：https://github.com/apache/fory-site/issues
+
+您需要有一个 [GitHub 帐号](https://github.com/signup) 才能创建问题。
+如果您没有 [GitHub 帐号](https://github.com/signup)，您可以发送电子邮件至 dev@fory.apache.org。
+
+### 报告 Bug
+
+您在报告 Bug 之前，应该：
+
+- 验证该 Bug 确实存在；
+- 搜索 [Issue List](https://github.com/apache/fory/issues) 以确保不存在相关 Bug。
+- 在 Issue List 中创建 [bug 报告](https://github.com/apache/fory/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml)。
+- 如果可能的话，深入研究 Apache Fory™ 的源代码，并针对您报告的 Bug 提交补丁，这有助于快速修复 Bug。
+
+### 报告安全漏洞
+
+Apache Fory™ 是 [Apache 软件基金会](https://apache.org/) 的一个项目，遵循 [ASF 漏洞处理流程](https://apache.org/security/#vulnerability-handling)。
+
+要报告您发现的新的安全漏洞，请遵循 [ASF 漏洞报告流程](https://apache.org/security/#reporting-a-vulnerability)，该流程解释了如何私下向社区维护者发送详细的漏洞信息。
+
+### New Feature
+
+欢迎您增强功能或新功能建议。提案越具体、越合理，您在 Apache Fory™ 社区的影响力就越大。它有可能在之后版本发布。
+
+### 项目源代码
+
+- Apache Fory™ Core 存储库：https://github.com/apache/fory
+- Apache Fory™ 网站存储库：https://github.com/apache/fory-site
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/community/how_to_join_community.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/community/how_to_join_community.md
new file mode 100644
index 000000000..e24a36673
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/community/how_to_join_community.md
@@ -0,0 +1,108 @@
+---
+title: 如何加入 Apache Fory™ 社区
+sidebar_position: 0
+id: how_to_join_community
+---
+
+首先为你选择加入开源贡献行列的行为点赞 👍🏻。再者，十分感谢你选择参与到 Apache Fory™ 社区，为这个开源项目做出贡献。
+
+## Apache Fory™ 贡献指南
+
+Apache Fory™ 团队通常在 github 上进行开发和 issue 维护，请打开 [Github 网站](https://github.com/)，点击右上角 `Sign up` 按钮，注册一个自己的账号，开启你开源之旅的第一步。
+
+在 [Apache Fory™ 仓库](https://github.com/apache/fory)中，我们有一份面向所有开源贡献者的[指南](https://fory.apache.org/zh-CN/docs/community/)，介绍了有关版本管理、分支管理等内容，**请花几分钟时间阅读了解一下**。
+
+## 你的第一个 Pull Request
+
+### Step0：安装 Git
+
+Git 是一种版本控制系统，用于跟踪和管理软件开发项目中的代码变更。它帮助开发者记录和管理代码的历史记录，方便团队协作、代码版本控制、合并代码等操作。通过 Git，您可以追踪每个文件的每个版本，并轻松地在不同版本之间进行切换和比较。Git 还提供了分支管理功能，使得可以同时进行多个并行开发任务。
+
+- 访问 Git 官方网站：[https://git-scm.com](https://git-scm.com)
+- 下载最新版本的 Git 安装程序。
+- 运行下载的安装程序，按照安装向导的提示进行安装。
+- 安装完成后，你可以通过命令行使用 `git version` 命令确认安装成功。
+
+### Step1：Fork 项目
+
+- 首先需要 fork 这个项目，进入[Apache Fory™ 项目页面](https://github.com/apache/fory)，点击右上角的 Fork 按钮
+- 你的 github 帐号中会出现 xxxx(你的 github 用户名)/fory 这个项目
+- 在本地电脑上使用以下命令: 得到一个 fory 文件夹
+
+```
+// ssh
+git clone git@github.com:xxxx(你的github用户名)/fory.git
+// https
+git clone https://github.com/xxxx(你的github用户名)/fory.git
+```
+
+### Step2：获取项目代码
+
+- 进入 fory 文件夹，添加 fory 的远程地址
+
+```
+git remote add upstream https://github.com/apache/fory.git
+```
+
+### Step3：创建分支
+
+- 好了，现在可以开始贡献我们的代码了。fory 默认分支为 main 分支。无论是功能开发、bug 修复、文档编写，都请新建立一个分支，再合并到 main 分支上。使用以下代码创建分支：
+
+```shell
+// 创建功能开发分支
+git checkout -b feat/xxxx
+
+// 创建问题修复开发分支
+git checkout -b fix/xxxx
+
+// 创建文档、demo分支
+git checkout -b docs/add-java-demo
+```
+
+假设我们创建了文档修改分支 `docs/add-java-demo`
+
+- 假设我们已经添加了一些代码，提交到代码库
+
+- git add .
+
+- git commit -a -m "docs: add java demo and related docs" 。
+
+### Step4：合并修改
+
+- 切换回自己的开发分支:
+
+```
+git checkout docs/add-java-demo
+```
+
+- 把更新代码提交到自己的分支中:
+
+```
+git push origin docs/add-java-demo
+```
+
+### Step5：提交 Pull Request
+
+你可以在你的 github 代码仓库页面点击 `Compare & pull request` 按钮。或通过 `contribute` 按钮创建。
+
+- 填写这是什么类型的修改
+- 填写关联的 issue
+- 若有复杂变更，请说明背景和解决方案
+
+相关信息填写完成后，点击 Create pull request 提交。
+
+## **轻松步入 Apache Fory™ 开源贡献之旅**
+
+"**good first issue**" 是一个在开源社区常见的标签，这个标签的目的是帮助新贡献者找到适合入门的问题。
+
+Apache Fory™ 的入门问题，你可以通过 [issue 列表](https://github.com/apache/fory/issues)查看。
+
+如果你当前**有时间和意愿**参与到社区贡献，可以在 issue 里看一看 **good first issue**，选择一个感兴趣、适合自己的认领。
+
+## 拥抱 Apache Fory™ 社区
+
+在你为 Apache Fory™ 贡献代码之余，我们鼓励你参与其他让社区更加繁荣的事情，比如：
+
+- 为项目的发展、功能规划 等提建议。
+- 创作文章、视频，开办讲座来宣传 Apache Fory™
+- 撰写推广计划，同团队一同执行。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/community/how_to_release.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/community/how_to_release.md
new file mode 100644
index 000000000..5813567f3
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/community/how_to_release.md
@@ -0,0 +1,431 @@
+---
+title: 如何发布
+sidebar_position: 0
+id: how_to_release
+---
+
+本文主要介绍如何发布新版本的 Apache Fory™。
+
+## 介绍
+
+源代码发布是 Apache 最重视以及最重要的部分。
+
+请注意许可证和发布的软件签名问题。发布软件是一件严肃的事情，并会产生相应的法律后果。
+
+## release manager 第一次发布
+
+### 环境要求
+
+此发布过程在 Ubuntu 系统中运行，需要以下几个环境依赖：
+
+- JDK 1.8+
+- Apache Maven 3.x+
+- Python 3.8
+- GnuPG 2.x
+- Git
+- SVN（Apache 基金会使用 svn 来托管项目发布）
+- **设置环境变量**：如果您在不同的目录下配置了 gpg 密钥，请执行 `export GNUPGHOME=$(xxx)` 导出环境变量。
+
+### 准备 GPG 密钥
+
+如果您是第一次作为软件发布者，您需要准备一个 GPG 密钥。
+
+您可以参考这里的[快速开始](https://infra.apache.org/openpgp.html)获取一个 GPG 密钥或者获取更多相关信息。
+
+#### 安装 GPG
+
+```bash
+sudo apt install gnupg2
+```
+
+#### 生成 GPG 密钥
+
+请使用您的 Apache 名字和电子邮件地址生成 GPG 密钥：
+
+```bash
+$ gpg --full-gen-key
+gpg (GnuPG) 2.2.20; Copyright (C) 2020 Free Software Foundation, Inc.
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+
+Please select what kind of key you want:
+ (1) RSA and RSA (default)
+ (2) DSA and Elgamal
+ (3) DSA (sign only)
+ (4) RSA (sign only)
+ (14) Existing key from card
+Your selection? 1 # input 1
+RSA keys may be between 1024 and 4096 bits long.
+What keysize do you want? (2048) 4096 # input 4096
+Requested keysize is 4096 bits
+Please specify how long the key should be valid.
+ 0 = key does not expire
+ <n> = key expires in n days
+ <n>w = key expires in n weeks
+ <n>m = key expires in n months
+ <n>y = key expires in n years
+Key is valid for? (0) 0 # input 0
+Key does not expire at all
+Is this correct? (y/N) y # input y
+
+GnuPG needs to construct a user ID to identify your key.
+
+Real name: Chaokun Yang # input your name
+Email address: chaokunyang@apache.org # input your email
+Comment: CODE SIGNING KEY # input some annotations, optional
+You selected this USER-ID:
+ "Chaokun <ch...@apache.org>"
+
+Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O # input O
+We need to generate a lot of random bytes. It is a good idea to perform
+some other action (type on the keyboard, move the mouse, utilize the
+disks) during the prime generation; this gives the random number
+generator a better chance to gain enough entropy.
+We need to generate a lot of random bytes. It is a good idea to perform
+some other action (type on the keyboard, move the mouse, utilize the
+disks) during the prime generation; this gives the random number
+generator a better chance to gain enough entropy.
+
+# Input the security key
+┌──────────────────────────────────────────────────────┐
+│ Please enter this passphrase │
+│ │
+│ Passphrase: _______________________________ │
+│ │
+│ <OK> <Cancel> │
+└──────────────────────────────────────────────────────┘
+# key generation will be done after your inputting the key with the following output
+gpg: key E49B00F626B marked as ultimately trusted
+gpg: revocation certificate stored as '/Users/chaokunyang/.gnupg/openpgp-revocs.d/1E2CDAE4C08AD7D694D1CB139D7BE8E45E580BA4.rev'
+public and secret key created and signed.
+
+pub rsa4096 2022-07-12 [SC]
+ 1E2CDAE4C08AD7D694D1CB139D7BE8E45E580BA4
+uid [ultimate] Chaokun <ch...@apache.org>
+sub rsa4096 2022-07-12 [E]
+```
+
+#### 上传公钥至 GPG 密钥服务器
+
+首先，列出您所创建的 GPG 密钥：
+
+```bash
+gpg --list-keys
+```
+
+执行相关命令之后，您将看到如下输出：
+
+```bash
+--------------------------------------------------
+pub rsa4096 2024-03-27 [SC]
+ 1E2CDAE4C08AD7D694D1CB139D7BE8E45E580BA4
+uid [ultimate] chaokunyang (CODE SIGNING KEY) <ch...@apache.org>
+sub rsa4096 2024-03-27 [E]
+```
+
+然后，将您的密钥 ID 发送到密钥服务器：
+
+```bash
+gpg --keyserver keys.openpgp.org --send-key <key-id> # e.g., 1E2CDAE4C08AD7D694D1CB139D7BE8E45E580BA4
+```
+
+其中，`keys.openpgp.org` 是一个随机选择的密钥服务器，可以使用 keyserver.ubuntu.com 或任何其他功能完备的密钥服务器。
+
+#### 检查密钥是否创建成功
+
+上传大约需要一分钟；之后，您可以通过电子邮件在相应的密钥服务器上检查。
+
+将密钥上传到密钥服务器的主要目的是为了加入一个可信的[信任网络](https://infra.apache.org/release-signing.html#web-of-trust)。
+
+#### 将 GPG 公钥添加到项目 KEYS 文件中
+
+发布分支的 svn 仓库是：https://dist.apache.org/repos/dist/release/fory
+
+请在发布分支的 KEYS 中添加公钥：
+
+```bash
+svn co https://dist.apache.org/repos/dist/release/fory fory-dist
+# As this step will copy all the versions, it will take some time. If the network is broken, please use svn cleanup to delete the lock before re-execute it.
+cd fory-dist
+(gpg --list-sigs YOUR_NAME@apache.org && gpg --export --armor YOUR_NAME@apache.org) >> KEYS # Append your key to the KEYS file
+svn add . # It is not needed if the KEYS document exists before.
+svn ci -m "add gpg key for YOUR_NAME" # Later on, if you are asked to enter a username and password, just use your apache username and password.
+```
+
+#### 将 GPG 公钥上传到您的 GitHub 帐户
+
+- 输入 `https://github.com/settings/keys` 以添加您的 GPG 密钥。
+- 如果添加后发现“未验证”字样，请将 GPG 密钥中使用的电子邮件地址绑定到您的 GitHub 帐户（https://github.com/settings/emails）。
+
+### 延伸阅读
+
+建议您在发布之前阅读以下文档，了解有关 Apache 基金会发布软件的更多详细信息，但这不是必须的：
+
+- 发布政策：https://www.apache.org/legal/release-policy.html
+- TLP 版本：https://infra.apache.org/release-distribution
+- 发布标志：https://infra.apache.org/release-signing.html
+- 发布发布：https://infra.apache.org/release-publishing.html
+- 发布下载页面：https://infra.apache.org/release-download-pages.html
+- 发布 maven artifacts：https://infra.apache.org/publishing-maven-artifacts.html
+
+## 开始有关发布的讨论
+
+通过发送电子邮件至以下地址发起有关下一个版本的讨论：dev@fory.apache.org：
+
+标题：
+
+```
+[DISCUSS] Release Apache Fory ${release_version}
+```
+
+内容：
+
+```
+Hello, Apache Fory Community,
+
+This is a call for a discussion to release Apache Fory version ${release_version}.
+
+The change lists about this release:
+
+https://github.com/apache/fory/compare/v0.11.2...v0.12.0
+
+Please leave your comments here about this release plan. We will bump the version in repo and start the release process after the discussion.
+
+Thanks,
+
+${name}
+```
+
+## 准备发布
+
+如果讨论结果中没有出现反对声音，您需要做一些发布版本的准备工作。
+
+### Github 分支和标签
+
+- 创建一个名为 `releases-0.16.0`
+- 通过执行命令将版本 `$version` 升级到 `python ci/release.py bump_version -l all -version $version`
+- 执行 git commit 并将分支推送到 `git@github.com:apache/fory.git`
+- 通过 `git tag v0.16.0-rc1` 创建一个 release 标签，然后将其推送到 `git@github.com:apache/fory.git`
+- 如果本次发布包含 `go/fory` 这个 Go 子模块，还需要额外创建并推送 Go 子模块标签。例如，对于最终版 `0.16.0`，执行：
+
+```bash
+git tag go/fory/v0.16.0
+git push apache go/fory/v0.16.0
+```
+
+### 构建 artifacts 并上传到 SVN dist/dev 仓库
+
+首先，您需要通过 `python ci/release.py build -v $version` 构建预发布 artifacts。
+
+然后您需要把它上传到 svn dist repo。dev 分支的 dist 仓库地址是：https://dist.apache.org/repos/dist/dev/fory
+
+```bash
+# As this step will copy all the versions, it will take some time. If the network is broken, please use svn cleanup to delete the lock before re-execute it.
+svn co https://dist.apache.org/repos/dist/dev/fory fory-dist-dev
+```
+
+然后，上传项目：
+
+```bash
+cd fory-dist-dev
+# create a directory named by version
+mkdir ${release_version}-${rc_version}
+# copy source code and signature package to the versioned directory
+cp ${repo_dir}/dist/* ${release_version}-${rc_version}
+# check svn status
+svn status
+# add to svn
+svn add ${release_version}-${rc_version}
+# check svn status
+svn status
+# commit to SVN remote server
+svn commit -m "Prepare for fory ${release_version}-${rc_version}"
+```
+
+访问 https://dist.apache.org/repos/dist/dev/fory/ 以检查 artifacts 是否正确上传。
+
+### 如果出现问题该怎么办
+
+如果某些文件是意外出现或者发生某些错误，则需要删除相关内容并执行 `svn delete`，然后重复上述上传过程。
+
+## 投票
+
+新版本发布需要 Apache Fory 社区的投票。
+
+- release_version：Fory 的版本，如 0.12.0。
+- release_candidate_version：投票的版本，如 0.12.0-rc1。
+- maven_artifact_number：Maven 暂存 artifacts 的数量。如 1001. 具体来说，可以通过搜索 “fory” 来找到 maven_artifact_number https://repository.apache.org/#stagingRepositories.
+
+### Fory 社区投票
+
+发送电子邮件至 Fory Community：dev@fory.apache.org：
+
+标题：
+
+```
+[VOTE] Release Apache Fory v${release_version}-${rc_version}
+```
+
+内容：
+
+```
+Hello, Apache Fory Community:
+
+This is a call for vote to release Apache Fory
+version release-0.12.0-rc1.
+
+Apache Fory - A blazingly fast multi-language serialization
+framework powered by JIT and zero-copy.
+
+The change lists about this release:
+
+https://github.com/apache/fory/compare/v0.12.0...v0.12.0-rc1
+
+The release candidates:
+https://dist.apache.org/repos/dist/dev/fory/0.12.0-rc1/
+
+The maven staging for this release:
+https://repository.apache.org/content/repositories/orgapachefory-1003
+
+Git tag for the release:
+https://github.com/apache/fory/releases/tag/v0.12.0-rc1
+
+如果本次发布还包含 Go 模块，请同时附上 Go 子模块标签：
+https://github.com/apache/fory/releases/tag/go/fory/v0.16.0
+
+Git commit for the release:
+https://github.com/apache/fory/commit/fae06330edd049bb960536e978a45b97bca66faf
+
+The artifacts signed with PGP key [5E580BA4], corresponding to
+[chaokunyang@apache.org], that can be found in keys file:
+https://downloads.apache.org/fory/KEYS
+
+The vote will be open for at least 72 hours until the necessary number of votes are reached.
+
+Please vote accordingly:
+
+[ ] +1 approve
+[ ] +0 no opinion
+[ ] -1 disapprove with the reason
+
+To learn more about Fory, please see https://fory.apache.org/
+
+*Valid check is a requirement for a vote. *Checklist for reference:
+
+[ ] Download Fory is valid.
+[ ] Checksums and PGP signatures are valid.
+[ ] Source code distributions have correct names matching the current release.
+[ ] LICENSE and NOTICE files are correct.
+[ ] All files have license headers if necessary.
+[ ] No compiled archives bundled in source archive.
+[ ] Can compile from source.
+
+How to Build and Test, please refer to: https://github.com/apache/fory/blob/main/docs/guide/DEVELOPMENT.md
+
+Thanks,
+Chaokun Yang
+```
+
+在至少获得 3 + 1 且具有约束力的投票（来自 Fory Podling PMC 成员和提交者）并没有收到否决票之后，发布投票结果：
+
+标题：
+
+```
+[RESULT][VOTE] Release Apache Fory v${release_version}-${rc_version}
+```
+
+内容：
+
+```
+Hello, Apache Fory Community,
+
+The vote to release Apache Fory v${release_version}-${rc_version} has passed.
+
+The vote PASSED with 3 binding +1 and 0 -1 vote:
+
+Binding votes:
+
+- xxx
+- yyy
+- zzz
+
+Vote thread: ${vote_thread_url}
+
+Thanks,
+
+${name}
+```
+
+### 如果投票失败怎么办
+
+如果投票失败，请单击“删除”以删除暂存的 Maven artifacts。
+
+解决提出的问题，然后再次提出 `rc_version` 的新投票。
+
+## 官方发布
+
+### 将 artifacts 发布到 SVN 发布目录
+
+- release_version：Fory 的发布版本，如 0.12.0
+- release_candidate_version：投票版本，如 0.12.0-rc1
+
+```bash
+svn mv https://dist.apache.org/repos/dist/dev/fory/${release_version}-${rc_version} https://dist.apache.org/repos/dist/release/fory/${release_version} -m "Release fory ${release_version}"
+```
+
+### 更改 Fory 网站下载链接
+
+提交 PR 到 https://github.com/apache/fory-site 仓库更新 Fory 版本，[下载页面](https://fory.apache.org/download)
+
+### 发布 Maven artifacts
+
+- maven_artifact_number：Maven 暂存 artifacts 的数量。如 1001。
+- 打开https://repository.apache.org/#stagingRepositories.
+- 找到 artifacts `orgapachefory-${maven_artifact_number}`，点击“发布”。
+
+### 发送公告
+
+将发布公告发送给 dev@fory.apache.org 并且抄送给 announce@apache.org。
+
+标题：
+
+```
+[ANNOUNCE] Apache Fory ${release_version} released
+```
+
+内容：
+
+```
+Hi all,
+
+The Apache Fory community is pleased to announce
+that Apache Fory {release_version} has been released!
+
+Apache Fory - A blazingly fast multi-language serialization
+framework powered by JIT and zero-copy.
+
+The release notes are available here:
+https://github.com/apache/fory/releases/tag/v${release_version}
+
+For the complete list of changes:
+https://github.com/apache/fory/compare/v0.12.0...v${release_version}
+
+Apache Fory website: https://fory.apache.org/
+
+Download Links: https://fory.apache.org/download
+
+Fory Resources:
+- Fory github repo: https://github.com/apache/fory
+- Issue: https://github.com/apache/fory/issues
+- Mailing list: dev@fory.apache.org
+
+We are looking to grow our community and welcome new contributors. If
+you are interested in contributing to Fory, please contact us on the
+mailing list or on GitHub. We will be happy to help you get started.
+
+------------------
+Best Regards,
+${your_name}
+```
+
+至此，整个发布流程结束。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/community/how_to_verify.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/community/how_to_verify.md
new file mode 100644
index 000000000..150fb90cf
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/community/how_to_verify.md
@@ -0,0 +1,119 @@
+---
+title: 如何验证 Apache Fory™
+sidebar_position: 0
+id: how_to_verify
+---
+
+## 下载 Apache Fory™
+
+```bash
+# If there is svn locally, you can clone to the local
+svn co https://dist.apache.org/repos/dist/dev/incubator/fory/${release_version}-${rc_version}/
+# You can download the material file directly
+wget https://dist.apache.org/repos/dist/dev/incubator/fory/${release_version}-${rc_version}/xxx.xxx
+```
+
+## 验证 checksums 和 signatures
+
+首先，您需要安装 gpg：
+
+```bash
+apt-get install gnupg
+# or
+yum install gnupg
+# or
+brew install gnupg
+```
+
+之后，导入 Apache Fory release manager 的公钥：
+
+```bash
+curl https://downloads.apache.org/incubator/fory/KEYS > KEYS # Download KEYS
+gpg --import KEYS # Import KEYS to local
+# Then, trust the public key:
+gpg --edit-key <KEY-used-in-this-version> # Edit the key(mentioned in vote email)
+# It will enter the interactive mode, use the following command to trust the key:
+gpg (GnuPG) 2.0.22; Copyright (C) 2013 Free Software Foundation, Inc.
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+
+
+pub 4096R/5E580BA4 created: 2024-03-27 expires: never usage: SC
+ trust: unknown validity: unknown
+sub 4096R/A31EF728 created: 2024-03-27 expires: never usage: E
+[ unknown] (1). chaokunyang (CODE SIGNING KEY) <ch...@apache.org>
+
+gpg> trust
+pub 4096R/5E580BA4 created: 2024-03-27 expires: never usage: SC
+ trust: unknown validity: unknown
+sub 4096R/A31EF728 created: 2024-03-27 expires: never usage: E
+[ unknown] (1). chaokunyang (CODE SIGNING KEY) <ch...@apache.org>
+
+Please decide how far you trust this user to correctly verify other users' keys
+(by looking at passports, checking fingerprints from different sources, etc.)
+
+ 1 = I don't know or won't say
+ 2 = I do NOT trust
+ 3 = I trust marginally
+ 4 = I trust fully
+ 5 = I trust ultimately
+ m = back to the main menu
+
+Your decision? 5
+Do you really want to set this key to ultimate trust? (y/N) y
+
+pub 4096R/5E580BA4 created: 2024-03-27 expires: never usage: SC
+ trust: ultimate validity: unknown
+sub 4096R/A31EF728 created: 2024-03-27 expires: never usage: E
+[ unknown] (1). chaokunyang (CODE SIGNING KEY) <ch...@apache.org>
+Please note that the shown key validity is not necessarily correct
+unless you restart the program.
+```
+
+接下来验证签名：
+
+```bash
+for i in *.tar.gz; do echo $i; gpg --verify $i.asc $i; done
+```
+
+如果出现如下内容，则表示签名正确：
+
+```bash
+apache-fory-0.5.0-src.tar.gz
+gpg: Signature made Wed 17 Apr 2024 11:49:45 PM CST using RSA key ID 5E580BA4
+gpg: checking the trustdb
+gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
+gpg: depth: 0 valid: 1 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 1u
+gpg: Good signature from "chaokunyang (CODE SIGNING KEY) <ch...@apache.org>"
+```
+
+然后验证 checksum：
+
+```bash
+for i in *.tar.gz; do echo $i; sha512sum --check $i.sha512; done
+```
+
+它应该输出如下内容：
+
+```bash
+apache-fory-0.12.0-src.tar.gz
+apache-fory-0.12.0-src.tar.gz: OK
+```
+
+## 检查源码包中的文件
+
+解压缩 `apache-fory-${release_version}-${rc_version}-src.tar.gz` 并检查以下内容：
+
+- 此存储库 LICENSE 和 NOTICE 文件是正确的；
+- 如有必要，所有文件都有 ASF 许可证标头；
+- 项目构建通过。
+
+## 检查 fory-java 的 Maven artifacts
+
+下载 Apache Fory™：https://repository.apache.org/content/repositories/orgapachefory-${maven_artifact_number}/.
+
+您可以检查以下内容：
+
+- JAR 的 Checksum 与项目绑定的 checksum 文件一致。
+- JAR 的 signature 与项目绑定的 signature 文件一致。
+- JAR 在本地是可重复的。这意味着您可以在计算机上构建 JAR，并验证 checksum 和与项目绑定的相同。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/compiler/_category_.json b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/compiler/_category_.json
new file mode 100644
index 000000000..abf19e9fc
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/compiler/_category_.json
@@ -0,0 +1,6 @@
+{
+ "position": 3,
+ "label": "Schema IDL 与编译器",
+ "collapsible": true,
+ "collapsed": true
+}
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/compiler/compiler-guide.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/compiler/compiler-guide.md
new file mode 100644
index 000000000..0046cbcd3
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/compiler/compiler-guide.md
@@ -0,0 +1,655 @@
+---
+title: 编译器指南
+sidebar_position: 3
+id: compiler_guide
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本指南介绍 Fory IDL 编译器的安装、命令行使用方式以及构建系统集成方案。
+
+## 安装
+
+### 从源码安装
+
+```bash
+cd compiler
+pip install -e .
+```
+
+### 验证安装
+
+```bash
+foryc --help
+```
+
+## 命令行接口
+
+### 基本用法
+
+```bash
+foryc [OPTIONS] FILES...
+```
+
+```bash
+foryc --scan-generated [OPTIONS]
+```
+
+### 选项
+
+编译选项：
+
+| 选项 | 说明 | 默认值 |
+| ------------------------------------- | ------------------------------------------------ | ------------- |
+| `--lang` | 目标语言列表（逗号分隔） | `all` |
+| `--output`, `-o` | 输出目录 | `./generated` |
+| `--package` | 覆盖 Fory IDL 文件中的 package | （来自文件） |
+| `-I`, `--proto_path`, `--import_path` | 添加 import 搜索路径（可重复） | （无） |
+| `--java_out=DST_DIR` | 将 Java 代码输出到 `DST_DIR` | （无） |
+| `--python_out=DST_DIR` | 将 Python 代码输出到 `DST_DIR` | （无） |
+| `--cpp_out=DST_DIR` | 将 C++ 代码输出到 `DST_DIR` | （无） |
+| `--go_out=DST_DIR` | 将 Go 代码输出到 `DST_DIR` | （无） |
+| `--rust_out=DST_DIR` | 将 Rust 代码输出到 `DST_DIR` | （无） |
+| `--go_nested_type_style` | Go 嵌套类型命名风格：`camelcase` 或 `underscore` | schema/默认值 |
+| `--emit-fdl` | 对非 `.fdl` 输入打印转换后的 Fory IDL | `false` |
+| `--emit-fdl-path` | 将转换后的 Fory IDL 写入文件或目录 | （stdout） |
+
+扫描选项（配合 `--scan-generated`）：
+
+| 选项 | 说明 | 默认值 |
+| ------------ | ---------------------- | ------- |
+| `--root` | 扫描根目录 | `.` |
+| `--relative` | 以相对路径输出 | `false` |
+| `--delete` | 删除匹配到的生成文件 | `false` |
+| `--dry-run` | 仅扫描输出，不执行删除 | `false` |
+
+### 扫描生成文件
+
+使用 `--scan-generated` 可以定位 `foryc` 生成的文件。扫描器会递归遍历目录树，跳过 `build/`、`target/` 和隐藏目录，并输出找到的每个生成文件。
+
+```bash
+# 扫描当前目录
+foryc --scan-generated
+
+# 扫描指定根目录
+foryc --scan-generated --root ./src
+
+# 输出相对路径
+foryc --scan-generated --root ./src --relative
+
+# 删除扫描到的生成文件
+foryc --scan-generated --root ./src --delete
+
+# Dry-run（仅扫描与输出）
+foryc --scan-generated --root ./src --dry-run
+```
+
+### 示例
+
+**为所有语言编译：**
+
+```bash
+foryc schema.fdl
+```
+
+**为指定语言编译：**
+
+```bash
+foryc schema.fdl --lang java,python
+```
+
+**指定输出目录：**
+
+```bash
+foryc schema.fdl --output ./src/generated
+```
+
+**覆盖 package：**
+
+```bash
+foryc schema.fdl --package com.myapp.models
+```
+
+**编译多个文件：**
+
+```bash
+foryc user.fdl order.fdl product.fdl --output ./generated
+```
+
+**使用 import 搜索路径：**
+
+```bash
+# 单个路径
+foryc src/main.fdl -I libs/common
+
+# 多个路径（重复参数）
+foryc src/main.fdl -I libs/common -I libs/types
+
+# 多个路径（逗号分隔）
+foryc src/main.fdl -I libs/common,libs/types,third_party/
+
+# --proto_path（protoc 兼容别名）
+foryc src/main.fdl --proto_path=libs/common
+
+# 混合写法
+foryc src/main.fdl -I libs/common,libs/types --proto_path third_party/
+```
+
+**语言定向输出目录（protoc 风格）：**
+
+```bash
+# 仅生成 Java
+foryc schema.fdl --java_out=./src/main/java
+
+# 多语言分别输出到不同目录
+foryc schema.fdl --java_out=./java/gen --python_out=./python/src --go_out=./go/gen
+
+# 结合 import 路径
+foryc schema.fdl --java_out=./gen/java -I proto/ -I common/
+```
+
+使用 `--{lang}_out` 时：
+
+- 只生成显式指定的语言（不会生成全部语言）
+- 输出写入指定目录（语言生成器可能继续按包/模块分层）
+- 兼容 protoc 风格工作流
+
+**查看 proto/fbs 输入转换后的 Fory IDL：**
+
+```bash
+# 输出到 stdout
+foryc schema.proto --emit-fdl
+
+# 输出到目录
+foryc schema.fbs --emit-fdl --emit-fdl-path ./translated
+```
+
+## Import 路径解析
+
+编译含 import 的 Fory IDL 文件时，导入文件按以下顺序查找：
+
+1. **相对于导入者文件目录（默认）**：始终优先查找，无需 `-I`
+2. **按顺序遍历每个 `-I` 路径**
+
+**同目录 import 可直接生效：**
+
+```protobuf
+// main.fdl
+import "common.fdl"; // 若 common.fdl 在同目录，将自动找到
+```
+
+```bash
+# 同目录导入无需 -I
+foryc main.fdl
+```
+
+**示例目录结构：**
+
+```
+project/
+├── src/
+│ └── main.fdl # import "common.fdl";
+└── libs/
+ └── common.fdl
+```
+
+**不加 `-I`（失败）：**
+
+```bash
+$ foryc src/main.fdl
+Import error: Import not found: common.fdl
+ Searched in: /project/src
+```
+
+**加 `-I`（成功）：**
+
+```bash
+$ foryc src/main.fdl -I libs/
+Compiling src/main.fdl...
+ Resolved 1 import(s)
+```
+
+## 支持语言
+
+| 语言 | 标记 | 输出后缀 | 说明 |
+| ------ | -------- | -------- | ---------------------- |
+| Java | `java` | `.java` | 带 Fory 注解的 POJO |
+| Python | `python` | `.py` | 带类型提示的 dataclass |
+| Go | `go` | `.go` | 带 struct tag 的结构体 |
+| Rust | `rust` | `.rs` | 带 derive 宏的结构体 |
+| C++ | `cpp` | `.h` | 带 FORY 宏的结构体 |
+
+## 输出结构
+
+### Java
+
+```
+generated/
+└── java/
+ └── com/
+ └── example/
+ ├── User.java
+ ├── Order.java
+ ├── Status.java
+ └── ExampleForyRegistration.java
+```
+
+- 每个类型（enum/message）单独一个文件
+- 包路径与 Fory IDL package 一致
+- 会生成注册辅助类
+
+### Python
+
+```
+generated/
+└── python/
+ └── example.py
+```
+
+- 所有类型位于单模块
+- 模块名由 package 派生
+- 包含注册函数
+
+### Go
+
+```
+generated/
+└── go/
+ └── example/
+ └── example.go
+```
+
+- 所有类型在单文件中
+- 目录名与包名来自 `go_package` 或 Fory IDL package
+- 包含注册函数
+
+### Rust
+
+```
+generated/
+└── rust/
+ └── example.rs
+```
+
+- 所有类型位于单模块
+- 模块名由 package 派生
+- 包含注册函数
+
+### C++
+
+```
+generated/
+└── cpp/
+ └── example.h
+```
+
+- 单头文件输出
+- 命名空间与 package 对齐（点号转换为 `::`）
+- 自动包含 header guard 与前向声明
+
+## 构建系统集成
+
+### Maven (Java)
+
+在 `pom.xml` 中添加：
+
+```xml
+<build>
+ <plugins>
+ <plugin>
+ <groupId>org.codehaus.mojo</groupId>
+ <artifactId>exec-maven-plugin</artifactId>
+ <version>3.1.0</version>
+ <executions>
+ <execution>
+ <id>generate-fory-types</id>
+ <phase>generate-sources</phase>
+ <goals>
+ <goal>exec</goal>
+ </goals>
+ <configuration>
+ <executable>foryc</executable>
+ <arguments>
+ <argument>${project.basedir}/src/main/fdl/schema.fdl</argument>
+ <argument>--java_out</argument>
+ <argument>${project.build.directory}/generated-sources/fory</argument>
+ </arguments>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+</build>
+```
+
+添加生成源码目录：
+
+```xml
+<build>
+ <plugins>
+ <plugin>
+ <groupId>org.codehaus.mojo</groupId>
+ <artifactId>build-helper-maven-plugin</artifactId>
+ <version>3.4.0</version>
+ <executions>
+ <execution>
+ <phase>generate-sources</phase>
+ <goals>
+ <goal>add-source</goal>
+ </goals>
+ <configuration>
+ <sources>
+ <source>${project.build.directory}/generated-sources/fory</source>
+ </sources>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+</build>
+```
+
+### Gradle (Java/Kotlin)
+
+在 `build.gradle` 中添加：
+
+```groovy
+task generateForyTypes(type: Exec) {
+ commandLine 'foryc',
+ "${projectDir}/src/main/fdl/schema.fdl",
+ '--java_out', "${buildDir}/generated/sources/fory"
+}
+
+compileJava.dependsOn generateForyTypes
+
+sourceSets {
+ main {
+ java {
+ srcDir "${buildDir}/generated/sources/fory"
+ }
+ }
+}
+```
+
+### Python (setuptools)
+
+在 `setup.py` 或 `pyproject.toml` 中加入生成步骤：
+
+```python
+# setup.py
+from setuptools import setup
+from setuptools.command.build_py import build_py
+import subprocess
+
+class BuildWithForyIdl(build_py):
+ def run(self):
+ subprocess.run([
+ 'foryc',
+ 'schema.fdl',
+ '--python_out', 'src/generated'
+ ], check=True)
+ super().run()
+
+setup(
+ cmdclass={'build_py': BuildWithForyIdl},
+ # ...
+)
+```
+
+### Go (`go generate`)
+
+在 Go 文件中添加：
+
+```go
+//go:generate foryc ../schema.fdl --lang go --output .
+package models
+```
+
+执行：
+
+```bash
+go generate ./...
+```
+
+### Rust (`build.rs`)
+
+在 `build.rs` 中添加：
+
+```rust
+use std::process::Command;
+
+fn main() {
+ println!("cargo:rerun-if-changed=schema.fdl");
+
+ let status = Command::new("foryc")
+ .args(&["schema.fdl", "--rust_out", "src/generated"])
+ .status()
+ .expect("Failed to run foryc");
+
+ if !status.success() {
+ panic!("Fory IDL compilation failed");
+ }
+}
+```
+
+### CMake (C++)
+
+在 `CMakeLists.txt` 中添加：
+
+```cmake
+find_program(FORY_COMPILER foryc)
+
+add_custom_command(
+ OUTPUT ${CMAKE_CURRENT_SOURCE_DIR}/generated/example.h
+ COMMAND ${FORY_COMPILER}
+ ${CMAKE_CURRENT_SOURCE_DIR}/schema.fdl
+ --cpp_out ${CMAKE_CURRENT_SOURCE_DIR}/generated
+ DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/schema.fdl
+ COMMENT "Generating Fory IDL types"
+)
+
+add_custom_target(generate_fory_idl DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/generated/example.h)
+
+add_library(mylib ...)
+add_dependencies(mylib generate_fory_idl)
+target_include_directories(mylib PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/generated)
+```
+
+### Bazel
+
+在 `BUILD` 中添加规则：
+
+```python
+genrule(
+ name = "generate_fdl",
+ srcs = ["schema.fdl"],
+ outs = ["generated/example.h"],
+ cmd = "$(location //:fory_compiler) $(SRCS) --cpp_out $(RULEDIR)/generated",
+ tools = ["//:fory_compiler"],
+)
+
+cc_library(
+ name = "models",
+ hdrs = [":generate_fdl"],
+ # ...
+)
+```
+
+## 错误处理
+
+### 语法错误
+
+```
+Error: Line 5, Column 12: Expected ';' after field declaration
+```
+
+修复方式：检查对应行是否缺少分号或存在语法问题。
+
+### 类型名重复
+
+```
+Error: Duplicate type name: User
+```
+
+修复方式：确保同一文件内每个 enum/message 名称唯一。
+
+### 类型 ID 重复
+
+```
+Error: Duplicate type ID 100: User and Order
+```
+
+修复方式：为每个类型分配唯一 ID。
+
+### 未知类型引用
+
+```
+Error: Unknown type 'Address' in Customer.address
+```
+
+修复方式：先定义被引用类型，或检查类型名拼写。
+
+### 字段号重复
+
+```
+Error: Duplicate field number 1 in User: name and id
+```
+
+修复方式：确保同一 message 内字段号唯一。
+
+## 最佳实践
+
+### 项目结构
+
+```
+project/
+├── fdl/
+│ ├── common.fdl # Shared types
+│ ├── user.fdl # User domain
+│ └── order.fdl # Order domain
+├── src/
+│ └── generated/ # Generated code (git-ignored)
+└── build.gradle
+```
+
+### 版本控制
+
+- **纳入版本控制**：Fory IDL schema 文件
+- **忽略生成代码**：可在构建时再生成
+
+在 `.gitignore` 中加入：
+
+```
+# Generated Fory IDL code
+src/generated/
+generated/
+```
+
+### CI/CD 集成
+
+在构建流程中始终重新生成代码：
+
+```yaml
+# GitHub Actions 示例
+steps:
+ - name: Install Fory IDL Compiler
+ run: pip install ./compiler
+
+ - name: Generate Types
+ run: foryc fdl/*.fdl --output src/generated
+
+ - name: Build
+ run: ./gradlew build
+```
+
+### Schema 演进
+
+修改 schema 时建议遵循：
+
+1. **不要复用字段号**：删除字段后应保留/预留
+2. **不要改动类型 ID**：类型 ID 属于二进制协议的一部分
+3. **新增字段使用新字段号**
+4. **优先使用 `optional`**：保持向后兼容
+
+```protobuf
+message User [id=100] {
+ string id = 1;
+ string name = 2;
+ // Field 3 was removed, don't reuse
+ optional string email = 4; // New field
+}
+```
+
+## 故障排查
+
+### Command Not Found
+
+```
+foryc: command not found
+```
+
+**解决：** 确认编译器已安装且在 PATH 中：
+
+```bash
+pip install -e ./compiler
+# Or add to PATH
+export PATH=$PATH:~/.local/bin
+```
+
+### Permission Denied
+
+```
+Permission denied: ./generated
+```
+
+**解决：** 确保输出目录具备写权限：
+
+```bash
+chmod -R u+w ./generated
+```
+
+### 生成代码 import 错误
+
+**Java：** 确保项目包含 Fory 依赖：
+
+```xml
+<dependency>
+ <groupId>org.apache.fory</groupId>
+ <artifactId>fory-core</artifactId>
+ <version>${fory.version}</version>
+</dependency>
+```
+
+**Python：** 确保安装 `pyfory`：
+
+```bash
+pip install pyfory
+```
+
+**Go：** 确保可获取 fory 模块：
+
+```bash
+go get github.com/apache/fory/go/fory
+```
+
+**Rust：** 确保 `Cargo.toml` 中包含 fory crate：
+
+```toml
+[dependencies]
+fory = "x.y.z"
+```
+
+**C++：** 确保编译器 include 路径可找到 Fory 头文件。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/compiler/flatbuffers-idl.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/compiler/flatbuffers-idl.md
new file mode 100644
index 000000000..6a2bfd288
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/compiler/flatbuffers-idl.md
@@ -0,0 +1,183 @@
+---
+title: FlatBuffers IDL 支持
+sidebar_position: 7
+id: flatbuffers_idl
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页说明 Apache Fory 如何读取 FlatBuffers schema（`.fbs`）并将其转换为 Fory IR 以生成代码。
+
+## 本页内容
+
+- 何时应在 Fory 中使用 FlatBuffers 输入
+- FlatBuffers 到 Fory 的精确映射行为
+- `.fbs` 中支持的 Fory 扩展属性
+- 迁移注意事项与生成代码差异
+
+## 为什么使用 Apache Fory
+
+- **生成代码更符合语言习惯**：Fory 会生成各语言常用风格的类/结构体，可直接作为领域对象使用。
+- **Java 性能更优**：在 Fory 的 Java 对象序列化基准中，Fory 通常快于 FlatBuffers。
+- **其他语言性能相近**：序列化性能通常处于同一量级。
+- **实际反序列化链路更高效**：FlatBuffers 默认并不做原生对象反序列化，因此看起来更快；但当业务需要原生对象时，还需额外转换，这一步往往成为主要开销。在这种场景下，Fory 端到端反序列化通常更快。
+- **API 更简单**：Fory 直接操作原生对象，无需反向构建 table 或手动管理 offset。
+- **对象图建模能力更强**：Fory 原生支持共享引用和循环引用。
+
+## 快速决策指南
+
+| 场景 | 建议路径 |
+| ----------------------------------------------- | ----------------------- |
+| 已有 `.fbs` schema，想接入 Fory 运行时/代码生成 | 使用 FlatBuffers 输入 |
+| 新建 schema，希望完整使用 Fory 语法能力 | 使用原生 Fory IDL |
+| 运行时必须保持 FlatBuffers 线格式兼容 | 继续使用 FlatBuffers 栈 |
+| 需要 Fory 对象图语义（`ref`、弱引用等） | 使用 Fory |
+
+## FlatBuffers 到 Fory 的映射
+
+### Schema 级规则
+
+- `namespace` 映射为 Fory package 命名空间。
+- `include` 映射为 Fory import。
+- `table` 会被翻译为 `evolving=true`。
+- `struct` 会被翻译为 `evolving=false`。
+- `root_type` 会被解析，但 Fory 运行时/代码生成不会使用。
+- `file_identifier` 与 `file_extension` 会被解析，但 Fory 代码生成不会使用。
+
+### 字段编号
+
+FlatBuffers 字段没有显式 field ID。Fory 会按源码声明顺序分配字段号，从 `1` 开始。
+
+### 标量类型映射
+
+| FlatBuffers | Fory Type |
+| ----------- | --------- |
+| `byte` | `int8` |
+| `ubyte` | `uint8` |
+| `short` | `int16` |
+| `ushort` | `uint16` |
+| `int` | `int32` |
+| `uint` | `uint32` |
+| `long` | `int64` |
+| `ulong` | `uint64` |
+| `float` | `float32` |
+| `double` | `float64` |
+| `bool` | `bool` |
+| `string` | `string` |
+
+向量（`[T]`）映射为 Fory 列表类型。
+
+### 联合类型
+
+FlatBuffers union 映射为 Fory union。
+
+- case ID 按声明顺序分配，从 `1` 开始。
+- case 名称由类型名转换为 snake_case 字段名。
+
+**FlatBuffers**
+
+```fbs
+union Payload {
+ Note,
+ Metric
+}
+
+table Container {
+ payload: Payload;
+}
+```
+
+**转换后的 Fory 结构**
+
+```protobuf
+union Payload {
+ Note note = 1;
+ Metric metric = 2;
+}
+
+message Container {
+ Payload payload = 1;
+}
+```
+
+### 默认值与元数据
+
+- FlatBuffers 默认值会被解析，但不会作为 Fory 运行时默认值生效。
+- 非 Fory 的 metadata 属性会作为通用 option 保留在 IR 中，供下游工具按需消费。
+
+## FlatBuffers 中的 Fory 扩展属性
+
+FlatBuffers metadata 属性写法为 `key:value`。对于 Fory 扩展选项，在 `.fbs` 中使用 `fory_`（或 `fory.`）前缀；解析时会去掉该前缀。
+
+### 支持的字段属性
+
+| FlatBuffers Attribute | 在 Fory 中的效果 |
+| -------------------------------- | --------------------------------- |
+| `fory_ref:true` | 为字段启用引用跟踪 |
+| `fory_nullable:true` | 将字段标记为 optional/nullable |
+| `fory_weak_ref:true` | 启用弱引用语义，并隐含开启 `ref` |
+| `fory_thread_safe_pointer:false` | 对 ref 字段选择非线程安全指针类型 |
+
+语义说明：
+
+- `fory_weak_ref:true` 隐含 `ref`。
+- `fory_thread_safe_pointer` 仅在字段启用 ref 跟踪时生效。
+- 对列表字段，`fory_ref:true` 作用于列表元素。
+
+示例：
+
+```fbs
+table Node {
+ parent: Node (fory_weak_ref: true);
+ children: [Node] (fory_ref: true);
+ cached: Node (fory_ref: true, fory_thread_safe_pointer: false);
+}
+```
+
+## 生成代码差异
+
+即使用 `.fbs` 作为 Fory 输入，生成的依然是标准 Fory 代码，而不是 FlatBuffers 的 `ByteBuffer` 风格 API。
+
+- Java：带 Fory 元数据的 POJO/record
+- Python：dataclass 与注册辅助代码
+- Go/Rust/C++：原生结构体与 Fory 元数据
+
+最终序列化格式是 Fory 二进制协议，而不是 FlatBuffers 线格式。
+
+## 用法
+
+直接编译 FlatBuffers schema：
+
+```bash
+foryc schema.fbs --lang java,python --output ./generated
+```
+
+输出转换后的 Fory schema 语法以便调试：
+
+```bash
+foryc schema.fbs --emit-fdl --emit-fdl-path ./translated
+```
+
+## 迁移注意事项
+
+1. 保持现有 `namespace` 稳定，以保证类型注册稳定。
+2. 检查依赖 FlatBuffers 字面量默认值的字段，并在业务代码中补充显式默认值。
+3. 在需要对象图语义的字段上添加 `fory_ref`/`fory_weak_ref`。
+4. 替换现有序列化路径前，先用 roundtrip 测试验证生成模型行为。
+
+## 总结
+
+FlatBuffers 输入模式可让你复用现有 `.fbs` schema，同时迁移到 Fory 运行时与代码生成模型。它适合渐进式迁移场景：既保留既有 schema 投入，又能采用 Fory 原生对象 API。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/compiler/generated-code.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/compiler/generated-code.md
new file mode 100644
index 000000000..cadf241ab
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/compiler/generated-code.md
@@ -0,0 +1,714 @@
+---
+title: 生成代码
+sidebar_position: 5
+id: generated_code
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本文档说明各目标语言的代码生成结果与结构。
+
+Fory IDL 生成的类型遵循宿主语言习惯，可直接作为领域对象使用。生成代码同时包含 `to/from bytes` 辅助方法和类型注册辅助逻辑。
+
+## 参考 Schema
+
+下面示例基于两个真实 schema：
+
+1. `addressbook.fdl`（显式类型 ID）
+2. `auto_id.fdl`（未显式声明类型 ID）
+
+### `addressbook.fdl`（节选）
+
+```protobuf
+package addressbook;
+
+option go_package = "github.com/myorg/myrepo/gen/addressbook;addressbook";
+
+message Person [id=100] {
+ string name = 1;
+ int32 id = 2;
+
+ enum PhoneType [id=101] {
+ PHONE_TYPE_MOBILE = 0;
+ PHONE_TYPE_HOME = 1;
+ PHONE_TYPE_WORK = 2;
+ }
+
+ message PhoneNumber [id=102] {
+ string number = 1;
+ PhoneType phone_type = 2;
+ }
+
+ list<PhoneNumber> phones = 7;
+ Animal pet = 8;
+}
+
+message Dog [id=104] {
+ string name = 1;
+ int32 bark_volume = 2;
+}
+
+message Cat [id=105] {
+ string name = 1;
+ int32 lives = 2;
+}
+
+union Animal [id=106] {
+ Dog dog = 1;
+ Cat cat = 2;
+}
+
+message AddressBook [id=103] {
+ list<Person> people = 1;
+ map<string, Person> people_by_name = 2;
+}
+```
+
+### `auto_id.fdl`（节选）
+
+```protobuf
+package auto_id;
+
+enum Status {
+ UNKNOWN = 0;
+ OK = 1;
+}
+
+message Envelope {
+ string id = 1;
+
+ message Payload {
+ int32 value = 1;
+ }
+
+ union Detail {
+ Payload payload = 1;
+ string note = 2;
+ }
+
+ Payload payload = 2;
+ Detail detail = 3;
+ Status status = 4;
+}
+
+union Wrapper {
+ Envelope envelope = 1;
+ string raw = 2;
+}
+```
+
+## Java
+
+### 输出布局
+
+对于 `package addressbook`，Java 输出通常位于：
+
+- `<java_out>/addressbook/`
+- 类型文件：`AddressBook.java`、`Person.java`、`Dog.java`、`Cat.java`、`Animal.java`
+- 注册辅助类：`AddressbookForyRegistration.java`
+
+### 类型生成
+
+message 会生成带 `@ForyField`、默认构造器、getter/setter 以及字节辅助方法的 Java 类：
+
+```java
+public class Person {
+ public static enum PhoneType {
+ MOBILE,
+ HOME,
+ WORK;
+ }
+
+ public static class PhoneNumber {
+ @ForyField(id = 1)
+ private String number;
+
+ @ForyField(id = 2)
+ private PhoneType phoneType;
+
+ public byte[] toBytes() { ... }
+ public static PhoneNumber fromBytes(byte[] bytes) { ... }
+ }
+
+ @ForyField(id = 1)
+ private String name;
+
+ @ForyField(id = 8)
+ private Animal pet;
+
+ public byte[] toBytes() { ... }
+ public static Person fromBytes(byte[] bytes) { ... }
+}
+```
+
+union 会生成继承 `org.apache.fory.type.union.Union` 的类：
+
+```java
+public final class Animal extends Union {
+ public enum AnimalCase {
+ DOG(1),
+ CAT(2);
+ public final int id;
+ AnimalCase(int id) { this.id = id; }
+ }
+
+ public static Animal ofDog(Dog v) { ... }
+ public AnimalCase getAnimalCase() { ... }
+ public int getAnimalCaseId() { ... }
+
+ public boolean hasDog() { ... }
+ public Dog getDog() { ... }
+ public void setDog(Dog v) { ... }
+}
+```
+
+### 注册
+
+生成的注册辅助方法：
+
+```java
+public static void register(Fory fory) {
+ org.apache.fory.resolver.TypeResolver resolver = fory.getTypeResolver();
+ resolver.registerUnion(Animal.class, 106L, new org.apache.fory.serializer.UnionSerializer(fory, Animal.class));
+ resolver.register(Person.class, 100L);
+ resolver.register(Person.PhoneType.class, 101L);
+ resolver.register(Person.PhoneNumber.class, 102L);
+ resolver.register(Dog.class, 104L);
+ resolver.register(Cat.class, 105L);
+ resolver.register(AddressBook.class, 103L);
+}
+```
+
+对于未显式 `[id=...]` 的 schema，注册代码会使用计算得到的数值 ID（例如 `auto_id.fdl`）：
+
+```java
+resolver.register(Status.class, 1124725126L);
+resolver.registerUnion(Wrapper.class, 1471345060L, new org.apache.fory.serializer.UnionSerializer(fory, Wrapper.class));
+resolver.register(Envelope.class, 3022445236L);
+resolver.registerUnion(Envelope.Detail.class, 1609214087L, new org.apache.fory.serializer.UnionSerializer(fory, Envelope.Detail.class));
+resolver.register(Envelope.Payload.class, 2862577837L);
+```
+
+若设置 `option enable_auto_type_id = false;`，则按命名空间与类型名注册：
+
+```java
+resolver.register(Config.class, "myapp.models", "Config");
+resolver.registerUnion(
+ Holder.class,
+ "myapp.models",
+ "Holder",
+ new org.apache.fory.serializer.UnionSerializer(fory, Holder.class));
+```
+
+### 使用示例
+
+```java
+Person person = new Person();
+person.setName("Alice");
+person.setPet(Animal.ofDog(new Dog()));
+
+byte[] data = person.toBytes();
+Person restored = Person.fromBytes(data);
+```
+
+## Python
+
+### 输出布局
+
+Python 每个 schema 文件生成一个模块，例如：
+
+- `<python_out>/addressbook.py`
+
+### 类型生成
+
+union 生成 case 枚举与 `Union` 子类，并提供类型化辅助方法：
+
+```python
+class AnimalCase(Enum):
+ DOG = 1
+ CAT = 2
+
+class Animal(Union):
+ @classmethod
+ def dog(cls, v: Dog) -> "Animal": ...
+
+ def case(self) -> AnimalCase: ...
+ def case_id(self) -> int: ...
+
+ def is_dog(self) -> bool: ...
+ def dog_value(self) -> Dog: ...
+ def set_dog(self, v: Dog) -> None: ...
+```
+
+message 生成 `@pyfory.dataclass` 类型，嵌套类型保持嵌套：
+
+```python
+@pyfory.dataclass
+class Person:
+ class PhoneType(IntEnum):
+ MOBILE = 0
+ HOME = 1
+ WORK = 2
+
+ @pyfory.dataclass
+ class PhoneNumber:
+ number: str = pyfory.field(id=1, default="")
+ phone_type: Person.PhoneType = pyfory.field(id=2, default=None)
+
+ name: str = pyfory.field(id=1, default="")
+ phones: List[Person.PhoneNumber] = pyfory.field(id=7, default_factory=list)
+ pet: Animal = pyfory.field(id=8, default=None)
+
+ def to_bytes(self) -> bytes: ...
+ @classmethod
+ def from_bytes(cls, data: bytes) -> "Person": ...
+```
+
+### 注册
+
+生成注册函数：
+
+```python
+def register_addressbook_types(fory: pyfory.Fory):
+ fory.register_union(Animal, type_id=106, serializer=AnimalSerializer(fory))
+ fory.register_type(Person, type_id=100)
+ fory.register_type(Person.PhoneType, type_id=101)
+ fory.register_type(Person.PhoneNumber, type_id=102)
+ fory.register_type(Dog, type_id=104)
+ fory.register_type(Cat, type_id=105)
+ fory.register_type(AddressBook, type_id=103)
+```
+
+未显式 `[id=...]` 时，注册代码使用计算得到的数值 ID：
+
+```python
+fory.register_type(Status, type_id=1124725126)
+fory.register_union(Wrapper, type_id=1471345060, serializer=WrapperSerializer(fory))
+fory.register_type(Envelope, type_id=3022445236)
+fory.register_union(Envelope.Detail, type_id=1609214087, serializer=Envelope.DetailSerializer(fory))
+fory.register_type(Envelope.Payload, type_id=2862577837)
+```
+
+若设置 `option enable_auto_type_id = false;`：
+
+```python
+fory.register_type(Config, namespace="myapp.models", typename="Config")
+fory.register_union(
+ Holder,
+ namespace="myapp.models",
+ typename="Holder",
+ serializer=HolderSerializer(fory),
+)
+```
+
+### 使用示例
+
+```python
+person = Person(name="Alice", pet=Animal.dog(Dog(name="Rex", bark_volume=10)))
+
+data = person.to_bytes()
+restored = Person.from_bytes(data)
+```
+
+## Rust
+
+### 输出布局
+
+Rust 每个 schema 生成一个模块文件，例如：
+
+- `<rust_out>/addressbook.rs`
+
+### 类型生成
+
+union 映射为 Rust enum，并用 `#[fory(id = ...)]` 声明 case ID：
+
+```rust
+#[derive(ForyObject, Debug, Clone, PartialEq)]
+pub enum Animal {
+ #[fory(id = 1)]
+ Dog(Dog),
+ #[fory(id = 2)]
+ Cat(Cat),
+}
+```
+
+嵌套类型生成嵌套 module：
+
+```rust
+pub mod person {
+ #[derive(ForyObject, Debug, Clone, PartialEq, Default)]
+ #[repr(i32)]
+ pub enum PhoneType {
+ #[default]
+ Mobile = 0,
+ Home = 1,
+ Work = 2,
+ }
+
+ #[derive(ForyObject, Debug, Clone, PartialEq, Default)]
+ pub struct PhoneNumber {
+ #[fory(id = 1)]
+ pub number: String,
+ #[fory(id = 2)]
+ pub phone_type: PhoneType,
+ }
+}
+```
+
+message 会 `derive(ForyObject)` 并生成 `to_bytes`/`from_bytes`：
+
+```rust
+#[derive(ForyObject, Debug, Clone, PartialEq, Default)]
+pub struct Person {
+ #[fory(id = 1)]
+ pub name: String,
+ #[fory(id = 7)]
+ pub phones: Vec<person::PhoneNumber>,
+ #[fory(id = 8, type_id = "union")]
+ pub pet: Animal,
+}
+```
+
+### 注册
+
+生成注册函数：
+
+```rust
+pub fn register_types(fory: &mut Fory) -> Result<(), fory::Error> {
+ fory.register_union::<Animal>(106)?;
+ fory.register::<person::PhoneType>(101)?;
+ fory.register::<person::PhoneNumber>(102)?;
+ fory.register::<Person>(100)?;
+ fory.register::<Dog>(104)?;
+ fory.register::<Cat>(105)?;
+ fory.register::<AddressBook>(103)?;
+ Ok(())
+}
+```
+
+未显式 `[id=...]` 时，注册代码使用计算得到的数值 ID：
+
+```rust
+fory.register::<Status>(1124725126)?;
+fory.register_union::<Wrapper>(1471345060)?;
+fory.register::<Envelope>(3022445236)?;
+fory.register_union::<envelope::Detail>(1609214087)?;
+fory.register::<envelope::Payload>(2862577837)?;
+```
+
+若设置 `option enable_auto_type_id = false;`：
+
+```rust
+fory.register_by_namespace::<Config>("myapp.models", "Config")?;
+fory.register_union_by_namespace::<Holder>("myapp.models", "Holder")?;
+```
+
+### 使用示例
+
+```rust
+let person = Person {
+ name: "Alice".into(),
+ pet: Animal::Dog(Dog::default()),
+ ..Default::default()
+};
+
+let bytes = person.to_bytes()?;
+let restored = Person::from_bytes(&bytes)?;
+```
+
+## C++
+
+### 输出布局
+
+C++ 每个 schema 文件生成一个头文件，例如：
+
+- `<cpp_out>/addressbook.h`
+
+### 类型生成
+
+message 会生成 `final` 类，并包含类型化访问器与字节辅助方法：
+
+```cpp
+class Person final {
+ public:
+ class PhoneNumber final {
+ public:
+ const std::string& number() const;
+ std::string* mutable_number();
+ template <class Arg, class... Args>
+ void set_number(Arg&& arg, Args&&... args);
+
+ fory::Result<std::vector<uint8_t>, fory::Error> to_bytes() const;
+ static fory::Result<PhoneNumber, fory::Error> from_bytes(const std::vector<uint8_t>& data);
+ };
+
+ const std::string& name() const;
+ std::string* mutable_name();
+ template <class Arg, class... Args>
+ void set_name(Arg&& arg, Args&&... args);
+
+ const Animal& pet() const;
+ Animal* mutable_pet();
+};
+```
+
+可选 message 字段会生成 `has_xxx`、`mutable_xxx`、`clear_xxx` API：
+
+```cpp
+class Envelope final {
+ public:
+ bool has_payload() const { return payload_ != nullptr; }
+ const Envelope::Payload& payload() const { return *payload_; }
+ Envelope::Payload* mutable_payload() {
+ if (!payload_) {
+ payload_ = std::make_unique<Envelope::Payload>();
+ }
+ return payload_.get();
+ }
+ void clear_payload() { payload_.reset(); }
+
+ private:
+ std::unique_ptr<Envelope::Payload> payload_;
+};
+```
+
+union 会生成基于 `std::variant` 的封装：
+
+```cpp
+class Animal final {
+ public:
+ enum class AnimalCase : uint32_t {
+ DOG = 1,
+ CAT = 2,
+ };
+
+ static Animal dog(Dog v);
+ static Animal cat(Cat v);
+
+ AnimalCase animal_case() const noexcept;
+ uint32_t animal_case_id() const noexcept;
+
+ bool is_dog() const noexcept;
+ const Dog* as_dog() const noexcept;
+ Dog* as_dog() noexcept;
+ const Dog& dog() const;
+ Dog& dog();
+
+ template <class Visitor>
+ decltype(auto) visit(Visitor&& vis) const;
+
+ private:
+ std::variant<Dog, Cat> value_;
+};
+```
+
+生成头文件还会包含 `FORY_UNION`、`FORY_FIELD_CONFIG`、`FORY_ENUM`、`FORY_STRUCT` 等序列化元信息宏。
+
+### 注册
+
+生成注册函数：
+
+```cpp
+inline void register_types(fory::serialization::BaseFory& fory) {
+ fory.register_union<Animal>(106);
+ fory.register_enum<Person::PhoneType>(101);
+ fory.register_struct<Person::PhoneNumber>(102);
+ fory.register_struct<Person>(100);
+ fory.register_struct<Dog>(104);
+ fory.register_struct<Cat>(105);
+ fory.register_struct<AddressBook>(103);
+}
+```
+
+未显式 `[id=...]` 时，注册代码使用计算得到的数值 ID：
+
+```cpp
+fory.register_enum<Status>(1124725126);
+fory.register_union<Wrapper>(1471345060);
+fory.register_struct<Envelope>(3022445236);
+fory.register_union<Envelope::Detail>(1609214087);
+fory.register_struct<Envelope::Payload>(2862577837);
+```
+
+若设置 `option enable_auto_type_id = false;`：
+
+```cpp
+fory.register_struct<Config>("myapp.models", "Config");
+fory.register_union<Holder>("myapp.models", "Holder");
+```
+
+### 使用示例
+
+```cpp
+addressbook::Person person;
+person.set_name("Alice");
+*person.mutable_pet() = addressbook::Animal::dog(addressbook::Dog{});
+
+auto bytes = person.to_bytes();
+auto restored = addressbook::Person::from_bytes(bytes.value());
+```
+
+## Go
+
+### 输出布局
+
+Go 输出路径受 schema 选项与 `--go_out` 共同影响。
+
+对于 `addressbook.fdl`，若配置了 `go_package`，生成结果会遵循对应 import path/package（位于 `--go_out` 根目录下）。
+
+若未配置 `go_package`，则使用 `--go_out` 指定目录，并按 package 规则生成文件名与包名。
+
+### 类型生成
+
+嵌套类型默认使用下划线命名（`Person_PhoneType`、`Person_PhoneNumber`）：
+
+```go
+type Person_PhoneType int32
+
+const (
+ Person_PhoneTypeMobile Person_PhoneType = 0
+ Person_PhoneTypeHome Person_PhoneType = 1
+ Person_PhoneTypeWork Person_PhoneType = 2
+)
+
+type Person_PhoneNumber struct {
+ Number string `fory:"id=1"`
+ PhoneType Person_PhoneType `fory:"id=2"`
+}
+```
+
+message 会生成带 `fory` tag 的 struct 与字节辅助方法：
+
+```go
+type Person struct {
+ Name string `fory:"id=1"`
+ Id int32 `fory:"id=2,compress=true"`
+ Phones []Person_PhoneNumber `fory:"id=7"`
+ Pet Animal `fory:"id=8"`
+}
+
+func (m *Person) ToBytes() ([]byte, error) { ... }
+func (m *Person) FromBytes(data []byte) error { ... }
+```
+
+union 会生成 case struct，并提供构造器/访问器/visitor API：
+
+```go
+type AnimalCase uint32
+
+type Animal struct {
+ case_ AnimalCase
+ value any
+}
+
+func DogAnimal(v *Dog) Animal { ... }
+func CatAnimal(v *Cat) Animal { ... }
+
+func (u Animal) Case() AnimalCase { ... }
+func (u Animal) AsDog() (*Dog, bool) { ... }
+func (u Animal) Visit(visitor AnimalVisitor) error { ... }
+```
+
+### 注册
+
+生成注册函数：
+
+```go
+func RegisterTypes(f *fory.Fory) error {
+ if err := f.RegisterUnion(Animal{}, 106, fory.NewUnionSerializer(...)); err != nil {
+ return err
+ }
+ if err := f.RegisterEnum(Person_PhoneType(0), 101); err != nil {
+ return err
+ }
+ if err := f.RegisterStruct(Person_PhoneNumber{}, 102); err != nil {
+ return err
+ }
+ if err := f.RegisterStruct(Person{}, 100); err != nil {
+ return err
+ }
+ return nil
+}
+```
+
+未显式 `[id=...]` 时，注册代码使用计算得到的数值 ID：
+
+```go
+if err := f.RegisterEnum(Status(0), 1124725126); err != nil { ... }
+if err := f.RegisterUnion(Wrapper{}, 1471345060, fory.NewUnionSerializer(...)); err != nil { ... }
+if err := f.RegisterStruct(Envelope{}, 3022445236); err != nil { ... }
+if err := f.RegisterUnion(Envelope_Detail{}, 1609214087, fory.NewUnionSerializer(...)); err != nil { ... }
+if err := f.RegisterStruct(Envelope_Payload{}, 2862577837); err != nil { ... }
+```
+
+若设置 `option enable_auto_type_id = false;`：
+
+```go
+if err := f.RegisterNamedStruct(Config{}, "myapp.models.Config"); err != nil { ... }
+if err := f.RegisterNamedUnion(Holder{}, "myapp.models.Holder", fory.NewUnionSerializer(...)); err != nil { ... }
+```
+
+`go_nested_type_style` 可控制嵌套类型命名风格：
+
+```protobuf
+option go_nested_type_style = "camelcase";
+```
+
+### 使用示例
+
+```go
+person := &Person{
+ Name: "Alice",
+ Pet: DogAnimal(&Dog{Name: "Rex"}),
+}
+
+data, err := person.ToBytes()
+if err != nil {
+ panic(err)
+}
+var restored Person
+if err := restored.FromBytes(data); err != nil {
+ panic(err)
+}
+```
+
+## 跨语言说明
+
+### 类型 ID 行为
+
+- 显式 `[id=...]` 会直接用于生成注册代码。
+- 未声明类型 ID 时，生成代码会使用计算得到的数值 ID（参见 `auto_id.*` 输出）。
+- 若设置 `option enable_auto_type_id = false;`，则生成代码改为使用 namespace/type-name 注册 API，而非数值 ID。
+
+### 嵌套类型形态
+
+| 语言 | 嵌套类型形式 |
+| ------ | ---------------------------- |
+| Java | `Person.PhoneNumber` |
+| Python | `Person.PhoneNumber` |
+| Rust | `person::PhoneNumber` |
+| C++ | `Person::PhoneNumber` |
+| Go | `Person_PhoneNumber`（默认） |
+
+### 字节辅助方法命名
+
+| 语言 | 辅助方法名称 |
+| ------ | ------------------------- |
+| Java | `toBytes` / `fromBytes` |
+| Python | `to_bytes` / `from_bytes` |
+| Rust | `to_bytes` / `from_bytes` |
+| C++ | `to_bytes` / `from_bytes` |
+| Go | `ToBytes` / `FromBytes` |
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/compiler/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/compiler/index.md
new file mode 100644
index 000000000..8e26cdd38
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/compiler/index.md
@@ -0,0 +1,212 @@
+---
+title: 概览
+sidebar_position: 1
+id: index
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Fory IDL 是 Apache Fory 的 Schema 定义语言，可实现类型安全的跨语言序列化。
+你只需定义一次数据结构，即可为 Java、Python、Go、Rust 和 C++ 生成原生数据结构代码。
+
+## 示例 Schema
+
+Fory IDL 提供了简单直观的语法来定义跨语言数据结构：
+
+```protobuf
+package example;
+
+enum Status {
+ PENDING = 0;
+ ACTIVE = 1;
+ COMPLETED = 2;
+}
+
+message User {
+ string name = 1;
+ int32 age = 2;
+ optional string email = 3;
+ list<string> tags = 4;
+}
+
+message Item {
+ string sku = 1;
+ int32 quantity = 2;
+}
+
+message Order {
+ ref User customer = 1;
+ list<Item> items = 2;
+ Status status = 3;
+ map<string, int32> metadata = 4;
+}
+
+message Dog [id=104] {
+ string name = 1;
+ int32 bark_volume = 2;
+}
+
+message Cat [id=105] {
+ string name = 1;
+ int32 lives = 2;
+}
+
+union Animal [id=106] {
+ Dog dog = 1;
+ Cat cat = 2;
+}
+```
+
+## 为什么选择 Fory IDL？
+
+### Schema 优先开发
+
+在 Fory IDL 中一次定义数据模型，即可在所有语言中生成一致且类型安全的代码。这样可以确保：
+
+- **类型安全**：在编译期而不是运行期发现类型错误
+- **一致性**：各语言使用相同字段名、类型和结构
+- **文档性**：Schema 本身就是可持续演进的文档
+- **可演进性**：可在所有实现中受控地进行 Schema 变更
+
+### Fory 原生能力
+
+与通用 IDL 不同，Fory IDL 专门为 Fory 序列化设计：
+
+- **引用跟踪**：通过 `ref` 一等支持共享引用和循环引用
+- **可空字段**：通过 `optional` 显式声明可空类型
+- **类型注册**：内置支持数值 ID 与基于命名空间的注册
+- **原生代码生成**：生成带 Fory 注解/宏的语言惯用代码
+
+### 集成开销低
+
+生成代码直接使用各语言原生构造：
+
+- Java：带 `@ForyField` 注解的普通 POJO
+- Python：带类型提示的 dataclass
+- Go：带 struct tag 的结构体
+- Rust：带 `#[derive(ForyObject)]` 的结构体
+- C++：带 `FORY_STRUCT` 宏的结构体
+
+## 快速开始
+
+### 1. 安装编译器
+
+```bash
+pip install fory-compiler
+```
+
+或从源码安装：
+
+```bash
+cd compiler
+pip install -e .
+```
+
+### 2. 编写 Schema
+
+创建 `example.fdl`：
+
+```protobuf
+package example;
+
+message Person {
+ string name = 1;
+ int32 age = 2;
+ optional string email = 3;
+}
+```
+
+### 3. 生成代码
+
+```bash
+# 为所有语言生成
+foryc example.fdl --output ./generated
+
+# 为指定语言生成
+foryc example.fdl --lang java,python --output ./generated
+```
+
+### 4. 使用生成代码
+
+**Java：**
+
+```java
+Person person = new Person();
+person.setName("Alice");
+person.setAge(30);
+byte[] data = person.toBytes();
+```
+
+**Python：**
+
+```python
+import pyfory
+from example import Person
+
+person = Person(name="Alice", age=30)
+data = bytes(person) # 或 `person.to_bytes()`
+```
+
+## 文档导航
+
+| 文档 | 说明 |
+| -------------------------------------------- | ---------------------------------- |
+| [Fory IDL 语法](schema-idl.md) | 完整语言语法与文法 |
+| [类型系统](schema-idl.md#type-system) | 基础类型、集合类型与类型规则 |
+| [编译器指南](compiler-guide.md) | CLI 选项与构建集成 |
+| [生成代码](generated-code.md) | 各目标语言的输出格式 |
+| [Protocol Buffers IDL 支持](protobuf-idl.md) | 与 protobuf 的对比及迁移指南 |
+| [FlatBuffers IDL 支持](flatbuffers-idl.md) | FlatBuffers 映射规则与代码生成差异 |
+
+## 核心概念
+
+### 字段修饰符
+
+- **`optional`**：字段可为 null/None
+- **`ref`**：为共享/循环引用启用引用跟踪
+- **`list`**：字段为列表/数组（别名：`repeated`）
+
+```protobuf
+message Example {
+ optional string nullable = 1;
+ ref Node parent = 2;
+ list<int32> numbers = 3;
+}
+```
+
+### 跨语言兼容
+
+Fory IDL 类型会映射为各语言原生类型：
+
+| Fory IDL 类型 | Java | Python | Go | Rust | C++ |
+| ------------- | --------- | -------------- | -------- | -------- | ------------- |
+| `int32` | `int` | `pyfory.int32` | `int32` | `i32` | `int32_t` |
+| `string` | `String` | `str` | `string` | `String` | `std::string` |
+| `bool` | `boolean` | `bool` | `bool` | `bool` | `bool` |
+
+完整映射请参见 [类型系统](schema-idl.md#type-system)。
+
+## 最佳实践
+
+1. **使用有意义的 package 名称**：将相关类型分组管理
+2. **为性能分配类型 ID**：数值 ID 比基于名称的注册更高效
+3. **预留 ID 范围**：为后续扩展保留空隙（例如用户 100-199，订单 200-299）
+4. **显式使用 `optional`**：清晰表达可空语义
+5. **共享对象使用 `ref`**：对象可能被多处引用时开启引用跟踪
+
+## 示例
+
+完整可运行示例见 [examples](https://github.com/apache/fory/tree/main/compiler/examples) 目录。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/compiler/protobuf-idl.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/compiler/protobuf-idl.md
new file mode 100644
index 000000000..d5bb1d879
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/compiler/protobuf-idl.md
@@ -0,0 +1,321 @@
+---
+title: Protobuf IDL 支持
+sidebar_position: 10
+id: protobuf_idl_support
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页说明 Apache Fory 如何处理 Protocol Buffers（`.proto`）schema、protobuf 概念如何映射到 Fory，以及 protobuf 专用 Fory 扩展选项的使用方式。
+
+## 本页内容
+
+- 如何在具体场景下选择 protobuf 或 Fory
+- 迁移时需要关注的语法与语义差异
+- `.proto` 文件中支持的 Fory 扩展选项
+- 从 protobuf 迁移到 Fory 的实践路径
+
+## 快速决策指南
+
+| 场景 | 建议格式 |
+| ----------------------------------------------------- | ---------------- |
+| 主要构建 gRPC API，依赖 protobuf 工具链 | Protocol Buffers |
+| 需要极致对象图性能与引用跟踪 | Fory |
+| 需要在序列化数据中表达循环/共享引用 | Fory |
+| 需要强 unknown-field 语义保证线格式兼容 | Protocol Buffers |
+| 希望直接使用原生 struct/class，而非 protobuf 包装类型 | Fory |
+
+## Protobuf 与 Fory 对比
+
+| 维度 | Protocol Buffers | Fory |
+| --------- | --------------------- | ---------------------- |
+| 主要目标 | RPC/消息契约 | 高性能对象序列化 |
+| 编码模型 | Tag-Length-Value | Fory 二进制协议 |
+| 引用跟踪 | 非内建 | 一等支持（`ref`） |
+| 循环引用 | 不支持 | 支持 |
+| 未知字段 | 保留 | 不保留 |
+| 生成类型 | protobuf 专用模型类型 | 语言原生构造 |
+| gRPC 生态 | 原生成熟 | 持续建设中（活跃开发） |
+
+Fory 的 gRPC 支持仍在持续开发中。当前生产级 gRPC 工作流里，protobuf 仍是更成熟的默认选择。
+
+## 为什么使用 Apache Fory
+
+- **代码更贴近语言习惯**：Fory IDL 生成的类和结构体可直接作为业务领域对象使用。
+- **序列化性能更高**：在 Fory 基准中，Fory 在对象序列化场景中可显著快于 protobuf。
+- **对象图表达更自然**：共享引用和循环引用是内建能力，无需通过业务层 ID 关联绕过。
+
+性能细节请参见 [性能参考](#性能参考)。
+
+## 语法与语义映射
+
+### Package 与文件级选项
+
+**Protocol Buffers**
+
+```protobuf
+syntax = "proto3";
+package example.models;
+option java_package = "com.example.models";
+option go_package = "example.com/models";
+```
+
+**Fory**
+
+```protobuf
+package example.models;
+```
+
+Fory 使用统一 package 命名空间做跨语言注册。语言特定的包路径仍可在代码生成阶段单独配置。
+
+### Message 与 Enum 定义
+
+**Protocol Buffers**
+
+```protobuf
+message User {
+ string id = 1;
+ string name = 2;
+ optional string email = 3;
+ int32 age = 4;
+ repeated string tags = 5;
+ map<string, string> metadata = 6;
+}
+
+enum Status {
+ STATUS_UNSPECIFIED = 0;
+ STATUS_ACTIVE = 1;
+}
+```
+
+**Fory**
+
+```protobuf
+message User [id=101] {
+ string id = 1;
+ string name = 2;
+ optional string email = 3;
+ int32 age = 4;
+ list<string> tags = 5;
+ map<string, string> metadata = 6;
+}
+
+enum Status [id=102] {
+ UNKNOWN = 0;
+ ACTIVE = 1;
+}
+```
+
+关键差异：
+
+- Fory 可直接分配稳定类型 ID（`[id=...]`）。
+- Fory 使用 `list<T>`（`repeated T` 为兼容别名）。
+- 枚举命名更偏向语言习惯，而非 protobuf 前缀风格。
+
+### `oneof` 到 `union`
+
+protobuf 的 `oneof` 会被翻译为嵌套 Fory `union`，并增加一个可选字段指向该 union。
+
+**Protocol Buffers**
+
+```protobuf
+message Event {
+ oneof payload {
+ string text = 1;
+ int32 number = 2;
+ }
+}
+```
+
+**转换后的 Fory 结构**
+
+```protobuf
+message Event {
+ union payload {
+ string text = 1;
+ int32 number = 2;
+ }
+ optional payload payload = 1;
+}
+```
+
+说明：
+
+- union case ID 来自原 `oneof` 字段号。
+- 自动生成的 union 引用字段使用 `oneof` 中最小字段号。
+
+### Import 与 Well-Known Types
+
+支持 protobuf import。常见 well-known types 会直接映射：
+
+- `google.protobuf.Timestamp` -> `timestamp`
+- `google.protobuf.Duration` -> `duration`
+- `google.protobuf.Any` -> `any`
+
+## 类型映射要点
+
+| Protobuf Type | Fory 映射 |
+| ---------------------------------------- | ----------------------------- |
+| `bool` | `bool` |
+| `int32`, `uint32` | 可变长 32 位整型家族 |
+| `sint32` | zigzag 32 位整型 |
+| `int64`, `uint64` | 可变长 64 位整型家族 |
+| `sint64` | zigzag 64 位整型 |
+| `fixed32`, `fixed64` | 定长无符号整型家族 |
+| `sfixed32`, `sfixed64` | 定长有符号整型家族 |
+| `float`, `double` | `float32`, `float64` |
+| `string`, `bytes` | `string`, `bytes` |
+| `repeated T` | `list<T>` |
+| `map<K, V>` | `map<K, V>` |
+| `optional T` | `optional T` |
+| `oneof` | `union` + 可选 union 引用字段 |
+| `int64 [(fory).type = "tagged_int64"]` | `tagged_int64` 编码 |
+| `uint64 [(fory).type = "tagged_uint64"]` | `tagged_uint64` 编码 |
+
+## Fory 扩展选项（Protobuf）
+
+`.proto` 文件中的 Fory 专用选项使用 `(fory).` 前缀。
+
+```protobuf
+option (fory).enable_auto_type_id = true;
+
+message TreeNode {
+ TreeNode parent = 1 [(fory).weak_ref = true];
+ repeated TreeNode children = 2 [(fory).ref = true];
+}
+```
+
+### 文件级选项
+
+| 选项 | 类型 | 说明 |
+| ------------------------------------ | ------ | --------------------------------------------------- |
+| `(fory).use_record_for_java_message` | bool | 对该文件所有 message 生成 Java record |
+| `(fory).polymorphism` | bool | 默认开启多态序列化元信息 |
+| `(fory).enable_auto_type_id` | bool | 缺失时自动生成类型 ID（编译器默认 true） |
+| `(fory).evolving` | bool | message 的默认 schema 演进行为 |
+| `(fory).go_nested_type_style` | string | Go 嵌套命名风格：`underscore`（默认）或 `camelcase` |
+
+### Message 与 Enum 级选项
+
+| 选项 | 作用对象 | 类型 | 说明 |
+| ---------------------------- | ------------- | ------ | ----------------------------- |
+| `(fory).id` | message, enum | int | 显式类型 ID（用于注册） |
+| `(fory).alias` | message, enum | string | 自动 ID 哈希使用的别名 |
+| `(fory).evolving` | message | bool | 覆盖文件级演进设置 |
+| `(fory).use_record_for_java` | message | bool | 为该 message 生成 Java record |
+| `(fory).deprecated` | message, enum | bool | 标记类型为弃用 |
+| `(fory).namespace` | message | string | 覆盖默认 package 命名空间 |
+
+### 字段级选项
+
+| 选项 | 类型 | 说明 |
+| ---------------------------- | ------ | ----------------------------------------------------- |
+| `(fory).ref` | bool | 为该字段启用引用跟踪 |
+| `(fory).nullable` | bool | 将字段视为可空（`optional`） |
+| `(fory).weak_ref` | bool | 生成弱指针语义（C++/Rust 代码生成） |
+| `(fory).thread_safe_pointer` | bool | ref 字段在 Rust 中的指针类型（`Arc` vs `Rc`） |
+| `(fory).deprecated` | bool | 标记字段为弃用 |
+| `(fory).type` | string | 基础类型覆盖，目前支持 `tagged_int64`/`tagged_uint64` |
+
+引用相关行为：
+
+- `weak_ref = true` 隐含开启 ref 跟踪。
+- 对 `repeated` 字段，`(fory).ref = true` 作用于列表元素。
+- 对 `map<K, V>` 字段，`(fory).ref = true` 作用于 map value。
+- `weak_ref` 与 `thread_safe_pointer` 是 C++/Rust 代码生成提示。
+
+### 典型选项组合示例
+
+```protobuf
+message Graph {
+ Node root = 1 [(fory).ref = true, (fory).thread_safe_pointer = false];
+ repeated Node nodes = 2 [(fory).ref = true];
+ map<string, Node> cache = 3 [(fory).ref = true];
+ Node parent = 4 [(fory).weak_ref = true];
+}
+```
+
+## 引用跟踪 vs Protobuf ID 关联
+
+protobuf 本身不保留共享/循环对象图。借助 Fory protobuf 扩展，可以显式启用对象图语义。
+
+**不使用 Fory ref 选项（protobuf 风格 ID 关联）：**
+
+```protobuf
+message TreeNode {
+ string id = 1;
+ string parent_id = 2;
+ repeated string child_ids = 3;
+}
+```
+
+**使用 Fory ref 选项（对象图语义）：**
+
+```protobuf
+message TreeNode {
+ TreeNode parent = 1 [(fory).weak_ref = true];
+ repeated TreeNode children = 2 [(fory).ref = true];
+}
+```
+
+## 迁移指南：Protobuf 到 Fory
+
+### 第 1 步：转换 schema 语法
+
+- 保持 package 名称稳定。
+- 将 `repeated T` 改为 `list<T>`（或保留 `repeated` 别名）。
+- 在需要稳定数值注册的位置添加显式 `[id=...]`。
+
+### 第 2 步：处理 `oneof` 与特殊类型
+
+- `oneof` -> `union` + 可选 union 字段。
+- 将 protobuf well-known types 映射到 Fory 基础类型（`timestamp`、`duration`、`any`）。
+
+### 第 3 步：用 `ref` 替换 protobuf 的对象图绕过方案
+
+若 protobuf 里通过手工 ID 关联表达对象图，迁移到 Fory 后应改用 `ref` 修饰符（必要时使用 `ref(weak=true)`）。
+
+### 第 4 步：更新构建与代码生成
+
+将 protobuf 代码生成步骤替换为 Fory 编译器针对目标语言的生成命令。
+
+### 第 5 步：执行兼容性验证
+
+分阶段迁移时，可并行保留两种格式，并通过集成测试验证 payload 级一致性。
+
+## 共存策略
+
+迁移期间可以并行运行 protobuf 与 Fory：
+
+```java
+public byte[] serialize(Object obj, Format format) {
+ if (format == Format.PROTOBUF) {
+ return ((MessageLite) obj).toByteArray();
+ }
+ return fory.serialize(obj);
+}
+```
+
+可在服务边界设置转换层，并优先迁移内部对象图较重的链路。
+
+## 性能参考
+
+- Benchmarks: https://fory.apache.org/docs/introduction/benchmark
+- Benchmark code: https://github.com/apache/fory/tree/main/benchmarks
+
+## 总结
+
+当主要关注 API 契约与 gRPC 生态时，建议使用 protobuf。若主要关注对象图性能、原生数据模型与引用语义，建议使用 Fory。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/compiler/schema-idl.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/compiler/schema-idl.md
new file mode 100644
index 000000000..be6d5c6b2
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/compiler/schema-idl.md
@@ -0,0 +1,737 @@
+---
+title: Schema IDL 语法
+sidebar_position: 2
+id: syntax
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本文档给出 Fory IDL 的语法与语义参考，覆盖文件结构、类型系统、字段规则、选项与类型注册策略。
+
+编译器使用方式与构建集成请参见 [Compiler Guide](compiler-guide.md)。
+protobuf/FlatBuffers 前端映射请参见 [Protocol Buffers IDL Support](protobuf-idl.md) 与 [FlatBuffers IDL Support](flatbuffers-idl.md)。
+
+## 文件结构
+
+一个 Fory IDL 文件通常包含：
+
+1. 可选 `package` 声明
+2. 可选文件级 `option`
+3. 可选 `import` 语句
+4. 类型定义（`enum`、`message`、`union`）
+
+```protobuf
+// Optional package declaration
+package com.example.models;
+
+// Optional file-level options
+option java_package = "com.example.models";
+
+// Import statements
+import "common/types.fdl";
+
+// Type definitions
+enum Color [id=100] { ... }
+message User [id=101] { ... }
+message Order [id=102] { ... }
+union Event [id=103] { ... }
+```
+
+## 注释
+
+支持单行注释与块注释：
+
+```protobuf
+// This is a single-line comment
+
+/*
+ * This is a block comment
+ * that spans multiple lines
+ */
+
+message Example {
+ string name = 1; // Inline comment
+}
+```
+
+## Package 声明
+
+`package` 定义文件中所有类型的命名空间。
+
+```protobuf
+package com.example.models;
+```
+
+也可以配置 alias（用于自动类型 ID 计算）：
+
+```protobuf
+package com.example.models alias models_v1;
+```
+
+规则：
+
+- 可选但推荐
+- 必须位于任何类型定义之前
+- 每个文件最多一个 `package`
+- 用于命名空间注册
+- `alias` 会参与 auto-ID 哈希
+
+语言映射：
+
+| 语言 | package 用法 |
+| ------ | ----------------------- |
+| Java | Java package |
+| Python | 模块名（`.` 转 `_`） |
+| Go | 包名（通常取最后一段） |
+| Rust | 模块名（`.` 转 `_`） |
+| C++ | 命名空间（`.` 转 `::`） |
+
+## 文件级选项
+
+文件级选项用于控制语言定制代码生成。
+
+### 语法
+
+```protobuf
+option option_name = value;
+```
+
+### Java Package 选项
+
+通过 `java_package` 覆盖 Java 输出包名：
+
+```protobuf
+package payment;
+option java_package = "com.mycorp.payment.v1";
+
+message Payment {
+ string id = 1;
+}
+```
+
+效果：
+
+- Java 文件输出到 `com/mycorp/payment/v1/`
+- Java `package` 声明使用该值
+- 跨语言类型注册仍以 Fory package（如 `payment`）为准
+
+### Go Package 选项
+
+通过 `go_package` 指定 Go import path 与包名：
+
+```protobuf
+package payment;
+option go_package = "github.com/mycorp/apis/gen/payment/v1;paymentv1";
+
+message Payment {
+ string id = 1;
+}
+```
+
+格式：`"import/path;package_name"` 或仅 `"import/path"`（包名取最后一段）。
+
+### Java Outer Classname 选项
+
+将多个类型包装到一个外层类：
+
+```protobuf
+package payment;
+option java_outer_classname = "DescriptorProtos";
+
+enum Status {
+ UNKNOWN = 0;
+ ACTIVE = 1;
+}
+
+message Payment {
+ string id = 1;
+ Status status = 2;
+}
+```
+
+默认会生成单文件，枚举与消息作为静态内部类型。
+
+### Java Multiple Files 选项
+
+控制 Java 是否拆分多文件：
+
+```protobuf
+package payment;
+option java_outer_classname = "PaymentProtos";
+option java_multiple_files = true;
+
+message Payment {
+ string id = 1;
+}
+
+message Receipt {
+ string id = 1;
+}
+```
+
+行为：
+
+| `java_outer_classname` | `java_multiple_files` | 结果 |
+| ---------------------- | --------------------- | ---------------- |
+| 未设置 | 任意 | 每个类型一个文件 |
+| 已设置 | `false`（默认） | 单文件 + 内部类 |
+| 已设置 | `true` | 强制拆分为多文件 |
+
+### 多个选项组合
+
+```protobuf
+package payment;
+option java_package = "com.mycorp.payment.v1";
+option go_package = "github.com/mycorp/apis/gen/payment/v1;paymentv1";
+option deprecated = true;
+```
+
+### Protobuf 扩展语法说明
+
+在 `.fdl` 中请使用 Fory 原生语法（如 `[id=100]`、`ref`、`optional`、`nullable=true`）。
+`(fory).xxx` 形式仅用于 `.proto`（protobuf 前端）。
+
+### 选项优先级
+
+语言包路径优先级：
+
+1. 命令行覆盖（最高）
+2. 语言选项（`java_package`、`go_package`）
+3. Fory IDL `package`（兜底）
+
+### 跨语言类型注册
+
+默认情况下，注册名由 `package + type name`（或类型 ID）确定。建议长期保持 `package` 稳定，以避免跨版本注册不一致。
+
+## Import 语句
+
+### 基本语法
+
+```protobuf
+import "common/types.fdl";
+```
+
+### 多个导入
+
+```protobuf
+import "common/types.fdl";
+import "domain/user.fdl";
+import "domain/order.fdl";
+```
+
+### 路径解析
+
+导入解析顺序：
+
+1. 导入者文件所在目录
+2. 命令行 `-I/--proto_path/--import_path` 指定目录（按给定顺序）
+
+### 完整示例
+
+```protobuf
+// src/main.fdl
+package app;
+
+import "common.fdl";
+import "models/user.fdl";
+
+message Main {
+ common.Meta meta = 1;
+ models.User user = 2;
+}
+```
+
+### 不支持的 import 写法
+
+- URL 形式（如 `https://...`）
+- 绝对路径依赖（不推荐，会破坏可移植性）
+
+### import 错误
+
+典型错误：
+
+- 文件不存在
+- 搜索路径未包含依赖目录
+- 同名文件冲突导致解析到错误版本
+
+## Enum 定义
+
+### 基本语法
+
+```protobuf
+enum Status {
+ UNKNOWN = 0;
+ ACTIVE = 1;
+ DISABLED = 2;
+}
+```
+
+### 显式类型 ID
+
+```protobuf
+enum Status [id=101] {
+ UNKNOWN = 0;
+ ACTIVE = 1;
+ DISABLED = 2;
+}
+```
+
+### 预留值
+
+```protobuf
+enum Status {
+ UNKNOWN = 0;
+ ACTIVE = 1;
+ reserved 2, 3;
+ reserved 10 to 20;
+}
+```
+
+### enum 类型选项
+
+常见：`id`、`alias`、`deprecated`。
+
+### 语言映射
+
+- Java：`enum`
+- Python：`IntEnum`
+- Go：`type + const`
+- Rust：`repr(i32)` 枚举
+- C++：`enum class`
+
+### 枚举前缀处理
+
+针对 protobuf 风格 `TYPE_NAME_VALUE`，生成器通常会按语言习惯去除冗余前缀，使 API 更自然。
+
+## Message 定义
+
+### 基本语法
+
+```protobuf
+message User {
+ string name = 1;
+ int32 age = 2;
+}
+```
+
+### 显式类型 ID
+
+```protobuf
+message User [id=100] {
+ string name = 1;
+ int32 age = 2;
+}
+```
+
+### 无显式类型 ID
+
+未声明 `[id=...]` 时，编译器可按配置自动生成类型 ID，或使用 namespace/name 注册。
+
+### 语言映射
+
+- Java：类 / record（按选项）
+- Python：dataclass
+- Go：struct
+- Rust：struct
+- C++：class/struct + 宏元信息
+
+### 预留字段
+
+```protobuf
+message User {
+ string name = 1;
+ reserved 2, 3;
+ reserved 10 to 20;
+}
+```
+
+### message 类型选项
+
+常见选项：`id`、`alias`、`evolving`、`deprecated`、`namespace`、`use_record_for_java`。
+
+## 嵌套类型
+
+### 嵌套 message
+
+```protobuf
+message Person {
+ message PhoneNumber {
+ string number = 1;
+ }
+ PhoneNumber phone = 1;
+}
+```
+
+### 嵌套 enum
+
+```protobuf
+message Person {
+ enum PhoneType {
+ MOBILE = 0;
+ HOME = 1;
+ }
+ PhoneType type = 1;
+}
+```
+
+### 限定类型名
+
+可使用完整限定名引用嵌套类型，例如 `Person.PhoneNumber`。
+
+### 深层嵌套类型
+
+支持多层嵌套，但建议控制层级，避免可读性下降。
+
+### 各语言生成形态
+
+| 语言 | 嵌套类型形态 |
+| ------ | --------------------- |
+| Java | `Outer.Inner` |
+| Python | `Outer.Inner` |
+| Rust | `outer::Inner` |
+| C++ | `Outer::Inner` |
+| Go | `Outer_Inner`（默认） |
+
+### 嵌套规则
+
+- 嵌套类型名在其父作用域内必须唯一
+- 可被同文件后续类型引用
+- 可通过 import + 限定名跨文件引用
+
+## Union 定义
+
+### 基本语法
+
+```protobuf
+union Animal {
+ Dog dog = 1;
+ Cat cat = 2;
+}
+```
+
+### 在 message 中使用 union
+
+```protobuf
+message Person {
+ Animal pet = 1;
+}
+```
+
+### 规则
+
+- case 字段号必须唯一
+- case 类型通常为消息类型或可序列化复合类型
+- 各语言会生成带 case 判别和访问器的 union 表达
+
+## 字段定义
+
+### 基本语法
+
+```protobuf
+string name = 1;
+```
+
+### 带修饰符语法
+
+```protobuf
+optional string nickname = 2;
+ref Node parent = 3;
+list<int32> scores = 4;
+```
+
+### 字段修饰符
+
+#### `optional`
+
+声明字段可为空（null/None）：
+
+```protobuf
+message User {
+ optional string email = 1;
+}
+```
+
+建议在跨语言场景显式使用，以避免默认值差异。
+
+#### `ref`
+
+开启引用跟踪，用于共享对象与循环结构：
+
+```protobuf
+message Node {
+ string name = 1;
+ ref Node parent = 2;
+ list<ref Node> children = 3;
+}
+```
+
+当运行时全局 ref tracking 开启时，字段级 `ref` 才会生效。
+
+#### `list`
+
+列表字段（`repeated` 为等价别名）：
+
+```protobuf
+message Group {
+ list<string> tags = 1;
+}
+```
+
+### 组合修饰符
+
+可组合使用：
+
+```protobuf
+message Graph {
+ optional ref Node root = 1;
+ list<ref Node> nodes = 2;
+}
+```
+
+## 字段号
+
+字段号规则：
+
+- 同一 message 内必须唯一
+- 必须为正整数
+- 不应复用已删除字段号（建议使用 `reserved`）
+- 建议预留编号区间以便演进
+
+## Type System {#type-system}
+
+Fory IDL 类型系统包括基础类型、命名类型和集合类型。
+
+### Primitive Types
+
+| 类型族 | 示例 |
+| -------- | --------------------------------- |
+| 布尔 | `bool` |
+| 整数 | `int8/int16/int32/int64`、`uint*` |
+| 浮点 | `float32`、`float64` |
+| 字符串 | `string` |
+| 字节数组 | `bytes` |
+| 时间 | `date`、`timestamp`、`duration` |
+| 动态类型 | `any` |
+
+#### Boolean
+
+`bool` 表示布尔值。
+
+#### Integer Types
+
+支持有符号/无符号与不同位宽。跨语言场景建议明确编码策略并保持字段语义稳定。
+
+#### Integer Encoding Variants
+
+常见编码：
+
+- `varint`：小值更省空间
+- `fixed`：固定长度，性能稳定
+- `tagged`：混合编码（特定类型可用）
+
+#### Floating-Point Types
+
+- `float32`
+- `float64`
+
+#### String Type
+
+`string` 使用 UTF-8 文本语义。
+
+#### Bytes Type
+
+`bytes` 用于原始二进制载荷。
+
+#### Temporal Types
+
+##### Date
+
+`date` 表示日期（不含时区时间部分）。
+
+##### Timestamp
+
+`timestamp` 表示时间点（跨语言应统一时间语义与精度预期）。
+
+#### Any
+
+`any` 允许存储动态类型值。使用 `any` 时建议配合清晰的业务约束，避免滥用导致模型不稳定。
+
+### Named Types
+
+命名类型包括：
+
+- `enum`
+- `message`
+- `union`
+
+支持跨文件 import 和限定名引用。
+
+### Collection Types
+
+#### List (`list`)
+
+```protobuf
+list<T>
+```
+
+等价别名：`repeated T`。
+
+#### Map
+
+```protobuf
+map<K, V>
+```
+
+约束：
+
+- `K` 一般应为可稳定比较的标量类型
+- `V` 可为任意支持类型
+
+### Type Compatibility Matrix
+
+跨语言建议：
+
+- 使用各语言都稳定支持的公共子集
+- 尽量避免平台相关宽度/语义差异
+- 对整数编码与可空语义显式声明
+
+### Best Practices
+
+1. 优先使用显式字段号与稳定命名
+2. 需要可空就显式 `optional`
+3. 存在共享/循环关系时使用 `ref`
+4. 降低 `any` 使用范围，优先强类型建模
+5. 预留字段号与枚举值区间
+
+## Type IDs
+
+类型 ID 用于跨语言快速注册与解码匹配。
+
+### 显式类型 ID
+
+```protobuf
+message User [id=100] {
+ string name = 1;
+}
+```
+
+### 无显式类型 ID
+
+未显式声明时可：
+
+- 自动生成数值 ID（默认配置）
+- 禁用自动 ID，改用 namespace/type-name 注册
+
+### 实践说明
+
+- 类型 ID 在协议层面应视为稳定标识
+- 一经发布，不建议更改
+- 建议按域规划 ID 段（如 100-199 用户域）
+
+### ID 分配策略
+
+- 核心高频模型优先分配固定 ID
+- 团队统一管理 ID 区间与分配规范
+- 在 CI 中增加 ID 冲突检查
+
+## 完整示例
+
+```protobuf
+package demo.order;
+
+option java_package = "com.example.demo.order";
+option go_package = "github.com/example/demo/gen/order;order";
+
+import "demo/common.fdl";
+
+enum Status [id=200] {
+ UNKNOWN = 0;
+ CREATED = 1;
+ PAID = 2;
+ SHIPPED = 3;
+}
+
+message Item [id=201] {
+ string sku = 1;
+ int32 quantity = 2;
+}
+
+message User [id=202] {
+ string id = 1;
+ string name = 2;
+ optional string email = 3;
+}
+
+union Animal [id=203] {
+ Dog dog = 1;
+ Cat cat = 2;
+}
+
+message Dog [id=204] {
+ string name = 1;
+}
+
+message Cat [id=205] {
+ string name = 1;
+}
+
+message Order [id=206] {
+ string id = 1;
+ ref User buyer = 2;
+ list<Item> items = 3;
+ Status status = 4;
+ map<string, string> metadata = 5;
+ optional Animal pet = 6;
+}
+```
+
+## 语法摘要
+
+以下为简化文法（便于快速查阅，具体以编译器实现为准）：
+
+```ebnf
+file = [packageDecl] {optionDecl} {importDecl} {typeDecl} ;
+
+packageDecl = "package" qualifiedName ["alias" identifier] ";" ;
+optionDecl = "option" identifier "=" optionValue ";" ;
+importDecl = "import" stringLiteral ";" ;
+
+typeDecl = enumDecl | messageDecl | unionDecl ;
+
+enumDecl = "enum" identifier [typeOptions] "{" {enumField | reservedDecl} "}" ;
+enumField = identifier "=" intLiteral ";" ;
+
+messageDecl = "message" identifier [typeOptions] "{" {fieldDecl | nestedTypeDecl | reservedDecl} "}" ;
+unionDecl = "union" identifier [typeOptions] "{" {unionCaseDecl} "}" ;
+
+fieldDecl = [fieldModifier] typeRef identifier "=" intLiteral [fieldOptions] ";" ;
+unionCaseDecl = typeRef identifier "=" intLiteral [fieldOptions] ";" ;
+
+fieldModifier = "optional" | "ref" | "list" ;
+
+typeRef = primitiveType | qualifiedName | listType | mapType ;
+listType = "list" "<" typeRef ">" ;
+mapType = "map" "<" typeRef "," typeRef ">" ;
+
+typeOptions = "[" optionPair {"," optionPair} "]" ;
+fieldOptions = "[" optionPair {"," optionPair} "]" ;
+optionPair = identifier "=" optionValue ;
+
+reservedDecl = "reserved" reservedItem {"," reservedItem} ";" ;
+reservedItem = intLiteral | intLiteral "to" intLiteral | stringLiteral ;
+```
+
+实现建议：如需严谨验证，请以编译器语法解析器和测试用例为准。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/DEVELOPMENT.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/DEVELOPMENT.md
new file mode 100644
index 000000000..004da7bd9
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/DEVELOPMENT.md
@@ -0,0 +1,146 @@
+---
+title: 开发指南
+sidebar_position: 20
+id: development
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+## 如何构建 Apache Fory™
+
+请从 https://github.com/apache/fory 检出源代码树。
+
+### 构建 Apache Fory™ Java
+
+```bash
+cd java
+mvn clean compile -DskipTests
+```
+
+#### 环境要求
+
+- java 1.8+
+- maven 3.6.3+
+
+### 构建 Apache Fory™ Python
+
+```bash
+cd python
+# 首先卸载 numpy，以便在安装 pyarrow 时自动安装正确的 numpy 版本。
+# 对于 Python 版本低于 3.13，目前不支持 numpy 2。
+pip uninstall -y numpy
+# 为 Python < 3.13 安装必要的环境。
+pip install pyarrow Cython wheel pytest
+# pip install pyarrow Cython wheel pytest
+pip install -v -e .
+```
+
+#### 环境要求
+
+- python 3.6+
+
+### 构建 Apache Fory™ C++
+
+构建 fory 行格式：
+
+```bash
+bazel build //cpp/fory/row:fory_row_format
+```
+
+构建 fory 行格式编码器：
+
+```bash
+bazel build //cpp/fory/encoder:fory_encoder
+```
+
+#### 环境要求
+
+- 支持 C++17 的编译器
+- bazel 6.3.2
+
+### 构建 Apache Fory™ GoLang
+
+```bash
+cd go/fory
+# 运行测试
+go test -v ./...
+# 运行跨语言测试
+go test -v fory_xlang_test.go
+```
+
+#### 环境要求
+
+- go 1.13+
+
+### 构建 Apache Fory™ Rust
+
+```bash
+cd rust
+# 构建
+cargo build
+# 运行测试
+cargo test
+# 运行特定测试
+cargo test -p tests --test $test_file $test_method
+# 运行子目录下的特定测试
+cargo test --test mod $dir$::$test_file::$test_method
+# 调试子目录下的特定测试并获取回溯信息
+RUST_BACKTRACE=1 FORY_PANIC_ON_ERROR=1 cargo test --test mod $dir$::$test_file::$test_method
+# 检查 fory derive 宏生成的代码
+cargo expand --test mod $mod$::$file$ > expanded.rs
+```
+
+#### 环境要求
+
+```bash
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+```
+
+### 构建 Apache Fory™ JavaScript
+
+```bash
+cd javascript
+npm install
+
+# 运行构建
+npm run build
+# 运行测试
+npm run test
+```
+
+#### 环境要求
+
+- node 14+
+- npm 8+
+
+### Lint Markdown 文档
+
+```bash
+# 全局安装 prettier
+npm install -g prettier
+
+# 格式化 markdown 文件
+prettier --write "**/*.md"
+```
+
+#### 环境要求
+
+- node 14+
+- npm 8+
+
+## 贡献
+
+更多信息，请参考[如何贡献到 Apache Fory™](https://github.com/apache/fory/blob/main/CONTRIBUTING.md)。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/_category_.json b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/_category_.json
new file mode 100644
index 000000000..ab7f160ea
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/_category_.json
@@ -0,0 +1 @@
+{"position": 3, "label": "用户指南"}
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/cpp/_category_.json b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/cpp/_category_.json
new file mode 100644
index 000000000..c543ab138
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/cpp/_category_.json
@@ -0,0 +1,6 @@
+{
+ "label": "C++",
+ "position": 3,
+ "collapsible": true,
+ "collapsed": true
+}
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/cpp/basic-serialization.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/cpp/basic-serialization.md
new file mode 100644
index 000000000..d047b5b99
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/cpp/basic-serialization.md
@@ -0,0 +1,238 @@
+---
+title: 基础序列化
+sidebar_position: 2
+id: basic_serialization
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍基础对象图序列化和核心序列化 API。
+
+## 对象图序列化
+
+Apache Fory™ 提供复杂对象图的自动序列化，保留对象之间的结构和关系。`FORY_STRUCT` 宏在编译时生成高效的序列化代码，消除运行时开销。
+
+**核心功能：**
+
+- 支持任意深度的嵌套结构体序列化
+- 集合类型（vector、set、map）
+- 使用 `std::optional<T>` 的可选字段
+- 智能指针（`std::shared_ptr`、`std::unique_ptr`）
+- 自动处理基本类型和字符串
+- 使用变长整数的高效二进制编码
+
+```cpp
+#include "fory/serialization/fory.h"
+#include <vector>
+#include <map>
+
+using namespace fory::serialization;
+
+// 定义结构体
+struct Address {
+ std::string street;
+ std::string city;
+ std::string country;
+
+ bool operator==(const Address &other) const {
+ return street == other.street && city == other.city &&
+ country == other.country;
+ }
+};
+FORY_STRUCT(Address, street, city, country);
+
+struct Person {
+ std::string name;
+ int32_t age;
+ Address address;
+ std::vector<std::string> hobbies;
+ std::map<std::string, std::string> metadata;
+
+ bool operator==(const Person &other) const {
+ return name == other.name && age == other.age &&
+ address == other.address && hobbies == other.hobbies &&
+ metadata == other.metadata;
+ }
+};
+FORY_STRUCT(Person, name, age, address, hobbies, metadata);
+
+int main() {
+ auto fory = Fory::builder().xlang(true).build();
+ fory.register_struct<Address>(100);
+ fory.register_struct<Person>(200);
+
+ Person person{
+ "John Doe",
+ 30,
+ {"123 Main St", "New York", "USA"},
+ {"reading", "coding"},
+ {{"role", "developer"}}
+ };
+
+ auto result = fory.serialize(person);
+ auto decoded = fory.deserialize<Person>(result.value());
+ assert(person == decoded.value());
+}
+```
+
+## 序列化 API
+
+### 序列化到新 Vector
+
+```cpp
+auto fory = Fory::builder().xlang(true).build();
+fory.register_struct<MyStruct>(1);
+
+MyStruct obj{/* ... */};
+
+// 序列化 - 返回 Result<std::vector<uint8_t>, Error>
+auto result = fory.serialize(obj);
+if (result.ok()) {
+ std::vector<uint8_t> bytes = std::move(result).value();
+ // 使用 bytes...
+} else {
+ // 处理错误
+ std::cerr << result.error().to_string() << std::endl;
+}
+```
+
+### 序列化到现有缓冲区
+
+```cpp
+// 序列化到现有 Buffer（最快路径）
+Buffer buffer;
+auto result = fory.serialize_to(buffer, obj);
+if (result.ok()) {
+ size_t bytes_written = result.value();
+ // buffer 现在包含序列化数据
+}
+
+// 序列化到现有 vector（零拷贝）
+std::vector<uint8_t> output;
+auto result = fory.serialize_to(output, obj);
+if (result.ok()) {
+ size_t bytes_written = result.value();
+ // output 现在包含序列化数据
+}
+```
+
+### 从字节数组反序列化
+
+```cpp
+// 从原始指针反序列化
+auto result = fory.deserialize<MyStruct>(data_ptr, data_size);
+if (result.ok()) {
+ MyStruct obj = std::move(result).value();
+}
+
+// 从 vector 反序列化
+std::vector<uint8_t> data = /* ... */;
+auto result = fory.deserialize<MyStruct>(data);
+
+// 从 Buffer 反序列化（更新 reader_index）
+Buffer buffer(data);
+auto result = fory.deserialize<MyStruct>(buffer);
+```
+
+## 错误处理
+
+Fory 使用 `Result<T, Error>` 类型进行错误处理：
+
+```cpp
+auto result = fory.serialize(obj);
+
+// 检查操作是否成功
+if (result.ok()) {
+ auto value = std::move(result).value();
+ // 使用 value...
+} else {
+ Error error = result.error();
+ std::cerr << "Error: " << error.to_string() << std::endl;
+}
+
+// 或使用 FORY_TRY 宏进行提前返回
+FORY_TRY(bytes, fory.serialize(obj));
+// 直接使用 bytes...
+```
+
+常见错误类型：
+
+- `Error::type_mismatch` - 反序列化时类型 ID 不匹配
+- `Error::invalid_data` - 无效或损坏的数据
+- `Error::buffer_out_of_bound` - 缓冲区溢出/下溢
+- `Error::type_error` - 类型注册错误
+
+## FORY_STRUCT 宏
+
+`FORY_STRUCT` 宏用于注册结构体以进行序列化：
+
+```cpp
+struct MyStruct {
+ int32_t x;
+ std::string y;
+ std::vector<int32_t> z;
+};
+
+// 必须与结构体在同一命名空间中
+FORY_STRUCT(MyStruct, x, y, z);
+```
+
+该宏：
+
+1. 生成编译时字段元数据
+2. 启用 ADL（参数依赖查找）进行序列化
+3. 通过模板特化创建高效的序列化代码
+
+**要求：**
+
+- 必须放在与结构体相同的命名空间中（用于 ADL）
+- 所有列出的字段必须是可序列化类型
+- 宏中的字段顺序决定序列化顺序
+
+## 嵌套结构体
+
+完全支持嵌套结构体：
+
+```cpp
+struct Inner {
+ int32_t value;
+};
+FORY_STRUCT(Inner, value);
+
+struct Outer {
+ Inner inner;
+ std::string label;
+};
+FORY_STRUCT(Outer, inner, label);
+
+// 两者都必须注册
+fory.register_struct<Inner>(1);
+fory.register_struct<Outer>(2);
+```
+
+## 性能提示
+
+- **缓冲区复用**：使用 `serialize_to(buffer, obj)` 配合预分配的缓冲区
+- **预注册**：在序列化开始前注册所有类型
+- **单线程**：尽可能使用 `build()` 而不是 `build_thread_safe()`
+- **禁用跟踪**：当不需要引用跟踪时使用 `track_ref(false)`
+- **紧凑编码**：使用变长编码提高空间效率
+
+## 相关主题
+
+- [配置](configuration.md) - 构建器选项
+- [类型注册](type-registration.md) - 注册类型
+- [支持的类型](supported-types.md) - 所有支持的类型
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/cpp/configuration.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/cpp/configuration.md
new file mode 100644
index 000000000..04b314dc9
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/cpp/configuration.md
@@ -0,0 +1,189 @@
+---
+title: 配置
+sidebar_position: 1
+id: configuration
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍 Fory 配置选项和序列化模式。
+
+## 序列化模式
+
+Apache Fory™ 支持两种序列化模式：
+
+### SchemaConsistent 模式（默认）
+
+类型声明必须在通信双方完全匹配：
+
+```cpp
+auto fory = Fory::builder().build(); // 默认为 SchemaConsistent
+```
+
+### Compatible 模式
+
+允许独立的 schema 演化：
+
+```cpp
+auto fory = Fory::builder().compatible(true).build();
+```
+
+## 构建器模式
+
+使用 `ForyBuilder` 构造具有自定义配置的 Fory 实例：
+
+```cpp
+#include "fory/serialization/fory.h"
+
+using namespace fory::serialization;
+
+// 默认配置
+auto fory = Fory::builder().build();
+
+// 用于 schema 演化的兼容模式
+auto fory = Fory::builder()
+ .compatible(true)
+ .build();
+
+// 跨语言模式
+auto fory = Fory::builder()
+ .xlang(true)
+ .build();
+
+// 完整配置
+auto fory = Fory::builder()
+ .compatible(true)
+ .xlang(true)
+ .track_ref(true)
+ .max_dyn_depth(10)
+ .check_struct_version(true)
+ .build();
+```
+
+## 配置选项
+
+### xlang(bool)
+
+启用/禁用跨语言（xlang）序列化模式。
+
+```cpp
+auto fory = Fory::builder()
+ .xlang(true) // 启用跨语言兼容性
+ .build();
+```
+
+启用后，包含用于与 Java、Python、Go、Rust 和 JavaScript 跨语言兼容的元数据。
+
+**默认值：** `true`
+
+### compatible(bool)
+
+启用/禁用用于 schema 演化的兼容模式。
+
+```cpp
+auto fory = Fory::builder()
+ .compatible(true) // 启用 schema 演化
+ .build();
+```
+
+启用后，支持读取使用不同 schema 版本序列化的数据。
+
+**默认值：** `false`
+
+### track_ref(bool)
+
+启用/禁用共享引用和循环引用的引用跟踪。
+
+```cpp
+auto fory = Fory::builder()
+ .track_ref(true) // 启用引用跟踪
+ .build();
+```
+
+启用后，避免重复序列化共享对象并处理循环引用。
+
+**默认值：** `true`
+
+### max_dyn_depth(uint32_t)
+
+设置动态类型对象的最大允许嵌套深度。
+
+```cpp
+auto fory = Fory::builder()
+ .max_dyn_depth(10) // 允许最多 10 层
+ .build();
+```
+
+这限制了嵌套多态对象序列化的最大深度（例如 `shared_ptr<Base>`、`unique_ptr<Base>`）。防止深度嵌套结构在动态序列化场景中导致栈溢出。
+
+**默认值：** `5`
+
+**何时调整：**
+
+- **增加**：对于合法的深度嵌套数据结构
+- **减少**：对于更严格的安全要求或浅层数据结构
+
+### check_struct_version(bool)
+
+启用/禁用结构体版本检查。
+
+```cpp
+auto fory = Fory::builder()
+ .check_struct_version(true) // 启用版本检查
+ .build();
+```
+
+启用后，验证类型哈希以检测 schema 不匹配。
+
+**默认值：** `false`
+
+## 线程安全 vs 单线程
+
+### 单线程（最快）
+
+```cpp
+auto fory = Fory::builder()
+ .xlang(true)
+ .build(); // 返回 Fory
+```
+
+单线程 `Fory` 是最快的选项，但非线程安全。每个线程使用一个实例。
+
+### 线程安全
+
+```cpp
+auto fory = Fory::builder()
+ .xlang(true)
+ .build_thread_safe(); // 返回 ThreadSafeFory
+```
+
+`ThreadSafeFory` 使用 Fory 实例池提供线程安全的序列化。由于池开销略慢，但可以从多个线程并发安全使用。
+
+## 配置摘要
+
+| 选项 | 说明 | 默认值 |
+| ---------------------------- | ---------------------- | ------- |
+| `xlang(bool)` | 启用跨语言模式 | `true` |
+| `compatible(bool)` | 启用 schema 演化 | `false` |
+| `track_ref(bool)` | 启用引用跟踪 | `true` |
+| `max_dyn_depth(uint32_t)` | 动态类型的最大嵌套深度 | `5` |
+| `check_struct_version(bool)` | 启用结构体版本检查 | `false` |
+
+## 相关主题
+
+- [基础序列化](basic-serialization.md) - 使用配置的 Fory
+- [跨语言](cross-language.md) - XLANG 模式详情
+- [类型注册](type-registration.md) - 注册类型
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/cpp/cross-language.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/cpp/cross-language.md
new file mode 100644
index 000000000..ef338ecba
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/cpp/cross-language.md
@@ -0,0 +1,271 @@
+---
+title: 跨语言序列化
+sidebar_position: 6
+id: cross_language
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍如何使用 Fory 在 C++ 和其他语言之间进行跨语言序列化。
+
+## 概述
+
+Apache Fory™ 支持在 C++、Java、Python、Go、Rust 和 JavaScript 之间无缝交换数据。xlang（跨语言）模式确保所有支持语言之间的二进制兼容性。
+
+## 启用跨语言模式
+
+```cpp
+#include "fory/serialization/fory.h"
+
+using namespace fory::serialization;
+
+auto fory = Fory::builder()
+ .xlang(true) // 启用跨语言模式
+ .build();
+```
+
+## 跨语言示例
+
+### C++ 生产者
+
+```cpp
+#include "fory/serialization/fory.h"
+#include <fstream>
+
+using namespace fory::serialization;
+
+struct Message {
+ std::string topic;
+ int64_t timestamp;
+ std::map<std::string, std::string> headers;
+ std::vector<uint8_t> payload;
+
+ bool operator==(const Message &other) const {
+ return topic == other.topic && timestamp == other.timestamp &&
+ headers == other.headers && payload == other.payload;
+ }
+};
+FORY_STRUCT(Message, topic, timestamp, headers, payload);
+
+int main() {
+ auto fory = Fory::builder().xlang(true).build();
+ fory.register_struct<Message>(100);
+
+ Message msg{
+ "events.user",
+ 1699999999000,
+ {{"content-type", "application/json"}},
+ {'h', 'e', 'l', 'l', 'o'}
+ };
+
+ auto result = fory.serialize(msg);
+ if (result.ok()) {
+ auto bytes = std::move(result).value();
+ // 写入文件、通过网络发送等
+ std::ofstream file("message.bin", std::ios::binary);
+ file.write(reinterpret_cast<const char*>(bytes.data()), bytes.size());
+ }
+ return 0;
+}
+```
+
+### Java 消费者
+
+```java
+import org.apache.fory.Fory;
+import org.apache.fory.config.Language;
+
+public class Message {
+ public String topic;
+ public long timestamp;
+ public Map<String, String> headers;
+ public byte[] payload;
+}
+
+public class Consumer {
+ public static void main(String[] args) throws Exception {
+ Fory fory = Fory.builder()
+ .withLanguage(Language.XLANG)
+ .build();
+ fory.register(Message.class, 100); // 与 C++ 相同的 ID
+
+ byte[] bytes = Files.readAllBytes(Path.of("message.bin"));
+ Message msg = (Message) fory.deserialize(bytes);
+
+ System.out.println("Topic: " + msg.topic);
+ System.out.println("Timestamp: " + msg.timestamp);
+ }
+}
+```
+
+### Python 消费者
+
+```python
+import pyfory
+
+class Message:
+ topic: str
+ timestamp: int
+ headers: dict[str, str]
+ payload: bytes
+
+fory = pyfory.Fory()
+fory.register(Message, type_id=100) # 与 C++ 相同的 ID
+
+with open("message.bin", "rb") as f:
+ data = f.read()
+
+msg = fory.deserialize(data)
+print(f"Topic: {msg.topic}")
+print(f"Timestamp: {msg.timestamp}")
+```
+
+## 类型映射
+
+### 基本类型
+
+| C++ 类型 | Java 类型 | Python 类型 | Go 类型 | Rust 类型 |
+| --------- | --------- | ----------- | --------- | --------- |
+| `bool` | `boolean` | `bool` | `bool` | `bool` |
+| `int8_t` | `byte` | `int` | `int8` | `i8` |
+| `int16_t` | `short` | `int` | `int16` | `i16` |
+| `int32_t` | `int` | `int` | `int32` | `i32` |
+| `int64_t` | `long` | `int` | `int64` | `i64` |
+| `float` | `float` | `float` | `float32` | `f32` |
+| `double` | `double` | `float` | `float64` | `f64` |
+
+### 字符串类型
+
+| C++ 类型 | Java 类型 | Python 类型 | Go 类型 | Rust 类型 |
+| ------------- | --------- | ----------- | -------- | --------- |
+| `std::string` | `String` | `str` | `string` | `String` |
+
+### 集合类型
+
+| C++ 类型 | Java 类型 | Python 类型 | Go 类型 |
+| ---------------- | ---------- | ----------- | ---------------- |
+| `std::vector<T>` | `List<T>` | `list` | `[]T` |
+| `std::set<T>` | `Set<T>` | `set` | `map[T]struct{}` |
+| `std::map<K,V>` | `Map<K,V>` | `dict` | `map[K]V` |
+
+### 时间类型
+
+| C++ 类型 | Java 类型 | Python 类型 | Go 类型 |
+| ----------- | ----------- | --------------- | --------------- |
+| `Timestamp` | `Instant` | `datetime` | `time.Time` |
+| `Duration` | `Duration` | `timedelta` | `time.Duration` |
+| `LocalDate` | `LocalDate` | `datetime.date` | `time.Time` |
+
+## 字段顺序要求
+
+**关键：** 字段将按照其 snake_cased 字段名排序，转换后的名称必须在各语言之间保持一致
+
+### C++
+
+```cpp
+struct Person {
+ std::string name; // 字段 0
+ int32_t age; // 字段 1
+ std::string email; // 字段 2
+};
+FORY_STRUCT(Person, name, age, email); // 顺序很重要！
+```
+
+### Java
+
+```java
+public class Person {
+ public String name; // 字段 0
+ public int age; // 字段 1
+ public String email; // 字段 2
+}
+```
+
+### Python
+
+```python
+class Person:
+ name: str # 字段 0
+ age: int # 字段 1
+ email: str # 字段 2
+```
+
+## 类型 ID 一致性
+
+所有语言必须使用相同的类型 ID：
+
+```cpp
+// C++
+fory.register_struct<Person>(100);
+fory.register_struct<Address>(101);
+fory.register_struct<Order>(102);
+```
+
+```java
+// Java
+fory.register(Person.class, 100);
+fory.register(Address.class, 101);
+fory.register(Order.class, 102);
+```
+
+```python
+# Python
+fory.register(Person, type_id=100)
+fory.register(Address, type_id=101)
+fory.register(Order, type_id=102)
+```
+
+## Compatible 模式
+
+用于跨语言边界的 schema 演化：
+
+```cpp
+// 使用 compatible 模式的 C++
+auto fory = Fory::builder()
+ .xlang(true)
+ .compatible(true) // 启用 schema 演化
+ .build();
+```
+
+Compatible 模式允许：
+
+- 添加新字段（带默认值）
+- 删除未使用的字段
+- 重排字段顺序
+
+## 故障排查
+
+### 类型不匹配错误
+
+```
+Error: Type mismatch: expected 100, got 101
+```
+
+**解决方案：** 确保类型 ID 在所有语言中匹配。
+
+### 编码错误
+
+```
+Error: Invalid UTF-8 sequence
+```
+
+**解决方案：** 确保所有语言中的字符串都是有效的 UTF-8。
+
+## 相关主题
+
+- [配置](configuration.md) - 构建器选项
+- [类型注册](type-registration.md) - 注册类型
+- [支持的类型](supported-types.md) - 类型兼容性
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/cpp/custom-serializers.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/cpp/custom-serializers.md
new file mode 100644
index 000000000..feab1bd95
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/cpp/custom-serializers.md
@@ -0,0 +1,371 @@
+---
+title: 自定义序列化器
+sidebar_position: 6
+id: custom_serializers
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+对于不支持 `FORY_STRUCT` 的类型，需要手动实现 `Serializer` 模板特化。
+
+## 何时使用自定义序列化器
+
+- External types from third-party libraries
+- Types with special serialization requirements
+- Legacy data format compatibility
+- Performance-critical custom encoding
+- Cross-language interoperability with custom protocols
+
+## 实现 Serializer 模板
+
+To create a custom serializer, specialize the `Serializer` template for your type within the `fory::serialization` namespace:
+
+```cpp
+#include "fory/serialization/fory.h"
+
+using namespace fory::serialization;
+
+// Define your custom type
+struct MyExt {
+ int32_t id;
+ bool operator==(const MyExt &other) const { return id == other.id; }
+};
+
+namespace fory {
+namespace serialization {
+
+template <>
+struct Serializer<MyExt> {
+ // Declare as extension type for custom serialization
+ static constexpr TypeId type_id = TypeId::EXT;
+
+ // Main write method - handles null checking and type info
+ static void write(const MyExt &value, WriteContext &ctx, RefMode ref_mode,
+ bool write_type, bool has_generics = false) {
+ (void)has_generics;
+ write_not_null_ref_flag(ctx, ref_mode);
+ if (write_type) {
+ auto result = ctx.write_any_type_info(
+ static_cast<uint32_t>(TypeId::UNKNOWN),
+ std::type_index(typeid(MyExt)));
+ if (!result.ok()) {
+ ctx.set_error(std::move(result).error());
+ return;
+ }
+ }
+ write_data(value, ctx);
+ }
+
+ // write only the data (no type info)
+ static void write_data(const MyExt &value, WriteContext &ctx) {
+ Serializer<int32_t>::write_data(value.id, ctx);
+ }
+
+ // write data with generics support
+ static void write_data_generic(const MyExt &value, WriteContext &ctx,
+ bool has_generics) {
+ (void)has_generics;
+ write_data(value, ctx);
+ }
+
+ // Main read method - handles null checking and type info
+ static MyExt read(ReadContext &ctx, RefMode ref_mode, bool read_type) {
+ bool has_value = read_null_only_flag(ctx, ref_mode);
+ if (ctx.has_error() || !has_value) {
+ return MyExt{};
+ }
+ if (read_type) {
+ const TypeInfo *type_info = ctx.read_any_type_info(ctx.error());
+ if (ctx.has_error()) {
+ return MyExt{};
+ }
+ if (!type_info) {
+ ctx.set_error(Error::type_error("TypeInfo for MyExt not found"));
+ return MyExt{};
+ }
+ }
+ return read_data(ctx);
+ }
+
+ // Read only the data (no type info)
+ static MyExt read_data(ReadContext &ctx) {
+ MyExt value;
+ value.id = Serializer<int32_t>::read_data(ctx);
+ return value;
+ }
+
+ // Read data with generics support
+ static MyExt read_data_generic(ReadContext &ctx, bool has_generics) {
+ (void)has_generics;
+ return read_data(ctx);
+ }
+
+ // Read with pre-resolved type info
+ static MyExt read_with_type_info(ReadContext &ctx, RefMode ref_mode,
+ const TypeInfo &type_info) {
+ (void)type_info;
+ return read(ctx, ref_mode, false);
+ }
+};
+
+} // namespace serialization
+} // namespace fory
+```
+
+## Required Methods
+
+A custom serializer must implement these static methods:
+
+| Method | Purpose |
+| --------------------- | ----------------------------------------------- |
+| `write` | Main serialization entry point with type info |
+| `write_data` | Serialize data only (no type info) |
+| `write_data_generic` | Serialize data with generics support |
+| `read` | Main deserialization entry point with type info |
+| `read_data` | Deserialize data only (no type info) |
+| `read_data_generic` | Deserialize data with generics support |
+| `read_with_type_info` | Deserialize with pre-resolved TypeInfo |
+
+The `type_id` constant should be set to `TypeId::EXT` for custom extension types.
+
+## Registering Custom Serializers
+
+Register your custom serializer with Fory before use:
+
+```cpp
+auto fory = Fory::builder().xlang(true).build();
+
+// Register with numeric type ID (must match across languages)
+auto result = fory.register_extension_type<MyExt>(103);
+if (!result.ok()) {
+ std::cerr << "Failed to register: " << result.error().to_string() << std::endl;
+}
+
+// Or register with type name for named type systems
+fory.register_extension_type<MyExt>("my_ext");
+
+// Or with namespace and type name
+fory.register_extension_type<MyExt>("com.example", "MyExt");
+```
+
+## Complete Example
+
+```cpp
+#include "fory/serialization/fory.h"
+#include <iostream>
+
+using namespace fory::serialization;
+
+struct CustomType {
+ int32_t value;
+ std::string name;
+
+ bool operator==(const CustomType &other) const {
+ return value == other.value && name == other.name;
+ }
+};
+
+namespace fory {
+namespace serialization {
+
+template <>
+struct Serializer<CustomType> {
+ static constexpr TypeId type_id = TypeId::EXT;
+
+ static void write(const CustomType &value, WriteContext &ctx,
+ RefMode ref_mode, bool write_type, bool has_generics = false) {
+ (void)has_generics;
+ write_not_null_ref_flag(ctx, ref_mode);
+ if (write_type) {
+ auto result = ctx.write_any_type_info(
+ static_cast<uint32_t>(TypeId::UNKNOWN),
+ std::type_index(typeid(CustomType)));
+ if (!result.ok()) {
+ ctx.set_error(std::move(result).error());
+ return;
+ }
+ }
+ write_data(value, ctx);
+ }
+
+ static void write_data(const CustomType &value, WriteContext &ctx) {
+ // write value as varint for compact encoding
+ Serializer<int32_t>::write_data(value.value, ctx);
+ // Delegate string serialization to built-in serializer
+ Serializer<std::string>::write_data(value.name, ctx);
+ }
+
+ static void write_data_generic(const CustomType &value, WriteContext &ctx,
+ bool has_generics) {
+ (void)has_generics;
+ write_data(value, ctx);
+ }
+
+ static CustomType read(ReadContext &ctx, RefMode ref_mode, bool read_type) {
+ bool has_value = read_null_only_flag(ctx, ref_mode);
+ if (ctx.has_error() || !has_value) {
+ return CustomType{};
+ }
+ if (read_type) {
+ const TypeInfo *type_info = ctx.read_any_type_info(ctx.error());
+ if (ctx.has_error()) {
+ return CustomType{};
+ }
+ if (!type_info) {
+ ctx.set_error(Error::type_error("TypeInfo for CustomType not found"));
+ return CustomType{};
+ }
+ }
+ return read_data(ctx);
+ }
+
+ static CustomType read_data(ReadContext &ctx) {
+ CustomType value;
+ value.value = Serializer<int32_t>::read_data(ctx);
+ value.name = Serializer<std::string>::read_data(ctx);
+ return value;
+ }
+
+ static CustomType read_data_generic(ReadContext &ctx, bool has_generics) {
+ (void)has_generics;
+ return read_data(ctx);
+ }
+
+ static CustomType read_with_type_info(ReadContext &ctx, RefMode ref_mode,
+ const TypeInfo &type_info) {
+ (void)type_info;
+ return read(ctx, ref_mode, false);
+ }
+};
+
+} // namespace serialization
+} // namespace fory
+
+int main() {
+ auto fory = Fory::builder().xlang(true).build();
+ fory.register_extension_type<CustomType>(100);
+
+ CustomType original{42, "test"};
+
+ auto serialized = fory.serialize(original);
+ if (!serialized.ok()) {
+ std::cerr << "Serialization failed" << std::endl;
+ return 1;
+ }
+
+ auto deserialized = fory.deserialize<CustomType>(serialized.value());
+ if (!deserialized.ok()) {
+ std::cerr << "Deserialization failed" << std::endl;
+ return 1;
+ }
+
+ assert(original == deserialized.value());
+ std::cout << "Custom serializer works!" << std::endl;
+ return 0;
+}
+```
+
+## WriteContext Methods
+
+The `WriteContext` provides methods for writing data:
+
+```cpp
+// Primitive types
+ctx.write_uint8(value);
+ctx.write_int8(value);
+ctx.write_uint16(value);
+
+// Variable-length integers (compact encoding)
+ctx.write_var_uint32(value); // Unsigned varint
+ctx.write_varint32(value); // Signed zigzag varint
+ctx.write_var_uint64(value); // Unsigned varint
+ctx.write_varint64(value); // Signed zigzag varint
+
+// Tagged integers (for mixed-size encoding)
+ctx.write_tagged_uint64(value);
+ctx.write_tagged_int64(value);
+
+// Raw bytes
+ctx.write_bytes(data_ptr, length);
+
+// Access underlying buffer for advanced operations
+ctx.buffer().write_int32(value);
+ctx.buffer().write_float(value);
+ctx.buffer().write_double(value);
+```
+
+## ReadContext Methods
+
+The `ReadContext` provides methods for reading data:
+
+```cpp
+// Primitive types (use error reference pattern)
+uint8_t u8 = ctx.read_uint8(ctx.error());
+int8_t i8 = ctx.read_int8(ctx.error());
+
+// Variable-length integers
+uint32_t u32 = ctx.read_var_uint32(ctx.error());
+int32_t i32 = ctx.read_varint32(ctx.error());
+uint64_t u64 = ctx.read_var_uint64(ctx.error());
+int64_t i64 = ctx.read_varint64(ctx.error());
+
+// Check for errors after read operations
+if (ctx.has_error()) {
+ return MyType{}; // Return default on error
+}
+
+// Access underlying buffer for advanced operations
+int32_t value = ctx.buffer().read_int32(ctx.error());
+float f = ctx.buffer().read_float(ctx.error());
+double d = ctx.buffer().read_double(ctx.error());
+```
+
+## Delegating to Built-in Serializers
+
+Reuse existing serializers for nested types:
+
+```cpp
+static void write_data(const MyType &value, WriteContext &ctx) {
+ // Delegate to built-in serializers
+ Serializer<int32_t>::write_data(value.int_field, ctx);
+ Serializer<std::string>::write_data(value.string_field, ctx);
+ Serializer<std::vector<int32_t>>::write_data(value.vec_field, ctx);
+}
+
+static MyType read_data(ReadContext &ctx) {
+ MyType value;
+ value.int_field = Serializer<int32_t>::read_data(ctx);
+ value.string_field = Serializer<std::string>::read_data(ctx);
+ value.vec_field = Serializer<std::vector<int32_t>>::read_data(ctx);
+ return value;
+}
+```
+
+## Best Practices
+
+1. **Use variable-length encoding** for integers that may be small
+2. **Check errors after read operations** using `ctx.has_error()`
+3. **Return default values on error** to maintain consistent behavior
+4. **Delegate to built-in serializers** for standard types
+5. **Match type IDs across languages** for cross-language compatibility
+6. **Use `(void)param`** to suppress unused parameter warnings
+
+## Related Topics
+
+- [Type Registration](type_registration) - Registering serializers
+- [Basic Serialization](basic_serialization) - Using FORY_STRUCT macro
+- [Schema Evolution](schema_evolution) - Compatible mode
+- [Cross-Language](cross_language) - Cross-language serialization
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/cpp/field-configuration.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/cpp/field-configuration.md
new file mode 100644
index 000000000..4dd404c29
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/cpp/field-configuration.md
@@ -0,0 +1,504 @@
+---
+title: 字段配置
+sidebar_position: 5
+id: field_configuration
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页说明如何在 C++ 中配置序列化字段级元信息。
+
+## 概述
+
+Apache Fory™ 在编译期提供两种字段元信息配置方式：
+
+1. **`fory::field<>` 模板**：在 struct 定义中内联声明元信息
+2. **`FORY_FIELD_TAGS` 宏**：在 struct 外部附加元信息（非侵入）
+
+这些机制可用于：
+
+- **Tag ID**：为 schema 演进分配紧凑数值 ID
+- **可空控制**：将指针字段标记为可空
+- **引用跟踪**：为共享指针启用引用跟踪
+
+## `fory::field` 模板
+
+```cpp
+template <typename T, int16_t Id, typename... Options>
+class field;
+```
+
+### 模板参数
+
+| 参数 | 说明 |
+| --------- | ------------------------------------------ |
+| `T` | 底层字段类型 |
+| `Id` | 字段 tag ID（`int16_t`），用于紧凑序列化 |
+| `Options` | 可选标签：`fory::nullable`、`fory::ref` 等 |
+
+### 基本用法
+
+```cpp
+#include "fory/serialization/fory.h"
+
+using namespace fory::serialization;
+
+struct Person {
+ fory::field<std::string, 0> name;
+ fory::field<int32_t, 1> age;
+ fory::field<std::optional<std::string>, 2> nickname;
+};
+FORY_STRUCT(Person, name, age, nickname);
+```
+
+`fory::field<>` 是透明包装，可像底层类型一样使用：
+
+```cpp
+Person person;
+person.name = "Alice"; // Direct assignment
+person.age = 30;
+std::string n = person.name; // Implicit conversion
+int a = person.age.get(); // Explicit get()
+```
+
+## 标签类型
+
+### `fory::nullable`
+
+将智能指针字段标记为可空（可为 `nullptr`）：
+
+```cpp
+struct Node {
+ fory::field<std::string, 0> name;
+ fory::field<std::shared_ptr<Node>, 1, fory::nullable> next; // Can be nullptr
+};
+FORY_STRUCT(Node, name, next);
+```
+
+**适用类型：** `std::shared_ptr<T>`、`std::unique_ptr<T>`
+
+**说明：** 对原生值类型或字符串的可空语义，请使用 `std::optional<T>`：
+
+```cpp
+// Correct: use std::optional for nullable primitives
+fory::field<std::optional<int32_t>, 0> optional_value;
+
+// Wrong: nullable is not allowed for primitives
+// fory::field<int32_t, 0, fory::nullable> value; // Compile error!
+```
+
+### `fory::not_null`
+
+显式声明指针字段不可空。虽然这是智能指针的默认行为，但可用于增强可读性：
+
+```cpp
+fory::field<std::shared_ptr<Data>, 0, fory::not_null> data; // Must not be nullptr
+```
+
+**适用类型：** `std::shared_ptr<T>`、`std::unique_ptr<T>`
+
+### `fory::ref`
+
+为共享指针字段启用引用跟踪。多个字段引用同一对象时，仅序列化一次并保持共享关系：
+
+```cpp
+struct Graph {
+ fory::field<std::string, 0> name;
+ fory::field<std::shared_ptr<Graph>, 1, fory::ref> left; // Ref tracked
+ fory::field<std::shared_ptr<Graph>, 2, fory::ref> right; // Ref tracked
+};
+FORY_STRUCT(Graph, name, left, right);
+```
+
+**适用类型：** 仅 `std::shared_ptr<T>`（需要共享所有权）
+
+### 组合标签
+
+共享指针可组合多个标签：
+
+```cpp
+// Nullable + ref tracking
+fory::field<std::shared_ptr<Node>, 0, fory::nullable, fory::ref> link;
+```
+
+## 类型规则
+
+| 类型 | 可用选项 | 可空语义 |
+| -------------------- | ----------------- | --------------------------------- |
+| 原生类型、字符串 | 无 | 若需可空请使用 `std::optional<T>` |
+| `std::optional<T>` | 无 | 天然可空 |
+| `std::shared_ptr<T>` | `nullable`、`ref` | 默认不可空 |
+| `std::unique_ptr<T>` | `nullable` | 默认不可空 |
+
+## 完整示例
+
+```cpp
+#include "fory/serialization/fory.h"
+
+using namespace fory::serialization;
+
+// Define a struct with various field configurations
+struct Document {
+ // Required fields (non-nullable)
+ fory::field<std::string, 0> title;
+ fory::field<int32_t, 1> version;
+
+ // Optional primitive using std::optional
+ fory::field<std::optional<std::string>, 2> description;
+
+ // Nullable pointer
+ fory::field<std::unique_ptr<std::string>, 3, fory::nullable> metadata;
+
+ // Reference-tracked shared pointer
+ fory::field<std::shared_ptr<Document>, 4, fory::ref> parent;
+
+ // Nullable + reference-tracked
+ fory::field<std::shared_ptr<Document>, 5, fory::nullable, fory::ref> related;
+};
+FORY_STRUCT(Document, title, version, description, metadata, parent, related);
+
+int main() {
+ auto fory = Fory::builder().xlang(true).build();
+ fory.register_struct<Document>(100);
+
+ Document doc;
+ doc.title = "My Document";
+ doc.version = 1;
+ doc.description = "A sample document";
+ doc.metadata = nullptr; // Allowed because nullable
+ doc.parent = std::make_shared<Document>();
+ doc.parent->title = "Parent Doc";
+ doc.related = nullptr; // Allowed because nullable
+
+ auto bytes = fory.serialize(doc).value();
+ auto decoded = fory.deserialize<Document>(bytes).value();
+}
+```
+
+## 编译期校验
+
+非法配置会在编译期报错：
+
+```cpp
+// Error: nullable and not_null are mutually exclusive
+fory::field<std::shared_ptr<int>, 0, fory::nullable, fory::not_null> bad1;
+
+// Error: nullable only valid for smart pointers
+fory::field<int32_t, 0, fory::nullable> bad2;
+
+// Error: ref only valid for shared_ptr
+fory::field<std::unique_ptr<int>, 0, fory::ref> bad3;
+
+// Error: options not allowed for std::optional (inherently nullable)
+fory::field<std::optional<int>, 0, fory::nullable> bad4;
+```
+
+## 向后兼容
+
+未使用 `fory::field<>` 包装的旧 struct 仍可正常工作：
+
+```cpp
+// Old style - still works
+struct LegacyPerson {
+ std::string name;
+ int32_t age;
+};
+FORY_STRUCT(LegacyPerson, name, age);
+
+// New style with field metadata
+struct ModernPerson {
+ fory::field<std::string, 0> name;
+ fory::field<int32_t, 1> age;
+};
+FORY_STRUCT(ModernPerson, name, age);
+```
+
+## `FORY_FIELD_TAGS` 宏
+
+`FORY_FIELD_TAGS` 提供了一种非侵入式方案：无需修改 struct 定义即可附加字段元信息。适用场景：
+
+- **第三方类型**：为非自有类型添加元信息
+- **纯净结构定义**：保持 struct 仅包含标准 C++ 类型
+- **依赖隔离**：将 Fory 头文件限制在序列化配置文件中
+
+### 用法
+
+```cpp
+// user_types.h - NO fory headers needed!
+struct Document {
+ std::string title;
+ int32_t version;
+ std::optional<std::string> description;
+ std::shared_ptr<User> author;
+ std::shared_ptr<User> reviewer;
+ std::shared_ptr<Document> parent;
+ std::unique_ptr<Data> data;
+};
+
+// serialization_config.cpp - fory config isolated here
+#include "fory/serialization/fory.h"
+#include "user_types.h"
+
+FORY_STRUCT(Document, title, version, description, author, reviewer, parent, data)
+
+FORY_FIELD_TAGS(Document,
+ (title, 0), // string: non-nullable
+ (version, 1), // int: non-nullable
+ (description, 2), // optional: inherently nullable
+ (author, 3), // shared_ptr: non-nullable (default)
+ (reviewer, 4, nullable), // shared_ptr: nullable
+ (parent, 5, ref), // shared_ptr: non-nullable, with ref tracking
+ (data, 6, nullable) // unique_ptr: nullable
+)
+```
+
+### `FORY_FIELD_TAGS` 选项
+
+| 字段类型 | 合法组合 |
+| -------------------- | ---------------------------------------------------------------------------------------- |
+| 原生类型、字符串 | 仅 `(field, id)` |
+| `std::optional<T>` | 仅 `(field, id)` |
+| `std::shared_ptr<T>` | `(field, id)`、`(field, id, nullable)`、`(field, id, ref)`、`(field, id, nullable, ref)` |
+| `std::unique_ptr<T>` | `(field, id)`、`(field, id, nullable)` |
+
+### API 对比
+
+| 维度 | `fory::field<>` 包装 | `FORY_FIELD_TAGS` 宏 |
+| -------------- | ------------------------ | ---------------------- |
+| **结构定义** | 需要改动（包装字段类型） | 无需改动（保持纯 C++） |
+| **IDE 体验** | 有模板噪音 | 更清晰（原生字段类型） |
+| **第三方类型** | 不支持 | 支持 |
+| **头文件依赖** | 各处都需要 | 可集中在配置文件 |
+| **迁移成本** | 高（修改全部字段） | 低（新增一个宏） |
+
+## `FORY_FIELD_CONFIG` 宏
+
+`FORY_FIELD_CONFIG` 是更强、更灵活的字段配置方式，提供：
+
+- **Builder 风格 API**：链式配置 `F(id).option1().option2()`
+- **编码控制**：指定无符号整数编码（varint、fixed、tagged）
+- **编译期校验**：通过成员指针校验字段名
+- **跨语言兼容**：按 Java、Rust 等语言期望配置编码
+
+### 基本语法
+
+```cpp
+FORY_FIELD_CONFIG(StructType,
+ (field1, fory::F(0)), // Simple: just ID
+ (field2, fory::F(1).nullable()), // With nullable
+ (field3, fory::F(2).varint()), // With encoding
+ (field4, fory::F(3).nullable().ref()), // Multiple options
+ (field5, 4) // Backward compatible: integer ID
+);
+```
+
+### `F()` Builder
+
+`fory::F(id)` 工厂函数会创建支持链式调用的 `FieldMeta` 对象：
+
+```cpp
+fory::F(0) // Create with field ID 0
+ .nullable() // Mark as nullable
+ .ref() // Enable reference tracking
+ .varint() // Use variable-length encoding
+ .fixed() // Use fixed-size encoding
+ .tagged() // Use tagged encoding
+ .monomorphic() // Mark as monomorphic type
+ .compress(false) // Disable compression
+```
+
+**提示：** 若希望省略 `fory::` 前缀，可添加 `using` 声明：
+
+```cpp
+using fory::F;
+
+FORY_FIELD_CONFIG(MyStruct,
+ (field1, F(0).varint()), // No prefix needed
+ (field2, F(1).nullable())
+);
+```
+
+### 无符号整数编码选项
+
+对于 `uint32_t` 与 `uint64_t` 字段，可显式指定线格式编码：
+
+| 方法 | Type ID | 说明 | 适用场景 |
+| ----------- | ------------- | --------------------------------- | ------------------------ |
+| `.varint()` | VAR_UINT32/64 | 变长编码（1-5 或 1-10 字节） | 数值通常较小 |
+| `.fixed()` | UINT32/64 | 定长编码（固定 4 或 8 字节） | 数值分布较均匀 |
+| `.tagged()` | TAGGED_UINT64 | 带大小提示的混合编码（仅 uint64） | 小值与大值混合（uint64） |
+
+**说明：** `uint8_t` 与 `uint16_t` 始终使用定长编码（UINT8、UINT16）。
+
+### 完整示例
+
+```cpp
+#include "fory/serialization/fory.h"
+
+using namespace fory::serialization;
+
+// Define struct with unsigned integer fields
+struct MetricsData {
+ // Counters - often small values, use varint for space efficiency
+ uint32_t requestCount;
+ uint64_t bytesSent;
+
+ // IDs - uniformly distributed, use fixed for consistent performance
+ uint32_t userId;
+ uint64_t sessionId;
+
+ // Timestamps - use tagged encoding for mixed value ranges
+ uint64_t createdAt;
+
+ // Nullable fields
+ std::optional<uint32_t> errorCount;
+ std::optional<uint64_t> lastAccessTime;
+};
+
+FORY_STRUCT(MetricsData, requestCount, bytesSent, userId, sessionId,
+ createdAt, errorCount, lastAccessTime);
+
+// Configure field encoding
+FORY_FIELD_CONFIG(MetricsData,
+ // Small counters - varint saves space
+ (requestCount, fory::F(0).varint()),
+ (bytesSent, fory::F(1).varint()),
+
+ // IDs - fixed for consistent performance
+ (userId, fory::F(2).fixed()),
+ (sessionId, fory::F(3).fixed()),
+
+ // Timestamp - tagged encoding
+ (createdAt, fory::F(4).tagged()),
+
+ // Nullable fields
+ (errorCount, fory::F(5).nullable().varint()),
+ (lastAccessTime, fory::F(6).nullable().tagged())
+);
+
+int main() {
+ auto fory = Fory::builder().xlang(true).build();
+ fory.register_struct<MetricsData>(100);
+
+ MetricsData data{
+ .requestCount = 42,
+ .bytesSent = 1024,
+ .userId = 12345678,
+ .sessionId = 9876543210,
+ .createdAt = 1704067200000000000ULL, // 2024-01-01 in nanoseconds
+ .errorCount = 3,
+ .lastAccessTime = std::nullopt
+ };
+
+ auto bytes = fory.serialize(data).value();
+ auto decoded = fory.deserialize<MetricsData>(bytes).value();
+}
+```
+
+### 跨语言兼容
+
+当序列化数据会被其他语言读取时，建议通过 `FORY_FIELD_CONFIG` 显式匹配目标语言编码约定。
+
+**Java 兼容示例：**
+
+```cpp
+// Java uses these type IDs for unsigned integers:
+// - Byte (u8): UINT8 (fixed)
+// - Short (u16): UINT16 (fixed)
+// - Integer (u32): VAR_UINT32 (varint) or UINT32 (fixed)
+// - Long (u64): VAR_UINT64 (varint), UINT64 (fixed), or TAGGED_UINT64
+
+struct JavaCompatible {
+ uint8_t byteField; // Maps to Java Byte
+ uint16_t shortField; // Maps to Java Short
+ uint32_t intVarField; // Maps to Java Integer with varint
+ uint32_t intFixedField; // Maps to Java Integer with fixed
+ uint64_t longVarField; // Maps to Java Long with varint
+ uint64_t longTagged; // Maps to Java Long with tagged
+};
+
+FORY_STRUCT(JavaCompatible, byteField, shortField, intVarField,
+ intFixedField, longVarField, longTagged);
+
+FORY_FIELD_CONFIG(JavaCompatible,
+ (byteField, fory::F(0)), // UINT8 (auto)
+ (shortField, fory::F(1)), // UINT16 (auto)
+ (intVarField, fory::F(2).varint()), // VAR_UINT32
+ (intFixedField, fory::F(3).fixed()), // UINT32
+ (longVarField, fory::F(4).varint()), // VAR_UINT64
+ (longTagged, fory::F(5).tagged()) // TAGGED_UINT64
+);
+```
+
+### 使用 `FORY_FIELD_CONFIG` 做 Schema 演进
+
+在兼容模式下，发送端和接收端可以对字段使用不同可空策略：
+
+```cpp
+// Version 1: All fields non-nullable
+struct DataV1 {
+ uint32_t id;
+ uint64_t timestamp;
+};
+FORY_STRUCT(DataV1, id, timestamp);
+FORY_FIELD_CONFIG(DataV1,
+ (id, fory::F(0).varint()),
+ (timestamp, fory::F(1).tagged())
+);
+
+// Version 2: Added nullable fields
+struct DataV2 {
+ uint32_t id;
+ uint64_t timestamp;
+ std::optional<uint32_t> version; // New nullable field
+};
+FORY_STRUCT(DataV2, id, timestamp, version);
+FORY_FIELD_CONFIG(DataV2,
+ (id, fory::F(0).varint()),
+ (timestamp, fory::F(1).tagged()),
+ (version, fory::F(2).nullable().varint()) // New field with nullable
+);
+```
+
+### `FORY_FIELD_CONFIG` 选项速查
+
+| 方法 | 说明 | 适用范围 |
+| ---------------- | ------------------------ | ---------------------- |
+| `.nullable()` | 将字段标记为可空 | 智能指针、可空值类型 |
+| `.ref()` | 启用引用跟踪 | 仅 `std::shared_ptr` |
+| `.monomorphic()` | 标记指针始终指向单一类型 | 智能指针 |
+| `.varint()` | 变长编码 | `uint32_t`、`uint64_t` |
+| `.fixed()` | 定长编码 | `uint32_t`、`uint64_t` |
+| `.tagged()` | tagged 混合编码 | 仅 `uint64_t` |
+| `.compress(v)` | 启用/禁用字段压缩 | 所有类型 |
+
+### 字段配置方案对比
+
+| 特性 | `fory::field<>` | `FORY_FIELD_TAGS` | `FORY_FIELD_CONFIG` |
+| ------------------- | ------------------ | ----------------- | ------------------------- |
+| **需要修改 struct** | 是（包装字段类型） | 否 | 否 |
+| **编码控制** | 否 | 否 | 是（varint/fixed/tagged） |
+| **Builder 风格** | 否 | 否 | 是 |
+| **编译期校验** | 是 | 有限 | 是（成员指针校验） |
+| **跨语言兼容能力** | 有限 | 有限 | 完整 |
+| **推荐场景** | 简单结构体 | 第三方类型 | 复杂/跨语言结构体 |
+
+## 相关主题
+
+- [类型注册](type-registration.md) - 使用 FORY_STRUCT 注册类型
+- [Schema 演进](schema-evolution.md) - 基于 tag ID 的演进策略
+- [配置](configuration.md) - 全局启用引用跟踪等选项
+- [跨语言](cross-language.md) - 与 Java、Rust、Python 的互操作
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/cpp/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/cpp/index.md
new file mode 100644
index 000000000..12049c1a8
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/cpp/index.md
@@ -0,0 +1,264 @@
+---
+title: C++ 序列化指南
+sidebar_position: 0
+id: serialization_index
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+**Apache Fory™** 是一个高性能的多语言序列化框架，基于 **JIT 编译**与**零拷贝**技术，在保持易用性和安全性的同时提供出色性能。
+
+C++ 实现基于现代 C++17 特性和模板元编程，提供具备编译时类型安全的高性能序列化能力。
+
+## 为什么选择 Apache Fory™ C++？
+
+- **高性能**：快速序列化与优化的二进制协议
+- **跨语言**：可在 Java、Python、C++、Go、JavaScript 和 Rust 之间无缝序列化与反序列化数据
+- **类型安全**：通过基于宏的结构体注册实现编译时类型检查
+- **引用跟踪**：自动跟踪共享引用和循环引用
+- **Schema 演进**：兼容模式支持独立的 Schema 变更
+- **双格式支持**：对象图序列化与零拷贝行格式
+- **线程安全**：同时提供单线程（最快）和线程安全两种变体
+
+## 安装
+
+C++ 实现同时支持 CMake 和 Bazel 构建系统。
+
+### 前置条件
+
+- CMake 3.16+（用于 CMake 构建）或 Bazel 8+（用于 Bazel 构建）
+- 支持 C++17 的编译器（GCC 7+、Clang 5+、MSVC 2017+）
+
+### 使用 CMake（推荐）
+
+最简单的集成方式是使用 CMake 的 `FetchContent` 模块：
+
+```cmake
+cmake_minimum_required(VERSION 3.16)
+project(my_project LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+if(MSVC)
+ add_compile_options(/Zc:preprocessor)
+endif()
+include(FetchContent)
+FetchContent_Declare(
+ fory
+ GIT_REPOSITORY https://github.com/apache/fory.git
+ GIT_TAG v0.17.0
+ SOURCE_SUBDIR cpp
+)
+FetchContent_MakeAvailable(fory)
+
+add_executable(my_app main.cc)
+target_link_libraries(my_app PRIVATE fory::serialization)
+```
+
+然后构建并运行：
+
+```bash
+mkdir build && cd build
+cmake .. -DCMAKE_BUILD_TYPE=Release
+cmake --build . --parallel
+./my_app
+```
+
+### 使用 Bazel
+
+在项目根目录创建 `MODULE.bazel` 文件：
+
+```bazel
+module(
+ name = "my_project",
+ version = "1.0.0",
+)
+
+bazel_dep(name = "rules_cc", version = "0.1.1")
+
+bazel_dep(name = "fory", version = "0.17.0")
+git_override(
+ module_name = "fory",
+ remote = "https://github.com/apache/fory.git",
+ commit = "v0.17.0", # 或使用特定 commit hash 以确保可复现性
+)
+```
+
+为应用程序创建 `BUILD` 文件：
+
+```bazel
+cc_binary(
+ name = "my_app",
+ srcs = ["main.cc"],
+ deps = ["@fory//cpp/fory/serialization:fory_serialization"],
+)
+```
+
+然后构建并运行：
+
+```bash
+bazel build //:my_app
+bazel run //:my_app
+```
+
+对于本地开发，也可以改用 `local_path_override`：
+
+```bazel
+bazel_dep(name = "fory", version = "0.17.0")
+local_path_override(
+ module_name = "fory",
+ path = "/path/to/fory",
+)
+```
+
+### 示例
+
+完整可运行示例请参见 [examples/cpp](https://github.com/apache/fory/tree/main/examples/cpp) 目录：
+
+- [hello_world](https://github.com/apache/fory/tree/main/examples/cpp/hello_world) - 对象图序列化
+- [hello_row](https://github.com/apache/fory/tree/main/examples/cpp/hello_row) - 行格式编码
+
+## 快速开始
+
+### 基础示例
+
+```cpp
+#include "fory/serialization/fory.h"
+#include <string>
+#include <vector>
+
+using namespace fory::serialization;
+
+// 定义结构体
+struct Person {
+ std::string name;
+ int32_t age;
+ std::vector<std::string> hobbies;
+
+ bool operator==(const Person &other) const {
+ return name == other.name && age == other.age && hobbies == other.hobbies;
+ }
+};
+FORY_STRUCT(Person, name, age, hobbies);
+
+int main() {
+ // 创建 Fory 实例
+ auto fory = Fory::builder()
+ .xlang(true) // 启用跨语言模式
+ .track_ref(false) // 对简单类型禁用引用跟踪
+ .build();
+
+ // 为类型注册唯一 ID
+ fory.register_struct<Person>(1);
+
+ // 创建对象
+ Person person{"Alice", 30, {"reading", "coding"}};
+
+ // 序列化
+ auto result = fory.serialize(person);
+ if (!result.ok()) {
+ // 处理错误
+ return 1;
+ }
+ std::vector<uint8_t> bytes = std::move(result).value();
+
+ // 反序列化
+ auto deser_result = fory.deserialize<Person>(bytes);
+ if (!deser_result.ok()) {
+ // 处理错误
+ return 1;
+ }
+ Person decoded = std::move(deser_result).value();
+
+ assert(person == decoded);
+ return 0;
+}
+```
+
+### 继承字段
+
+如果希望派生类型包含基类字段，请在 `FORY_STRUCT` 中写入 `FORY_BASE(Base)`。基类本身也必须定义自己的 `FORY_STRUCT`，这样其字段才能被引用。
+
+```cpp
+struct Base {
+ int32_t id;
+ FORY_STRUCT(Base, id);
+};
+
+struct Derived : Base {
+ std::string name;
+ FORY_STRUCT(Derived, FORY_BASE(Base), name);
+};
+```
+
+## 线程安全
+
+Apache Fory™ C++ 面向不同线程需求提供两种变体：
+
+### 单线程（最快）
+
+```cpp
+// 单线程 Fory：速度最快，但不是线程安全的
+auto fory = Fory::builder()
+ .xlang(true)
+ .build();
+```
+
+### 线程安全
+
+```cpp
+// 线程安全 Fory：使用上下文池
+auto fory = Fory::builder()
+ .xlang(true)
+ .build_thread_safe();
+
+// 可安全用于多线程
+std::thread t1([&]() {
+ auto result = fory.serialize(obj1);
+});
+std::thread t2([&]() {
+ auto result = fory.serialize(obj2);
+});
+```
+
+**提示：** 请在启动线程之前完成类型注册，以确保每个工作线程都能看到一致的元数据。
+
+## 使用场景
+
+### 对象序列化
+
+- 含嵌套对象和引用的复杂数据结构
+- 微服务中的跨语言通信
+- 具备完整类型安全的通用序列化
+- 使用兼容模式进行 Schema 演进
+
+### 行格式序列化
+
+- 高吞吐数据处理
+- 需要快速字段访问的分析型负载
+- 内存受限环境
+- 零拷贝场景
+
+## 后续步骤
+
+- [配置](configuration.md) - 构建器选项与模式
+- [基础序列化](basic-serialization.md) - 对象图序列化
+- [Schema 演进](schema-evolution.md) - 兼容模式与 Schema 变更
+- [类型注册](type-registration.md) - 注册类型
+- [字段配置](field-configuration.md) - 字段级元数据（可空、引用跟踪）
+- [支持的类型](supported-types.md) - 全部支持的类型
+- [跨语言](cross-language.md) - XLANG 模式
+- [行格式](row-format.md) - 零拷贝行格式
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/cpp/polymorphism.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/cpp/polymorphism.md
new file mode 100644
index 000000000..d083d8c4a
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/cpp/polymorphism.md
@@ -0,0 +1,480 @@
+---
+title: 多态序列化
+sidebar_position: 5
+id: polymorphism
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Apache Fory™ 通过智能指针（`std::shared_ptr` 与 `std::unique_ptr`）支持多态序列化，为继承体系提供动态分派与类型灵活性。
+
+## 支持的多态类型
+
+- `std::shared_ptr<Base>` - Shared ownership with polymorphic dispatch
+- `std::unique_ptr<Base>` - Exclusive ownership with polymorphic dispatch
+- Collections: `std::vector<std::shared_ptr<Base>>`, `std::map<K, std::unique_ptr<Base>>`
+- Optional: `std::optional<std::shared_ptr<Base>>`
+
+## 基础多态序列化
+
+```cpp
+#include "fory/serialization/fory.h"
+
+using namespace fory::serialization;
+
+// Define base class with virtual methods
+struct Animal {
+ virtual ~Animal() = default;
+ virtual std::string speak() const = 0;
+ int32_t age = 0;
+};
+FORY_STRUCT(Animal, age);
+
+// Define derived classes
+struct Dog : Animal {
+ std::string speak() const override { return "Woof!"; }
+ std::string breed;
+};
+FORY_STRUCT(Dog, age, breed);
+
+struct Cat : Animal {
+ std::string speak() const override { return "Meow!"; }
+ std::string color;
+};
+FORY_STRUCT(Cat, age, color);
+
+// Struct with polymorphic field
+struct Zoo {
+ std::shared_ptr<Animal> star_animal;
+};
+FORY_STRUCT(Zoo, star_animal);
+
+int main() {
+ auto fory = Fory::builder().track_ref(true).build();
+
+ // Register all types with unique type IDs
+ fory.register_struct<Zoo>(100);
+ fory.register_struct<Dog>(101);
+ fory.register_struct<Cat>(102);
+
+ // Create object with polymorphic field
+ Zoo zoo;
+ zoo.star_animal = std::make_shared<Dog>();
+ zoo.star_animal->age = 3;
+ static_cast<Dog*>(zoo.star_animal.get())->breed = "Labrador";
+
+ // Serialize
+ auto bytes_result = fory.serialize(zoo);
+ assert(bytes_result.ok());
+
+ // Deserialize - runtime type is preserved
+ auto decoded_result = fory.deserialize<Zoo>(bytes_result.value());
+ assert(decoded_result.ok());
+
+ auto decoded = std::move(decoded_result).value();
+ assert(decoded.star_animal->speak() == "Woof!");
+ assert(decoded.star_animal->age == 3);
+
+ auto* dog_ptr = dynamic_cast<Dog*>(decoded.star_animal.get());
+ assert(dog_ptr != nullptr);
+ assert(dog_ptr->breed == "Labrador");
+}
+```
+
+## Type Registration for Polymorphism
+
+For polymorphic serialization, register derived types with unique type IDs:
+
+```cpp
+// Register with numeric type ID
+fory.register_struct<Derived1>(100);
+fory.register_struct<Derived2>(101);
+```
+
+**Why type ID registration?**
+
+- Compact binary representation
+- Fast type lookup and dispatch
+- Consistent with non-polymorphic type registration
+
+## Automatic Polymorphism Detection
+
+Fory automatically detects polymorphic types using `std::is_polymorphic<T>`:
+
+```cpp
+struct Base {
+ virtual ~Base() = default; // Virtual destructor makes it polymorphic
+ int32_t value = 0;
+};
+
+struct NonPolymorphic {
+ int32_t value = 0; // No virtual methods
+};
+
+// Polymorphic field - type info written automatically
+struct Container1 {
+ std::shared_ptr<Base> ptr; // Auto-detected as polymorphic
+};
+
+// Non-polymorphic field - no type info written
+struct Container2 {
+ std::shared_ptr<NonPolymorphic> ptr; // Not polymorphic
+};
+```
+
+## Controlling Dynamic Dispatch
+
+Use `fory::dynamic<V>` to override automatic polymorphism detection:
+
+```cpp
+struct Animal {
+ virtual ~Animal() = default;
+ virtual std::string speak() const = 0;
+};
+
+struct Pet {
+ // Auto-detected: type info written (Animal has virtual methods)
+ std::shared_ptr<Animal> animal1;
+
+ // Force dynamic: type info written explicitly
+ fory::field<std::shared_ptr<Animal>, 0, fory::dynamic<true>> animal2;
+
+ // Force non-dynamic: skip type info (faster but no runtime subtyping)
+ fory::field<std::shared_ptr<Animal>, 1, fory::dynamic<false>> animal3;
+};
+FORY_STRUCT(Pet, animal1, animal2, animal3);
+```
+
+**When to use `fory::dynamic<false>`:**
+
+- You know the runtime type will always match the declared type
+- Performance is critical and you don't need subtype support
+- Working with monomorphic data despite having a polymorphic base class
+
+### Field Configuration Without Wrapper Types
+
+Use `FORY_FIELD_CONFIG` to configure fields without `fory::field<>` wrapper:
+
+```cpp
+struct Zoo {
+ std::shared_ptr<Animal> star; // Auto-detected as polymorphic
+ std::shared_ptr<Animal> backup; // Nullable polymorphic field
+ std::shared_ptr<Animal> mascot; // Non-dynamic (no subtype dispatch)
+};
+FORY_STRUCT(Zoo, star, backup, mascot);
+
+// Configure fields with tag IDs and options
+FORY_FIELD_CONFIG(Zoo,
+ (star, fory::F(0)), // Tag ID 0, default options
+ (backup, fory::F(1).nullable()), // Tag ID 1, allow nullptr
+ (mascot, fory::F(2).dynamic(false)) // Tag ID 2, disable polymorphism
+);
+```
+
+See [Field Configuration](field_configuration) for complete details on `fory::nullable`, `fory::ref`, and other field-level options
+
+## std::unique_ptr Polymorphism
+
+`std::unique_ptr` works the same way as `std::shared_ptr` for polymorphic types:
+
+```cpp
+struct Container {
+ std::unique_ptr<Animal> pet;
+};
+FORY_STRUCT(Container, pet);
+
+auto fory = Fory::builder().track_ref(true).build();
+fory.register_struct<Container>(200);
+fory.register_struct<Dog>(201);
+
+Container container;
+container.pet = std::make_unique<Dog>();
+static_cast<Dog*>(container.pet.get())->breed = "Beagle";
+
+auto bytes = fory.serialize(container).value();
+auto decoded = fory.deserialize<Container>(bytes).value();
+
+// Runtime type preserved
+auto* dog = dynamic_cast<Dog*>(decoded.pet.get());
+assert(dog != nullptr);
+assert(dog->breed == "Beagle");
+```
+
+## Collections of Polymorphic Objects
+
+```cpp
+#include <vector>
+#include <map>
+
+struct AnimalShelter {
+ std::vector<std::shared_ptr<Animal>> animals;
+ std::map<std::string, std::unique_ptr<Animal>> registry;
+};
+FORY_STRUCT(AnimalShelter, animals, registry);
+
+auto fory = Fory::builder().track_ref(true).build();
+fory.register_struct<AnimalShelter>(100);
+fory.register_struct<Dog>(101);
+fory.register_struct<Cat>(102);
+
+AnimalShelter shelter;
+shelter.animals.push_back(std::make_shared<Dog>());
+shelter.animals.push_back(std::make_shared<Cat>());
+shelter.registry["pet1"] = std::make_unique<Dog>();
+
+auto bytes = fory.serialize(shelter).value();
+auto decoded = fory.deserialize<AnimalShelter>(bytes).value();
+
+// All runtime types preserved
+assert(dynamic_cast<Dog*>(decoded.animals[0].get()) != nullptr);
+assert(dynamic_cast<Cat*>(decoded.animals[1].get()) != nullptr);
+assert(dynamic_cast<Dog*>(decoded.registry["pet1"].get()) != nullptr);
+```
+
+## Reference Tracking
+
+Reference tracking for `std::shared_ptr` works the same with polymorphic types.
+See [Supported Types](supported_types) for details and examples.
+
+## Nested Polymorphism Depth Limit
+
+To prevent stack overflow from deeply nested polymorphic structures, Fory limits the maximum dynamic nesting depth:
+
+```cpp
+struct Container {
+ virtual ~Container() = default;
+ int32_t value = 0;
+ std::shared_ptr<Container> nested;
+};
+FORY_STRUCT(Container, value, nested);
+
+// Default max_dyn_depth is 5
+auto fory1 = Fory::builder().build();
+assert(fory1.config().max_dyn_depth == 5);
+
+// Increase limit for deeper nesting
+auto fory2 = Fory::builder().max_dyn_depth(10).build();
+fory2.register_struct<Container>(1);
+
+// Create deeply nested structure
+auto level3 = std::make_shared<Container>();
+level3->value = 3;
+
+auto level2 = std::make_shared<Container>();
+level2->value = 2;
+level2->nested = level3;
+
+auto level1 = std::make_shared<Container>();
+level1->value = 1;
+level1->nested = level2;
+
+// Serialization succeeds
+auto bytes = fory2.serialize(level1).value();
+
+// Deserialization succeeds with sufficient depth
+auto decoded = fory2.deserialize<std::shared_ptr<Container>>(bytes).value();
+```
+
+**Depth exceeded error:**
+
+```cpp
+auto fory_shallow = Fory::builder().max_dyn_depth(2).build();
+fory_shallow.register_struct<Container>(1);
+
+// 3 levels exceeds max_dyn_depth=2
+auto result = fory_shallow.deserialize<std::shared_ptr<Container>>(bytes);
+assert(!result.ok()); // Fails with depth exceeded error
+```
+
+**When to adjust:**
+
+- **Increase `max_dyn_depth`**: For legitimate deeply nested polymorphic data structures
+- **Decrease `max_dyn_depth`**: For stricter security requirements or shallow data structures
+
+## Nullability for Polymorphic Fields
+
+By default, `std::shared_ptr<T>` and `std::unique_ptr<T>` fields are treated as
+non-nullable in the schema. To allow `nullptr`, wrap the field with
+`fory::field<>` (or `FORY_FIELD_TAGS`) and opt in with `fory::nullable`.
+
+```cpp
+struct Pet {
+ // Non-nullable (default)
+ std::shared_ptr<Animal> primary;
+
+ // Nullable via explicit field metadata
+ fory::field<std::shared_ptr<Animal>, 0, fory::nullable> optional;
+};
+FORY_STRUCT(Pet, primary, optional);
+```
+
+See [Field Configuration](field_configuration) for more details.
+
+## Combining Polymorphism with Other Features
+
+### Polymorphism + Reference Tracking
+
+```cpp
+struct GraphNode {
+ virtual ~GraphNode() = default;
+ int32_t id = 0;
+ std::vector<std::shared_ptr<GraphNode>> neighbors;
+};
+FORY_STRUCT(GraphNode, id, neighbors);
+
+struct WeightedNode : GraphNode {
+ double weight = 0.0;
+};
+FORY_STRUCT(WeightedNode, id, neighbors, weight);
+
+// Enable ref tracking to handle shared references and cycles
+auto fory = Fory::builder().track_ref(true).build();
+fory.register_struct<GraphNode>(100);
+fory.register_struct<WeightedNode>(101);
+
+// Create cyclic graph
+auto node1 = std::make_shared<WeightedNode>();
+node1->id = 1;
+
+auto node2 = std::make_shared<WeightedNode>();
+node2->id = 2;
+
+node1->neighbors.push_back(node2);
+node2->neighbors.push_back(node1); // Cycle
+
+auto bytes = fory.serialize(node1).value();
+auto decoded = fory.deserialize<std::shared_ptr<GraphNode>>(bytes).value();
+// Cycle handled correctly
+```
+
+### Polymorphism + Schema Evolution
+
+Use compatible mode for schema evolution with polymorphic types:
+
+```cpp
+auto fory = Fory::builder()
+ .compatible(true) // Enable schema evolution
+ .track_ref(true)
+ .build();
+```
+
+## Best Practices
+
+1. **Use type ID registration** for polymorphic types:
+
+ ```cpp
+ fory.register_struct<DerivedType>(100);
+ ```
+
+2. **Enable reference tracking** for polymorphic types:
+
+ ```cpp
+ auto fory = Fory::builder().track_ref(true).build();
+ ```
+
+3. **Virtual destructors required**: Ensure base classes have virtual destructors:
+
+ ```cpp
+ struct Base {
+ virtual ~Base() = default; // Required for polymorphism
+ };
+ ```
+
+4. **Register all concrete types** before serialization/deserialization:
+
+ ```cpp
+ fory.register_struct<Derived1>(100);
+ fory.register_struct<Derived2>(101);
+ ```
+
+5. **Use `dynamic_cast`** to downcast after deserialization:
+
+ ```cpp
+ auto* derived = dynamic_cast<DerivedType*>(base_ptr.get());
+ if (derived) {
+ // Use derived-specific members
+ }
+ ```
+
+6. **Adjust `max_dyn_depth`** based on your data structure depth:
+
+ ```cpp
+ auto fory = Fory::builder().max_dyn_depth(10).build();
+ ```
+
+7. **Use `fory::nullable`** for optional polymorphic fields:
+
+ ```cpp
+ fory::field<std::shared_ptr<Base>, 0, fory::nullable> optional_ptr;
+ ```
+
+## Error Handling
+
+```cpp
+auto bytes_result = fory.serialize(obj);
+if (!bytes_result.ok()) {
+ std::cerr << "Serialization failed: "
+ << bytes_result.error().to_string() << std::endl;
+ return;
+}
+
+auto decoded_result = fory.deserialize<MyType>(bytes_result.value());
+if (!decoded_result.ok()) {
+ std::cerr << "Deserialization failed: "
+ << decoded_result.error().to_string() << std::endl;
+ return;
+}
+```
+
+**Common errors:**
+
+- **Type not registered**: Register all concrete types with unique IDs before use
+- **Depth exceeded**: Increase `max_dyn_depth` for deeply nested structures
+- **Type ID conflict**: Ensure each type has a unique type ID across all registered types
+
+## Performance Considerations
+
+**Polymorphic serialization overhead:**
+
+- Type metadata written for each polymorphic object (~16-32 bytes)
+- Dynamic type resolution during deserialization
+- Virtual function calls for runtime dispatch
+
+**Optimization tips:**
+
+1. **Use `fory::dynamic<false>`** when runtime type matches declared type:
+
+ ```cpp
+ fory::field<std::shared_ptr<Base>, 0, fory::dynamic<false>> fixed_type;
+ ```
+
+2. **Minimize nesting depth** to reduce metadata overhead
+
+3. **Batch polymorphic objects** in collections rather than individual fields
+
+4. **Consider non-polymorphic alternatives** when polymorphism isn't needed:
+
+ ```cpp
+ std::variant<Dog, Cat> animal; // Type-safe union instead of polymorphism
+ ```
+
+## Related Topics
+
+- [Type Registration](type_registration) - Registering types for serialization
+- [Field Configuration](field_configuration) - Field-level metadata and options
+- [Supported Types](supported_types) - Smart pointers and collections
+- [Configuration](configuration) - `max_dyn_depth` and other settings
+- [Basic Serialization](basic_serialization) - Core serialization concepts
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/cpp/row-format.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/cpp/row-format.md
new file mode 100644
index 000000000..76b1ad42c
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/cpp/row-format.md
@@ -0,0 +1,516 @@
+---
+title: 行格式
+sidebar_position: 7
+id: row_format
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍用于高性能、缓存友好的数据访问的行格式序列化。
+
+## 概述
+
+Apache Fory™ 行格式是一种针对以下场景优化的二进制格式：
+
+- **随机访问**：无需反序列化整个对象即可读取任意字段
+- **零拷贝**：无数据复制的直接内存访问
+- **缓存友好**：连续内存布局提高 CPU 缓存效率
+- **列式转换**：易于转换为 Apache Arrow 格式
+- **部分序列化**：只序列化需要的字段
+
+## 何时使用行格式
+
+| 使用场景 | 行格式 | 对象图 |
+| ------------------ | ------ | ------ |
+| 分析/OLAP | ✅ | ❌ |
+| 随机字段访问 | ✅ | ❌ |
+| 完整对象序列化 | ❌ | ✅ |
+| 复杂对象图 | ❌ | ✅ |
+| 引用跟踪 | ❌ | ✅ |
+| 跨语言（简单类型） | ✅ | ✅ |
+
+## 快速开始
+
+```cpp
+#include "fory/encoder/row_encoder.h"
+#include "fory/row/writer.h"
+
+using namespace fory::row;
+using namespace fory::row::encoder;
+
+// 定义结构体
+struct Person {
+ int32_t id;
+ std::string name;
+ float score;
+};
+
+// 注册字段元数据（行编码必需）
+FORY_FIELD_INFO(Person, id, name, score);
+
+int main() {
+ // 创建编码器
+ RowEncoder<Person> encoder;
+
+ // 编码一个 person
+ Person person{1, "Alice", 95.5f};
+ encoder.Encode(person);
+
+ // 获取编码后的行
+ auto row = encoder.GetWriter().ToRow();
+
+ // 随机访问字段
+ int32_t id = row->GetInt32(0);
+ std::string name = row->GetString(1);
+ float score = row->GetFloat(2);
+
+ assert(id == 1);
+ assert(name == "Alice");
+ assert(score == 95.5f);
+
+ return 0;
+}
+```
+
+## 行编码器
+
+### 基本用法
+
+`RowEncoder<T>` 模板类提供类型安全的编码：
+
+```cpp
+#include "fory/encoder/row_encoder.h"
+
+// 使用 FORY_FIELD_INFO 定义结构体
+struct Point {
+ double x;
+ double y;
+};
+FORY_FIELD_INFO(Point, x, y);
+
+// 创建编码器
+RowEncoder<Point> encoder;
+
+// 访问 schema（用于检查）
+const Schema& schema = encoder.GetSchema();
+std::cout << "Fields: " << schema.field_names().size() << std::endl;
+
+// 编码值
+Point p{1.0, 2.0};
+encoder.Encode(p);
+
+// 获取结果作为 Row
+auto row = encoder.GetWriter().ToRow();
+```
+
+### 嵌套结构体
+
+```cpp
+struct Address {
+ std::string city;
+ std::string country;
+};
+FORY_FIELD_INFO(Address, city, country);
+
+struct Person {
+ std::string name;
+ Address address;
+};
+FORY_FIELD_INFO(Person, name, address);
+
+// 编码嵌套结构体
+RowEncoder<Person> encoder;
+Person person{"Alice", {"New York", "USA"}};
+encoder.Encode(person);
+
+auto row = encoder.GetWriter().ToRow();
+std::string name = row->GetString(0);
+
+// 访问嵌套结构体
+auto address_row = row->GetStruct(1);
+std::string city = address_row->GetString(0);
+std::string country = address_row->GetString(1);
+```
+
+### 数组 / 列表
+
+```cpp
+struct Record {
+ std::vector<int32_t> values;
+ std::string label;
+};
+FORY_FIELD_INFO(Record, values, label);
+
+RowEncoder<Record> encoder;
+Record record{{1, 2, 3, 4, 5}, "test"};
+encoder.Encode(record);
+
+auto row = encoder.GetWriter().ToRow();
+auto array = row->GetArray(0);
+
+int count = array->num_elements();
+for (int i = 0; i < count; i++) {
+ int32_t value = array->GetInt32(i);
+}
+```
+
+### 直接编码数组
+
+```cpp
+// 直接编码 vector（不在结构体内）
+std::vector<Person> people{
+ {"Alice", {"NYC", "USA"}},
+ {"Bob", {"London", "UK"}}
+};
+
+RowEncoder<decltype(people)> encoder;
+encoder.Encode(people);
+
+// 获取数组数据
+auto array = encoder.GetWriter().CopyToArrayData();
+auto first_person = array->GetStruct(0);
+std::string first_name = first_person->GetString(0);
+```
+
+## 行数据访问
+
+### Row 类
+
+`Row` 类提供对结构体字段的随机访问：
+
+```cpp
+class Row {
+public:
+ // 空值检查
+ bool IsNullAt(int i) const;
+
+ // 基本类型 getter
+ bool GetBoolean(int i) const;
+ int8_t GetInt8(int i) const;
+ int16_t GetInt16(int i) const;
+ int32_t GetInt32(int i) const;
+ int64_t GetInt64(int i) const;
+ float GetFloat(int i) const;
+ double GetDouble(int i) const;
+
+ // 字符串/二进制 getter
+ std::string GetString(int i) const;
+ std::vector<uint8_t> GetBinary(int i) const;
+
+ // 嵌套类型
+ std::shared_ptr<Row> GetStruct(int i) const;
+ std::shared_ptr<ArrayData> GetArray(int i) const;
+ std::shared_ptr<MapData> GetMap(int i) const;
+
+ // 元数据
+ int num_fields() const;
+ SchemaPtr schema() const;
+
+ // 调试
+ std::string ToString() const;
+};
+```
+
+### ArrayData 类
+
+`ArrayData` 类提供对列表/数组元素的访问：
+
+```cpp
+class ArrayData {
+public:
+ // 空值检查
+ bool IsNullAt(int i) const;
+
+ // 元素数量
+ int num_elements() const;
+
+ // 基本类型 getter（与 Row 相同）
+ int32_t GetInt32(int i) const;
+ // ... 其他基本类型
+
+ // 字符串 getter
+ std::string GetString(int i) const;
+
+ // 嵌套类型
+ std::shared_ptr<Row> GetStruct(int i) const;
+ std::shared_ptr<ArrayData> GetArray(int i) const;
+ std::shared_ptr<MapData> GetMap(int i) const;
+
+ // 类型信息
+ ListTypePtr type() const;
+};
+```
+
+### MapData 类
+
+`MapData` 类提供对 map 键值对的访问：
+
+```cpp
+class MapData {
+public:
+ // 元素数量
+ int num_elements();
+
+ // 以数组形式访问键和值
+ std::shared_ptr<ArrayData> keys_array();
+ std::shared_ptr<ArrayData> values_array();
+
+ // 类型信息
+ MapTypePtr type();
+};
+```
+
+## Schema 和类型
+
+### Schema 定义
+
+Schema 定义行数据的结构：
+
+```cpp
+#include "fory/row/schema.h"
+
+using namespace fory::row;
+
+// 以编程方式创建 schema
+auto person_schema = schema({
+ field("id", int32()),
+ field("name", utf8()),
+ field("score", float32()),
+ field("active", boolean())
+});
+
+// 访问 schema 信息
+for (const auto& f : person_schema->fields()) {
+ std::cout << f->name() << ": " << f->type()->name() << std::endl;
+}
+```
+
+### 类型系统
+
+行格式可用的类型：
+
+```cpp
+// 基本类型
+DataTypePtr boolean(); // bool
+DataTypePtr int8(); // int8_t
+DataTypePtr int16(); // int16_t
+DataTypePtr int32(); // int32_t
+DataTypePtr int64(); // int64_t
+DataTypePtr float32(); // float
+DataTypePtr float64(); // double
+
+// 字符串和二进制
+DataTypePtr utf8(); // std::string
+DataTypePtr binary(); // std::vector<uint8_t>
+
+// 复杂类型
+DataTypePtr list(DataTypePtr element_type);
+DataTypePtr map(DataTypePtr key_type, DataTypePtr value_type);
+DataTypePtr struct_(std::vector<FieldPtr> fields);
+```
+
+### 类型推断
+
+`RowEncodeTrait` 模板自动推断类型：
+
+```cpp
+// 基本类型的类型推断
+RowEncodeTrait<int32_t>::Type(); // 返回 int32()
+RowEncodeTrait<float>::Type(); // 返回 float32()
+RowEncodeTrait<std::string>::Type(); // 返回 utf8()
+
+// 集合的类型推断
+RowEncodeTrait<std::vector<int32_t>>::Type(); // 返回 list(int32())
+
+// map 的类型推断
+RowEncodeTrait<std::map<std::string, int32_t>>::Type();
+// 返回 map(utf8(), int32())
+
+// 结构体的类型推断（需要 FORY_FIELD_INFO）
+RowEncodeTrait<Person>::Type(); // 返回 struct_({...})
+RowEncodeTrait<Person>::Schema(); // 返回 schema({...})
+```
+
+## 行写入器
+
+### RowWriter
+
+用于手动构造行：
+
+```cpp
+#include "fory/row/writer.h"
+
+// 创建 schema
+auto my_schema = schema({
+ field("x", int32()),
+ field("y", float64()),
+ field("name", utf8())
+});
+
+// 创建写入器
+RowWriter writer(my_schema);
+writer.Reset();
+
+// 写入字段
+writer.Write(0, 42); // x = 42
+writer.Write(1, 3.14); // y = 3.14
+writer.WriteString(2, "test"); // name = "test"
+
+// 获取结果
+auto row = writer.ToRow();
+```
+
+### ArrayWriter
+
+用于手动构造数组：
+
+```cpp
+// 创建数组类型
+auto array_type = list(int32());
+
+// 创建写入器
+ArrayWriter writer(array_type);
+writer.Reset(5); // 5 个元素
+
+// 写入元素
+for (int i = 0; i < 5; i++) {
+ writer.Write(i, i * 10);
+}
+
+// 获取结果
+auto array = writer.CopyToArrayData();
+```
+
+### 空值
+
+```cpp
+// 在特定索引处设置空值
+writer.SetNullAt(2); // 字段 2 为空
+
+// 读取时检查空值
+if (!row->IsNullAt(2)) {
+ std::string value = row->GetString(2);
+}
+```
+
+## 内存布局
+
+### 行布局
+
+```
++------------------+--------------------+--------------------+
+| 空值位图 | 固定大小数据 | 变长数据 |
++------------------+--------------------+--------------------+
+| ceil(n/8) B | 8 * n 字节 | 可变 |
++------------------+--------------------+--------------------+
+```
+
+- **空值位图**：每字段一位，指示空值
+- **固定大小数据**：每字段 8 字节（基本类型直接存储，变长类型存储偏移量+大小）
+- **变长数据**：字符串、数组、嵌套结构体
+
+### 数组布局
+
+```
++------------+------------------+--------------------+--------------------+
+| 元素数量 | 空值位图 | 固定大小数据 | 变长数据 |
++------------+------------------+--------------------+--------------------+
+| 8 字节 | ceil(n/8) 字节 | elem_size * n | 可变 |
++------------+------------------+--------------------+--------------------+
+```
+
+### Map 布局
+
+```
++------------------+------------------+
+| 键数组 | 值数组 |
++------------------+------------------+
+```
+
+## 性能提示
+
+### 1. 复用编码器
+
+```cpp
+RowEncoder<Person> encoder;
+
+// 编码多条记录
+for (const auto& person : people) {
+ encoder.Encode(person);
+ auto row = encoder.GetWriter().ToRow();
+ // 处理 row...
+}
+```
+
+### 2. 预分配缓冲区
+
+```cpp
+// 获取缓冲区引用进行预分配
+auto& buffer = encoder.GetWriter().buffer();
+buffer->Reserve(expected_size);
+```
+
+### 3. 批量处理
+
+```cpp
+// 批量处理以提高缓存利用率
+std::vector<Person> batch;
+batch.reserve(BATCH_SIZE);
+
+while (hasMore()) {
+ batch.clear();
+ fillBatch(batch);
+
+ for (const auto& person : batch) {
+ encoder.Encode(person);
+ process(encoder.GetWriter().ToRow());
+ }
+}
+```
+
+### 4. 零拷贝读取
+
+```cpp
+// 指向现有缓冲区（零拷贝）
+Row row(schema);
+row.PointTo(buffer, offset, size);
+
+// 直接从缓冲区访问字段
+int32_t id = row.GetInt32(0);
+```
+
+## 支持类型汇总
+
+| C++ 类型 | 行类型 | 固定大小 |
+| ------------------------ | ---------------- | -------- |
+| `bool` | `boolean()` | 1 字节 |
+| `int8_t` | `int8()` | 1 字节 |
+| `int16_t` | `int16()` | 2 字节 |
+| `int32_t` | `int32()` | 4 字节 |
+| `int64_t` | `int64()` | 8 字节 |
+| `float` | `float32()` | 4 字节 |
+| `double` | `float64()` | 8 字节 |
+| `std::string` | `utf8()` | 可变 |
+| `std::vector<T>` | `list(T)` | 可变 |
+| `std::map<K,V>` | `map(K,V)` | 可变 |
+| `std::optional<T>` | 内部类型 | 可空 |
+| 结构体 (FORY_FIELD_INFO) | `struct_({...})` | 可变 |
+
+## 相关主题
+
+- [基础序列化](basic-serialization.md) - 对象图序列化
+- [配置](configuration.md) - 构建器选项
+- [支持的类型](supported-types.md) - 所有支持的类型
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/cpp/schema-evolution.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/cpp/schema-evolution.md
new file mode 100644
index 000000000..fd8c7bfca
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/cpp/schema-evolution.md
@@ -0,0 +1,404 @@
+---
+title: Schema 演化
+sidebar_position: 3
+id: schema_evolution
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Apache Fory™ 在 **Compatible 模式**下支持 schema 演化，允许序列化和反序列化双方拥有不同的类型定义。
+
+## Compatible 模式
+
+使用 `compatible(true)` 启用 schema 演化：
+
+```cpp
+#include "fory/serialization/fory.h"
+
+using namespace fory::serialization;
+
+// 版本 1：原始 schema
+struct PersonV1 {
+ std::string name;
+ int32_t age;
+};
+FORY_STRUCT(PersonV1, name, age);
+
+// 版本 2：添加 email 字段
+struct PersonV2 {
+ std::string name;
+ int32_t age;
+ std::string email; // 新字段
+};
+FORY_STRUCT(PersonV2, name, age, email);
+
+int main() {
+ // 为每个 schema 版本创建单独的 Fory 实例
+ auto fory_v1 = Fory::builder()
+ .compatible(true) // 启用 schema 演化
+ .xlang(true)
+ .build();
+
+ auto fory_v2 = Fory::builder()
+ .compatible(true)
+ .xlang(true)
+ .build();
+
+ // 使用相同的类型 ID 进行 schema 演化
+ constexpr uint32_t PERSON_TYPE_ID = 100;
+ fory_v1.register_struct<PersonV1>(PERSON_TYPE_ID);
+ fory_v2.register_struct<PersonV2>(PERSON_TYPE_ID);
+
+ // 使用 V1 序列化
+ PersonV1 v1{"Alice", 30};
+ auto bytes = fory_v1.serialize(v1).value();
+
+ // 反序列化为 V2 - email 获得默认值（空字符串）
+ auto v2 = fory_v2.deserialize<PersonV2>(bytes).value();
+ assert(v2.name == "Alice");
+ assert(v2.age == 30);
+ assert(v2.email == ""); // 缺失字段的默认值
+
+ return 0;
+}
+```
+
+## Schema 演化特性
+
+Compatible 模式支持以下 schema 变更：
+
+| 变更类型 | 支持 | 行为 |
+| ------------ | ---- | ---------------------------- |
+| 添加新字段 | ✅ | 缺失字段使用默认值 |
+| 删除字段 | ✅ | 额外字段被跳过 |
+| 重排字段顺序 | ✅ | 按名称匹配字段，而非位置 |
+| 更改可空性 | ✅ | `T` ↔ `std::optional<T>` |
+| 更改字段类型 | ❌ | 类型必须兼容 |
+| 重命名字段 | ❌ | 字段名必须匹配（区分大小写） |
+
+## 添加字段（向后兼容）
+
+当使用具有额外字段的新 schema 反序列化旧数据时：
+
+```cpp
+// 旧 schema (V1)
+struct ProductV1 {
+ std::string name;
+ double price;
+};
+FORY_STRUCT(ProductV1, name, price);
+
+// 新 schema (V2) 带有额外字段
+struct ProductV2 {
+ std::string name;
+ double price;
+ std::vector<std::string> tags; // 新字段
+ std::map<std::string, std::string> attributes; // 新字段
+};
+FORY_STRUCT(ProductV2, name, price, tags, attributes);
+
+// 序列化 V1
+ProductV1 v1{"Laptop", 999.99};
+auto bytes = fory_v1.serialize(v1).value();
+
+// 反序列化为 V2
+auto v2 = fory_v2.deserialize<ProductV2>(bytes).value();
+assert(v2.name == "Laptop");
+assert(v2.price == 999.99);
+assert(v2.tags.empty()); // 默认：空 vector
+assert(v2.attributes.empty()); // 默认：空 map
+```
+
+## 删除字段（向前兼容）
+
+当使用具有较少字段的旧 schema 反序列化新数据时：
+
+```cpp
+// 完整 schema
+struct UserFull {
+ int64_t id;
+ std::string username;
+ std::string email;
+ std::string password_hash;
+ int32_t login_count;
+};
+FORY_STRUCT(UserFull, id, username, email, password_hash, login_count);
+
+// 精简 schema（删除了 3 个字段）
+struct UserMinimal {
+ int64_t id;
+ std::string username;
+};
+FORY_STRUCT(UserMinimal, id, username);
+
+// 序列化完整版本
+UserFull full{12345, "johndoe", "john@example.com", "hash123", 42};
+auto bytes = fory_full.serialize(full).value();
+
+// 反序列化为精简版本 - 额外字段被跳过
+auto minimal = fory_minimal.deserialize<UserMinimal>(bytes).value();
+assert(minimal.id == 12345);
+assert(minimal.username == "johndoe");
+// email、password_hash、login_count 被跳过
+```
+
+## 字段重排
+
+在 compatible 模式下，字段按名称匹配，而非位置：
+
+```cpp
+// 原始字段顺序
+struct ConfigOriginal {
+ std::string host;
+ int32_t port;
+ bool enable_ssl;
+ std::string protocol;
+};
+FORY_STRUCT(ConfigOriginal, host, port, enable_ssl, protocol);
+
+// 重排后的字段
+struct ConfigReordered {
+ bool enable_ssl; // 移到第一位
+ std::string protocol; // 移到第二位
+ std::string host; // 移到第三位
+ int32_t port; // 移到最后
+};
+FORY_STRUCT(ConfigReordered, enable_ssl, protocol, host, port);
+
+// 使用原始顺序序列化
+ConfigOriginal orig{"localhost", 8080, true, "https"};
+auto bytes = fory_orig.serialize(orig).value();
+
+// 使用不同字段顺序反序列化 - 正常工作
+auto reordered = fory_reord.deserialize<ConfigReordered>(bytes).value();
+assert(reordered.host == "localhost");
+assert(reordered.port == 8080);
+assert(reordered.enable_ssl == true);
+assert(reordered.protocol == "https");
+```
+
+## 嵌套结构体演化
+
+Schema 演化递归支持嵌套结构体：
+
+```cpp
+// V1 Address
+struct AddressV1 {
+ std::string street;
+ std::string city;
+};
+FORY_STRUCT(AddressV1, street, city);
+
+// V2 Address 带有新字段
+struct AddressV2 {
+ std::string street;
+ std::string city;
+ std::string country; // 新字段
+ std::string zipcode; // 新字段
+};
+FORY_STRUCT(AddressV2, street, city, country, zipcode);
+
+// V1 Employee 使用 V1 Address
+struct EmployeeV1 {
+ std::string name;
+ AddressV1 home_address;
+};
+FORY_STRUCT(EmployeeV1, name, home_address);
+
+// V2 Employee 使用 V2 Address 和新字段
+struct EmployeeV2 {
+ std::string name;
+ AddressV2 home_address; // 嵌套结构体已演化
+ std::string employee_id; // 新字段
+};
+FORY_STRUCT(EmployeeV2, name, home_address, employee_id);
+
+// 使用相同 ID 注册类型
+constexpr uint32_t ADDRESS_TYPE_ID = 100;
+constexpr uint32_t EMPLOYEE_TYPE_ID = 101;
+
+fory_v1.register_struct<AddressV1>(ADDRESS_TYPE_ID);
+fory_v1.register_struct<EmployeeV1>(EMPLOYEE_TYPE_ID);
+fory_v2.register_struct<AddressV2>(ADDRESS_TYPE_ID);
+fory_v2.register_struct<EmployeeV2>(EMPLOYEE_TYPE_ID);
+
+// 序列化 V1
+EmployeeV1 emp_v1{"Jane Doe", {"123 Main St", "NYC"}};
+auto bytes = fory_v1.serialize(emp_v1).value();
+
+// 反序列化为 V2
+auto emp_v2 = fory_v2.deserialize<EmployeeV2>(bytes).value();
+assert(emp_v2.name == "Jane Doe");
+assert(emp_v2.home_address.street == "123 Main St");
+assert(emp_v2.home_address.city == "NYC");
+assert(emp_v2.home_address.country == ""); // 默认值
+assert(emp_v2.home_address.zipcode == ""); // 默认值
+assert(emp_v2.employee_id == ""); // 默认值
+```
+
+## 双向演化
+
+Schema 演化双向工作：
+
+```cpp
+// V2 -> V1（降级）
+PersonV2 v2{"Charlie", 35, "charlie@example.com"};
+auto bytes = fory_v2.serialize(v2).value();
+
+auto v1 = fory_v1.deserialize<PersonV1>(bytes).value();
+assert(v1.name == "Charlie");
+assert(v1.age == 35);
+// email 字段在反序列化时被丢弃
+```
+
+## 默认值
+
+当字段缺失时，使用 C++ 默认初始化：
+
+| 类型 | 默认值 |
+| ---------------------- | -------------- |
+| `int8_t`、`int16_t`... | `0` |
+| `float`、`double` | `0.0` |
+| `bool` | `false` |
+| `std::string` | `""` |
+| `std::vector<T>` | 空 vector |
+| `std::map<K,V>` | 空 map |
+| `std::set<T>` | 空 set |
+| `std::optional<T>` | `std::nullopt` |
+| 结构体类型 | 默认构造 |
+
+## SchemaConsistent 模式（默认）
+
+不使用 compatible 模式时，schema 必须完全匹配：
+
+```cpp
+// 严格模式（默认）
+auto fory = Fory::builder()
+ .compatible(false) // 默认：schema 必须匹配
+ .xlang(true)
+ .build();
+
+// 序列化/反序列化要求相同的 schema
+// Schema 不匹配可能导致错误或未定义行为
+```
+
+**何时使用 SchemaConsistent 模式：**
+
+- Schema 保证匹配（相同的二进制版本）
+- 需要最高性能（更少的元数据开销）
+- 您同时控制序列化和反序列化
+
+**何时使用 Compatible 模式：**
+
+- Schema 可能独立演化
+- 需要跨版本兼容性
+- 不同服务可能有不同的 schema 版本
+
+## 类型 ID 要求
+
+要使 schema 演化正常工作：
+
+1. **相同类型 ID**：同一结构体的不同版本必须使用相同的类型 ID
+2. **一致的 ID**：类型 ID 必须在所有 Fory 实例中保持一致
+3. **注册所有版本**：每个 Fory 实例注册自己的结构体版本
+
+```cpp
+constexpr uint32_t PERSON_TYPE_ID = 100;
+
+// 实例 1 使用 PersonV1
+fory_v1.register_struct<PersonV1>(PERSON_TYPE_ID);
+
+// 实例 2 使用 PersonV2
+fory_v2.register_struct<PersonV2>(PERSON_TYPE_ID);
+
+// 相同的类型 ID 启用 schema 演化
+```
+
+## 最佳实践
+
+### 1. 为演化做规划
+
+设计 schema 时考虑未来的变更：
+
+```cpp
+// 好的做法：对可能删除的字段使用 optional
+struct Config {
+ std::string host;
+ int32_t port;
+ std::optional<std::string> deprecated_field; // 以后可以删除
+};
+```
+
+### 2. 使用有意义的默认值
+
+考虑新字段使用什么默认值才有意义：
+
+```cpp
+struct Settings {
+ int32_t timeout_ms; // 默认：0（可能需要一个合理的默认值）
+ bool enabled; // 默认：false
+ std::string mode; // 默认：""（可能需要 "default"）
+};
+```
+
+### 3. 记录 Schema 版本
+
+跟踪 schema 变更以便调试：
+
+```cpp
+// V1：初始 schema（2024-01-01）
+// V2：添加 email 字段（2024-02-01）
+// V3：添加 phone、address 字段（2024-03-01）
+```
+
+### 4. 测试演化路径
+
+测试升级和降级场景：
... 59492 lines suppressed ...
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@fory.apache.org
For additional commands, e-mail: commits-help@fory.apache.org
(fory-site) 02/09: Add release-major-version skill
Posted by ch...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
chaokunyang pushed a commit to branch release_0.17.0
in repository https://gitbox.apache.org/repos/asf/fory-site.git
commit 9c02a59a9d23ae68d90ec9f0e645fcb31e663eff
Author: 慕白 <ch...@antgroup.com>
AuthorDate: Sun Apr 19 22:54:04 2026 +0800
Add release-major-version skill
---
.claude/skills/release-major-version/SKILL.md | 258 ++++++++++++++++++++++++++
1 file changed, 258 insertions(+)
diff --git a/.claude/skills/release-major-version/SKILL.md b/.claude/skills/release-major-version/SKILL.md
new file mode 100644
index 000000000..9b0f50164
--- /dev/null
+++ b/.claude/skills/release-major-version/SKILL.md
@@ -0,0 +1,258 @@
+---
+name: release-major-version
+description: >-
+ Prepare the Apache Fory site for a new major-ish docs release such as 0.17:
+ write the release blog, checkpoint with git commits, translate the zh-CN
+ release blog and docs, create the versioned docs snapshot, update the
+ default docs version, and run an independent self-review to catch remaining
+ issues. Use when the user asks to cut a new docs/site release version on
+ this repository.
+---
+
+# Release Big Version
+
+Use this skill for the `apache/fory-site` repository when preparing a new docs/site release such as `0.17`.
+
+This skill is for the website/docs repository workflow, not the ASF source release/signing workflow in `docs/community/how_to_release.md`.
+
+## Scope
+
+This workflow covers:
+
+1. Write the release blog post
+2. Git commit the blog/content checkpoint
+3. Translate the zh-CN release blog and zh-CN docs
+4. Git commit the translation checkpoint
+5. Version the docs with `yarn docusaurus docs:version <version>`
+6. Update the default docs version to the new version
+7. Run a fresh subagent review before calling the work done
+
+## Repository Facts You Must Respect
+
+- Current docs live in `docs/`
+- Versioned English docs live in `versioned_docs/version-<ver>/`
+- Versioned sidebars live in `versioned_sidebars/version-<ver>-sidebars.json`
+- Chinese docs live in `i18n/zh-CN/docusaurus-plugin-content-docs/current/`
+- Versioned Chinese docs live in `i18n/zh-CN/docusaurus-plugin-content-docs/version-<ver>/`
+- Chinese blog posts live in `i18n/zh-CN/docusaurus-plugin-content-blog/`
+- Docs version history is recorded in `versions.json`
+- The default released docs version is controlled by `docs.lastVersion` in `docusaurus.config.ts`
+- The wrapped versioning command is `yarn docusaurus docs:version <ver>`, which calls `scripts/docusaurus-with-i18n.sh`
+- The wrapper copies every locale's `current/` docs tree to `version-<ver>/` after Docusaurus versions the English docs
+
+## Important Caveats
+
+- Do not run raw `docusaurus docs:version <ver>` directly. Use `yarn docusaurus docs:version <ver>` so zh-CN docs are copied too.
+- Do not version docs before the English docs and zh-CN docs are in the state you want to freeze for that release.
+- Run `npm run copy-i18n-fallback` before cutting the version if zh-CN `benchmarks/` or `specification/` content may still rely on fallback copies.
+- `copy-i18n-fallback.sh` can create untracked fallback files under `i18n/zh-CN/.../benchmarks` and `.../specification`; do not confuse those with intentional edits.
+- This repo already has some broken zh-CN doc links. A full build can fail for pre-existing reasons unrelated to your release changes. Distinguish new regressions from known baseline issues.
+- Keep `tasks/*.md` and `tasks/lessons.md` out of git.
+- `docs/guide` and `docs/specification` are mainly synced from `apache/fory`; avoid site-only divergence there unless that upstream sync is intentionally part of the release work.
+- Abort early if target-version artifacts already exist unless the user explicitly wants to resume/repair a partial release cut. This includes:
+ - `blog/*fory_<version>_release.md`
+ - `static/img/blog/fory_<version>_release/`
+ - `versioned_docs/version-<version>/`
+ - `versioned_sidebars/version-<version>-sidebars.json`
+ - `i18n/zh-CN/docusaurus-plugin-content-docs/version-<version>/`
+
+## Step 0: Prepare Context
+
+1. Read:
+ - `package.json`
+ - `docusaurus.config.ts`
+ - `versions.json`
+ - `scripts/docusaurus-with-i18n.sh`
+2. Confirm the current latest released version, the target new version, and the previous released version that will become the explicit older-version route after the cut.
+3. Verify the site repo already contains the intended upstream docs state from `apache/fory` before you start. At minimum:
+ - check whether the needed `docs/guide` and `docs/specification` changes are already present in this repo
+ - if not, stop and sync or ask the user before freezing a stale snapshot
+4. Check that the target version is clean:
+ - the release blog filename does not already exist unless this is an intentional continuation
+ - the blog asset directory does not already exist unless this is an intentional continuation
+ - `versioned_docs/version-<version>/` does not already exist
+ - `versioned_sidebars/version-<version>-sidebars.json` does not already exist
+ - `i18n/zh-CN/docusaurus-plugin-content-docs/version-<version>/` does not already exist
+5. Scan:
+ - `blog/` for the previous release post to use as template
+ - `docs/`, `versioned_docs/`, and `i18n/zh-CN/docusaurus-plugin-content-docs/` so you understand the current tree
+6. If the task is non-trivial, maintain a task note under `tasks/task-<slug>.md` and archive it to `tasks/history/` when finished.
+
+## Step 1: Write the Release Blog
+
+1. Find the previous release blog in `blog/`, typically `blog/YYYY-MM-DD-fory_<prev>_release.md`.
+2. Create the new release post by adapting the previous one instead of starting from scratch.
+3. Update the post carefully:
+ - frontmatter `slug`, `title`, `tags`, date-based filename
+ - opening release paragraph
+ - compare link
+ - PR counts / contributor counts if the post includes them
+ - highlights/features/fixes sections
+ - benchmark images and asset paths
+4. Put blog-specific assets under `static/img/blog/fory_<version>_release/` when the post needs dedicated images.
+5. If you add benchmark images, ensure the referenced static paths and copied files match exactly.
+6. Validate the post for obvious copy/paste errors from the previous release.
+
+## Step 1A: Bump Versioned References in Current Docs
+
+Before translating the zh-CN blog/docs or freezing the docs version, update all pinned current-doc references to the new release version.
+
+Required targets:
+
+1. `docs/start/install.md`
+2. `docs/guide/**/index.md` for each language/runtime that includes versioned install or dependency examples
+3. other current guide pages with pinned version examples, dependency strings, or install snippets
+4. any other current docs page that still advertises the previous release as the recommended install version
+
+Minimum workflow:
+
+1. Replace the previous release version with the new release version in `docs/start/install.md`
+2. Scan all current docs for pinned release strings and update them where they describe the latest recommended version
+3. Explicitly inspect `docs/guide/**/index.md` because these pages often carry language-specific install snippets and versioned dependency examples
+4. Update every latest-version reference before `yarn docusaurus docs:version <version>` so the frozen snapshot inherits the correct release version
+5. Be especially suspicious of:
+ - Maven/Gradle coordinates
+ - `pip install`, `go get`, `cargo add`, `dotnet add package`
+ - Bazel dependency examples
+ - language-guide install snippets under `docs/guide/**`
+ - language `index.md` pages under `docs/guide/**/index.md`
+6. Finish all of these English/current-doc version updates before starting zh-CN translation, so the Chinese docs/blog are translated once from the final English source rather than patched twice
+7. Do this before `yarn docusaurus docs:version <version>` so the released snapshot freezes the correct install guidance
+
+## Step 2: Git Commit the Blog Checkpoint
+
+1. Review the diff for the new blog post and any new assets.
+2. Make a focused git commit for the blog/release-post changes.
+3. Do not bundle unrelated generated files into this commit.
+
+## Step 3: Translate zh-CN Docs
+
+1. Use the Chinese translation workflow skill:
+ - Prefer repo-local `.agents/skills/translate-docs-zh/SKILL.md` if it exists
+ - Otherwise use `.claude/skills/translate-docs-zh/SKILL.md`
+2. Start this step only after the English release blog and all current-doc version bumps are final.
+3. Translate or sync the zh-CN release blog:
+ - source: `blog/<release-file>.md`
+ - target: `i18n/zh-CN/docusaurus-plugin-content-blog/<release-file>.md`
+ - preserve frontmatter structure and blog metadata unless a localized change is needed
+ - keep blog asset paths aligned with the English source unless there is a deliberate zh-only asset change
+4. Translate or sync the zh-CN docs for the doc changes that should ship with the new release.
+ - primary path mapping: `docs/<subpath>` -> `i18n/zh-CN/docusaurus-plugin-content-docs/current/<subpath>`
+5. Follow the translation skill's hard rule: no external translation tools or services.
+6. If top-level category labels changed, also update:
+ - `i18n/zh-CN/docusaurus-plugin-content-docs/current.json`
+7. If the release needs localized version metadata, plan a manual follow-up for `i18n/zh-CN/docusaurus-plugin-content-docs/version-<version>.json`; the versioning wrapper does not create it.
+
+## Step 4: Git Commit the zh-CN Checkpoint
+
+1. Review only the intended zh-CN docs changes.
+2. Include both the zh-CN release blog and zh-CN docs translation/sync in this checkpoint.
+3. Commit the Chinese translation/sync separately from the release blog commit.
+4. Leave task notes and lessons unstaged.
+
+## Step 5: Freeze the New Docs Version
+
+Before freezing:
+
+```bash
+npm run copy-i18n-fallback
+```
+
+Then, after English and zh-CN current docs are ready, run:
+
+```bash
+yarn docusaurus docs:version <version>
+```
+
+Expected effects:
+
+- Docusaurus snapshots English docs into `versioned_docs/version-<version>/`
+- Docusaurus creates `versioned_sidebars/version-<version>-sidebars.json`
+- The wrapper script copies zh-CN current docs into `i18n/zh-CN/docusaurus-plugin-content-docs/version-<version>/`
+- `versions.json` is updated
+
+After the command:
+
+1. Inspect the new `versioned_docs/version-<version>/` tree
+2. Inspect `versioned_sidebars/version-<version>-sidebars.json`
+3. Inspect `i18n/zh-CN/docusaurus-plugin-content-docs/version-<version>/`
+4. Check for accidental carry-over of placeholder or half-English zh-CN content before accepting the snapshot
+5. Decide whether a manual `i18n/zh-CN/docusaurus-plugin-content-docs/version-<version>.json` should be added for this release
+6. If a later validation/build step generates additional fallback files under the new `version-<version>/` zh-CN tree, inspect them explicitly and decide whether they belong in the release commit
+
+## Step 6: Update the Default Docs Version
+
+1. Edit `docusaurus.config.ts`
+2. Change:
+
+```ts
+docs: {
+ lastVersion: '<version>',
+}
+```
+
+3. Keep the existing repo style for `docs.versions` entries unless there is a concrete reason to change it
+4. Verify `versions.json` now lists the new version first
+
+## Step 7: Validate
+
+Minimum validation:
+
+1. `npm run typecheck`
+2. `npm run build`
+3. Review the output and separate:
+ - new failures caused by your changes
+ - pre-existing failures, especially zh-CN broken links
+
+Recommended route checks when the build is usable:
+
+- `/`
+- `/docs`
+- `/zh-CN/docs`
+- `/docs/<previous-version>/`
+- `/zh-CN/docs/<previous-version>/`
+- `/blog`
+- `/zh-CN/blog`
+
+Also run targeted checks:
+
+- parameterize stale-version scans using the actual old/new versions instead of hard-coded values
+- scan at least: `blog`, `docs`, `versioned_docs/version-<version>`, and `i18n/zh-CN/docusaurus-plugin-content-docs`
+- for example, search for the previous release string, older release strings likely to be copy/paste remnants, and placeholders such as `TODO` / `TBD`
+- treat stale latest-version references in current install/docs pages as blocking, especially in `docs/start/install.md`, `docs/guide/**/index.md`, and other `docs/guide/**` pages
+- confirm release blog asset paths exist under `static/img/blog/fory_<version>_release/`
+
+## Step 8: Fresh Self-Review
+
+Before marking the task complete, spawn a fresh subagent and ask it to review the work with no answer leakage.
+
+The review should check at least:
+
+1. Are there still stale version strings or previous-release copy/paste remnants?
+2. Did versioning update the expected files only?
+3. Are zh-CN docs/versioned docs consistent with the intended snapshot?
+4. Are the zh-CN release blog and English release blog both present and consistent with the intended release state?
+5. Are blog asset paths and benchmark links valid?
+6. Are there any obvious missing follow-up edits, such as `docs/start/install.md` or guide pages with pinned version references that should move to the new release?
+7. Did the workflow accidentally snapshot stale site docs because upstream `apache/fory` doc changes were not synced first?
+
+Treat review findings as blocking until resolved or explicitly documented.
+
+## Commit Strategy
+
+Preferred checkpoints:
+
+1. Blog/release-post commit
+2. zh-CN release blog + docs translation commit
+3. versioning/default-version commit
+
+Keep commits focused so rollback and review stay simple.
+
+## Output Requirements
+
+When reporting completion, include:
+
+1. What changed
+2. Which commits or commit boundaries were created
+3. Validation results
+4. Any remaining known issues or pre-existing build failures
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@fory.apache.org
For additional commands, e-mail: commits-help@fory.apache.org
(fory-site) 06/09: Complete zh docs and blog for 0.17
Posted by ch...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
chaokunyang pushed a commit to branch release_0.17.0
in repository https://gitbox.apache.org/repos/asf/fory-site.git
commit 0c9f74409b00f9a4067585ac235d69996d1deb47
Author: 慕白 <ch...@antgroup.com>
AuthorDate: Sun Apr 19 23:24:21 2026 +0800
Complete zh docs and blog for 0.17
---
.../2026-04-19-fory_0_17_0_release.md | 52 +++++
.../current/guide/csharp/index.md | 22 +--
.../current/guide/dart/_category_.json | 6 +
.../current/guide/dart/basic-serialization.md | 144 ++++++++++++++
.../current/guide/dart/code-generation.md | 113 +++++++++++
.../current/guide/dart/configuration.md | 121 ++++++++++++
.../current/guide/dart/cross-language.md | 193 ++++++++++++++++++
.../current/guide/dart/custom-serializers.md | 139 +++++++++++++
.../current/guide/dart/field-configuration.md | 127 ++++++++++++
.../current/guide/dart/index.md | 141 +++++++++++++
.../current/guide/dart/schema-evolution.md | 92 +++++++++
.../current/guide/dart/supported-types.md | 102 ++++++++++
.../current/guide/dart/troubleshooting.md | 103 ++++++++++
.../current/guide/dart/type-registration.md | 98 +++++++++
.../current/guide/java/enum-configuration.md | 104 ++++++++++
.../current/guide/java/virtual-threads.md | 114 +++++++++++
.../current/guide/javascript/_category_.json | 6 +
.../guide/javascript/basic-serialization.md | 219 +++++++++++++++++++++
.../current/guide/javascript/cross-language.md | 128 ++++++++++++
.../current/guide/javascript/index.md | 141 +++++++++++++
.../current/guide/javascript/references.md | 111 +++++++++++
.../current/guide/javascript/schema-evolution.md | 99 ++++++++++
.../current/guide/javascript/supported-types.md | 177 +++++++++++++++++
.../current/guide/javascript/troubleshooting.md | 105 ++++++++++
.../current/guide/javascript/type-registration.md | 200 +++++++++++++++++++
25 files changed, 2846 insertions(+), 11 deletions(-)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-blog/2026-04-19-fory_0_17_0_release.md b/i18n/zh-CN/docusaurus-plugin-content-blog/2026-04-19-fory_0_17_0_release.md
index 7a709c9c0..a1752fa04 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-blog/2026-04-19-fory_0_17_0_release.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-blog/2026-04-19-fory_0_17_0_release.md
@@ -228,3 +228,55 @@ void main() {
* fix(java): 在首次使用时固定 codegen config hash，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3495
* fix(rust): 修复 cargo-fuzz 检测到的多个 panic，作者 @BaldDemian，见 https://github.com/apache/fory/pull/3483
* fix(java): 处理 private final map 的代码生成，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3504
+* fix(compiler): 修复失效的 service 示例并补充回归覆盖，作者 @VikingDeng，见 https://github.com/apache/fory/pull/3505
+* fix(rust): 深拷贝 TypeMeta，避免并发场景中的未定义行为，作者 @BaldDemian，见 https://github.com/apache/fory/pull/3511
+* fix(compiler): 修复 compiler 测试失败问题，并增加 compiler CI，作者 @BaldDemian，见 https://github.com/apache/fory/pull/3516
+* fix(compiler): 允许在 FDL RPC 签名中使用带限定名的嵌套类型，作者 @VikingDeng，见 https://github.com/apache/fory/pull/3518
+* fix(java): 在复制时保留 ConcurrentSkipListSet comparator，作者 @mandrean，见 https://github.com/apache/fory/pull/3520
+* test(compiler): 为 gRPC service 支持增加 IR 校验与代码生成测试，作者 @darius024，见 https://github.com/apache/fory/pull/3528
+* fix(java): 修正 GraalVM 中依赖/嵌套 serializer 的解析，作者 @rakow，见 https://github.com/apache/fory/pull/3532
+* fix(java): 修复 objectstream serializer 的异步 JIT 与 GraalVM 支持，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3534
+* ci: 修复 C++ workflow 的 Bazel 缓存路径，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3535
+* fix(python): 修复 visit_other 中错误的调用顺序，作者 @BaldDemian，见 https://github.com/apache/fory/pull/3542
+* fix(js): 修正 float64 array 大小计算错误，作者 @ayush00git，见 https://github.com/apache/fory/pull/3541
+* fix(java): 在构建期间配置 type checker，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3550
+* fix(java): 为排序容器自动选择子 serializer，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3552
+* fix(java): 支持在 java11+ 中跳过可选 SQL serializer，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3553
+* fix(rust): 为嵌套类型统一应用 PascalCase 命名，作者 @utafrali，见 https://github.com/apache/fory/pull/3548
+* fix(javascript): 修复不稳定的 javascript IDL 测试，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3565
+* fix(swift): 修复 swift 生成代码的编译告警，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3566
+* fix(java): 为此前遗漏的回归问题增加测试，作者 @PiotrDuz，见 https://github.com/apache/fory/pull/3573
+
+## 其他改进
+* chore(java): 更新 Spotless 和 Checkstyle，以支持使用 JDK25 构建，作者 @stevenschlansker，见 https://github.com/apache/fory/pull/3476
+* chore(java): 清理 Javadoc 告警，并在引入新告警时让构建失败，作者 @stevenschlansker，见 https://github.com/apache/fory/pull/3477
+* chore: 将版本号提升到 0.16.0，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3488
+* docs: 在 readme 中增加 python benchmark 结果，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3496
+* docs: 修复 benchmark 图表，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3498
+* docs: 新增 fory code review skill，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3500
+* chore: 调整 skills 软链接，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3501
+* chore(cpp): 配置 CI，从 Markdown 中提取并执行 C++ 代码，作者 @Tyooughtul，见 https://github.com/apache/fory/pull/3381
+* docs: 改进 Java generator 中的注释，作者 @codewithtarun2005，见 https://github.com/apache/fory/pull/3507
+* docs: 重构 agents.md 以减少 token 使用，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3538
+* docs: 增加 ai-review 策略，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3545
+* chore: 在 /java/fory-test-core 中将 org.apache.logging.log4j:log4j-core 从 2.25.3 升级到 2.25.4，作者 @dependabot[bot]，见 https://github.com/apache/fory/pull/3556
+* chore(javascript): 将 ref tracking 重命名为 ref，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3559
+* docs(dart): 增加 dart 文档，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3560
+* docs(javascript): 增加 javascript 文档，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3561
+* docs: 完善 dart 和 javascript 文档，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3567
+* docs(dart): 更新 dart benchmark 文档，作者 @yash-agarwa-l，见 https://github.com/apache/fory/pull/3568
+* docs: 更新 readme，作者 @chaokunyang，见 https://github.com/apache/fory/pull/3575
+
+## 新贡献者
+* @utafrali 首次贡献见 https://github.com/apache/fory/pull/3481
+* @BaldDemian 首次贡献见 https://github.com/apache/fory/pull/3490
+* @retryoos 首次贡献见 https://github.com/apache/fory/pull/3493
+* @Tyooughtul 首次贡献见 https://github.com/apache/fory/pull/3381
+* @UninspiredCarrot 首次贡献见 https://github.com/apache/fory/pull/3487
+* @VikingDeng 首次贡献见 https://github.com/apache/fory/pull/3505
+* @codewithtarun2005 首次贡献见 https://github.com/apache/fory/pull/3507
+* @darius024 首次贡献见 https://github.com/apache/fory/pull/3528
+* @rakow 首次贡献见 https://github.com/apache/fory/pull/3532
+* @PiotrDuz 首次贡献见 https://github.com/apache/fory/pull/3573
+
+**完整更新日志**: https://github.com/apache/fory/compare/v0.16.0...v0.17.0
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/index.md
index 4cd2780ce..30f8b06dc 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/index.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/index.md
@@ -85,17 +85,17 @@ User decoded = fory.Deserialize<User>(payload);
| 主题 | 说明 |
| --------------------------------------------- | ---------------------------------- |
-| [配置](configuration.md) | 构建器选项与运行时模式 |
-| [基础序列化](basic-serialization.md) | 强类型和动态序列化 API |
-| [类型注册](type-registration.md) | 注册用户类型和自定义序列化器 |
-| [自定义序列化器](custom-serializers.md) | 实现 `Serializer<T>` |
-| [字段配置](field-configuration.md) | `[Field]` 特性与整数编码选项 |
-| [引用](references.md) | 共享引用与循环引用处理 |
-| [Schema 演进](schema-evolution.md) | 兼容模式行为 |
-| [跨语言](cross-language.md) | 互操作性指导 |
-| [支持的类型](supported-types.md) | 内置类型与生成类型支持 |
-| [线程安全](thread-safety.md) | `Fory` 与 `ThreadSafeFory` 的用法 |
-| [故障排查](troubleshooting.md) | 常见错误与调试步骤 |
+| [配置](https://fory.apache.org/docs/guide/csharp/configuration) | 构建器选项与运行时模式 |
+| [基础序列化](https://fory.apache.org/docs/guide/csharp/basic-serialization) | 强类型和动态序列化 API |
+| [类型注册](https://fory.apache.org/docs/guide/csharp/type-registration) | 注册用户类型和自定义序列化器 |
+| [自定义序列化器](https://fory.apache.org/docs/guide/csharp/custom-serializers) | 实现 `Serializer<T>` |
+| [字段配置](https://fory.apache.org/docs/guide/csharp/field-configuration) | `[Field]` 特性与整数编码选项 |
+| [引用](https://fory.apache.org/docs/guide/csharp/references) | 共享引用与循环引用处理 |
+| [Schema 演进](https://fory.apache.org/docs/guide/csharp/schema-evolution) | 兼容模式行为 |
+| [跨语言](https://fory.apache.org/docs/guide/csharp/cross-language) | 互操作性指导 |
+| [支持的类型](https://fory.apache.org/docs/guide/csharp/supported-types) | 内置类型与生成类型支持 |
+| [线程安全](https://fory.apache.org/docs/guide/csharp/thread-safety) | `Fory` 与 `ThreadSafeFory` 的用法 |
+| [故障排查](https://fory.apache.org/docs/guide/csharp/troubleshooting) | 常见错误与调试步骤 |
## 相关资源
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/dart/_category_.json b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/dart/_category_.json
new file mode 100644
index 000000000..b2d06cfcd
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/dart/_category_.json
@@ -0,0 +1,6 @@
+{
+ "label": "Dart",
+ "position": 9,
+ "collapsible": true,
+ "collapsed": true
+}
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/dart/basic-serialization.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/dart/basic-serialization.md
new file mode 100644
index 000000000..59aaed47a
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/dart/basic-serialization.md
@@ -0,0 +1,144 @@
+---
+title: 基础序列化
+sidebar_position: 2
+id: dart_basic_serialization
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍如何使用 Apache Fory™ Dart 对值进行序列化和反序列化。
+
+## 创建 `Fory` 实例
+
+创建一个实例并复用它。每次调用都新建 `Fory` 只会浪费资源。
+
+```dart
+import 'package:fory/fory.dart';
+
+final fory = Fory();
+```
+
+## 序列化和反序列化带注解的类型
+
+```dart
+import 'package:fory/fory.dart';
+
+part 'person.fory.dart';
+
+@ForyStruct()
+class Person {
+ Person();
+
+ String name = '';
+ Int32 age = Int32(0);
+}
+
+void main() {
+ final fory = Fory();
+ PersonFory.register(
+ fory,
+ Person,
+ namespace: 'example',
+ typeName: 'Person',
+ );
+
+ final person = Person()
+ ..name = 'Ada'
+ ..age = Int32(36);
+
+ final bytes = fory.serialize(person);
+ final roundTrip = fory.deserialize<Person>(bytes);
+ print(roundTrip.name);
+}
+```
+
+`deserialize<T>` 会返回并转换为 `T` 的解码结果。如果载荷描述的类型与 `T` 不一致，就会抛出异常。
+
+## Null 值
+
+支持直接序列化 `null`：
+
+```dart
+final fory = Fory();
+final bytes = fory.serialize(null);
+final value = fory.deserialize<Object?>(bytes);
+```
+
+## 序列化集合和动态载荷
+
+你可以直接序列化集合值：
+
+```dart
+final fory = Fory();
+final bytes = fory.serialize(<Object?>[
+ 'hello',
+ Int32(42),
+ true,
+]);
+final value = fory.deserialize<List<Object?>>(bytes);
+```
+
+对于异构集合，请反序列化为 `Object?`、`List<Object?>` 或 `Map<Object?, Object?>`。
+
+## 引用跟踪
+
+默认情况下，Fory 不会跟踪对象标识。如果同一个对象在列表中出现两次，它会被序列化两次。当数据包含共享引用或循环结构时，请启用引用跟踪。
+
+对于顶层集合：
+
+```dart
+final fory = Fory();
+final shared = String.fromCharCodes('shared'.codeUnits);
+final bytes = fory.serialize(<Object?>[shared, shared], trackRef: true);
+final roundTrip = fory.deserialize<List<Object?>>(bytes);
+print(identical(roundTrip[0], roundTrip[1])); // true
+```
+
+对于生成结构体中的字段，请改用该字段上的 `@ForyField(ref: true)`。
+
+## 复用缓冲区
+
+如果你想避免每次调用都分配新的 `Uint8List`，可以配合显式 `Buffer` 使用 `serializeTo` 和 `deserializeFrom`：
+
+```dart
+final fory = Fory();
+final buffer = Buffer();
+
+fory.serializeTo(Int32(42), buffer);
+final value = fory.deserializeFrom<Int32>(buffer);
+```
+
+这是性能优化手段。对大多数应用来说，默认的 `serialize` / `deserialize` 就足够了。
+
+## 在序列化前注册类型
+
+在序列化自定义类或枚举之前，必须先把它注册到 `Fory` 中。生成代码会让这件事变得很简单：
+
+```dart
+PersonFory.register(
+ fory,
+ Person,
+ id: 100,
+);
+```
+
+如果跳过注册，运行时会得到 `Type ... is not registered` 错误。参见 [类型注册](type-registration.md) 和 [代码生成](code-generation.md)。
+
+## 相关主题
+
+- [配置](configuration.md)
+- [类型注册](type-registration.md)
+- [字段配置](field-configuration.md)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/dart/code-generation.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/dart/code-generation.md
new file mode 100644
index 000000000..53b760eb5
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/dart/code-generation.md
@@ -0,0 +1,113 @@
+---
+title: 代码生成
+sidebar_position: 3
+id: dart_code_generation
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Fory 会在构建阶段为你的 Dart 类生成高性能序列化代码。你只需要给模型加注解、运行 `build_runner`，剩下的由 Fory 处理。
+
+## 第一步：给模型加注解
+
+为每个需要序列化的类添加 `@ForyStruct()`。同时在文件顶部加入生成的 `part` 指令。
+
+```dart
+import 'package:fory/fory.dart';
+
+part 'models.fory.dart';
+
+@ForyStruct()
+class Address {
+ Address();
+
+ String city = '';
+ String street = '';
+}
+
+@ForyStruct()
+class User {
+ User();
+
+ String name = '';
+ Int32 age = Int32(0);
+ Address address = Address();
+}
+```
+
+定义在同一文件中的枚举会自动包含到生成的注册代码里。
+
+## 第二步：运行生成器
+
+在包含 `pubspec.yaml` 的目录下运行：
+
+```bash
+dart run build_runner build --delete-conflicting-outputs
+```
+
+这会在源文件旁边生成一个 `.fory.dart` 文件。每当你新增或重命名带注解的类型时，都需要重新运行这个命令。
+
+## 第三步：注册并使用
+
+生成器会创建一个以源文件命名的命名空间，并提供 `register` 函数。请在序列化前调用它：
+
+```dart
+final fory = Fory();
+ModelsFory.register(fory, Address, id: 1);
+ModelsFory.register(fory, User, id: 2);
+```
+
+也可以用稳定名称代替数字 ID，这在跨语言场景中更有用：
+
+```dart
+ModelsFory.register(
+ fory,
+ User,
+ namespace: 'example',
+ typeName: 'User',
+);
+```
+
+关于如何在 ID 和名称之间做选择，见 [类型注册](type-registration.md)。
+
+## Schema 演进：`evolving`
+
+`@ForyStruct()` 默认使用 `evolving: true`，这对大多数应用都是正确选择。
+
+- `evolving: true`：Fory 会保存足够的元信息，因此当你之后新增或删除字段时，旧代码与新代码仍然可以交换消息。只要你的应用或服务可能存在多个版本同时运行，就应该启用它。
+- `evolving: false`：不写入额外元信息，载荷会略小一些。只有在写端和读端总是一起升级时才安全。
+
+```dart
+// evolving: true 是默认值，可以省略
+@ForyStruct(evolving: true)
+class Event {
+ Event();
+
+ String name = '';
+}
+```
+
+使用 evolving 结构体时，也要在首次对外发送载荷之前通过 `@ForyField(id: ...)` 为字段分配稳定 ID，因为 Fory 会依赖这些 ID 在 Schema 变化后匹配字段。
+
+## 什么时候不要使用代码生成
+
+如果你无法给某个类型加注解，例如它来自一个你无法修改的第三方包，那就改用 [自定义序列化器](custom-serializers.md)。
+
+## 相关主题
+
+- [类型注册](type-registration.md)
+- [字段配置](field-configuration.md)
+- [Schema 演进](schema-evolution.md)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/dart/configuration.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/dart/configuration.md
new file mode 100644
index 000000000..0f53ceb69
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/dart/configuration.md
@@ -0,0 +1,121 @@
+---
+title: 配置
+sidebar_position: 1
+id: dart_configuration
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍 `Fory` 构造函数的可选项。
+
+## 创建 `Fory` 实例
+
+直接把选项传给构造函数：
+
+```dart
+import 'package:fory/fory.dart';
+
+// 默认配置，适合大多数单服务场景
+final fory = Fory();
+
+// 需要 Schema 演进的跨语言服务
+final fory = Fory(
+ compatible: true,
+ maxDepth: 512,
+);
+```
+
+每个应用创建一个实例并复用即可。按请求新建 `Fory` 没有任何收益。
+
+## 选项
+
+### `compatible`
+
+当你的服务需要处理来自另一份模型版本代码的载荷时，请设置为 `true`。例如各服务独立发布，无法保证通信双方同时升级。
+
+```dart
+final fory = Fory(compatible: true);
+```
+
+当 `compatible: true` 时：
+
+- 一侧新增或删除字段不会破坏另一侧。
+- 各端仍然必须使用相同的 `namespace` + `typeName`，或者相同的数字 `id` 来标识类型。
+
+当 `compatible: false`（默认）时：
+
+- 双方必须拥有完全相同的 Schema。这样会略快一些，适合仅有 Dart 服务或始终一起升级的场景。
+
+### `checkStructVersion`
+
+仅在 `compatible: false` 时相关。当它为 `true` 时，Fory 会校验载荷中的 Schema 版本是否与接收端已知版本一致，从而在运行时尽早发现误用的 Schema。
+
+```dart
+final fory = Fory(
+ compatible: false,
+ checkStructVersion: true, // default
+);
+```
+
+当 `compatible: true` 时，这个选项不起作用。
+
+### `maxDepth`
+
+限制对象图的最大嵌套深度。如果你的数据确实有很深的树形结构，可以增大它；如果你想快速拒绝异常深的载荷，可以减小它。
+
+```dart
+final fory = Fory(maxDepth: 128);
+```
+
+### `maxCollectionSize`
+
+任意单个 list、set 或 map 字段可接受的最大元素数。用于防止畸形消息触发失控的内存分配。
+
+```dart
+final fory = Fory(maxCollectionSize: 100000);
+```
+
+### `maxBinarySize`
+
+任意单个二进制 blob 字段允许接受的最大字节数。
+
+```dart
+final fory = Fory(maxBinarySize: 8 * 1024 * 1024);
+```
+
+## 默认值
+
+| 选项 | 默认值 |
+| -------------------- | --------- |
+| `compatible` | `false` |
+| `checkStructVersion` | `true` |
+| `maxDepth` | 256 |
+| `maxCollectionSize` | 1 048 576 |
+| `maxBinarySize` | 64 MiB |
+
+## 跨语言说明
+
+当 Fory 用于不同语言实现的服务之间通信时：
+
+- 如果任意一端需要 Schema 演进，则**所有**端都应设置 `compatible: true`。
+- 每一端都要使用相同的数字 ID，或者相同的 `namespace + typeName` 组合。
+- 写端和读端的 `compatible` 设置必须一致，模式不匹配会直接失败。
+
+## 相关主题
+
+- [基础序列化](basic-serialization.md)
+- [Schema 演进](schema-evolution.md)
+- [跨语言](cross-language.md)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/dart/cross-language.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/dart/cross-language.md
new file mode 100644
index 000000000..08560d943
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/dart/cross-language.md
@@ -0,0 +1,193 @@
+---
+title: 跨语言序列化
+sidebar_position: 9
+id: dart_cross_language
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Apache Fory™ Dart 生成的二进制格式与 Java、Go、C#、Python、Rust 和 Swift 的 Fory 运行时保持一致。你可以在 Dart 中写消息，在 Java 中读取，或者反过来，整个过程都不需要额外的转换层。
+
+## 设置
+
+像平常一样创建 `Fory` 实例即可。Dart 中不需要单独开启“跨语言模式”：
+
+```dart
+final fory = Fory(); // 或者在需要 Schema 演进时使用 Fory(compatible: true)
+```
+
+关键要求是：通信两端必须用同一身份注册同一个类型。
+
+## 注册身份
+
+最重要的规则是：**每一端都要使用相同的类型身份**。你有两种选择：
+
+### 数字 ID
+
+更适合小团队、强协同的场景：
+
+```dart
+// Dart
+ModelsFory.register(fory, Person, id: 100);
+```
+
+### Namespace + Type Name
+
+更适合多个团队分别定义类型的场景：
+
+```dart
+// Dart
+ModelsFory.register(
+ fory,
+ Person,
+ namespace: 'example',
+ typeName: 'Person',
+);
+```
+
+不要在不同运行时上对同一个类型混用这两种策略。
+
+## Dart 到 Java 示例
+
+### Dart
+
+```dart
+import 'package:fory/fory.dart';
+
+part 'person.fory.dart';
+
+@ForyStruct()
+class Person {
+ Person();
+
+ String name = '';
+ Int32 age = Int32(0);
+}
+
+final fory = Fory();
+PersonFory.register(fory, Person, id: 100);
+final bytes = fory.serialize(Person()
+ ..name = 'Alice'
+ ..age = Int32(30));
+```
+
+### Java
+
+```java
+Fory fory = Fory.builder()
+ .withLanguage(Language.XLANG)
+ .build();
+
+fory.register(Person.class, 100);
+Person value = (Person) fory.deserialize(bytesFromDart);
+```
+
+## Dart 到 C# 示例
+
+### Dart
+
+```dart
+final fory = Fory(compatible: true);
+PersonFory.register(fory, Person, id: 100);
+final bytes = fory.serialize(Person()
+ ..name = 'Alice'
+ ..age = Int32(30));
+```
+
+### CSharp
+
+```csharp
+[ForyObject]
+public sealed class Person
+{
+ public string Name { get; set; } = string.Empty;
+ public int Age { get; set; }
+}
+
+Fory fory = Fory.Builder()
+ .Compatible(true)
+ .Build();
+
+fory.Register<Person>(100);
+Person person = fory.Deserialize<Person>(payloadFromDart);
+```
+
+## Dart 到 Go 示例
+
+### Dart
+
+```dart
+final fory = Fory();
+PersonFory.register(fory, Person, id: 100);
+final bytes = fory.serialize(Person()
+ ..name = 'Alice'
+ ..age = Int32(30));
+```
+
+### Go
+
+```go
+type Person struct {
+ Name string
+ Age int32
+}
+
+f := fory.New(fory.WithXlang(true))
+_ = f.RegisterStruct(Person{}, 100)
+
+var person Person
+_ = f.Deserialize(bytesFromDart, &person)
+```
+
+## 字段匹配规则
+
+Fory 会按字段名或稳定字段 ID 匹配字段。为了获得稳健的跨语言互操作性：
+
+1. 各端对同一类型使用相同的类型身份，即相同的数字 ID 或相同的 `namespace + typeName`。
+2. 在首次对外发送载荷之前，为所有字段分配稳定的 `@ForyField(id: ...)`。
+3. 保持字段名一致，或者依赖字段 ID，因为 Dart 通常使用 `lowerCamelCase`，Go 为导出字段使用 `PascalCase`，C# 也常用 `PascalCase` 属性。
+4. 使用兼容的数字类型：当对端为 Java `int`、Go `int32` 或 C# `int` 时，在 Dart 中使用 `Int32`；Dart 的 `double` 对应 64 位浮点；32 位浮点请使用 `Float32`。
+5. 日期时间字段优先使用 `Timestamp` 和 `LocalDate`，不要直接用原始 `DateTime`。
+6. 发布前一定要在所有目标语言间完成真实 round trip 验证。
+
+## Dart 的类型映射说明
+
+由于 Dart `int` 本身并不承诺精确的跨语言编码宽度，所以一旦跨语言解释需要精确定义，就应优先使用包装类型或数字字段注解：
+
+- `Int32` 对应 xlang `int32`
+- `UInt32` 对应 xlang `uint32`
+- `Float16` 和 `Float32` 对应用于较小宽度的浮点数
+- `Timestamp` 和 `LocalDate` 用于显式的时间语义
+
+参见 [支持的类型](supported-types.md) 和 [xlang type mapping](../../specification/xlang_type_mapping.md)。
+
+## 验证
+
+在生产环境依赖跨语言契约之前，请让每一种支持的运行时都完成端到端验证。
+
+运行 Dart 端：
+
+```bash
+dart run build_runner build --delete-conflicting-outputs
+dart analyze
+dart test
+```
+
+## 相关主题
+
+- [类型注册](type-registration.md)
+- [Schema 演进](schema-evolution.md)
+- [跨语言指南](../xlang/index.md)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/dart/custom-serializers.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/dart/custom-serializers.md
new file mode 100644
index 000000000..43052efd7
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/dart/custom-serializers.md
@@ -0,0 +1,139 @@
+---
+title: 自定义序列化器
+sidebar_position: 5
+id: dart_custom_serializers
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+自定义序列化器让你可以完全控制某个类型如何编码和解码。通常只有在以下情况才需要使用它：
+
+- 类型来自你无法修改的第三方包，无法添加 `@ForyStruct()`
+- 你需要完全自定义的二进制布局
+- 你要实现 union / discriminated type
+
+对于你自己的模型，`@ForyStruct()` 配合代码生成几乎总是更好的选择。
+
+## 实现 `Serializer<T>`
+
+继承 `Serializer<T>` 并实现 `write` 和 `read`。通过 `context.buffer` 直接读写原始字节：
+
+```dart
+import 'package:fory/fory.dart';
+
+final class Person {
+ Person(this.name, this.age);
+
+ final String name;
+ final int age;
+}
+
+final class PersonSerializer extends Serializer<Person> {
+ const PersonSerializer();
+
+ @override
+ void write(WriteContext context, Person value) {
+ final buffer = context.buffer;
+ buffer.writeUtf8(value.name);
+ buffer.writeInt64(value.age);
+ }
+
+ @override
+ Person read(ReadContext context) {
+ final buffer = context.buffer;
+ return Person(buffer.readUtf8(), buffer.readInt64());
+ }
+}
+```
+
+在使用前先注册这个序列化器：
+
+```dart
+final fory = Fory();
+fory.registerSerializer(
+ Person,
+ const PersonSerializer(),
+ namespace: 'example',
+ typeName: 'Person',
+);
+```
+
+## 写入嵌套对象
+
+如果自定义序列化器中的某个字段本身也是由 Fory 管理的类型，请使用 `context.writeRef` 和 `context.readRef`，而不是递归调用 `fory.serialize`。这样才能保持引用跟踪正确，也避免在嵌套载荷里再写入完整根帧。
+
+```dart
+@override
+void write(WriteContext context, Wrapper value) {
+ context.writeRef(value.child);
+}
+
+@override
+Wrapper read(ReadContext context) {
+ return Wrapper(context.readRef() as Child);
+}
+```
+
+如果你明确知道某个嵌套值永远不会在对象图中重复出现，也不需要保持引用标识，可以用 `writeNonRef`：
+
+```dart
+context.writeNonRef(value.child);
+```
+
+## Union
+
+对于带判别标签的 union，请继承 `UnionSerializer<T>` 而不是 `Serializer<T>`。先写入判别值，再写入当前激活的变体；读取时先解析判别值，再分派到正确分支。
+
+```dart
+final class ShapeSerializer extends UnionSerializer<Shape> {
+ const ShapeSerializer();
+
+ @override
+ void write(WriteContext context, Shape value) {
+ // write active variant
+ }
+
+ @override
+ Shape read(ReadContext context) {
+ // read discriminant, return correct variant
+ throw UnimplementedError();
+ }
+}
+```
+
+## 自定义序列化器中的循环引用
+
+如果你的序列化器会遇到循环对象图，那么在读取嵌套字段之前，必须先把对象绑定到引用跟踪器中：
+
+```dart
+final value = Node.empty();
+context.reference(value); // register the object first
+value.next = context.readRef() as Node?; // now nested reads can refer back to it
+return value;
+```
+
+跳过这一步会导致指向该对象的回溯引用解析成 `null`。
+
+## 提示
+
+- 在热点路径中，优先使用 `context.buffer` 直接读写字节。
+- 在所有端上，都用相同的身份注册该序列化器，即相同的 `id` 或相同的 `namespace + typeName`。
+
+## 相关主题
+
+- [类型注册](type-registration.md)
+- [跨语言](cross-language.md)
+- [故障排查](troubleshooting.md)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/dart/field-configuration.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/dart/field-configuration.md
new file mode 100644
index 000000000..a5a414cd4
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/dart/field-configuration.md
@@ -0,0 +1,127 @@
+---
+title: 字段配置
+sidebar_position: 6
+id: dart_field_configuration
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+在 `@ForyStruct()` 类中的字段上添加 `@ForyField(...)`，即可改变该字段的序列化方式。
+
+## 快速参考
+
+```dart
+@ForyField(
+ skip: false, // exclude the field from serialization
+ id: 10, // stable field ID for schema evolution
+ nullable: true, // override nullability detection
+ ref: true, // enable reference tracking for this field
+ dynamic: false, // control whether the runtime type is written
+)
+```
+
+## `skip`
+
+完全把该字段排除在序列化之外。适合缓存值、计算值或仅用于 UI 的值，这些值不应该进入持久化或传输消息。
+
+```dart
+@ForyField(skip: true)
+String cachedDisplayName = '';
+```
+
+## `id`
+
+为字段分配稳定身份，这样在 Schema 变化后，例如字段重命名或重排时，Fory 仍然可以通过 ID 匹配它。**如果你未来可能新增、删除或重命名字段，请现在就为所有字段分配 ID**，而且要在第一份载荷发出之前完成。
+
+```dart
+@ForyField(id: 1)
+String name = '';
+```
+
+一旦载荷已经在服务之间共享，就永远不要把某个 `id` 复用到另一个不同字段上。
+
+## `nullable`
+
+显式声明字段是可空还是非可空，从而覆盖 Fory 根据 Dart 类型做出的推断。当 Dart 类型是非可空，但你仍希望 Fory 在线路上接受 `null` 时，可以使用它，例如为了读取旧生产者生成、可能省略该字段的消息。
+
+```dart
+@ForyField(nullable: true)
+String nickname = '';
+```
+
+在跨语言场景下，也要确保可空性契约与对端运行时的预期一致。
+
+## `ref`
+
+为某个字段启用引用跟踪。当对象图中的多个对象可能引用同一个实例，或该字段类型本身可能形成循环时，请使用这个选项。没有 `ref: true` 时，如果同一个对象出现在两个字段里，Fory 会把它的值序列化两次。
+
+```dart
+@ForyField(ref: true)
+List<Object?> sharedNodes = <Object?>[];
+```
+
+注意：即使设置了 `ref: true`，像 `int`、`double`、`bool` 这样的标量类型也不会从引用跟踪中受益。
+
+## `dynamic`
+
+控制 Fory 是否把字段值的具体运行时类型写入载荷。
+
+- `null`（默认）：Fory 根据声明类型自动决定。
+- `false`：始终使用字段的声明类型，载荷更紧凑，但反序列化端必须知道精确类型。
+- `true`：始终写入实际运行时类型；当字段声明为 `Object?` 或基类，但运行时可能持有多种具体类型时，这是必需的。
+
+```dart
+@ForyField(dynamic: true)
+Object? payload; // can hold any registered type at runtime
+```
+
+## 数字字段注解
+
+Dart `int` 在运行时是 64 位值。当你与 Java、Go 或 C# 交换消息时，对端可能期望更窄的整数类型。可以使用数字注解来固定精确的编码格式：
+
+```dart
+@ForyStruct()
+class Sample {
+ Sample();
+
+ @Int32Type(compress: false) // always writes 4 bytes
+ int fixedWidthInt = 0;
+
+ @Int64Type(encoding: LongEncoding.tagged) // variable-length encoding
+ int compactLong = 0;
+
+ @Uint32Type(compress: true) // variable-length unsigned
+ int smallUnsigned = 0;
+}
+```
+
+可用注解包括：`@Int32Type`、`@Int64Type`、`@Uint8Type`、`@Uint16Type`、`@Uint32Type`、`@Uint64Type`。
+
+或者，也可以使用 [支持的类型](supported-types.md) 中介绍的显式包装类型，例如 `Int32`、`UInt32` 等。
+
+## 跨语言字段对齐
+
+当同一个模型在多种语言中分别定义时：
+
+- 为所有未来可能变化的字段分配稳定 `id`。
+- 对真正具备多态性的字段使用 `dynamic: true`。
+- 保持字段的逻辑含义在各语言之间一致。Fory 可以按名称或 ID 匹配字段，但无法替你弥合语义上的差异。
+
+## 相关主题
+
+- [代码生成](code-generation.md)
+- [Schema 演进](schema-evolution.md)
+- [跨语言](cross-language.md)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/dart/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/dart/index.md
new file mode 100644
index 000000000..fab52fbba
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/dart/index.md
@@ -0,0 +1,141 @@
+---
+title: Dart 序列化指南
+sidebar_position: 0
+id: dart_serialization_index
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Apache Fory™ Dart 可以把 Dart 对象序列化为字节，再从字节反序列化回来，并且支持与 Java、Go、C#、Python 以及其他 Fory 支持语言编写的服务进行互通。
+
+## 为什么选择 Fory Dart？
+
+- **跨语言**：在 Dart 中序列化，在 Java、Go、C# 等语言中反序列化，无需额外胶水代码
+- **高性能**：生成的序列化代码会替代运行时反射
+- **Schema 演进**：可以新增或删除字段，而不破坏已有消息
+- **循环引用**：可选的引用跟踪可处理共享或递归对象图
+- **逃生口**：对任何无法加注解的类型，你都可以手写序列化器
+
+## 快速开始
+
+### 要求
+
+- Dart SDK 3.6 或更高版本
+- `build_runner`，用于生成序列化代码
+
+### 安装
+
+把依赖加入你的 `pubspec.yaml`：
+
+```yaml
+dependencies:
+ fory: ^0.17.0
+
+dev_dependencies:
+ build_runner: ^2.4.0
+```
+
+### 基础示例
+
+定义模型，先运行一次生成器，然后进行序列化：
+
+```dart
+import 'package:fory/fory.dart';
+
+part 'person.fory.dart';
+
+enum Color {
+ red,
+ blue,
+}
+
+@ForyStruct()
+class Person {
+ Person();
+
+ String name = '';
+ Int32 age = Int32(0);
+ Color favoriteColor = Color.red;
+ List<String> tags = <String>[];
+}
+
+void main() {
+ final fory = Fory();
+ PersonFory.register(
+ fory,
+ Color,
+ namespace: 'example',
+ typeName: 'Color',
+ );
+ PersonFory.register(
+ fory,
+ Person,
+ namespace: 'example',
+ typeName: 'Person',
+ );
+
+ final person = Person()
+ ..name = 'Ada'
+ ..age = Int32(36)
+ ..favoriteColor = Color.blue
+ ..tags = <String>['engineer', 'mathematician'];
+
+ final bytes = fory.serialize(person);
+ final roundTrip = fory.deserialize<Person>(bytes);
+ print(roundTrip.name);
+}
+```
+
+在运行程序之前，先生成配套文件：
+
+```bash
+dart run build_runner build --delete-conflicting-outputs
+```
+
+`PersonFory` 由 `build_runner` 生成。`namespace` 和 `typeName` 是其他语言中的对端识别同一类型的方式，一旦服务进入生产环境，就应保持稳定。
+
+## API 概览
+
+- `Fory(...)`：创建序列化实例；创建一次并复用
+- `fory.serialize(value)`：返回 `Uint8List` 字节
+- `fory.deserialize<T>(bytes)`：返回一个 `T`
+- `@ForyStruct()`：标记需要生成代码的类
+- `@ForyField(...)`：字段级选项，例如跳过、ID、可空性、引用
+- 整数包装类型：`Int8`、`Int16`、`Int32`、`UInt8`、`UInt16`、`UInt32`
+- 浮点包装类型：`Float16`、`Float32`
+- 时间包装类型：`LocalDate`、`Timestamp`
+
+## 文档
+
+| 主题 | 说明 |
+| --------------------------------------------- | ------------------------------------ |
+| [配置](configuration.md) | 运行时选项、兼容模式和安全限制 |
+| [基础序列化](basic-serialization.md) | `serialize`、`deserialize`、生成注册、根对象图 |
+| [代码生成](code-generation.md) | `@ForyStruct`、build runner 和生成命名空间 |
+| [类型注册](type-registration.md) | 基于 ID 与基于名称的注册，以及注册规则 |
+| [自定义序列化器](custom-serializers.md) | 手写 `Serializer<T>` 实现与 union |
+| [字段配置](field-configuration.md) | `@ForyField`、字段 ID、可空性、引用、多态 |
+| [支持的类型](supported-types.md) | 内置 xlang 值、包装类型、集合和结构体 |
+| [Schema 演进](schema-evolution.md) | 兼容结构体与可演进 Schema |
+| [跨语言](cross-language.md) | 互操作规则与字段对齐 |
+| [故障排查](troubleshooting.md) | 常见错误、诊断方法和验证步骤 |
+
+## 相关资源
+
+- [Xlang 序列化规范](../../specification/xlang_serialization_spec.md)
+- [Xlang 实现指南](../../specification/xlang_implementation_guide.md)
+- [跨语言指南](../xlang/index.md)
+- [Dart 运行时源码目录](https://github.com/apache/fory/tree/main/dart)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/dart/schema-evolution.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/dart/schema-evolution.md
new file mode 100644
index 000000000..267cd63f3
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/dart/schema-evolution.md
@@ -0,0 +1,92 @@
+---
+title: Schema 演进
+sidebar_position: 8
+id: dart_schema_evolution
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Schema 演进让应用的不同版本之间也能安全交换消息。例如，v2 写出的消息仍然可以被 v1 读取，反过来也一样。
+
+## 两种模式
+
+### 兼容模式（推荐给会演进的服务）
+
+当服务可能同时运行不同版本时启用它，例如滚动发布期间，或者客户端无法立即升级时。
+
+```dart
+final fory = Fory(compatible: true);
+```
+
+在兼容模式下，Fory 会在每条消息中写入足够的字段元信息，使读端能够跳过未知字段，并为缺失字段使用默认值。请用稳定字段 ID 来锚定跨版本 Schema。
+
+### Schema 一致模式（默认）
+
+通信双方必须拥有同一个模型。Fory 会校验双方 Schema 是否一致，并拒绝来自其他 Schema 版本的消息。适用于所有服务总是一起升级，并且你希望尽早把 Schema 不匹配直接报错的场景。
+
+```dart
+final fory = Fory(); // compatible: false by default
+```
+
+## 为演进做好准备
+
+为了安全地使用兼容模式，请给结构体添加 `@ForyStruct(evolving: true)`（默认值），并在第一次对外发送载荷之前，为每个字段都分配稳定的 `@ForyField(id: ...)`：
+
+```dart
+@ForyStruct(evolving: true)
+class UserProfile {
+ UserProfile();
+
+ @ForyField(id: 1)
+ String name = '';
+
+ @ForyField(id: 2, nullable: true)
+ String? nickname;
+}
+```
+
+如果载荷已经在生产环境中存在之后你才补加字段 ID，那么旧消息里不会包含这些 ID，Schema 演进也就无法正确工作。
+
+## 哪些变更是安全的
+
+**安全变更**（双方兼容）：
+
+- 新增一个带新字段 ID 的可选字段
+- 重命名字段，只要 `@ForyField(id: ...)` 保持不变
+- 删除字段，对端会忽略缺失值并使用 Dart 默认值
+
+**危险变更**（可能破坏已有消息）：
+
+- 把一个已有字段 ID 复用给另一个不同字段
+- 将字段类型改为不兼容类型，例如 `Int32` 改成 `String`
+- 在消息进入生产环境后修改某个类型的注册身份，即 `id`、`namespace` 或 `typeName`
+- 不改字段 ID，却改变字段的逻辑含义
+
+## 跨语言说明
+
+只有在**所有**交换消息的运行时都一致满足以下条件时，Schema 演进才会生效：
+
+1. 使用相同的 `compatible` 设置。
+2. 使用相同的类型注册身份，即相同的数字 ID，或者相同的 `namespace + typeName`。
+3. 对字段 ID 的逻辑含义有相同理解。
+
+部署前请用真实 round trip 覆盖滚动升级场景。
+
+## 相关主题
+
+- [配置](configuration.md)
+- [字段配置](field-configuration.md)
+- [跨语言](cross-language.md)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/dart/supported-types.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/dart/supported-types.md
new file mode 100644
index 000000000..a6d996ce4
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/dart/supported-types.md
@@ -0,0 +1,102 @@
+---
+title: 支持的类型
+sidebar_position: 7
+id: dart_supported_types
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页列出可在 Fory 消息中使用的 Dart 类型，并标出哪些地方在跨语言兼容性上需要特别小心。
+
+## 内置原始类型
+
+以下 Dart 类型可以直接序列化，不需要特殊处理：
+
+| Dart 类型 | 跨语言说明 |
+| -------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `bool` | 直接映射 |
+| `int` | 默认按 64 位序列化。如果对端期望更窄的整数，请使用包装类型或 `@Int32Type` 等注解 |
+| `double` | 映射为 64 位浮点数。如果对端期望 32 位浮点，请使用 `Float32` 包装类型 |
+| `String` | 直接映射 |
+| `Uint8List` | 二进制 blob |
+| `List`, `Set`, `Map` | 支持，但元素类型也必须是受支持类型 |
+| `DateTime` | 如需明确语义，请使用 `Timestamp` 或 `LocalDate` 包装类型 |
+
+## 整数包装类型
+
+Dart `int` 在运行时是 64 位值。如果对端语言期望 32 位整数，例如 Java `int`、Go `int32`、C# `int`，而你发送的是 Dart `int`，反序列化可能失败，或者静默截断。
+
+使用整数包装类型可以固定精确的编码宽度：
+
+```dart
+final Int8 tiny = Int8(-1); // 8-bit signed
+final Int16 shortValue = Int16(7); // 16-bit signed
+final Int32 age = Int32(36); // 32-bit signed — matches Java int, C# int, Go int32
+final UInt8 flags = UInt8(255); // 8-bit unsigned
+final UInt16 port = UInt16(65535); // 16-bit unsigned
+final UInt32 count = UInt32(4000000000); // 32-bit unsigned
+```
+
+每个包装类型都会把存储值限制在目标位宽内。
+
+## 浮点包装类型
+
+Dart `double` 对应 64 位浮点。如果对端使用 32 位浮点，请改用包装类型：
+
+- `Float32`：32 位浮点，对应 Java `float`、C# `float`、Go `float32`
+- `Float16`：半精度浮点，适用于专门的数值载荷
+
+## 时间和日期类型
+
+不要直接把原始 `DateTime` 跨语言发送。时区处理和 epoch 差异在不同语言间并不完全一致。请改用下面这些显式包装类型：
+
+- `Timestamp`：带纳秒精度的 UTC 时间点，即秒数加纳秒数
+- `LocalDate`：不带时间和时区的日历日期
+
+```dart
+final now = Timestamp.fromDateTime(DateTime.now().toUtc());
+final birthday = LocalDate(1990, 12, 1);
+```
+
+## Struct 和 Enum
+
+给类添加 `@ForyStruct()`，然后运行 `build_runner`，它们就能序列化。定义在同一文件中的枚举会自动包含进去。
+
+```dart
+@ForyStruct()
+class User {
+ User();
+
+ String name = '';
+ Int32 age = Int32(0); // use Int32 when peers expect a 32-bit integer
+}
+```
+
+参见 [代码生成](code-generation.md)。
+
+## 集合
+
+Fory 支持 `List<T>`、`Set<T>` 和 `Map<K, V>`。元素类型和键类型本身也必须可序列化。请避免使用可变对象作为 map 键。
+
+## 兼容性提示
+
+一旦不确定某个 Dart 类型是否与对端预期一致，就优先使用显式包装类型。数字宽度选错，是跨语言场景里最常见的 bug 之一。
+
+## 相关主题
+
+- [字段配置](field-configuration.md)
+- [跨语言](cross-language.md)
+- [Schema 演进](schema-evolution.md)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/dart/troubleshooting.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/dart/troubleshooting.md
new file mode 100644
index 000000000..5be8b796a
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/dart/troubleshooting.md
@@ -0,0 +1,103 @@
+---
+title: 故障排查
+sidebar_position: 10
+id: dart_troubleshooting
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页汇总 Dart 运行时中常见的问题及其修复方式。
+
+## `Only xlang payloads are supported by the Dart runtime.`
+
+写端发送的是 native-mode（非 xlang）载荷。请确保每个服务都走跨语言兼容路径：
+
+- **Java**：在 Fory builder 上添加 `.withLanguage(Language.XLANG)`。
+- **Go**：在 Fory 选项中使用 `WithXlang(true)`。
+- **其他运行时**：查看各自文档，确认如何启用跨语言模式。
+
+## `Type ... is not registered.`
+
+Fory 不知道如何序列化或反序列化这个类型。可按以下方式修复：
+
+1. 如果还没生成代码，先运行：`dart run build_runner build --delete-conflicting-outputs`
+2. 在调用 `serialize` 或 `deserialize` **之前**，先调用生成的 `register` 函数，或者 `registerSerializer`
+3. 注册消息中可能出现的**所有**类型，而不仅仅是根类型。例如，如果 `Order` 包含 `Address`，那两者都要注册
+
+## 生成的 part 文件缺失或已过期
+
+重新生成代码：
+
+```bash
+cd dart/packages/fory
+dart run build_runner build --delete-conflicting-outputs
+```
+
+如果你移动了文件或重命名了类型，请在重新执行分析或测试前先重新构建。
+
+## `Deserialized value has type ..., expected ...`
+
+载荷描述的类型与 `deserialize<T>` 中的 `T` 不一致。常见原因包括：
+
+- 写端注册该类型时使用的 ID 或名称，与读端不一致
+- 载荷来自另一条代码路径，根对象类型不同
+- 你正在反序列化异构容器。应先按 `Object?` 或 `List<Object?>` 解码，再做类型转换
+
+## 反序列化后对象不再是同一个实例
+
+默认情况下，Fory 不会跟踪对象标识，因此两个字段如果指向同一个对象，round trip 后会变成两个独立副本。
+
+如果需要保留对象标识：
+
+- 对 `@ForyStruct` 内部字段，在对应字段上加 `@ForyField(ref: true)`
+- 对顶层集合，调用 `fory.serialize(...)` 时传入 `trackRef: true`
+- 在自定义序列化器中，使用 `context.writeRef` / `context.readRef`，并在读取嵌套字段之前先调用 `context.reference(obj)`
+
+## 跨语言字段不匹配（数据缺失或值错误）
+
+典型症状：往返另一种语言后，字段变成默认值，或者类型错误。
+
+检查清单：
+
+1. 双方使用相同的注册身份，即相同数字 ID，**或**相同的 `namespace + typeName`
+2. 在第一份载荷发送前，就已经分配了稳定 `@ForyField(id: ...)`
+3. 数字宽度兼容。当对端字段是 Java `int`、Go `int32` 或 C# `int` 时，在 Dart 端使用 `Int32`
+4. 日期时间字段使用 `Timestamp` / `LocalDate`，而不是原始 `DateTime`
+5. 如果用到 Schema 演进，则**双方**都要开启 `compatible: true`
+
+## 本地运行测试
+
+主 Dart 包：
+
+```bash
+dart run build_runner build --delete-conflicting-outputs
+dart analyze
+dart test
+```
+
+集成测试包：
+
+```bash
+cd dart/packages/fory-test
+dart run build_runner build --delete-conflicting-outputs
+dart test
+```
+
+## 相关主题
+
+- [跨语言](cross-language.md)
+- [代码生成](code-generation.md)
+- [自定义序列化器](custom-serializers.md)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/dart/type-registration.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/dart/type-registration.md
new file mode 100644
index 000000000..bd5f7e097
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/dart/type-registration.md
@@ -0,0 +1,98 @@
+---
+title: 类型注册
+sidebar_position: 4
+id: dart_type_registration
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Fory 需要知道序列化消息中的某个类型对应哪个类。你要做的，就是在序列化或反序列化之前注册每个类。
+
+## 选择注册策略
+
+Fory 提供两种策略。选定一种后，就要在所有读写该类型的语言里保持一致。
+
+### 策略一：数字 ID
+
+更紧凑，也更快。适合小团队在服务间统一协调 ID。
+
+```dart
+ModelsFory.register(fory, User, id: 100);
+```
+
+其他语言里也必须使用相同的数字：
+
+```java
+// Java side
+fory.register(User.class, 100);
+```
+
+### 策略二：Namespace + Type Name
+
+自描述性更强。适合多个团队或多个包独立定义类型，而协调数字 ID 不现实的场景。
+
+```dart
+ModelsFory.register(
+ fory,
+ User,
+ namespace: 'example',
+ typeName: 'User',
+);
+```
+
+每个读写该类型的运行时都必须使用相同的 `namespace` 和 `typeName`。
+
+> **不要对同一个类型混用策略。** 如果一侧使用数字 ID，另一侧使用名称，反序列化会失败。
+
+## 注册生成类型
+
+调用 `.fory.dart` 文件中生成的 `register` 函数，它会为你安装好所需的全部序列化元信息：
+
+```dart
+UserModelsFory.register(fory, User, id: 100);
+```
+
+## 注册自定义序列化器
+
+对于无法添加 `@ForyStruct()` 的类型，可以直接传入序列化器实例：
+
+```dart
+fory.registerSerializer(
+ ExternalType,
+ const ExternalTypeSerializer(),
+ namespace: 'example',
+ typeName: 'ExternalType',
+);
+```
+
+关于如何实现序列化器，见 [自定义序列化器](custom-serializers.md)。
+
+## 必须遵守的规则
+
+- 在第一次调用 `serialize` 或 `deserialize` **之前**完成注册
+- 注册消息中可能出现的**每一个**类，而不仅是根类型
+- 一旦载荷已经持久化，或已经在服务间交换，就必须保持 ID 或名称**稳定**
+- 对同一个类型，不要一侧用数字 ID，另一侧用名称
+
+## 跨语言要求
+
+所有读写该类型的运行时都必须使用相同的数字 ID，或者相同的 `namespace + typeName` 组合。示例见 [跨语言](cross-language.md)。
+
+## 相关主题
+
+- [代码生成](code-generation.md)
+- [跨语言](cross-language.md)
+- [自定义序列化器](custom-serializers.md)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/enum-configuration.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/enum-configuration.md
new file mode 100644
index 000000000..0b168034e
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/enum-configuration.md
@@ -0,0 +1,104 @@
+---
+title: 枚举配置
+sidebar_position: 6
+id: enum_configuration
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页说明如何在 Apache Fory 中配置 Java 枚举的序列化方式。
+
+## 默认枚举行为
+
+Java 枚举可以通过两种模式进行序列化：
+
+1. **按数值 tag**：默认行为
+2. **按枚举名称**：通过 `serializeEnumByName(true)` 启用
+
+在 xlang 模式下，始终使用数值 tag。在原生 Java 模式下，`serializeEnumByName(true)` 会把枚举序列化方式切换为按名称，而不是按数值 tag。
+
+## 按名称序列化枚举
+
+当原生 Java 对端应按名称而不是按数值 tag 匹配枚举常量时，请使用 `serializeEnumByName(true)`。
+
+```java
+Fory fory = Fory.builder()
+ .withLanguage(Language.JAVA)
+ .serializeEnumByName(true)
+ .build();
+```
+
+当声明顺序可能不稳定，但枚举名称保持固定时，这种模式很有用。它只影响原生 Java 模式；xlang 仍然使用数值 tag。
+
+## 稳定的数值枚举 ID
+
+如果未启用 `serializeEnumByName(true)`，Java 枚举会按数值 tag 序列化。默认的 tag 是声明顺序对应的 ordinal。如果枚举需要与声明顺序无关的稳定 ID，请只使用一种 `@ForyEnumId` 来源：要么标注唯一一个 ID 来源，要么为每个枚举常量都显式标注 tag 值。
+
+```java
+import org.apache.fory.annotation.ForyEnumId;
+
+enum Status {
+ Unknown(10),
+ Running(20),
+ Finished(30);
+
+ private final int id;
+
+ Status(int id) {
+ this.id = id;
+ }
+
+ @ForyEnumId
+ public int getId() {
+ return id;
+ }
+}
+```
+
+Java 也支持在某个枚举实例字段上标注 `@ForyEnumId`，或者直接在每个枚举常量上标注，例如 `@ForyEnumId(10) Unknown`。
+
+### `@ForyEnumId` 的三种样式
+
+`@ForyEnumId` 只支持以下三种配置方式：
+
+1. 标注一个枚举实例字段，并在该字段中保存数值 ID
+2. 标注一个无参 public 实例方法，例如 `getId()`
+3. 为每个枚举常量都直接标注显式值，例如 `@ForyEnumId(10) Unknown`
+
+### 校验规则
+
+1. 对于同一个枚举，只能使用上述三种方式中的一种
+2. 字段和方法上的注解必须保持 `value()` 为默认值 `-1`
+3. 一旦有任意一个枚举常量使用 `@ForyEnumId`，所有枚举常量都必须标注
+4. 所有 ID 都必须非负、唯一，并且能放入 Java `int`
+
+### 查找行为
+
+1. 没有 `@ForyEnumId` 时，Fory 写入声明顺序对应的 ordinal
+2. 使用 `@ForyEnumId` 时，Fory 会改为写入配置好的稳定数值 tag
+3. 对于较小且稠密的 tag，内部会使用数组查找；对稀疏且较大的 tag，则退回到 map 查找
+
+## 如何在名称模式和数值模式之间选择
+
+- 当枚举只在 Java 内部使用，且常量名才是兼容性主键时，使用**枚举名称**
+- 当需要处理跨语言载荷，或需要稳定的显式 ID 时，使用**数值 tag**
+- 当声明顺序可能变化，但编码格式中的数值 ID 必须保持稳定时，使用 **`@ForyEnumId`**
+
+## 相关主题
+
+- [配置选项](configuration.md) - `serializeEnumByName` 及其他运行时选项
+- [字段配置](field-configuration.md) - `@ForyField`、`@Ignore` 和整数编码注解
+- [跨语言序列化](cross-language.md) - Xlang 枚举互操作
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/virtual-threads.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/virtual-threads.md
new file mode 100644
index 000000000..40f46007c
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/virtual-threads.md
@@ -0,0 +1,114 @@
+---
+title: 虚拟线程
+sidebar_position: 8
+id: java_virtual_threads
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Apache Fory Java 在虚拟线程工作负载下应使用 `buildThreadSafeFory()`。它会构建一个固定大小的共享 `ThreadPoolFory`，其大小为 `4 * availableProcessors()`。如果你需要不同的固定池大小，请使用 `buildThreadSafeForyPool(poolSize)`。
+
+## 使用二进制输入/输出 API
+
+在使用虚拟线程时，应始终使用 Fory 的二进制输入/输出 API：
+
+- `serialize(Object)` 或 `serialize(MemoryBuffer, Object)`
+- `deserialize(byte[])` 或 `deserialize(MemoryBuffer)`
+
+典型用法：
+
+```java
+ThreadSafeFory fory = Fory.builder()
+ .requireClassRegistration(false)
+ .buildThreadSafeFory();
+
+byte[] bytes = fory.serialize(request);
+Object value = fory.deserialize(bytes);
+```
+
+## 在大量虚拟线程场景下不要使用 Stream API
+
+对于大量依赖虚拟线程的工作负载，不要使用基于 stream 或 channel 的 API：
+
+- `serialize(OutputStream, Object)`
+- `deserialize(ForyInputStream)`
+- `deserialize(ForyReadableChannel)`
+
+这些 API 会在整个阻塞调用期间一直占用一个池化的 `Fory` 实例。在大量虚拟线程场景下，这意味着许多 `Fory` 实例会在等待 I/O 时持续处于占用状态。每个 `Fory` 实例通常会使用大约 `30~50 KB` 内存，因此在阻塞 I/O 期间保留大量实例会很快累积出明显的内存开销。
+
+只有当你的虚拟线程数量至多是几百个，并且这些额外保留的 `Fory` 内存仍然可以接受时，才建议在虚拟线程中使用 stream API。
+
+## 为什么二进制 API 更合适
+
+序列化和反序列化属于 CPU 工作。Fory 本身足够快，因此这部分 CPU 时间通常远短于网络传输时间。
+
+在大多数情况下，你并不需要让网络传输与 Fory 反序列化重叠执行。Fory 反序列化的耗时通常不到网络传输时间的 `1/10`，因此相比尝试通过 Fory 逐步流式处理一个对象图，优化传输路径往往更重要。
+
+大多数 RPC 系统本身也是基于带帧的字节消息，而不是 Java 对象流。例如，gRPC 使用长度定界帧，这与 Fory 的二进制 API 天然契合。
+
+一个适合虚拟线程的模式是：
+
+1. 读取一条完整的带帧消息到字节数组中
+2. 调用 `fory.deserialize(bytes)`
+3. 生成响应对象
+4. 调用 `fory.serialize(response)`
+5. 将响应字节写成下一段带帧数据
+
+## 推荐模式
+
+```java
+byte[] requestBytes = readOneFrame(channel);
+Request request = (Request) fory.deserialize(requestBytes);
+
+Response response = handle(request);
+byte[] responseBytes = fory.serialize(response);
+writeOneFrame(channel, responseBytes);
+```
+
+这种方式让 Fory 只参与高效的 CPU 密集部分，而把阻塞 I/O 留在序列化器之外。
+
+## 超大载荷：分块的长度定界流式处理
+
+对于大多数场景，上述常规的带帧字节模式已经足够。只有在载荷非常大，并且你希望让传输与序列化/反序列化重叠时，才需要考虑分块流式处理。
+
+即便如此，也不要使用 Fory 自带的 stream API。正确做法是：把一个大载荷拆成多个子对象图，将每个子对象图分别序列化为 `byte[]`，然后按以下顺序写出：
+
+1. 帧长度
+2. 分块字节
+
+在虚拟线程中进行反序列化时：
+
+1. 读取帧长度
+2. 精确读取对应字节数
+3. 调用 `fory.deserialize(chunkBytes)`
+
+这样可以让传输按块推进，而 Fory 始终只处理完整的二进制帧。
+
+```java
+for (Object chunk : splitIntoSubGraphs(largePayload)) {
+ byte[] bytes = fory.serialize(chunk);
+ writeFrame(output, bytes);
+}
+
+while (hasMoreFrames(input)) {
+ int length = readLength(input);
+ byte[] bytes = readBytes(input, length);
+ Object chunk = fory.deserialize(bytes);
+ consumeChunk(chunk);
+}
+```
+
+长度定界帧非常常见，gRPC 也使用长度定界帧而不是 Java 对象流，因此这种模式与典型 RPC 和虚拟线程传输模型非常契合。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/javascript/_category_.json b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/javascript/_category_.json
new file mode 100644
index 000000000..2434e92ab
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/javascript/_category_.json
@@ -0,0 +1,6 @@
+{
+ "label": "JavaScript",
+ "position": 6,
+ "collapsible": true,
+ "collapsed": true
+}
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/javascript/basic-serialization.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/javascript/basic-serialization.md
new file mode 100644
index 000000000..78d3926d3
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/javascript/basic-serialization.md
@@ -0,0 +1,219 @@
+---
+title: 基础序列化
+sidebar_position: 1
+id: basic_serialization
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本指南介绍 Apache Fory JavaScript 中的核心序列化 API。
+
+## 创建 `Fory` 实例
+
+```ts
+import Fory from "@apache-fory/core";
+
+const fory = new Fory();
+```
+
+创建一个实例，注册你的 schema，并重复复用它。Fory 会在首次调用 `register` 后缓存生成的序列化器，因此如果每个请求都重新创建实例，就会浪费这部分工作。
+
+## 使用 `Type.struct` 定义 Schema
+
+最常见的方式是先定义 schema，再进行注册。
+
+```ts
+import Fory, { Type } from "@apache-fory/core";
+
+const accountType = Type.struct(
+ { typeName: "example.account" },
+ {
+ id: Type.int64(),
+ owner: Type.string(),
+ active: Type.bool(),
+ nickname: Type.string().setNullable(true),
+ },
+);
+
+const fory = new Fory();
+const { serialize, deserialize } = fory.register(accountType);
+```
+
+## 序列化与反序列化
+
+```ts
+const bytes = serialize({
+ id: 42n,
+ owner: "Alice",
+ active: true,
+ nickname: null,
+});
+
+const value = deserialize(bytes);
+console.log(value);
+// { id: 42n, owner: 'Alice', active: true, nickname: null }
+```
+
+返回的 `bytes` 值是 `Uint8Array`/平台缓冲区，可以通过网络发送或写入存储。
+
+## 根级动态序列化
+
+`Fory` 也支持在不先绑定特定 schema 序列化器的情况下，对动态根值进行序列化。
+
+```ts
+const fory = new Fory();
+
+const bytes = fory.serialize(
+ new Map([
+ ["name", "Alice"],
+ ["age", 30],
+ ]),
+);
+
+const value = fory.deserialize(bytes);
+```
+
+这对动态载荷很方便，但对于稳定接口和跨语言契约，显式 schema 通常更合适。
+
+## 原始值
+
+```ts
+const fory = new Fory();
+
+fory.deserialize(fory.serialize(true));
+// true
+
+fory.deserialize(fory.serialize("hello"));
+// 'hello'
+
+fory.deserialize(fory.serialize(123));
+// 123
+
+fory.deserialize(fory.serialize(123n));
+// 123n
+
+fory.deserialize(fory.serialize(new Date("2021-10-20T09:13:00Z")));
+// Date
+```
+
+### `number` 与 `bigint`
+
+JavaScript 的 `number` 是 64 位浮点数，无法精确表示所有 64 位整数。对于跨语言契约，或任何需要精确整数宽度的场景，请在 schema 中使用显式字段类型：
+
+- `Type.int32()`：32 位整数；使用 JavaScript `number`
+- `Type.int64()`：64 位整数；使用 JavaScript `bigint`
+- `Type.float32()` / `Type.float64()`：浮点数
+
+动态根序列化（即不使用 schema，直接调用 `fory.serialize(someNumber)`）会推断类型，但 API 不保证推断结果稳定。对于任何稳定契约，都应使用 schema。
+
+## 数组、Map 和 Set
+
+```ts
+const inventoryType = Type.struct("example.inventory", {
+ tags: Type.array(Type.string()),
+ counts: Type.map(Type.string(), Type.int32()),
+ labels: Type.set(Type.string()),
+});
+
+const fory = new Fory({ ref: true });
+const { serialize, deserialize } = fory.register(inventoryType);
+
+const bytes = serialize({
+ tags: ["hot", "new"],
+ counts: new Map([
+ ["apple", 3],
+ ["pear", 8],
+ ]),
+ labels: new Set(["featured", "seasonal"]),
+});
+
+const value = deserialize(bytes);
+```
+
+## 嵌套 Struct
+
+```ts
+const addressType = Type.struct("example.address", {
+ city: Type.string(),
+ country: Type.string(),
+});
+
+const userType = Type.struct("example.user", {
+ name: Type.string(),
+ address: Type.struct("example.address", {
+ city: Type.string(),
+ country: Type.string(),
+ }),
+});
+
+const fory = new Fory();
+const { serialize, deserialize } = fory.register(userType);
+
+const bytes = serialize({
+ name: "Alice",
+ address: { city: "Hangzhou", country: "CN" },
+});
+
+const user = deserialize(bytes);
+```
+
+如果嵌套值可能缺失，请将其标记为可空：
+
+```ts
+const wrapperType = Type.struct("example.wrapper", {
+ child: Type.struct("example.child", {
+ name: Type.string(),
+ }).setNullable(true),
+});
+```
+
+## 基于 Decorator 的注册
+
+TypeScript decorator 也受支持。
+
+```ts
+import Fory, { Type } from "@apache-fory/core";
+
+@Type.struct("example.user")
+class User {
+ @Type.int64()
+ id!: bigint;
+
+ @Type.string()
+ name!: string;
+}
+
+const fory = new Fory();
+const { serialize, deserialize } = fory.register(User);
+
+const user = new User();
+user.id = 1n;
+user.name = "Alice";
+
+const copy = deserialize(serialize(user));
+console.log(copy instanceof User); // true
+```
+
+## 可空性
+
+在基于 schema 的 struct 中，字段的可空性需要显式声明。
+
+```ts
+const nullableType = Type.struct("example.optional_user", {
+ name: Type.string(),
+ email: Type.string().setNullable(true),
+});
+```
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/javascript/cross-language.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/javascript/cross-language.md
new file mode 100644
index 000000000..7aa9eb0d5
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/javascript/cross-language.md
@@ -0,0 +1,128 @@
+---
+title: 跨语言序列化
+sidebar_position: 80
+id: cross_language
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Fory JavaScript 与 Java、Python、Go、Rust、Swift 和 C++ 的 Fory 运行时使用相同的二进制格式进行序列化。你可以在 JavaScript 中写入消息，再在 Java 中读取它，反过来也一样，无需额外的转换层。
+
+需要注意：
+
+- Fory JavaScript 运行时只读写跨语言载荷，不支持任何语言原生格式。
+- 当前暂不支持 out-of-band mode。
+
+## 成功完成往返的要求
+
+要让一条消息能在 JavaScript 与另一种运行时之间稳定往返，双方必须满足：
+
+1. 两端具有**相同的类型标识**，即相同的数值 ID，或相同的 `namespace + typeName`
+2. **字段类型兼容**，例如 JavaScript 中的 `Type.int32()` 字段应对应 Java `int`、Go `int32`、C# `int`
+3. **可空性一致**，如果一侧把字段标记为可空，另一侧也应如此
+4. 如果使用 Schema 演进，双方的 `compatible` 模式必须一致
+5. 如果数据包含共享引用或循环引用，双方的引用跟踪配置也必须一致
+
+## 分步说明：从 JavaScript 到其他运行时
+
+1. 在 JavaScript 中使用与其他运行时相同的类型名称或数值 ID 定义 schema
+2. 在两端都注册该 schema
+3. 对齐字段类型、可空性和 `compatible` 设置
+4. 在发布前对真实载荷做端到端测试
+
+JavaScript 侧：
+
+```ts
+import Fory, { Type } from "@apache-fory/core";
+
+const messageType = Type.struct(
+ { typeName: "example.message" },
+ {
+ id: Type.int64(),
+ content: Type.string(),
+ },
+);
+
+const fory = new Fory();
+const { serialize } = fory.register(messageType);
+
+const bytes = serialize({
+ id: 1n,
+ content: "hello from JavaScript",
+});
+```
+
+在另一侧，请使用对应运行时的 API 注册同一个 `example.message` 类型，即相同的名称或相同的数值 ID：
+
+- [Java guide](../java/index.md)
+- [Python guide](../python/index.md)
+- [Go guide](../go/index.md)
+- [Rust guide](../rust/index.md)
+
+## 字段命名
+
+Fory 按字段名匹配字段。当模型在多种语言中定义时，应保持字段名一致，或者至少采用能够在不同语言间无歧义映射的命名方案，例如统一使用 `snake_case`。
+
+当使用 `compatible: true` 进行 Schema 演进时，字段顺序的差异是允许的，但字段名本身仍必须一致。
+
+## 数值类型
+
+JavaScript 的 `number` 是 64 位浮点数，无法与其他语言中的所有整数类型一一对应。因此应使用显式 schema 类型：
+
+- `Type.int32()`：用于 32 位整数，对应 Java `int`、Go `int32`、C# `int`
+- `Type.int64()`：配合 `bigint` 值使用，用于 64 位整数，对应 Java `long`、Go `int64`
+- `Type.float32()` 或 `Type.float64()`：用于浮点数
+
+## 日期与时间
+
+- `Type.timestamp()`：表示一个时间点；往返后仍是 JavaScript `Date`
+- `Type.date()`：表示不带时间的日期；反序列化结果为 `Date`
+- `Type.duration()`：在 JavaScript 中暴露为毫秒数
+
+## 多态字段
+
+`Type.any()` 允许字段在运行时承载不同类型的值，但它在跨语言场景中更难保持一致。只要可能，就应优先使用显式字段 schema。
+
+```ts
+const wrapperType = Type.struct(
+ { typeId: 3001 },
+ {
+ payload: Type.any(),
+ },
+);
+```
+
+## 枚举
+
+枚举成员的**顺序**必须在不同语言间保持一致。Fory 按 ordinal position 而不是按枚举值对枚举进行编码。
+
+```ts
+const Color = { Red: 1, Green: 2, Blue: 3 };
+const fory = new Fory();
+fory.register(Type.enum({ typeId: 210 }, Color));
+```
+
+在每个对端运行时中都应使用相同的类型 ID 或类型名。
+
+## 安全限制
+
+`maxDepth`、`maxBinarySize` 和 `maxCollectionSize` 这些选项用于保护 JavaScript 运行时，防止接收过大载荷。它们不会改变二进制格式，只决定本地运行时愿意接受什么样的数据。
+
+## 相关主题
+
+- [支持的类型](supported-types.md)
+- [Schema 演进](schema-evolution.md)
+- [Xlang 序列化规范](../../specification/xlang_serialization_spec.md)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/javascript/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/javascript/index.md
new file mode 100644
index 000000000..ae4b5b8f8
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/javascript/index.md
@@ -0,0 +1,141 @@
+---
+title: JavaScript 序列化指南
+sidebar_position: 0
+id: index
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Apache Fory JavaScript 让你可以把 JavaScript 和 TypeScript 对象序列化为字节，并再把它们反序列化回来，包括与 Java、Python、Go、Rust、Swift 以及其他 Fory 支持的语言编写的服务进行跨语言互通。
+
+## 为什么选择 Fory JavaScript？
+
+- **跨语言**：可以在 JavaScript 中序列化，在 Java、Python、Go 等语言中反序列化，无需编写胶水代码
+- **高性能**：序列化器代码会在首次注册 schema 时生成并缓存，而不是每次调用时都重新生成
+- **具备引用感知能力**：启用后可支持共享引用和循环对象图
+- **显式 schema**：字段类型、可空性和多态行为通过 `Type.*` builder 或 TypeScript decorator 一次性声明
+- **安全默认值**：可配置的深度、二进制大小和集合大小限制可以拒绝超出预期的大载荷或深层嵌套载荷
+- **现代类型支持**：支持 `bigint`、typed array、`Map`、`Set`、`Date`、`float16` 和 `bfloat16`
+
+## 安装
+
+从 npm 安装 JavaScript 包：
+
+```bash
+npm install @apache-fory/core
+```
+
+可选的 Node.js 字符串快速路径支持由 `@apache-fory/hps` 提供：
+
+```bash
+npm install @apache-fory/core @apache-fory/hps
+```
+
+`@apache-fory/hps` 依赖 Node.js 20+，并且是可选的。如果不可用，Fory 仍可正常工作；只需在配置中省略 `hps`。
+
+## 快速开始
+
+```ts
+import Fory, { Type } from "@apache-fory/core";
+
+const userType = Type.struct(
+ { typeName: "example.user" },
+ {
+ id: Type.int64(),
+ name: Type.string(),
+ age: Type.int32(),
+ },
+);
+
+const fory = new Fory();
+const { serialize, deserialize } = fory.register(userType);
+
+const bytes = serialize({
+ id: 1n,
+ name: "Alice",
+ age: 30,
+});
+
+const user = deserialize(bytes);
+console.log(user);
+// { id: 1n, name: 'Alice', age: 30 }
+```
+
+## 工作原理
+
+Fory 是由 schema 驱动的。你先用 `Type.*` builder 或 TypeScript decorator 描述一次数据结构，然后调用 `fory.register(schema)`。这会返回一个可高频复用、调用开销较低的 `{ serialize, deserialize }` 对。
+
+```ts
+// 1. 定义 schema
+const personType = Type.struct("example.person", {
+ name: Type.string(),
+ email: Type.string().setNullable(true),
+});
+
+// 2. 注册一次
+const fory = new Fory();
+const { serialize, deserialize } = fory.register(personType);
+
+// 3. 按需重复使用
+const bytes = serialize({ name: "Alice", email: null });
+const person = deserialize(bytes);
+```
+
+每个应用创建一个 `Fory` 实例并持续复用即可；如果每个请求都新建实例，就会浪费 schema 注册带来的缓存收益。
+
+## 配置
+
+```ts
+import Fory from "@apache-fory/core";
+import hps from "@apache-fory/hps";
+
+const fory = new Fory({
+ ref: true,
+ compatible: true,
+ maxDepth: 100,
+ maxBinarySize: 64 * 1024 * 1024,
+ maxCollectionSize: 1_000_000,
+ hps,
+});
+```
+
+| 选项 | 默认值 | 说明 |
+| -------------------------- | ----------- | ------------------------------------------------------------------------------------ |
+| `ref` | `false` | 为共享引用或循环对象图启用引用跟踪 |
+| `compatible` | `false` | 允许在不破坏现有消息的前提下新增或删除字段 |
+| `maxDepth` | `50` | 最大嵌套深度，必须 `>= 2`。如果结构嵌套很深，可适当调大 |
+| `maxBinarySize` | 64 MiB | 任意单个二进制字段可接受的最大字节数 |
+| `maxCollectionSize` | `1_000_000` | 任意 list、set 或 map 中可接受的最大元素数 |
+| `useSliceString` | `false` | Node.js 下的可选字符串读取优化。除非做过基准测试，否则保持默认即可 |
+| `hps` | unset | 来自 `@apache-fory/hps` 的可选快速字符串辅助模块（Node.js 20+） |
+| `hooks.afterCodeGenerated` | unset | 用于查看生成后的序列化器代码的回调，对调试很有帮助 |
+
+## 文档导航
+
+| 主题 | 说明 |
+| --------------------------------------------- | ------------------------------------------------------ |
+| [基础序列化](basic-serialization.md) | 核心 API 与日常用法 |
+| [类型注册](type-registration.md) | 数值 ID、名称、decorator 与 schema 注册方式 |
+| [支持的类型](supported-types.md) | 原始类型、集合、时间、枚举与 struct 的映射方式 |
+| [引用](references.md) | 共享引用与循环对象图 |
+| [Schema 演进](schema-evolution.md) | 兼容模式与 struct 演进 |
+| [跨语言](cross-language.md) | 互操作指导与类型映射规则 |
+| [故障排查](troubleshooting.md) | 常见问题、限制项与调试技巧 |
+
+## 相关资源
+
+- [Xlang 序列化规范](../../specification/xlang_serialization_spec.md)
+- [跨语言类型映射](../../specification/xlang_type_mapping.md)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/javascript/references.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/javascript/references.md
new file mode 100644
index 000000000..e084bcf2a
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/javascript/references.md
@@ -0,0 +1,111 @@
+---
+title: 引用
+sidebar_position: 50
+id: references
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+默认情况下，Fory 会把每个值都当作独立副本处理。如果同一个对象出现在两个字段中，它会被序列化两次；反序列化后，你得到的也是两个彼此独立的副本。以下情况应启用引用跟踪：
+
+- 同一个对象实例会在对象图中的多个位置被引用
+- 数据中包含循环结构，例如一个节点指向自己
+- 往返之后必须保留对象身份
+
+对于普通的树状数据，应保持引用跟踪关闭，因为它会引入少量额外开销。
+
+## 第一步：在 `Fory` 实例上启用引用跟踪
+
+```ts
+const fory = new Fory({ ref: true });
+```
+
+## 第二步：标记可能出现共享引用或循环引用的字段
+
+对于每个值可能被共享或形成循环的字段，都需要在字段 schema 上调用 `.setTrackingRef(true)`：
+
+```ts
+const nodeType = Type.struct("example.node", {
+ value: Type.string(),
+ next: Type.struct("example.node").setNullable(true).setTrackingRef(true),
+});
+```
+
+全局开关和字段级开关必须**同时**启用。缺少任何一个，值都会被复制，而不是按引用恢复。
+
+## 循环自引用示例
+
+```ts
+import Fory, { Type } from "@apache-fory/core";
+
+const nodeType = Type.struct("example.node", {
+ name: Type.string(),
+ selfRef: Type.struct("example.node").setNullable(true).setTrackingRef(true),
+});
+
+const fory = new Fory({ ref: true });
+const { serialize, deserialize } = fory.register(nodeType);
+
+const node: any = { name: "root", selfRef: null };
+node.selfRef = node;
+
+const copy = deserialize(serialize(node));
+console.log(copy.selfRef === copy); // true
+```
+
+## 共享嵌套引用示例
+
+```ts
+const innerType = Type.struct(501, {
+ value: Type.string(),
+});
+
+const outerType = Type.struct(502, {
+ left: Type.struct(501).setNullable(true).setTrackingRef(true),
+ right: Type.struct(501).setNullable(true).setTrackingRef(true),
+});
+
+const fory = new Fory({ ref: true });
+const { serialize, deserialize } = fory.register(outerType);
+
+const shared = { value: "same-object" };
+const copy = deserialize(serialize({ left: shared, right: shared }));
+console.log(copy.left === copy.right); // true
+```
+
+## 何时启用
+
+以下情况建议启用引用跟踪：
+
+- 同一个对象实例会被多个字段重复引用
+- 你的对象图可能存在环
+- 反序列化后对象身份是否保持一致很重要
+
+以下情况建议关闭：
+
+- 数据是普通树结构
+- 你希望获得最低开销
+- 对象身份并不重要
+
+## 跨语言说明
+
+引用跟踪是 Fory 二进制协议的一部分，并且可以跨运行时工作。为了让行为一致，两端都必须启用引用跟踪，并把相同字段标记为引用跟踪字段。
+
+## 相关主题
+
+- [基础序列化](basic-serialization.md)
+- [Schema 演进](schema-evolution.md)
+- [跨语言](cross-language.md)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/javascript/schema-evolution.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/javascript/schema-evolution.md
new file mode 100644
index 000000000..adbb202b1
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/javascript/schema-evolution.md
@@ -0,0 +1,99 @@
+---
+title: Schema 演进
+sidebar_position: 60
+id: schema_evolution
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Schema 演进允许不同版本的服务安全地交换消息。也就是说，v2 写入端生成的消息，v1 读取端仍然可以理解，反之亦然。
+
+## 两种模式
+
+- **Schema-consistent 模式**（默认）：更紧凑，但双方必须拥有完全相同的 schema。适合所有服务统一升级的场景。
+- **兼容模式**：会写入额外的字段元信息，使读取端能够跳过未知字段并容忍缺失字段。适合独立部署或滚动升级场景。
+
+## 启用兼容模式
+
+```ts
+const fory = new Fory({ compatible: true });
+```
+
+以下情况建议使用：
+
+- 服务会独立发布 schema 变更
+- 较旧的读取端可能会看到较新的载荷
+- 较新的读取端可能会看到字段尚未添加之前产生的旧载荷
+
+## 示例
+
+写入端 schema：
+
+```ts
+const writerType = Type.struct(
+ { typeId: 1001 },
+ {
+ name: Type.string(),
+ age: Type.int32(),
+ },
+);
+```
+
+字段更少的读取端 schema：
+
+```ts
+const readerType = Type.struct(
+ { typeId: 1001 },
+ {
+ name: Type.string(),
+ },
+);
+```
+
+启用 `compatible: true` 后，读取端会忽略自己不认识的字段，并为未知字段填充默认值。
+
+## 为单个 Struct 关闭演进
+
+即使实例启用了 `compatible: true`，你仍然可以为某个特定 struct 关闭演进元信息：
+
+```ts
+const fixedType = Type.struct(
+ { typeId: 1002, evolving: false },
+ {
+ name: Type.string(),
+ },
+);
+```
+
+`evolving: false` 会让该 struct 的消息更小，但**写入端和读取端必须在这个设置上保持一致**。如果一侧以 `evolving: false` 写入，而另一侧按兼容元信息读取，反序列化将失败。
+
+## 何时使用每种模式
+
+| | Schema-consistent | Compatible |
+| ------------------------------- | ----------------- | ------------------- |
+| 服务总是同时更新 | ✔ 最佳选择 | 可用，但有浪费 |
+| 独立部署 | 会出错 | ✔ 最佳选择 |
+| 需要尽可能小的消息 | ✔ | 稍大一些 |
+| 滚动升级 | 有风险 | ✔ 安全 |
+
+## 跨语言要求
+
+兼容模式只能帮你处理类型**字段**层面的 schema 差异。对于类型标识本身，你仍然需要在各端保持一致，即相同的数值 ID 或相同的 `namespace + typeName`。参见 [跨语言](cross-language.md)。
+
+## 相关主题
+
+- [类型注册](type-registration.md)
+- [跨语言](cross-language.md)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/javascript/supported-types.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/javascript/supported-types.md
new file mode 100644
index 000000000..0bbbf022f
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/javascript/supported-types.md
@@ -0,0 +1,177 @@
+---
+title: 支持的类型
+sidebar_position: 40
+id: supported_types
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页列出 Fory 支持的 JavaScript 和 TypeScript 类型，并说明在跨语言兼容场景下何时需要对类型选择保持明确和谨慎。
+
+## 原始类型与标量类型
+
+| JavaScript 值 | Fory schema | 说明 |
+| ------------------ | ----------------------------------------------------------------------------------- | ---------------------------------------------- |
+| `boolean` | `Type.bool()` | |
+| `number` | `Type.int8()` / `Type.int16()` / `Type.int32()` / `Type.float32()` / `Type.float64()` | 选择与对端语言一致的位宽 |
+| `bigint` | `Type.int64()` / `Type.varInt64()` / `Type.uint64()` | 64 位整数应使用 `bigint` |
+| `string` | `Type.string()` | |
+| `Uint8Array` | `Type.binary()` | 二进制 blob |
+| `Date` | `Type.timestamp()` | 序列化/反序列化结果均为 `Date` |
+| `Date` | `Type.date()` | 只包含日期，不包含时间；反序列化结果为 `Date` |
+| duration（毫秒） | `Type.duration()` | 在 JavaScript 中暴露为毫秒数 |
+| `number` | `Type.float16()` | 半精度浮点数 |
+| `BFloat16` / `number` | `Type.bfloat16()` | 反序列化结果为 `BFloat16` |
+
+## 整数类型
+
+JavaScript 的 `number` 是 64 位浮点数，无法安全表示所有 64 位整数，超过 `Number.MAX_SAFE_INTEGER` 的整数会丢失精度。请使用显式 schema，使其与对端语言期望的位宽一致：
+
+```ts
+Type.int8(); // -128 to 127
+Type.int16(); // -32,768 to 32,767
+Type.int32(); // matches Java int, Go int32, C# int
+Type.varInt32(); // variable-length encoding; smaller for small values
+Type.int64(); // use with bigint; matches Java long, Go int64
+Type.varInt64();
+Type.sliInt64();
+Type.uint8();
+Type.uint16();
+Type.uint32();
+Type.varUInt32();
+Type.uint64(); // use with bigint
+Type.varUInt64();
+Type.taggedUInt64();
+```
+
+**经验法则**：凡是在其他语言中映射为 64 位整数的值，在 JavaScript 侧都应使用 `Type.int64()` 或 `Type.uint64()`，并以 `bigint` 形式传入。
+
+## 浮点类型
+
+```ts
+Type.float16();
+Type.float32();
+Type.float64();
+Type.bfloat16();
+```
+
+当需要与使用低精度数值格式的运行时或载荷互操作时，`float16` 和 `bfloat16` 会很有用。
+
+## 数组与 Typed Array
+
+### 通用数组
+
+```ts
+Type.array(Type.string());
+Type.array(
+ Type.struct("example.item", {
+ id: Type.int64(),
+ }),
+);
+```
+
+它们会映射为 JavaScript 数组。
+
+## 优化过的数值数组
+
+对于数值数组，请使用专门的 typed array schema。它们更紧凑，并且会映射到原生 typed array：
+
+```ts
+Type.boolArray(); // boolean[] in JS
+Type.int16Array(); // Int16Array
+Type.int32Array(); // Int32Array
+Type.int64Array(); // BigInt64Array
+Type.float32Array(); // Float32Array
+Type.float64Array(); // Float64Array
+Type.float16Array(); // number[]
+Type.bfloat16Array(); // BFloat16[]
+```
+
+对于非数值数组或 struct 数组，应改用 `Type.array(elementType)`。
+
+## Map 与 Set
+
+```ts
+Type.map(Type.string(), Type.int32());
+Type.set(Type.string());
+```
+
+它们会映射为 JavaScript `Map` 和 `Set`。
+
+## Struct
+
+```ts
+Type.struct("example.user", {
+ id: Type.int64(),
+ name: Type.string(),
+ tags: Type.array(Type.string()),
+});
+```
+
+Struct 可以以内联方式声明，也可以通过 decorator 声明，或者嵌套在其他 schema 中。
+
+## 枚举
+
+```ts
+Type.enum("example.color", {
+ Red: 1,
+ Green: 2,
+ Blue: 3,
+});
+```
+
+Fory 按对象中的 ordinal position 编码枚举值，而不是按它们的取值进行编码。两端都必须以相同顺序声明枚举成员。与其他语言互操作时，必须保证成员顺序一致，而不仅仅是值相同。
+
+## 可空字段
+
+当字段可能为 `null` 时，请使用 `.setNullable(true)`。
+
+```ts
+Type.string().setNullable(true);
+```
+
+## 动态字段
+
+当字段在运行时可能承载不同类型的值时，请使用 `Type.any()`。
+
+```ts
+const eventType = Type.struct("example.event", {
+ kind: Type.string(),
+ payload: Type.any(),
+});
+```
+
+如果字段类型是已知的，应优先使用显式字段 schema，因为 `Type.any()` 更难在不同语言间保持对齐。
+
+## 引用跟踪字段
+
+当同一个对象实例可能出现在多个字段中，或者你的对象图存在循环时，应为对应字段单独启用引用跟踪：
+
+```ts
+Type.struct("example.node").setTrackingRef(true).setNullable(true);
+```
+
+这需要同时配置 `new Fory({ ref: true })`。参见 [引用](references.md)。
+
+## 扩展类型
+
+对于需要完全自定义编码的类型，可以使用 `Type.ext(...)`，并向 `fory.register(...)` 传入自定义序列化器。这属于高级用法；大多数场景下，标准的 `Type.struct` 已经足够。
+
+## 相关主题
+
+- [基础序列化](basic-serialization.md)
+- [引用](references.md)
+- [跨语言](cross-language.md)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/javascript/troubleshooting.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/javascript/troubleshooting.md
new file mode 100644
index 000000000..a4d83c62b
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/javascript/troubleshooting.md
@@ -0,0 +1,105 @@
+---
+title: 故障排查
+sidebar_position: 90
+id: troubleshooting
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍使用 Fory JavaScript 时常见的问题。
+
+## 无法反序列化非跨语言载荷
+
+Fory JavaScript 运行时只能读取 Fory 的跨语言载荷。如果生产端是 Java 或 Go 服务，并且使用的是语言原生格式，那么 JavaScript 侧无法解码。
+
+修复方式：把生产端切换到跨语言模式。Java 请使用 `.withLanguage(Language.XLANG)`，Go 请使用 `WithXlang(true)`。
+
+## `maxDepth must be an integer >= 2`
+
+这表示你传入了无效的 `maxDepth` 值。它必须是大于等于 2 的正整数。
+
+```ts
+new Fory({ maxDepth: 100 });
+```
+
+只有当你的数据确实存在很深的嵌套时，才应提高这个值。
+
+## `Binary size ... exceeds maxBinarySize`
+
+某个二进制字段或整条消息超过了安全限制。如果这个大小符合预期，且数据源可信，可以提高限制：
+
+```ts
+new Fory({ maxBinarySize: 128 * 1024 * 1024 });
+```
+
+## `Collection size ... exceeds maxCollectionSize`
+
+某个 list、set 或 map 的元素数量超过了配置上限。这通常意味着数据异常地大。如果这是合法场景，可以提高限制：
+
+```ts
+new Fory({ maxCollectionSize: 2_000_000 });
+```
+
+## `Field "..." is not nullable`
+
+你向一个未声明为可空的字段传入了 `null`。修复方式：在字段 schema 上添加 `.setNullable(true)`：
+
+```ts
+const userType = Type.struct("example.user", {
+ name: Type.string(),
+ email: Type.string().setNullable(true), // ← this field can be null
+});
+```
+
+## 反序列化后对象不是同一个实例
+
+默认情况下，Fory 不保留对象身份。两个字段如果指向同一个对象，反序列化后会变成两个彼此独立的副本。
+
+修复方式：同时启用以下**两个**开关：
+
+1. 在实例上配置 `new Fory({ ref: true })`
+2. 在具体字段上调用 `.setTrackingRef(true)`
+
+参见 [引用](references.md)。
+
+## 大整数会以 `bigint` 返回
+
+这是预期行为。对于任何 64 位整数字段，例如 `Type.int64()`、`Type.uint64()`，Fory 都会使用 `bigint`。如果你确实需要 `number`，请使用更小的整数类型，比如 `Type.int32()`，但前提是该值确实能装进 32 位。
+
+## 查看生成的序列化器代码
+
+如果你需要排查 Fory 在底层生成了什么，可以通过 hook 查看生成后的序列化器代码：
+
+```ts
+const fory = new Fory({
+ hooks: {
+ afterCodeGenerated(code) {
+ console.log(code);
+ return code;
+ },
+ },
+});
+```
+
+## `@apache-fory/hps` 安装失败
+
+`@apache-fory/hps` 是一个可选的 Node.js 加速模块。如果它安装失败，例如当前平台不支持原生模块，只需把它从依赖中移除即可。即使没有它，Fory 也能正常工作。
+
+## 相关主题
+
+- [基础序列化](basic-serialization.md)
+- [引用](references.md)
+- [跨语言](cross-language.md)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/javascript/type-registration.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/javascript/type-registration.md
new file mode 100644
index 000000000..5fa242e88
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/javascript/type-registration.md
@@ -0,0 +1,200 @@
+---
+title: 类型注册
+sidebar_position: 30
+id: type_registration
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+你要序列化的每个 struct 和 enum，在使用前都必须先注册到 `Fory` 实例中。注册会告诉 Fory：如何在消息中标识该类型，以及如何对其进行编码和解码。
+
+## 注册 Struct
+
+你可以使用数值 ID 或名称来标识一个 struct。选择一种策略，并在所有共享这类消息的语言中保持一致。
+
+### 按数值 ID 注册
+
+编码更紧凑。当团队规模较小、可以协调 ID 分配时，这是很好的选择。
+
+```ts
+const userType = Type.struct(
+ { typeId: 1001 },
+ {
+ id: Type.int64(),
+ name: Type.string(),
+ },
+);
+
+const fory = new Fory();
+const { serialize, deserialize } = fory.register(userType);
+```
+
+所有读写该类型的运行时都必须使用同一个数值。
+
+### 按名称注册
+
+更容易跨团队协同，但消息中的元信息会稍大一些。
+
+```ts
+const userType = Type.struct(
+ { typeName: "example.user" },
+ {
+ id: Type.int64(),
+ name: Type.string(),
+ },
+);
+
+const fory = new Fory();
+const { serialize, deserialize } = fory.register(userType);
+```
+
+你也可以显式拆分 `namespace` 和类型名：
+
+```ts
+const userType = Type.struct(
+ { namespace: "example", typeName: "user" },
+ {
+ id: Type.int64(),
+ name: Type.string(),
+ },
+);
+```
+
+> **同一个类型不要在不同运行时中混用两种策略。** 如果一侧使用数值 ID，另一侧使用名称，反序列化会失败。
+
+## 使用 Decorator 注册
+
+```ts
+@Type.struct({ typeId: 1001 })
+class User {
+ @Type.int64()
+ id!: bigint;
+
+ @Type.string()
+ name!: string;
+}
+
+const fory = new Fory();
+const { serialize, deserialize } = fory.register(User);
+```
+
+当你希望 TypeScript 类声明与 schema 定义放在一起时，基于 decorator 的注册会很方便。
+
+## 注册 Enum
+
+Fory JavaScript 同时支持普通 JavaScript 风格的枚举对象和 TypeScript enum。
+
+### JavaScript 对象枚举
+
+```ts
+const Color = {
+ Red: 1,
+ Green: 2,
+ Blue: 3,
+};
+
+const fory = new Fory();
+const colorSerde = fory.register(Type.enum("example.color", Color));
+```
+
+### TypeScript enum
+
+```ts
+enum Status {
+ Pending = "pending",
+ Active = "active",
+}
+
+const fory = new Fory();
+fory.register(Type.enum("example.status", Status));
+```
+
+## 注册作用域
+
+注册是以 `Fory` 实例为作用域的。如果你创建了两个实例，就需要在两个实例中都注册 schema。
+
+## `register` 的返回值
+
+`fory.register(schema)` 会返回一个绑定后的序列化器对：
+
+```ts
+const { serialize, deserialize } = fory.register(orderType);
+
+// serialize returns Uint8Array bytes
+const bytes = serialize({ id: 1n, total: 99.99 });
+
+// deserialize returns the decoded value
+const order = deserialize(bytes);
+```
+
+把这个返回对保存起来并重复复用，它就是性能最优的调用路径。
+
+## 字段选项
+
+### 可空字段
+
+如果字段可能为 `null`，请显式标记。向不可空字段传入 `null` 会抛出异常。
+
+```ts
+Type.string().setNullable(true);
+```
+
+### 字段上的引用跟踪
+
+当同一个对象实例可能出现在多个字段中时，需要启用字段级引用跟踪，详见 [引用](references.md)：
+
+```ts
+Type.struct("example.node").setTrackingRef(true);
+```
+
+只有在同时设置了 `new Fory({ ref: true })` 时，这个选项才会生效。
+
+### 多态字段
+
+当字段在运行时可能承载不同类型的值时，可以使用 `Type.any()`：
+
+```ts
+const eventType = Type.struct("example.event", {
+ kind: Type.string(),
+ payload: Type.any(),
+});
+```
+
+如果你需要更细粒度地控制某个 struct 字段如何处理运行时类型，可以调用 `.setDynamic(Dynamic.FALSE)`，表示始终按声明类型处理；或者调用 `.setDynamic(Dynamic.TRUE)`，表示始终写入运行时类型。默认值 `Dynamic.AUTO` 适用于绝大多数场景。
+
+## 如何选择 ID 与名称
+
+以下情况适合使用**数值 ID**：
+
+- 你希望消息尽可能小
+- 你的组织能够保证 ID 稳定且全局唯一
+- 服务之间协同非常紧密
+
+以下情况适合使用**名称**：
+
+- 不同团队独立定义类型
+- schema 本身已经通过 package/module name 标识
+- 可以接受稍大的元信息开销
+
+## 跨语言
+
+如果要让消息在 JavaScript 与其他运行时之间往返，双方必须对某个类型使用相同的类型标识：相同的数值 ID，或相同的 `namespace + typeName`。参见 [跨语言](cross-language.md)。
+
+## 相关主题
+
+- [基础序列化](basic-serialization.md)
+- [Schema 演进](schema-evolution.md)
+- [跨语言](cross-language.md)
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@fory.apache.org
For additional commands, e-mail: commits-help@fory.apache.org
(fory-site) 03/09: Require user draft for release blog skill
Posted by ch...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
chaokunyang pushed a commit to branch release_0.17.0
in repository https://gitbox.apache.org/repos/asf/fory-site.git
commit 4496fd3e3fe1d6e64760c5634a524e497de9cbb7
Author: 慕白 <ch...@antgroup.com>
AuthorDate: Sun Apr 19 22:55:38 2026 +0800
Require user draft for release blog skill
---
.claude/skills/release-major-version/SKILL.md | 14 ++++++++------
1 file changed, 8 insertions(+), 6 deletions(-)
diff --git a/.claude/skills/release-major-version/SKILL.md b/.claude/skills/release-major-version/SKILL.md
index 9b0f50164..87638c616 100644
--- a/.claude/skills/release-major-version/SKILL.md
+++ b/.claude/skills/release-major-version/SKILL.md
@@ -80,18 +80,20 @@ This workflow covers:
## Step 1: Write the Release Blog
-1. Find the previous release blog in `blog/`, typically `blog/YYYY-MM-DD-fory_<prev>_release.md`.
-2. Create the new release post by adapting the previous one instead of starting from scratch.
-3. Update the post carefully:
+1. Ask the user to provide the English draft for the release blog if it has not already been provided.
+2. Find the previous release blog in `blog/`, typically `blog/YYYY-MM-DD-fory_<prev>_release.md`.
+3. Use the previous release blog as a structural/reference template, but treat the user-provided English draft as the source content for the new post.
+4. Create or revise the new release post around that English draft rather than inventing the release narrative from scratch.
+5. Update the post carefully:
- frontmatter `slug`, `title`, `tags`, date-based filename
- opening release paragraph
- compare link
- PR counts / contributor counts if the post includes them
- highlights/features/fixes sections
- benchmark images and asset paths
-4. Put blog-specific assets under `static/img/blog/fory_<version>_release/` when the post needs dedicated images.
-5. If you add benchmark images, ensure the referenced static paths and copied files match exactly.
-6. Validate the post for obvious copy/paste errors from the previous release.
+6. Put blog-specific assets under `static/img/blog/fory_<version>_release/` when the post needs dedicated images.
+7. If you add benchmark images, ensure the referenced static paths and copied files match exactly.
+8. Validate the post for obvious copy/paste errors from the previous release.
## Step 1A: Bump Versioned References in Current Docs
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@fory.apache.org
For additional commands, e-mail: commits-help@fory.apache.org
(fory-site) 01/09: 0.17.0 release blog
Posted by ch...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
chaokunyang pushed a commit to branch release_0.17.0
in repository https://gitbox.apache.org/repos/asf/fory-site.git
commit 8ff820d2e6a974c746258631ae1f2a715e4addc8
Author: 慕白 <ch...@antgroup.com>
AuthorDate: Sun Apr 19 22:06:24 2026 +0800
0.17.0 release blog
---
blog/2026-03-17-fory_0_16_0_release.md | 2 +-
blog/2026-04-19-fory_0_17_0_release.md | 293 +++++++++++++++++++++
.../blog/fory_0_17_0_release/dart_throughput.png | Bin 0 -> 89092 bytes
.../fory_0_17_0_release/javascript_throughput.png | Bin 0 -> 81947 bytes
4 files changed, 294 insertions(+), 1 deletion(-)
diff --git a/blog/2026-03-17-fory_0_16_0_release.md b/blog/2026-03-17-fory_0_16_0_release.md
index ffbcf2c67..6d4086ad0 100644
--- a/blog/2026-03-17-fory_0_16_0_release.md
+++ b/blog/2026-03-17-fory_0_16_0_release.md
@@ -5,7 +5,7 @@ authors: [chaokunyang]
tags: [fory, c#, swift, c++, java, python, compiler]
---
-The Apache Fory team is pleased to announce the 0.16.0 release. This is a major release that includes [91 PR](https://github.com/apache/fory/compare/v0.14.1...v0.15.0) from 17 distinct contributors. See the [Install](https://fory.apache.org/docs/start/install) Page to learn how to get the libraries for your platform.
+The Apache Fory team is pleased to announce the 0.16.0 release. This is a major release that includes [91 PR](https://github.com/apache/fory/compare/v0.15.0...v0.16.0) from 17 distinct contributors. See the [Install](https://fory.apache.org/docs/start/install) Page to learn how to get the libraries for your platform.
## Highlights
diff --git a/blog/2026-04-19-fory_0_17_0_release.md b/blog/2026-04-19-fory_0_17_0_release.md
new file mode 100644
index 000000000..1078fbad3
--- /dev/null
+++ b/blog/2026-04-19-fory_0_17_0_release.md
@@ -0,0 +1,293 @@
+---
+slug: fory_0_17_0_release
+title: Fory v0.17.0 Released
+authors: [chaokunyang]
+tags: [fory, c#, swift, c++, java, python, compiler]
+---
+
+The Apache Fory team is pleased to announce the 0.17.0 release. This is a major release that includes [71 PR](https://github.com/apache/fory/compare/v0.16.0...v0.17.0) from 19 distinct contributors. See the [Install](https://fory.apache.org/docs/start/install) Page to learn how to get the libraries for your platform.
+
+## JavaScript/NodeJS Serialization: First Release
+
+Apache Fory 0.17.0 marks the first release with official JavaScript/NodeJS
+documentation, benchmark coverage, and TypeScript-friendly IDL code generation.
+The JavaScript runtime is built for modern Node.js services and TypeScript
+codebases, while preserving Fory's cross-language object model, schema-driven
+APIs, and optional reference tracking.
+
+**Key capabilities:**
+
+* High-performance serialization for JavaScript and TypeScript objects in Node.js
+* Cross-language compatibility with Java, Python, Go, Rust, C#, Swift, and Dart
+* Schema-driven APIs via `Type.*` builders and TypeScript decorators
+* Optional reference tracking for shared and circular object graphs
+* Compatible mode for schema evolution
+* Configurable depth, binary size, and collection size guardrails
+* JavaScript/TypeScript target support in the Fory IDL/compiler workflow
+* Optional `@apache-fory/hps` fast string path for Node.js 20+
+
+### Quick Start
+
+```ts
+import Fory, { Type } from "@apache-fory/core";
+
+const userType = Type.struct(
+ { typeName: "example.user" },
+ {
+ id: Type.int64(),
+ name: Type.string(),
+ age: Type.int32(),
+ },
+);
+
+const fory = new Fory();
+const { serialize, deserialize } = fory.register(userType);
+
+const bytes = serialize({
+ id: 1n,
+ name: "Alice",
+ age: 30,
+});
+
+const user = deserialize(bytes);
+console.log(user);
+```
+
+* JavaScript guide: https://fory.apache.org/docs/guide/javascript/
+* Compiler docs: https://fory.apache.org/docs/compiler/
+
+### JavaScript Benchmarks
+
+<img src="/img/blog/fory_0_17_0_release/javascript_throughput.png" width="90%"/>
+
+Below are throughput results (ops/sec; higher is better) comparing Fory with
+Protocol Buffers and JSON across representative data structures.
+
+| Datatype | Operation | Fory TPS | Protobuf TPS | JSON TPS | Fastest |
+| ---------------- | ----------- | --------- | ------------ | --------- | ------- |
+| Struct | Serialize | 8,453,950 | 1,903,706 | 3,058,232 | fory |
+| Struct | Deserialize | 9,705,287 | 8,233,664 | 3,860,538 | fory |
+| Sample | Serialize | 1,498,391 | 422,620 | 744,790 | fory |
+| Sample | Deserialize | 1,918,162 | 819,010 | 762,048 | fory |
+| MediaContent | Serialize | 1,293,157 | 729,497 | 1,299,908 | json |
+| MediaContent | Deserialize | 1,638,086 | 1,209,140 | 921,191 | fory |
+| StructList | Serialize | 3,928,325 | 495,648 | 891,810 | fory |
+| StructList | Deserialize | 3,264,827 | 1,529,744 | 986,144 | fory |
+| SampleList | Serialize | 355,581 | 92,741 | 163,120 | fory |
+| SampleList | Deserialize | 424,916 | 163,253 | 162,520 | fory |
+| MediaContentList | Serialize | 286,053 | 148,977 | 282,445 | fory |
+| MediaContentList | Deserialize | 376,826 | 244,622 | 190,155 | fory |
+
+Serialized data sizes (bytes):
+
+| Datatype | Fory | Protobuf | JSON |
+| ---------------- | ---- | -------- | ---- |
+| Struct | 58 | 61 | 103 |
+| Sample | 446 | 377 | 724 |
+| MediaContent | 391 | 307 | 596 |
+| StructList | 184 | 315 | 537 |
+| SampleList | 1980 | 1900 | 3642 |
+| MediaContentList | 1665 | 1550 | 3009 |
+
+Benchmark details: https://github.com/apache/fory/tree/v0.17.0/benchmarks/javascript
+
+## Dart Serialization: First Release
+
+Apache Fory 0.17.0 also marks the first release with official Dart
+documentation, benchmark coverage, a rebuilt runtime, and Dart IDL support.
+The Dart implementation focuses on generated serializers, stable
+cross-language type identity, schema evolution, and predictable APIs for
+service workloads.
+
+**Key capabilities:**
+
+* High-performance Dart serialization with generated code instead of reflection
+* Cross-language compatibility with Java, Python, Go, Rust, C#, Swift, and JavaScript
+* `@ForyStruct` and `@ForyField` annotations with `build_runner` code generation
+* Compatible mode for schema evolution across versions
+* Optional reference tracking for shared and circular object graphs
+* Manual `Serializer<T>` extension points for advanced or custom types
+* Dart target support in the Fory IDL/compiler workflow
+
+### Quick Start
+
+```dart
+import 'package:fory/fory.dart';
+
+part 'person.fory.dart';
+
+enum Color {
+ red,
+ blue,
+}
+
+@ForyStruct()
+class Person {
+ Person();
+
+ String name = '';
+ Int32 age = Int32(0);
+ Color favoriteColor = Color.red;
+}
+
+void main() {
+ final fory = Fory();
+ PersonFory.register(
+ fory,
+ Color,
+ namespace: 'example',
+ typeName: 'Color',
+ );
+ PersonFory.register(
+ fory,
+ Person,
+ namespace: 'example',
+ typeName: 'Person',
+ );
+
+ final bytes = fory.serialize(Person()
+ ..name = 'Ada'
+ ..age = Int32(36)
+ ..favoriteColor = Color.blue);
+ final roundTrip = fory.deserialize<Person>(bytes);
+ print(roundTrip.name);
+}
+```
+
+* Dart guide: https://fory.apache.org/docs/guide/dart/
+* Compiler docs: https://fory.apache.org/docs/compiler/
+
+### Dart Benchmarks
+
+<img src="/img/blog/fory_0_17_0_release/dart_throughput.png" width="90%"/>
+
+Below are throughput results (ops/sec; higher is better) comparing Fory with
+Protocol Buffers across representative data structures.
+
+| Datatype | Operation | Fory TPS | Protobuf TPS | Fastest |
+| ---------------- | ----------- | --------: | -----------: | ------------ |
+| Struct | Serialize | 3,989,432 | 1,884,653 | fory (2.12x) |
+| Struct | Deserialize | 5,828,197 | 4,199,680 | fory (1.39x) |
+| Sample | Serialize | 1,649,722 | 500,167 | fory (3.30x) |
+| Sample | Deserialize | 2,060,113 | 785,109 | fory (2.62x) |
+| MediaContent | Serialize | 800,876 | 391,235 | fory (2.05x) |
+| MediaContent | Deserialize | 1,315,115 | 683,533 | fory (1.92x) |
+| StructList | Serialize | 1,456,396 | 367,506 | fory (3.96x) |
+| StructList | Deserialize | 1,921,006 | 645,958 | fory (2.97x) |
+| SampleList | Serialize | 411,144 | 48,508 | fory (8.48x) |
+| SampleList | Deserialize | 464,273 | 103,558 | fory (4.48x) |
+| MediaContentList | Serialize | 186,870 | 77,029 | fory (2.43x) |
+| MediaContentList | Deserialize | 330,293 | 128,215 | fory (2.58x) |
+
+Serialized data sizes (bytes):
+
+| Datatype | Fory | Protobuf |
+| ---------------- | ---: | -------: |
+| Struct | 58 | 61 |
+| Sample | 446 | 377 |
+| MediaContent | 365 | 307 |
+| StructList | 184 | 315 |
+| SampleList | 1980 | 1900 |
+| MediaContentList | 1535 | 1550 |
+
+Benchmark details: https://github.com/apache/fory/tree/v0.17.0/benchmarks/dart
+
+## Highlights
+* refactor(java): refactor fory java serialization api by @chaokunyang in https://github.com/apache/fory/pull/3537
+* refactor(python): refactor python serialization api by @chaokunyang in https://github.com/apache/fory/pull/3543
+* feat(java): reduce java serializer memory usage by share across Fory instances by @chaokunyang in https://github.com/apache/fory/pull/3546
+* feat(java): remove guava dependency from fory java by @chaokunyang in https://github.com/apache/fory/pull/3557
+* refactor(dart): new dart implementation by @chaokunyang in https://github.com/apache/fory/pull/3551
+
+## Features
+* refactor(javascript): rename apache-fory/fory to apache-fory/core by @chaokunyang in https://github.com/apache/fory/pull/3489
+* feat(ci): add bazel downloads retry by @BaldDemian in https://github.com/apache/fory/pull/3492
+* feat(go): add configurable size guardrails by @ayush00git in https://github.com/apache/fory/pull/3475
+* refactor(ci): install Bazel using setup-bazel by @BaldDemian in https://github.com/apache/fory/pull/3494
+* perf(rust): Rewrite Rust benchmarks around shared bench.proto data by @chaokunyang in https://github.com/apache/fory/pull/3497
+* feat(cpp): add float16 to c++ by @UninspiredCarrot in https://github.com/apache/fory/pull/3487
+* feat(java): add float support by @mengnankkkk in https://github.com/apache/fory/pull/3254
+* feat(java): support java virtual threads by @chaokunyang in https://github.com/apache/fory/pull/3522
+* perf(java): optimize thread safe fory for java by @chaokunyang in https://github.com/apache/fory/pull/3529
+* test(cpp): optimize float16 sign symmetry test for ASAN by @Geethapranay1 in https://github.com/apache/fory/pull/3531
+* feat(java): add dedicated exception serializers by @chaokunyang in https://github.com/apache/fory/pull/3536
+* refactor(java): refactor fory java serialization api by @chaokunyang in https://github.com/apache/fory/pull/3537
+* refactor(python): refactor python serialization api by @chaokunyang in https://github.com/apache/fory/pull/3543
+* feat(dart): Introduce id based enum serialization by @yash-agarwa-l in https://github.com/apache/fory/pull/3482
+* feat(javascript): add configurable size guardrails by @ayush00git in https://github.com/apache/fory/pull/3539
+* feat(java): reduce java serializer memory usage by share across Fory instances by @chaokunyang in https://github.com/apache/fory/pull/3546
+* refactor(javascript): move serialization runtime state into contexts by @chaokunyang in https://github.com/apache/fory/pull/3549
+* refactor(swift): refine swift api by @chaokunyang in https://github.com/apache/fory/pull/3554
+* feat(xlang): refine xlang api and enum serialization by @chaokunyang in https://github.com/apache/fory/pull/3555
+* feat(java): remove guava dependency from fory java by @chaokunyang in https://github.com/apache/fory/pull/3557
+* refactor(dart): new dart implementation by @chaokunyang in https://github.com/apache/fory/pull/3551
+* feat(compiler): Add JavaScript/TypeScript IDL code generation by @miantalha45 in https://github.com/apache/fory/pull/3394
+* perf(javascript): add javascript benchmark by @chaokunyang in https://github.com/apache/fory/pull/3562
+* perf(dart): optimize struct deserialize with direct dispatch codegen by @yash-agarwa-l in https://github.com/apache/fory/pull/3563
+* feat(dart): add dart IDL support by @chaokunyang in https://github.com/apache/fory/pull/3571
+* feat(python): fix python struct xlang ref track error by @chaokunyang in https://github.com/apache/fory/pull/3574
+* feat: make generate enum use id for wire format by @chaokunyang in https://github.com/apache/fory/pull/3576
+
+
+## Bug Fix
+* fix(java): Restore compact codec fixed width optimizations by @stevenschlansker in https://github.com/apache/fory/pull/3478
+* fix(rust): handle panics from fuzz-found edge cases by @utafrali in https://github.com/apache/fory/pull/3481
+* fix(rust): add error handling logic for std duration; add support for chrono duration by @BaldDemian in https://github.com/apache/fory/pull/3490
+* fix(compiler): validate rpc request/response types by @retryoos in https://github.com/apache/fory/pull/3493
+* fix(c++): fix misaligned address access errors detected by UBSan in buffer.h by @BaldDemian in https://github.com/apache/fory/pull/3479
+* fix(java): finalize codegen config hash on first use by @chaokunyang in https://github.com/apache/fory/pull/3495
+* fix(rust): fix several panics detected by cargo-fuzz by @BaldDemian in https://github.com/apache/fory/pull/3483
+* fix(java): handle private final map codegen by @chaokunyang in https://github.com/apache/fory/pull/3504
+* fix(compiler): repair broken service example and add regression coverage by @VikingDeng in https://github.com/apache/fory/pull/3505
+* fix(rust): deep clone TypeMeta to prevent UB in concurrent scenarios by @BaldDemian in https://github.com/apache/fory/pull/3511
+* fix(compiler): fix failed tests in compiler; add compiler CI by @BaldDemian in https://github.com/apache/fory/pull/3516
+* fix(compiler): allow qualified nested types in FDL rpc signatures by @VikingDeng in https://github.com/apache/fory/pull/3518
+* fix(java): preserve ConcurrentSkipListSet comparator on copy by @mandrean in https://github.com/apache/fory/pull/3520
+* test(compiler): add IR validation and codegen tests for gRPC service support by @darius024 in https://github.com/apache/fory/pull/3528
+* fix(java): Correct resolution of dependent/nested serializers in GraalVM by @rakow in https://github.com/apache/fory/pull/3532
+* fix(java): fix objectstream serializer async jit and graalvm support by @chaokunyang in https://github.com/apache/fory/pull/3534
+* ci: fix Bazel cache paths for C++ workflows by @chaokunyang in https://github.com/apache/fory/pull/3535
+* fix(python): fix wrong calling orders in visit_other by @BaldDemian in https://github.com/apache/fory/pull/3542
+* fix(js): corrected the float64 array size by @ayush00git in https://github.com/apache/fory/pull/3541
+* fix(java): configure type checker during build by @chaokunyang in https://github.com/apache/fory/pull/3550
+* fix(java): auto-select child serializers for sorted containers by @chaokunyang in https://github.com/apache/fory/pull/3552
+* fix(java): support skip optional sql serializers for java11+ by @chaokunyang in https://github.com/apache/fory/pull/3553
+* fix(rust): apply consistent pascalcase naming for nested types by @utafrali in https://github.com/apache/fory/pull/3548
+* fix(javascript): fix flaky javascript idl tests by @chaokunyang in https://github.com/apache/fory/pull/3565
+* fix(swift): fix swift generated code compile warnings by @chaokunyang in https://github.com/apache/fory/pull/3566
+* fix(java): add test for previous uncaught regression. by @PiotrDuz in https://github.com/apache/fory/pull/3573
+
+## Other Improvements
+* chore(java): Update Spotless and Checkstyle to allow building with JDK25 by @stevenschlansker in https://github.com/apache/fory/pull/3476
+* chore(java): Clean up Javadoc warnings, and fail the build if any new ones are introduced by @stevenschlansker in https://github.com/apache/fory/pull/3477
+* chore: bump version to 0.16.0 by @chaokunyang in https://github.com/apache/fory/pull/3488
+* docs: add python benchmark result to readme by @chaokunyang in https://github.com/apache/fory/pull/3496
+* docs: fix benchmark plots by @chaokunyang in https://github.com/apache/fory/pull/3498
+* docs: add fory code review skill by @chaokunyang in https://github.com/apache/fory/pull/3500
+* chore: adjust skills softlinks by @chaokunyang in https://github.com/apache/fory/pull/3501
+* chore(cpp): configure CI to extract and execute C++ code from Markdo… by @Tyooughtul in https://github.com/apache/fory/pull/3381
+* docs: improve comments in Java generator by @codewithtarun2005 in https://github.com/apache/fory/pull/3507
+* docs: refactor agents.md to reduce token usage by @chaokunyang in https://github.com/apache/fory/pull/3538
+* docs: add ai-review policy by @chaokunyang in https://github.com/apache/fory/pull/3545
+* chore: Bump org.apache.logging.log4j:log4j-core from 2.25.3 to 2.25.4 in /java/fory-test-core by @dependabot[bot] in https://github.com/apache/fory/pull/3556
+* chore(javascript): rename ref tracking to ref by @chaokunyang in https://github.com/apache/fory/pull/3559
+* docs(dart): add dart docs by @chaokunyang in https://github.com/apache/fory/pull/3560
+* docs(javascript): add javascript docs by @chaokunyang in https://github.com/apache/fory/pull/3561
+* docs: refine dart and javascript docs by @chaokunyang in https://github.com/apache/fory/pull/3567
+* docs(dart): update dart benchmark docs by @yash-agarwa-l in https://github.com/apache/fory/pull/3568
+* docs: update readme by @chaokunyang in https://github.com/apache/fory/pull/3575
+
+## New Contributors
+* @utafrali made their first contribution in https://github.com/apache/fory/pull/3481
+* @BaldDemian made their first contribution in https://github.com/apache/fory/pull/3490
+* @retryoos made their first contribution in https://github.com/apache/fory/pull/3493
+* @Tyooughtul made their first contribution in https://github.com/apache/fory/pull/3381
+* @UninspiredCarrot made their first contribution in https://github.com/apache/fory/pull/3487
+* @VikingDeng made their first contribution in https://github.com/apache/fory/pull/3505
+* @codewithtarun2005 made their first contribution in https://github.com/apache/fory/pull/3507
+* @darius024 made their first contribution in https://github.com/apache/fory/pull/3528
+* @rakow made their first contribution in https://github.com/apache/fory/pull/3532
+* @PiotrDuz made their first contribution in https://github.com/apache/fory/pull/3573
+
+
+**Full Changelog**: https://github.com/apache/fory/compare/v0.16.0...v0.17.0
diff --git a/static/img/blog/fory_0_17_0_release/dart_throughput.png b/static/img/blog/fory_0_17_0_release/dart_throughput.png
new file mode 100644
index 000000000..f0c4d91d8
Binary files /dev/null and b/static/img/blog/fory_0_17_0_release/dart_throughput.png differ
diff --git a/static/img/blog/fory_0_17_0_release/javascript_throughput.png b/static/img/blog/fory_0_17_0_release/javascript_throughput.png
new file mode 100644
index 000000000..fffd41c47
Binary files /dev/null and b/static/img/blog/fory_0_17_0_release/javascript_throughput.png differ
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@fory.apache.org
For additional commands, e-mail: commits-help@fory.apache.org
(fory-site) 09/09: update skill
Posted by ch...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
chaokunyang pushed a commit to branch release_0.17.0
in repository https://gitbox.apache.org/repos/asf/fory-site.git
commit 32d68f41561a7bff1269a50dc83ac492ad694c2f
Author: 慕白 <ch...@antgroup.com>
AuthorDate: Mon Apr 20 00:20:55 2026 +0800
update skill
---
.claude/skills/release-major-version/SKILL.md | 30 +++++++++++++++++++++------
1 file changed, 24 insertions(+), 6 deletions(-)
diff --git a/.claude/skills/release-major-version/SKILL.md b/.claude/skills/release-major-version/SKILL.md
index 87638c616..46721088d 100644
--- a/.claude/skills/release-major-version/SKILL.md
+++ b/.claude/skills/release-major-version/SKILL.md
@@ -64,18 +64,22 @@ This workflow covers:
- `versions.json`
- `scripts/docusaurus-with-i18n.sh`
2. Confirm the current latest released version, the target new version, and the previous released version that will become the explicit older-version route after the cut.
-3. Verify the site repo already contains the intended upstream docs state from `apache/fory` before you start. At minimum:
- - check whether the needed `docs/guide` and `docs/specification` changes are already present in this repo
- - if not, stop and sync or ask the user before freezing a stale snapshot
+3. Verify the site repo already contains the intended upstream docs state from `apache/fory` before you start. Do not assume the release only touches `docs/guide`.
+ - compare current `docs/` against `versioned_docs/version-<previous-version>/` to discover the actual English doc delta for this release
+ - inspect the changed paths across all doc trees, including `docs/start`, `docs/guide`, `docs/compiler`, `docs/benchmarks`, `docs/specification`, `docs/introduction`, and `docs/community`
+ - explicitly confirm that any upstream docs expected for the release are already synced into this repo before freezing the snapshot
+ - if needed upstream docs are missing, stop and sync or ask the user before freezing a stale snapshot
4. Check that the target version is clean:
- the release blog filename does not already exist unless this is an intentional continuation
- the blog asset directory does not already exist unless this is an intentional continuation
- `versioned_docs/version-<version>/` does not already exist
- `versioned_sidebars/version-<version>-sidebars.json` does not already exist
- `i18n/zh-CN/docusaurus-plugin-content-docs/version-<version>/` does not already exist
-5. Scan:
- - `blog/` for the previous release post to use as template
- - `docs/`, `versioned_docs/`, and `i18n/zh-CN/docusaurus-plugin-content-docs/` so you understand the current tree
+5. Build a concrete release-doc scope before editing:
+ - scan `blog/` for the previous release post to use as template
+ - scan `docs/`, `versioned_docs/`, and `i18n/zh-CN/docusaurus-plugin-content-docs/` so you understand the current tree
+ - derive the release-doc scope from `versioned_docs/version-<previous-version>/` vs `docs/`
+ - treat that changed-doc list as the required release-doc scope for zh-CN translation and final review, instead of guessing only a few subtrees
6. If the task is non-trivial, maintain a task note under `tasks/task-<slug>.md` and archive it to `tasks/history/` when finished.
## Step 1: Write the Release Blog
@@ -140,6 +144,10 @@ Minimum workflow:
- keep blog asset paths aligned with the English source unless there is a deliberate zh-only asset change
4. Translate or sync the zh-CN docs for the doc changes that should ship with the new release.
- primary path mapping: `docs/<subpath>` -> `i18n/zh-CN/docusaurus-plugin-content-docs/current/<subpath>`
+ - do not limit this to `docs/guide/**`
+ - translate or sync every changed English doc in the release-doc scope relative to `versioned_docs/version-<previous-version>/`
+ - this includes changed files under `docs/benchmarks/**`, `docs/community/**`, `docs/compiler/**`, `docs/guide/**`, `docs/introduction/**`, `docs/specification/**`, and `docs/start/**`
+ - if a changed English current doc has no matching zh-CN current update before versioning, treat that as a blocking gap unless the file is intentionally English-only and documented as such
5. Follow the translation skill's hard rule: no external translation tools or services.
6. If top-level category labels changed, also update:
- `i18n/zh-CN/docusaurus-plugin-content-docs/current.json`
@@ -181,6 +189,11 @@ After the command:
4. Check for accidental carry-over of placeholder or half-English zh-CN content before accepting the snapshot
5. Decide whether a manual `i18n/zh-CN/docusaurus-plugin-content-docs/version-<version>.json` should be added for this release
6. If a later validation/build step generates additional fallback files under the new `version-<version>/` zh-CN tree, inspect them explicitly and decide whether they belong in the release commit
+7. Before accepting the snapshot, explicitly compare the release-doc scope in:
+ - `docs/<subpath>`
+ - `i18n/zh-CN/docusaurus-plugin-content-docs/current/<subpath>`
+ - `i18n/zh-CN/docusaurus-plugin-content-docs/version-<version>/<subpath>`
+ and resolve any obvious case where the versioned zh snapshot froze an older current zh file
## Step 6: Update the Default Docs Version
@@ -223,6 +236,9 @@ Also run targeted checks:
- for example, search for the previous release string, older release strings likely to be copy/paste remnants, and placeholders such as `TODO` / `TBD`
- treat stale latest-version references in current install/docs pages as blocking, especially in `docs/start/install.md`, `docs/guide/**/index.md`, and other `docs/guide/**` pages
- confirm release blog asset paths exist under `static/img/blog/fory_<version>_release/`
+- compare the release-doc scope against the previous release snapshot so you do not miss changed docs outside `guide/` such as `compiler/generated-code.md`
+- for each changed English current doc in the release-doc scope, verify whether the matching zh current doc is updated, missing, or intentionally left as English fallback
+- if any changed doc under `benchmarks/`, `community/`, `compiler/`, `guide/`, `introduction/`, `specification/`, or `start/` is missing from zh current, treat that as unfinished release work rather than optional follow-up
## Step 8: Fresh Self-Review
@@ -237,6 +253,8 @@ The review should check at least:
5. Are blog asset paths and benchmark links valid?
6. Are there any obvious missing follow-up edits, such as `docs/start/install.md` or guide pages with pinned version references that should move to the new release?
7. Did the workflow accidentally snapshot stale site docs because upstream `apache/fory` doc changes were not synced first?
+8. Did any changed English current doc outside `guide/` fail to get translated or reviewed in zh-CN before versioning, for example under `compiler/`, `benchmarks/`, `specification/`, `start/`, or `introduction/`?
+9. Does every changed zh current doc in the release-doc scope match the intended `version-<version>` snapshot, or did the workflow freeze an older zh current state?
Treat review findings as blocking until resolved or explicitly documented.
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@fory.apache.org
For additional commands, e-mail: commits-help@fory.apache.org
(fory-site) 08/09: Sync stale zh docs for 0.17
Posted by ch...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
chaokunyang pushed a commit to branch release_0.17.0
in repository https://gitbox.apache.org/repos/asf/fory-site.git
commit e25838356cb796aeb06acfa2ff0090999a75e4b2
Author: 慕白 <ch...@antgroup.com>
AuthorDate: Mon Apr 20 00:20:22 2026 +0800
Sync stale zh docs for 0.17
---
docs/start/usage.md | 4 +-
.../current/benchmarks/cpp/README.md | 110 +++-
.../benchmarks/dart/README.md | 34 +-
.../current/benchmarks/dart/mediacontent.png | Bin 0 -> 52584 bytes
.../current/benchmarks/dart/mediacontentlist.png | Bin 0 -> 55357 bytes
.../current/benchmarks/dart/sample.png | Bin 0 -> 42105 bytes
.../current/benchmarks/dart/samplelist.png | Bin 0 -> 51598 bytes
.../current/benchmarks/dart/struct.png | Bin 0 -> 38645 bytes
.../current/benchmarks/dart/structlist.png | Bin 0 -> 44541 bytes
.../current/benchmarks/dart/throughput.png | Bin 0 -> 89092 bytes
.../benchmarks/javascript/README.md | 46 +-
.../current/benchmarks/javascript/mediacontent.png | Bin 0 -> 55168 bytes
.../benchmarks/javascript/mediacontentlist.png | Bin 0 -> 56815 bytes
.../current/benchmarks/javascript/sample.png | Bin 0 -> 57185 bytes
.../current/benchmarks/javascript/samplelist.png | Bin 0 -> 57215 bytes
.../current/benchmarks/javascript/struct.png | Bin 0 -> 50777 bytes
.../current/benchmarks/javascript/structlist.png | Bin 0 -> 54735 bytes
.../current/benchmarks/javascript/throughput.png | Bin 0 -> 81947 bytes
.../current/benchmarks/python/README.md | 102 ++-
.../current/benchmarks/rust/README.md | 195 +++---
.../current/benchmarks/rust/mediacontent.png | Bin 0 -> 54130 bytes
.../current/benchmarks/rust/mediacontentlist.png | Bin 0 -> 54154 bytes
.../current/benchmarks/rust/sample.png | Bin 0 -> 44641 bytes
.../current/benchmarks/rust/samplelist.png | Bin 0 -> 46992 bytes
.../current/benchmarks/rust/struct.png | Bin 0 -> 49558 bytes
.../current/benchmarks/rust/structlist.png | Bin 0 -> 45987 bytes
.../current/benchmarks/rust/throughput.png | Bin 0 -> 75422 bytes
.../current/compiler/compiler-guide.md | 103 ++-
.../current/compiler/generated-code.md | 351 +++++++++-
.../current/compiler/index.md | 18 +-
.../current/compiler/schema-idl.md | 195 +++++-
.../current/guide/cpp/_category_.json | 2 +-
.../guide/{scala => csharp}/_category_.json | 2 +-
.../current/guide/csharp/basic-serialization.md | 131 ++++
.../current/guide/csharp/configuration.md | 124 ++++
.../current/guide/csharp/cross-language.md | 105 +++
.../current/guide/csharp/custom-serializers.md | 84 +++
.../current/guide/csharp/field-configuration.md | 75 +++
.../current/guide/csharp/index.md | 22 +-
.../current/guide/csharp/references.md | 72 +++
.../current/guide/csharp/schema-evolution.md | 90 +++
.../current/guide/csharp/supported-types.md | 97 +++
.../current/guide/csharp/thread-safety.md | 73 +++
.../current/guide/csharp/troubleshooting.md | 92 +++
.../current/guide/csharp/type-registration.md | 82 +++
.../current/guide/go/_category_.json | 2 +-
.../current/guide/go/codegen.md | 256 ++++----
.../current/guide/go/index.md | 15 +-
.../current/guide/graalvm_guide.md | 55 +-
.../current/guide/java/_category_.json | 2 +-
.../current/guide/java/advanced-features.md | 2 +-
.../current/guide/java/configuration.md | 66 +-
.../current/guide/java/custom-serializers.md | 713 ++++-----------------
.../current/guide/java/field-configuration.md | 7 +-
.../current/guide/java/index.md | 79 ++-
.../current/guide/java/migration.md | 2 +-
.../current/guide/java/schema-evolution.md | 40 +-
.../current/guide/java/troubleshooting.md | 112 ++--
.../current/guide/java/type-registration.md | 65 +-
.../current/guide/kotlin/_category_.json | 2 +-
.../current/guide/kotlin/fory-creation.md | 14 +-
.../current/guide/python/_category_.json | 2 +-
.../current/guide/python/custom-serializers.md | 32 +-
.../current/guide/python/type-registration.md | 2 +-
.../current/guide/rust/_category_.json | 2 +-
.../current/guide/scala/_category_.json | 2 +-
.../current/guide/scala/fory-creation.md | 15 +-
.../kotlin => current/guide/swift}/_category_.json | 2 +-
.../current/guide/swift/basic-serialization.md | 114 ++++
.../current/guide/swift/configuration.md | 99 +++
.../current/guide/swift/cross-language.md | 97 +++
.../current/guide/swift/custom-serializers.md | 84 +++
.../current/guide/swift/field-configuration.md | 92 +++
.../current/guide/swift/index.md | 84 +++
.../current/guide/swift/polymorphism.md | 80 +++
.../current/guide/swift/references.md | 110 ++++
.../current/guide/swift/row-format.md | 38 ++
.../current/guide/swift/schema-evolution.md | 77 +++
.../current/guide/swift/troubleshooting.md | 92 +++
.../current/guide/swift/type-registration.md | 76 +++
.../current/guide/xlang/_category_.json | 2 +-
.../specification/java_serialization_spec.md | 4 +-
.../specification/xlang_implementation_guide.md | 553 ++++++++++------
.../specification/xlang_serialization_spec.md | 2 +-
.../current/specification/xlang_type_mapping.md | 4 +-
.../current/start/usage.md | 4 +-
.../version-0.17/benchmarks/cpp/README.md | 110 +++-
.../version-0.17/benchmarks/dart/README.md | 34 +-
.../version-0.17/benchmarks/javascript/README.md | 46 +-
.../version-0.17/benchmarks/python/README.md | 102 ++-
.../version-0.17/benchmarks/rust/README.md | 195 +++---
.../version-0.17/compiler/compiler-guide.md | 103 ++-
.../version-0.17/compiler/generated-code.md | 351 +++++++++-
.../version-0.17/compiler/index.md | 18 +-
.../version-0.17/compiler/schema-idl.md | 195 +++++-
.../version-0.17/guide/cpp/_category_.json | 2 +-
.../guide/csharp}/_category_.json | 2 +-
.../guide/csharp/basic-serialization.md | 131 ++++
.../version-0.17/guide/csharp/configuration.md | 124 ++++
.../version-0.17/guide/csharp/cross-language.md | 105 +++
.../guide/csharp/custom-serializers.md | 84 +++
.../guide/csharp/field-configuration.md | 75 +++
.../version-0.17/guide/csharp/index.md | 22 +-
.../version-0.17/guide/csharp/references.md | 72 +++
.../version-0.17/guide/csharp/schema-evolution.md | 90 +++
.../version-0.17/guide/csharp/supported-types.md | 97 +++
.../version-0.17/guide/csharp/thread-safety.md | 73 +++
.../version-0.17/guide/csharp/troubleshooting.md | 92 +++
.../version-0.17/guide/csharp/type-registration.md | 82 +++
.../version-0.17/guide/go/_category_.json | 2 +-
.../version-0.17/guide/go/codegen.md | 256 ++++----
.../version-0.17/guide/go/index.md | 15 +-
.../version-0.17/guide/graalvm_guide.md | 55 +-
.../version-0.17/guide/java/_category_.json | 2 +-
.../version-0.17/guide/java/advanced-features.md | 2 +-
.../version-0.17/guide/java/configuration.md | 66 +-
.../version-0.17/guide/java/custom-serializers.md | 713 ++++-----------------
.../version-0.17/guide/java/field-configuration.md | 7 +-
.../version-0.17/guide/java/index.md | 79 ++-
.../version-0.17/guide/java/migration.md | 2 +-
.../version-0.17/guide/java/schema-evolution.md | 40 +-
.../version-0.17/guide/java/troubleshooting.md | 112 ++--
.../version-0.17/guide/java/type-registration.md | 65 +-
.../version-0.17/guide/kotlin/_category_.json | 2 +-
.../version-0.17/guide/kotlin/fory-creation.md | 14 +-
.../version-0.17/guide/python/_category_.json | 2 +-
.../guide/python/custom-serializers.md | 32 +-
.../version-0.17/guide/python/type-registration.md | 2 +-
.../version-0.17/guide/rust/_category_.json | 2 +-
.../version-0.17/guide/scala/_category_.json | 2 +-
.../version-0.17/guide/scala/fory-creation.md | 15 +-
.../guide/{kotlin => swift}/_category_.json | 2 +-
.../guide/swift/basic-serialization.md | 114 ++++
.../version-0.17/guide/swift/configuration.md | 99 +++
.../version-0.17/guide/swift/cross-language.md | 97 +++
.../version-0.17/guide/swift/custom-serializers.md | 84 +++
.../guide/swift/field-configuration.md | 92 +++
.../version-0.17/guide/swift/index.md | 84 +++
.../version-0.17/guide/swift/polymorphism.md | 80 +++
.../version-0.17/guide/swift/references.md | 110 ++++
.../version-0.17/guide/swift/row-format.md | 38 ++
.../version-0.17/guide/swift/schema-evolution.md | 77 +++
.../version-0.17/guide/swift/troubleshooting.md | 92 +++
.../version-0.17/guide/swift/type-registration.md | 76 +++
.../version-0.17/guide/xlang/_category_.json | 2 +-
.../version-0.17/start/usage.md | 4 +-
versioned_docs/version-0.17/start/usage.md | 4 +-
147 files changed, 7323 insertions(+), 2734 deletions(-)
diff --git a/docs/start/usage.md b/docs/start/usage.md
index 4dc169da0..4fa4a2f0b 100644
--- a/docs/start/usage.md
+++ b/docs/start/usage.md
@@ -172,7 +172,7 @@ let result: Person = try fory.deserialize(data)
print("\(result.name) \(result.age)")
```
-For detailed Swift usage including polymorphism, schema evolution, and troubleshooting, see [Swift Guide](../guide/swift/index.md).
+For detailed Swift usage including polymorphism, schema evolution, and troubleshooting, see [Swift Guide](../guide/swift/).
### Rust Serialization
@@ -496,7 +496,7 @@ For examples with circular references, shared references, and polymorphism acros
- [Cross-Language Serialization Guide](../guide/xlang/index.md)
- [Go Guide - Cross Language](../guide/go/cross-language.md)
- [C# Guide - Cross Language](../guide/csharp/cross-language.md)
-- [Swift Guide - Cross Language](../guide/swift/cross-language.md)
+- [Swift Guide - Cross Language](../guide/swift/cross_language)
## Row Format Encoding
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/cpp/README.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/cpp/README.md
index a2be4452e..1dc362e9d 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/cpp/README.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/cpp/README.md
@@ -1,60 +1,104 @@
# C++ 基准性能报告
-_生成时间：2025-12-15 23:03:06_
+_生成于 2026-02-19 10:20:08_
## 如何生成本报告
```bash
-cd benchmarks/cpp_benchmark/build
+cd benchmarks/cpp/build
./fory_benchmark --benchmark_format=json --benchmark_out=benchmark_results.json
cd ..
python benchmark_report.py --json-file build/benchmark_results.json --output-dir report
```
-## 硬件与系统信息
+## 硬件与操作系统信息
-| Key | Value |
+| 键 | 值 |
| -------------------------- | ------------------------- |
-| OS | Darwin 24.6.0 |
-| Machine | arm64 |
-| Processor | arm |
-| CPU Cores (Physical) | 12 |
-| CPU Cores (Logical) | 12 |
-| Total RAM (GB) | 48.0 |
-| Benchmark Date | 2025-12-15T23:02:49+08:00 |
-| CPU Cores (from benchmark) | 12 |
+| 操作系统 | Darwin 24.6.0 |
+| 机器架构 | arm64 |
+| 处理器 | arm |
+| CPU 核心数（物理） | 12 |
+| CPU 核心数（逻辑） | 12 |
+| 总内存（GB） | 48.0 |
+| 基准日期 | 2026-02-19T10:19:31+08:00 |
+| CPU 核心数（基准采集） | 12 |
## 基准图表
+下列各类图表均展示吞吐量（ops/sec）。
+
+### 总吞吐量
+
+### Mediacontent
+
+
+
+### Mediacontentlist
+
+
+
+### Sample
+
+
+
+### Samplelist
+
+
+
+### Struct
+
+
+
+### Structlist
+
+
+
## 基准结果
-### 耗时结果（纳秒）
+### 延迟结果（纳秒）
-| Datatype | Operation | Fory (ns) | Protobuf (ns) | Faster |
-| ------------ | ----------- | --------- | ------------- | ----------- |
-| Mediacontent | Serialize | 443.5 | 1982.5 | Fory (4.5x) |
-| Mediacontent | Deserialize | 1349.0 | 2525.2 | Fory (1.9x) |
-| Sample | Serialize | 235.4 | 309.7 | Fory (1.3x) |
-| Sample | Deserialize | 1068.7 | 1397.0 | Fory (1.3x) |
-| Struct | Serialize | 109.4 | 170.0 | Fory (1.6x) |
-| Struct | Deserialize | 129.1 | 161.2 | Fory (1.2x) |
+| 数据类型 | 操作 | fory (ns) | protobuf (ns) | msgpack (ns) | 最快 |
+| ---------------- | ----------- | --------- | ------------- | ------------ | ------- |
+| MediaContent | Serialize | 120.4 | 863.8 | 281.1 | fory |
+| MediaContent | Deserialize | 397.9 | 1197.9 | 2768.6 | fory |
+| MediaContentList | Serialize | 480.9 | 4744.3 | 1407.5 | fory |
+| MediaContentList | Deserialize | 2022.1 | 6426.0 | 13595.9 | fory |
+| Sample | Serialize | 72.8 | 92.0 | 296.1 | fory |
+| Sample | Deserialize | 328.2 | 641.2 | 2642.9 | fory |
+| SampleList | Serialize | 287.3 | 4761.2 | 1506.7 | fory |
+| SampleList | Deserialize | 1711.8 | 4875.2 | 13232.0 | fory |
+| Struct | Serialize | 27.3 | 32.4 | 55.2 | fory |
+| Struct | Deserialize | 21.4 | 25.0 | 747.3 | fory |
+| StructList | Serialize | 69.4 | 419.8 | 285.9 | fory |
+| StructList | Deserialize | 129.4 | 334.4 | 3385.8 | fory |
### 吞吐结果（ops/sec）
-| Datatype | Operation | Fory TPS | Protobuf TPS | Faster |
-| ------------ | ----------- | --------- | ------------ | ----------- |
-| Mediacontent | Serialize | 2,254,915 | 504,410 | Fory (4.5x) |
-| Mediacontent | Deserialize | 741,303 | 396,013 | Fory (1.9x) |
-| Sample | Serialize | 4,248,973 | 3,229,102 | Fory (1.3x) |
-| Sample | Deserialize | 935,709 | 715,837 | Fory (1.3x) |
-| Struct | Serialize | 9,143,618 | 5,881,005 | Fory (1.6x) |
-| Struct | Deserialize | 7,746,787 | 6,202,164 | Fory (1.2x) |
+| 数据类型 | 操作 | fory TPS | protobuf TPS | msgpack TPS | 最快 |
+| ---------------- | ----------- | ---------- | ------------ | ----------- | ------- |
+| MediaContent | Serialize | 8,306,128 | 1,157,712 | 3,557,700 | fory |
+| MediaContent | Deserialize | 2,513,488 | 834,808 | 361,190 | fory |
+| MediaContentList | Serialize | 2,079,229 | 210,777 | 710,492 | fory |
+| MediaContentList | Deserialize | 494,523 | 155,617 | 73,551 | fory |
+| Sample | Serialize | 13,745,041 | 10,871,787 | 3,377,292 | fory |
+| Sample | Deserialize | 3,047,224 | 1,559,633 | 378,369 | fory |
+| SampleList | Serialize | 3,481,110 | 210,029 | 663,693 | fory |
+| SampleList | Deserialize | 584,168 | 205,121 | 75,574 | fory |
+| Struct | Serialize | 36,672,581 | 30,900,039 | 18,114,682 | fory |
+| Struct | Deserialize | 46,637,124 | 39,947,557 | 1,338,225 | fory |
+| StructList | Serialize | 14,419,548 | 2,381,886 | 3,497,903 | fory |
+| StructList | Deserialize | 7,729,173 | 2,990,652 | 295,353 | fory |
### 序列化数据大小（字节）
-| Datatype | Fory | Protobuf |
-| -------- | ---- | -------- |
-| Struct | 32 | 61 |
-| Sample | 384 | 375 |
+| 数据类型 | fory | protobuf | msgpack |
+| ---------------- | ---- | -------- | ------- |
+| Struct | 58 | 61 | 55 |
+| Sample | 446 | 375 | 530 |
+| MediaContent | 365 | 301 | 480 |
+| StructList | 184 | 315 | 289 |
+| SampleList | 1980 | 1890 | 2664 |
+| MediaContentList | 1535 | 1520 | 2421 |
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/dart/README.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/dart/README.md
similarity index 58%
copy from i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/dart/README.md
copy to i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/dart/README.md
index 090c930bf..6b8055d7d 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/dart/README.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/dart/README.md
@@ -1,26 +1,26 @@
-# Fory Dart Benchmark
+# Fory Dart 基准
-This benchmark compares serialization and deserialization throughput for Apache Fory and Protocol Buffers in Dart.
+该基准用于比较 Apache Fory 和 Protocol Buffers 在 Dart 中的序列化与反序列化吞吐量。
-## Hardware and Runtime Info
+## 硬件与运行时信息
-| Key | Value |
+| 键 | 值 |
| --------------------- | ---------------------------------------------------------------- |
-| Timestamp | 2026-04-13T21:55:28.456625Z |
-| OS | Version 26.2 (Build 25C56) |
-| Host | Macbook-Air.local |
-| CPU Cores (Logical) | 8 |
-| Memory (GB) | 8.00 |
+| 时间戳 | 2026-04-13T21:55:28.456625Z |
+| 操作系统 | Version 26.2 (Build 25C56) |
+| 主机 | Macbook-Air.local |
+| CPU 核心数（逻辑） | 8 |
+| 内存（GB） | 8.00 |
| Dart | 3.10.4 (stable) (Tue Dec 9 00:01:55 2025 -0800) on "macos_arm64" |
-| Samples per case | 5 |
-| Warmup per case (s) | 1.0 |
-| Duration per case (s) | 1.5 |
+| 每个用例的采样次数 | 5 |
+| 每个用例的预热时长（秒） | 1.0 |
+| 每个用例的持续时长（秒） | 1.5 |
-## Throughput Results
+## 吞吐结果
-| Datatype | Operation | Fory TPS | Protobuf TPS | Fastest |
+| 数据类型 | 操作 | Fory TPS | Protobuf TPS | 最快 |
| ---------------- | ----------- | --------: | -----------: | ------------ |
| Struct | Serialize | 3,989,432 | 1,884,653 | fory (2.12x) |
| Struct | Deserialize | 5,828,197 | 4,199,680 | fory (1.39x) |
@@ -35,9 +35,9 @@ This benchmark compares serialization and deserialization throughput for Apache
| MediaContentList | Serialize | 186,870 | 77,029 | fory (2.43x) |
| MediaContentList | Deserialize | 330,293 | 128,215 | fory (2.58x) |
-## Serialized Size (bytes)
+## 序列化大小（字节）
-| Datatype | Fory | Protobuf |
+| 数据类型 | Fory | Protobuf |
| ---------------- | ---: | -------: |
| Struct | 58 | 61 |
| Sample | 446 | 377 |
@@ -46,7 +46,7 @@ This benchmark compares serialization and deserialization throughput for Apache
| SampleList | 1980 | 1900 |
| MediaContentList | 1535 | 1550 |
-## Per-workload Plots
+## 各工作负载图表
### Struct
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/dart/mediacontent.png b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/dart/mediacontent.png
new file mode 100644
index 000000000..17bd33a9b
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/dart/mediacontent.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/dart/mediacontentlist.png b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/dart/mediacontentlist.png
new file mode 100644
index 000000000..a0d404e06
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/dart/mediacontentlist.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/dart/sample.png b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/dart/sample.png
new file mode 100644
index 000000000..11f2d7743
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/dart/sample.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/dart/samplelist.png b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/dart/samplelist.png
new file mode 100644
index 000000000..a4b8cb1c0
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/dart/samplelist.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/dart/struct.png b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/dart/struct.png
new file mode 100644
index 000000000..7d616cbed
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/dart/struct.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/dart/structlist.png b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/dart/structlist.png
new file mode 100644
index 000000000..01484cfe9
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/dart/structlist.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/dart/throughput.png b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/dart/throughput.png
new file mode 100644
index 000000000..f0c4d91d8
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/dart/throughput.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/javascript/README.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/javascript/README.md
similarity index 73%
copy from i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/javascript/README.md
copy to i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/javascript/README.md
index f51899233..9aa5ca43a 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/javascript/README.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/javascript/README.md
@@ -1,34 +1,34 @@
-# JavaScript Benchmark Performance Report
+# JavaScript 基准性能报告
-_Generated on 2026-04-14 17:11:43_
+_生成于 2026-04-14 17:11:43_
-## How to Generate This Report
+## 如何生成本报告
```bash
cd benchmarks/javascript
./run.sh
```
-## Hardware & OS Info
+## 硬件与操作系统信息
-| Key | Value |
+| 键 | 值 |
| -------------------------- | ------------------------ |
-| OS | Darwin 24.6.0 |
-| Machine | arm64 |
-| Processor | arm |
-| CPU Cores (Physical) | 12 |
-| CPU Cores (Logical) | 12 |
-| Total RAM (GB) | 48.0 |
-| Benchmark Date | 2026-04-14T09:09:51.959Z |
-| CPU Cores (from benchmark) | 12 |
+| 操作系统 | Darwin 24.6.0 |
+| 机器架构 | arm64 |
+| 处理器 | arm |
+| CPU 核心数（物理） | 12 |
+| CPU 核心数（逻辑） | 12 |
+| 总内存（GB） | 48.0 |
+| 基准日期 | 2026-04-14T09:09:51.959Z |
+| CPU 核心数（基准采集） | 12 |
| Node.js | v22.20.0 |
| V8 | 12.4.254.21-node.33 |
-## Benchmark Plots
+## 基准图表
-All class-level plots below show throughput (ops/sec).
+下列各类图表均展示吞吐量（ops/sec）。
-### Throughput
+### 总吞吐量
@@ -56,11 +56,11 @@ All class-level plots below show throughput (ops/sec).
-## Benchmark Results
+## 基准结果
-### Timing Results (nanoseconds)
+### 延迟结果（纳秒）
-| Datatype | Operation | fory (ns) | protobuf (ns) | json (ns) | Fastest |
+| 数据类型 | 操作 | fory (ns) | protobuf (ns) | json (ns) | 最快 |
| ---------------- | ----------- | --------- | ------------- | --------- | ------- |
| Struct | Serialize | 118.3 | 525.3 | 327.0 | fory |
| Struct | Deserialize | 103.0 | 121.5 | 259.0 | fory |
@@ -75,9 +75,9 @@ All class-level plots below show throughput (ops/sec).
| MediaContentList | Serialize | 3495.9 | 6712.4 | 3540.5 | fory |
| MediaContentList | Deserialize | 2653.7 | 4087.9 | 5258.9 | fory |
-### Throughput Results (ops/sec)
+### 吞吐结果（ops/sec）
-| Datatype | Operation | fory TPS | protobuf TPS | json TPS | Fastest |
+| 数据类型 | 操作 | fory TPS | protobuf TPS | json TPS | 最快 |
| ---------------- | ----------- | --------- | ------------ | --------- | ------- |
| Struct | Serialize | 8,453,950 | 1,903,706 | 3,058,232 | fory |
| Struct | Deserialize | 9,705,287 | 8,233,664 | 3,860,538 | fory |
@@ -92,9 +92,9 @@ All class-level plots below show throughput (ops/sec).
| MediaContentList | Serialize | 286,053 | 148,977 | 282,445 | fory |
| MediaContentList | Deserialize | 376,826 | 244,622 | 190,155 | fory |
-### Serialized Data Sizes (bytes)
+### 序列化数据大小（字节）
-| Datatype | fory | protobuf | json |
+| 数据类型 | fory | protobuf | json |
| ---------------- | ---- | -------- | ---- |
| Struct | 58 | 61 | 103 |
| Sample | 446 | 377 | 724 |
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/javascript/mediacontent.png b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/javascript/mediacontent.png
new file mode 100644
index 000000000..45d2c34db
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/javascript/mediacontent.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/javascript/mediacontentlist.png b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/javascript/mediacontentlist.png
new file mode 100644
index 000000000..a5763d069
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/javascript/mediacontentlist.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/javascript/sample.png b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/javascript/sample.png
new file mode 100644
index 000000000..57c619b33
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/javascript/sample.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/javascript/samplelist.png b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/javascript/samplelist.png
new file mode 100644
index 000000000..6e66a0a11
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/javascript/samplelist.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/javascript/struct.png b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/javascript/struct.png
new file mode 100644
index 000000000..e78a56967
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/javascript/struct.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/javascript/structlist.png b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/javascript/structlist.png
new file mode 100644
index 000000000..cae684ed2
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/javascript/structlist.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/javascript/throughput.png b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/javascript/throughput.png
new file mode 100644
index 000000000..fffd41c47
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/javascript/throughput.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/python/README.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/python/README.md
index 0cf659028..053db4c42 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/python/README.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/python/README.md
@@ -1,6 +1,6 @@
# Python 基准性能报告
-_生成于 2026-03-03 13:42:38_
+_生成于 2026-04-14 14:53:18_
## 如何生成本报告
@@ -39,89 +39,75 @@ cd benchmarks/python
### 总吞吐量
-<p align="center">
-<img src="throughput.png" width="90%" />
-</p>
+
-### `MediaContent` 基准
+### Mediacontent
-<p align="center">
-<img src="mediacontent.png" width="90%" />
-</p>
+
-### `MediaContentList` 基准
+### Mediacontentlist
-<p align="center">
-<img src="mediacontentlist.png" width="90%" />
-</p>
+
### Sample
-<p align="center">
-<img src="sample.png" width="90%" />
-</p>
+
### Samplelist
-<p align="center">
-<img src="samplelist.png" width="90%" />
-</p>
+
### Struct
-<p align="center">
-<img src="struct.png" width="90%" />
-</p>
+
### Structlist
-<p align="center">
-<img src="structlist.png" width="90%" />
-</p>
+
## 基准结果
### 延迟结果（纳秒）
-| 数据类型 | 操作 | fory (ns) | pickle (ns) | protobuf (ns) | 最快 |
-| ---------------- | ----------- | --------- | ----------- | ------------- | ------- |
-| Struct | Serialize | 417.9 | 868.9 | 548.9 | fory |
-| Struct | Deserialize | 516.1 | 910.6 | 742.4 | fory |
-| Sample | Serialize | 828.1 | 1663.5 | 2383.7 | fory |
-| Sample | Deserialize | 1282.4 | 2296.3 | 3992.7 | fory |
-| MediaContent | Serialize | 1139.9 | 2859.7 | 2867.1 | fory |
-| MediaContent | Deserialize | 1719.5 | 2854.3 | 3236.1 | fory |
-| StructList | Serialize | 1009.1 | 2630.6 | 3281.6 | fory |
-| StructList | Deserialize | 1387.2 | 2651.9 | 3547.9 | fory |
-| SampleList | Serialize | 2828.3 | 5541.0 | 15256.6 | fory |
-| SampleList | Deserialize | 5043.4 | 8144.7 | 18912.5 | fory |
-| MediaContentList | Serialize | 3417.9 | 9341.9 | 15853.2 | fory |
-| MediaContentList | Deserialize | 6138.7 | 8435.3 | 16442.6 | fory |
+| 数据类型 | 操作 | fory (ns) | pickle (ns) | protobuf (ns) | 最快 |
+| ---------------- | ----------- | --------- | ----------- | ------------- | -------- |
+| Struct | Serialize | 431.3 | 963.9 | 604.3 | fory |
+| Struct | Deserialize | 476.6 | 925.1 | 804.8 | fory |
+| Sample | Serialize | 4966.3 | 12725.1 | 4396.0 | protobuf |
+| Sample | Deserialize | 4362.9 | 6409.2 | 6620.1 | fory |
+| MediaContent | Serialize | 1213.1 | 4263.1 | 3173.7 | fory |
+| MediaContent | Deserialize | 1620.7 | 4625.8 | 4306.3 | fory |
+| StructList | Serialize | 1072.0 | 2798.6 | 3759.0 | fory |
+| StructList | Deserialize | 1334.7 | 2756.7 | 3963.5 | fory |
+| SampleList | Serialize | 23866.8 | 33484.5 | 18711.7 | protobuf |
+| SampleList | Deserialize | 17347.5 | 22999.0 | 36077.1 | fory |
+| MediaContentList | Serialize | 3526.9 | 11258.1 | 17670.6 | fory |
+| MediaContentList | Deserialize | 6241.1 | 10209.5 | 21440.7 | fory |
### 吞吐结果（ops/sec）
-| 数据类型 | 操作 | fory TPS | pickle TPS | protobuf TPS | 最快 |
-| ---------------- | ----------- | --------- | ---------- | ------------ | ------- |
-| Struct | Serialize | 2,393,086 | 1,150,946 | 1,821,982 | fory |
-| Struct | Deserialize | 1,937,707 | 1,098,170 | 1,346,915 | fory |
-| Sample | Serialize | 1,207,542 | 601,144 | 419,511 | fory |
-| Sample | Deserialize | 779,789 | 435,489 | 250,460 | fory |
-| MediaContent | Serialize | 877,300 | 349,688 | 348,780 | fory |
-| MediaContent | Deserialize | 581,563 | 350,354 | 309,018 | fory |
-| StructList | Serialize | 991,017 | 380,145 | 304,732 | fory |
-| StructList | Deserialize | 720,901 | 377,081 | 281,855 | fory |
-| SampleList | Serialize | 353,574 | 180,473 | 65,545 | fory |
-| SampleList | Deserialize | 198,280 | 122,780 | 52,875 | fory |
-| MediaContentList | Serialize | 292,578 | 107,045 | 63,079 | fory |
-| MediaContentList | Deserialize | 162,902 | 118,550 | 60,818 | fory |
+| 数据类型 | 操作 | fory TPS | pickle TPS | protobuf TPS | 最快 |
+| ---------------- | ----------- | --------- | ---------- | ------------ | -------- |
+| Struct | Serialize | 2,318,598 | 1,037,429 | 1,654,700 | fory |
+| Struct | Deserialize | 2,098,391 | 1,081,003 | 1,242,545 | fory |
+| Sample | Serialize | 201,358 | 78,585 | 227,479 | protobuf |
+| Sample | Deserialize | 229,204 | 156,026 | 151,056 | fory |
+| MediaContent | Serialize | 824,338 | 234,569 | 315,087 | fory |
+| MediaContent | Deserialize | 616,999 | 216,177 | 232,216 | fory |
+| StructList | Serialize | 932,803 | 357,322 | 266,029 | fory |
+| StructList | Deserialize | 749,212 | 362,753 | 252,301 | fory |
+| SampleList | Serialize | 41,899 | 29,865 | 53,442 | protobuf |
+| SampleList | Deserialize | 57,645 | 43,480 | 27,718 | fory |
+| MediaContentList | Serialize | 283,535 | 88,825 | 56,591 | fory |
+| MediaContentList | Deserialize | 160,227 | 97,948 | 46,640 | fory |
### 序列化数据大小（字节）
| 数据类型 | fory | pickle | protobuf |
| ---------------- | ---- | ------ | -------- |
-| Struct | 72 | 126 | 61 |
-| Sample | 517 | 793 | 375 |
-| MediaContent | 470 | 586 | 301 |
-| StructList | 205 | 420 | 315 |
-| SampleList | 1810 | 2539 | 1890 |
-| MediaContentList | 1756 | 1377 | 1520 |
+| Struct | 58 | 126 | 61 |
+| Sample | 446 | 1176 | 375 |
+| MediaContent | 391 | 624 | 301 |
+| StructList | 184 | 420 | 315 |
+| SampleList | 1980 | 3546 | 1890 |
+| MediaContentList | 1665 | 1415 | 1520 |
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/rust/README.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/rust/README.md
index fdaa812b8..d09f26abf 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/rust/README.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/rust/README.md
@@ -1,104 +1,103 @@
-## 性能对比报告
+# Rust 基准性能报告
-_生成时间：2025-10-26 18:36:41_
+_生成于 2026-03-20 18:40:46_
-如何生成性能报告：
+## 如何生成本报告
```bash
-cd benchmarks/rust_benchmark
-cargo bench 2>&1 | tee cargo_bench.log
-python benchmark_report.py --log-file cargo_bench.log --output-dir=report_output
+cd benchmarks/rust
+cargo bench --bench serialization_bench 2>&1 | tee results/cargo_bench.log
+cargo run --release --bin fory_profiler -- --print-all-serialized-sizes | tee results/serialized_sizes.txt
+python benchmark_report.py --log-file results/cargo_bench.log --size-file results/serialized_sizes.txt --output-dir results
```
-### 硬件与系统信息
-
-| Key | Value |
-| -------------------- | ------------- |
-| OS | Darwin 24.5.0 |
-| Machine | arm64 |
-| Processor | arm |
-| CPU Cores (Physical) | 12 |
-| CPU Cores (Logical) | 12 |
-| Total RAM (GB) | 48.0 |
-
-### 基准图表
-
-**company**
-
-
-
-**ecommerce_data**
-
-
-
-**person**
-
-
-
-**simple_list**
-
-
-
-**simple_map**
-
-
-
-**simple_struct**
-
-
-
-**system_data**
-
-
-
-### 序列化结果
-
-| Datatype | Size | Operation | Fory TPS | JSON TPS | Protobuf TPS | Fastest |
-| -------------- | ------ | --------- | ---------- | ---------- | ------------ | ------- |
-| company | small | serialize | 10,063,906 | 761,673 | 896,620 | fory |
-| company | medium | serialize | 412,507 | 33,835 | 37,590 | fory |
-| company | large | serialize | 9,183 | 793 | 880 | fory |
-| ecommerce_data | small | serialize | 2,350,729 | 206,262 | 256,970 | fory |
-| ecommerce_data | medium | serialize | 59,977 | 4,699 | 5,242 | fory |
-| ecommerce_data | large | serialize | 3,727 | 266 | 295 | fory |
-| person | small | serialize | 13,632,522 | 1,345,189 | 1,475,035 | fory |
-| person | medium | serialize | 3,839,656 | 337,610 | 369,031 | fory |
-| person | large | serialize | 907,853 | 79,631 | 91,408 | fory |
-| simple_list | small | serialize | 27,726,945 | 4,874,957 | 4,643,172 | fory |
-| simple_list | medium | serialize | 4,770,765 | 401,558 | 397,551 | fory |
-| simple_list | large | serialize | 606,061 | 41,061 | 44,565 | fory |
-| simple_map | small | serialize | 22,862,369 | 3,888,025 | 2,695,999 | fory |
-| simple_map | medium | serialize | 2,128,973 | 204,319 | 193,132 | fory |
-| simple_map | large | serialize | 177,847 | 18,419 | 18,668 | fory |
-| simple_struct | small | serialize | 35,729,598 | 10,167,045 | 8,633,342 | fory |
-| simple_struct | medium | serialize | 34,988,279 | 9,737,098 | 6,433,350 | fory |
-| simple_struct | large | serialize | 31,801,558 | 4,545,041 | 7,420,049 | fory |
-| system_data | small | serialize | 5,382,131 | 468,033 | 569,930 | fory |
-| system_data | medium | serialize | 174,240 | 11,896 | 14,753 | fory |
-| system_data | large | serialize | 10,671 | 876 | 1,040 | fory |
-
-### 反序列化结果
-
-| Datatype | Size | Operation | Fory TPS | JSON TPS | Protobuf TPS | Fastest |
-| -------------- | ------ | ----------- | ---------- | ---------- | ------------ | ------- |
-| company | small | deserialize | 1,145,593 | 718,597 | 917,431 | fory |
-| company | medium | deserialize | 35,195 | 24,474 | 25,057 | fory |
-| company | large | deserialize | 836 | 623 | 623 | fory |
-| ecommerce_data | small | deserialize | 278,427 | 183,237 | 241,109 | fory |
-| ecommerce_data | medium | deserialize | 5,622 | 3,820 | 4,249 | fory |
-| ecommerce_data | large | deserialize | 298 | 204 | 217 | fory |
-| person | small | deserialize | 1,924,372 | 1,214,388 | 1,675,631 | fory |
-| person | medium | deserialize | 371,016 | 265,280 | 266,333 | fory |
-| person | large | deserialize | 84,839 | 63,975 | 61,820 | fory |
-| simple_list | small | deserialize | 6,129,329 | 3,599,582 | 4,429,286 | fory |
-| simple_list | medium | deserialize | 460,745 | 305,409 | 337,336 | fory |
-| simple_list | large | deserialize | 54,348 | 33,962 | 38,776 | fory |
-| simple_map | small | deserialize | 3,686,364 | 3,090,426 | 3,477,051 | fory |
-| simple_map | medium | deserialize | 171,774 | 126,638 | 119,323 | fory |
-| simple_map | large | deserialize | 16,501 | 10,920 | 10,853 | fory |
-| simple_struct | small | deserialize | 31,476,235 | 12,948,168 | 28,280,543 | fory |
-| simple_struct | medium | deserialize | 30,077,902 | 10,431,118 | 23,012,841 | fory |
-| simple_struct | large | deserialize | 28,201,585 | 8,955,759 | 23,528,858 | fory |
-| system_data | small | deserialize | 644,870 | 421,106 | 549,209 | fory |
-| system_data | medium | deserialize | 14,322 | 9,205 | 10,565 | fory |
-| system_data | large | deserialize | 961 | 634 | 706 | fory |
+## 硬件与操作系统信息
+
+| 键 | 值 |
+| --------------------- | ------------------- |
+| 操作系统 | Darwin 24.6.0 |
+| 机器架构 | arm64 |
+| 处理器 | arm |
+| CPU 核心数（物理） | 12 |
+| CPU 核心数（逻辑） | 12 |
+| 总内存（GB） | 48.0 |
+| 基准日期 | 2026-03-20T18:40:44 |
+
+## 基准图表
+
+下列各类图表均展示吞吐量（ops/sec）。
+
+### 总吞吐量
+
+
+
+### MediaContent
+
+
+
+### MediaContentList
+
+
+
+### Sample
+
+
+
+### SampleList
+
+
+
+### Struct
+
+
+
+### StructList
+
+
+
+## 基准结果
+
+### 延迟结果（纳秒）
+
+| 数据类型 | 操作 | fory (ns) | protobuf (ns) | 最快 |
+| ---------------- | ----------- | --------- | ------------- | ------- |
+| Struct | Serialize | 69.6 | 76.8 | fory |
+| Struct | Deserialize | 27.0 | 70.4 | fory |
+| Sample | Serialize | 148.5 | 584.3 | fory |
+| Sample | Deserialize | 350.9 | 983.1 | fory |
+| MediaContent | Serialize | 277.8 | 553.2 | fory |
+| MediaContent | Deserialize | 472.3 | 706.4 | fory |
+| StructList | Serialize | 170.4 | 385.4 | fory |
+| StructList | Deserialize | 96.8 | 294.7 | fory |
+| SampleList | Serialize | 356.2 | 3155.7 | fory |
+| SampleList | Deserialize | 1644.1 | 4361.0 | fory |
+| MediaContentList | Serialize | 657.4 | 2844.0 | fory |
+| MediaContentList | Deserialize | 2397.7 | 3696.6 | fory |
+
+### 吞吐结果（ops/sec）
+
+| 数据类型 | 操作 | fory TPS | protobuf TPS | 最快 |
+| ---------------- | ----------- | ---------- | ------------ | ------- |
+| Struct | Serialize | 14,366,165 | 13,022,359 | fory |
+| Struct | Deserialize | 37,065,866 | 14,202,528 | fory |
+| Sample | Serialize | 6,734,914 | 1,711,537 | fory |
+| Sample | Deserialize | 2,849,409 | 1,017,201 | fory |
+| MediaContent | Serialize | 3,600,230 | 1,807,664 | fory |
+| MediaContent | Deserialize | 2,117,433 | 1,415,689 | fory |
+| StructList | Serialize | 5,866,823 | 2,595,043 | fory |
+| StructList | Deserialize | 10,330,152 | 3,393,051 | fory |
+| SampleList | Serialize | 2,807,333 | 316,887 | fory |
+| SampleList | Deserialize | 608,236 | 229,305 | fory |
+| MediaContentList | Serialize | 1,521,098 | 351,617 | fory |
+| MediaContentList | Deserialize | 417,066 | 270,519 | fory |
+
+### 序列化数据大小（字节）
+
+| 数据类型 | fory | protobuf |
+| ---------------- | ---- | -------- |
+| Struct | 58 | 61 |
+| Sample | 446 | 375 |
+| MediaContent | 365 | 301 |
+| StructList | 184 | 315 |
+| SampleList | 1980 | 1890 |
+| MediaContentList | 1535 | 1520 |
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/rust/mediacontent.png b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/rust/mediacontent.png
new file mode 100644
index 000000000..8d026ef4b
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/rust/mediacontent.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/rust/mediacontentlist.png b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/rust/mediacontentlist.png
new file mode 100644
index 000000000..f2bf6b721
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/rust/mediacontentlist.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/rust/sample.png b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/rust/sample.png
new file mode 100644
index 000000000..e63ebcbad
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/rust/sample.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/rust/samplelist.png b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/rust/samplelist.png
new file mode 100644
index 000000000..b7ba75b72
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/rust/samplelist.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/rust/struct.png b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/rust/struct.png
new file mode 100644
index 000000000..e12c6a332
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/rust/struct.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/rust/structlist.png b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/rust/structlist.png
new file mode 100644
index 000000000..e030cf45f
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/rust/structlist.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/rust/throughput.png b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/rust/throughput.png
new file mode 100644
index 000000000..be89782fb
Binary files /dev/null and b/i18n/zh-CN/docusaurus-plugin-content-docs/current/benchmarks/rust/throughput.png differ
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/compiler-guide.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/compiler-guide.md
index 0046cbcd3..54e888663 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/compiler-guide.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/compiler-guide.md
@@ -63,7 +63,11 @@ foryc --scan-generated [OPTIONS]
| `--cpp_out=DST_DIR` | 将 C++ 代码输出到 `DST_DIR` | （无） |
| `--go_out=DST_DIR` | 将 Go 代码输出到 `DST_DIR` | （无） |
| `--rust_out=DST_DIR` | 将 Rust 代码输出到 `DST_DIR` | （无） |
+| `--javascript_out=DST_DIR` | 将 JavaScript 代码输出到 `DST_DIR` | （无） |
+| `--swift_out=DST_DIR` | 将 Swift 代码输出到 `DST_DIR` | （无） |
+| `--dart_out=DST_DIR` | 将 Dart 代码输出到 `DST_DIR` | （无） |
| `--go_nested_type_style` | Go 嵌套类型命名风格：`camelcase` 或 `underscore` | schema/默认值 |
+| `--swift_namespace_style` | Swift 命名空间风格：`enum` 或 `flatten` | `enum` |
| `--emit-fdl` | 对非 `.fdl` 输入打印转换后的 Fory IDL | `false` |
| `--emit-fdl-path` | 将转换后的 Fory IDL 写入文件或目录 | （stdout） |
@@ -108,7 +112,7 @@ foryc schema.fdl
**为指定语言编译：**
```bash
-foryc schema.fdl --lang java,python
+foryc schema.fdl --lang java,python,csharp,javascript,swift,dart
```
**指定输出目录：**
@@ -129,6 +133,12 @@ foryc schema.fdl --package com.myapp.models
foryc user.fdl order.fdl product.fdl --output ./generated
```
+**编译包含 service 定义的简单 schema（生成 Java + Python 模型）：**
+
+```bash
+foryc compiler/examples/service.fdl --java_out=./generated/java --python_out=./generated/python
+```
+
**使用 import 搜索路径：**
```bash
@@ -155,7 +165,7 @@ foryc src/main.fdl -I libs/common,libs/types --proto_path third_party/
foryc schema.fdl --java_out=./src/main/java
# 多语言分别输出到不同目录
-foryc schema.fdl --java_out=./java/gen --python_out=./python/src --go_out=./go/gen
+foryc schema.fdl --java_out=./java/gen --python_out=./python/src --go_out=./go/gen --csharp_out=./csharp/gen --javascript_out=./javascript/src --swift_out=./swift/gen --dart_out=./dart/gen
# 结合 import 路径
foryc schema.fdl --java_out=./gen/java -I proto/ -I common/
@@ -224,13 +234,16 @@ Compiling src/main.fdl...
## 支持语言
-| 语言 | 标记 | 输出后缀 | 说明 |
-| ------ | -------- | -------- | ---------------------- |
-| Java | `java` | `.java` | 带 Fory 注解的 POJO |
-| Python | `python` | `.py` | 带类型提示的 dataclass |
-| Go | `go` | `.go` | 带 struct tag 的结构体 |
-| Rust | `rust` | `.rs` | 带 derive 宏的结构体 |
-| C++ | `cpp` | `.h` | 带 FORY 宏的结构体 |
+| 语言 | 标记 | 输出后缀 | 说明 |
+| ---------- | ------------ | -------- | ------------------------- |
+| Java | `java` | `.java` | 带 Fory 注解的 POJO |
+| Python | `python` | `.py` | 带类型提示的 dataclass |
+| Go | `go` | `.go` | 带 struct tag 的结构体 |
+| Rust | `rust` | `.rs` | 带 derive 宏的结构体 |
+| C++ | `cpp` | `.h` | 带 FORY 宏的结构体 |
+| JavaScript | `javascript` | `.ts` | 带注册函数的接口 |
+| Swift | `swift` | `.swift` | `@ForyObject` Swift 模型 |
+| Dart | `dart` | `.dart` | 带注解的 `@ForyStruct` 类 |
## 输出结构
@@ -300,6 +313,35 @@ generated/
- 命名空间与 package 对齐（点号转换为 `::`）
- 自动包含 header guard 与前向声明
+### JavaScript
+
+```
+generated/
+└── javascript/
+ └── example.ts
+```
+
+- 每个 schema 生成一个 `.ts` 文件
+- message 生成为 `export interface`
+- enum 生成为 `export enum`
+- union 生成为带 case enum 的判别联合
+- 文件内包含注册辅助函数
+
+### Dart
+
+```
+generated/
+└── dart/
+ └── package/
+ ├── package.dart
+ └── package.fory.dart
+```
+
+- 每个 schema 生成两个文件：带注解类型的主 `.dart` 文件，以及带序列化器的 `.fory.dart` part 文件
+- package 各段映射为目录层级（例如 `demo.foo` -> `demo/foo/`）
+- 注册辅助类位于 part 文件中
+- 非可空、非 `ref` 的基础类型列表会使用类型化数组（例如 `Int32List`）
+
## 构建系统集成
### Maven (Java)
@@ -488,6 +530,30 @@ cc_library(
)
```
+### Dart / Flutter
+
+在 `pubspec.yaml` 中加入 Fory 依赖：
+
+```yaml
+dependencies:
+ fory: ^0.1.0
+
+dev_dependencies:
+ build_runner: ^2.4.0
+```
+
+用编译器生成 schema 类型：
+
+```bash
+foryc schema.fdl --dart_out=lib/generated
+```
+
+随后运行 `build_runner` 生成序列化器：
+
+```bash
+dart run build_runner build
+```
+
## 错误处理
### 语法错误
@@ -496,6 +562,18 @@ cc_library(
Error: Line 5, Column 12: Expected ';' after field declaration
```
+### 未知类型引用
+
+```
+Error: Unknown type 'Address' in Customer.address
+```
+
+修复方式：先定义被引用的类型，或检查拼写是否正确。
+
+service RPC 的请求和响应类型也按同样规则校验。例如
+`rpc SayHello (HelloRequest) returns (HelloReply);`
+中的类型必须已定义；否则校验器会在 RPC 所在行报出 `Unknown type '...'` 错误。
+
修复方式：检查对应行是否缺少分号或存在语法问题。
### 类型名重复
@@ -653,3 +731,10 @@ fory = "x.y.z"
```
**C++：** 确保编译器 include 路径可找到 Fory 头文件。
+
+**Dart：** 确保 `pubspec.yaml` 中包含 fory 依赖：
+
+```yaml
+dependencies:
+ fory: ^0.1.0
+```
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/generated-code.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/generated-code.md
index cadf241ab..a8fda3eda 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/generated-code.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/generated-code.md
@@ -685,6 +685,321 @@ if err := restored.FromBytes(data); err != nil {
}
```
+## C#
+
+### 输出布局
+
+C# 输出通常是每个 schema 对应一个 `.cs` 文件，例如：
+
+- `<csharp_out>/addressbook/addressbook.cs`
+
+### 类型生成
+
+message 会生成带 `[ForyObject]` 的类、C# 属性以及字节辅助方法：
+
+```csharp
+[ForyObject]
+public sealed partial class Person
+{
+ public string Name { get; set; } = string.Empty;
+ public int Id { get; set; }
+ public List<Person.PhoneNumber> Phones { get; set; } = new();
+ public Animal Pet { get; set; } = null!;
+
+ public byte[] ToBytes() { ... }
+ public static Person FromBytes(byte[] data) { ... }
+}
+```
+
+union 会生成带类型化 case 辅助方法的 `Union` 子类：
+
+```csharp
+public sealed class Animal : Union
+{
+ public static Animal Dog(Dog value) { ... }
+ public static Animal Cat(Cat value) { ... }
+ public bool IsDog => ...;
+ public Dog DogValue() { ... }
+}
+```
+
+### 注册
+
+每个 schema 都会生成一个注册辅助类：
+
+```csharp
+public static class AddressbookForyRegistration
+{
+ public static void Register(Fory fory)
+ {
+ fory.Register<addressbook.Animal>((uint)106);
+ fory.Register<addressbook.Person>((uint)100);
+ // ...
+ }
+}
+```
+
+若未显式提供类型 ID，生成的注册代码会像其他目标语言一样使用计算得到的数值 ID。
+
+## JavaScript
+
+### 输出布局
+
+JavaScript 输出通常是每个 schema 对应一个 `.ts` 文件，例如：
+
+- `<javascript_out>/addressbook.ts`
+
+### 类型生成
+
+message 会生成使用 camelCase 字段名的 `export interface` 声明：
+
+```typescript
+export interface Person {
+ name: string;
+ id: number;
+ phones: PhoneNumber[];
+ pet?: Animal | null;
+}
+```
+
+enum 会生成 `export enum` 声明：
+
+```typescript
+export enum PhoneType {
+ MOBILE = 0,
+ HOME = 1,
+ WORK = 2,
+}
+```
+
+union 会生成带 case enum 的判别联合类型：
+
+```typescript
+export enum AnimalCase {
+ DOG = 1,
+ CAT = 2,
+}
+
+export type Animal =
+ | { case: AnimalCase.DOG; value: Dog }
+ | { case: AnimalCase.CAT; value: Cat };
+```
+
+## Swift
+
+### 输出布局
+
+Swift 输出通常是每个 schema 对应一个 `.swift` 文件，例如：
+
+- `<swift_out>/addressbook/addressbook.swift`
+
+### 类型生成
+
+生成器会创建带 `@ForyObject` 和字段 ID 的 Swift 模型。
+
+当 package/namespace 非空时，命名空间形态由 `swift_namespace_style` 控制：
+
+- `enum`（默认）：生成嵌套 enum 命名空间包装
+- `flatten`：在顶层类型名上加上由 package 派生的前缀（例如 `Demo_Foo_User`）
+
+当 package/namespace 为空时，不会生成 enum 包装或 flatten 前缀。
+
+对于非空 package 且使用默认 `enum` 风格时：
+
+```swift
+public enum Addressbook {
+ @ForyObject
+ public enum Animal: Equatable {
+ @ForyField(id: 1)
+ case dog(Addressbook.Dog)
+ @ForyField(id: 2)
+ case cat(Addressbook.Cat)
+ }
+
+ @ForyObject
+ public struct Person: Equatable {
+ @ForyField(id: 1)
+ public var name: String = ""
+ @ForyField(id: 8)
+ public var pet: Addressbook.Animal = .foryDefault()
+ }
+}
+```
+
+对于非空 package 且使用 `flatten` 风格时：
+
+```swift
+@ForyObject
+public struct Addressbook_Person: Equatable { ... }
+```
+
+当命令行和 schema 选项同时设置时，CLI 参数 `--swift_namespace_style` 会覆盖 schema 中的 `swift_namespace_style`。
+
+union 会生成带关联值的标记 Swift enum。
+带 `ref`/`weak_ref` 字段的 message 会生成 `final class` 模型，以保留引用语义。
+
+### 注册
+
+每个 schema 都会生成带传递性 import 注册的辅助类：
+
+```swift
+public enum ForyRegistration {
+ public static func register(_ fory: Fory) throws {
+ try ComplexPb.ForyRegistration.register(fory)
+ fory.register(Addressbook.Person.self, id: 100)
+ fory.register(Addressbook.Animal.self, id: 106)
+ }
+}
+```
+
+对于非空 package 且使用 `flatten` 风格时，辅助类名称也会带前缀（例如 `Addressbook_ForyRegistration`）。
+
+若未显式提供 `[id=...]`，注册会使用计算得到的数值 ID。
+若设置 `option enable_auto_type_id = false;`，则生成代码会改用基于名称的注册 API。
+
+## Dart
+
+### 输出布局
+
+Dart 输出通常是每个 schema 对应两个文件：一个带注解类型的主 `.dart` 文件，以及一个包含生成序列化器和注册辅助逻辑的 `.fory.dart` part 文件。
+
+- `<dart_out>/package/package.dart`
+- `<dart_out>/package/package.fory.dart`
+
+### 类型生成
+
+message 会生成带 `@ForyStruct` 注解的 `final class`，并在每个字段上加 `@ForyField`：
+
+```dart
+@ForyStruct()
+final class Person {
+ Person();
+
+ @ForyField(id: 1)
+ String name = '';
+
+ @ForyField(id: 2)
+ Int32 id = Int32(0);
+
+ @ForyField(id: 7)
+ List<Person_PhoneNumber> phones = <Person_PhoneNumber>[];
+
+ @ForyField(id: 8)
+ Animal pet = Animal._empty();
+}
+```
+
+enum 会生成带 `rawValue` getter 和 `fromRawValue` factory 的 Dart `enum`：
+
+```dart
+enum Person_PhoneType {
+ mobile,
+ home,
+ work;
+
+ int get rawValue => switch (this) {
+ Person_PhoneType.mobile => 0,
+ Person_PhoneType.home => 1,
+ Person_PhoneType.work => 2,
+ };
+
+ static Person_PhoneType fromRawValue(int value) => switch (value) {
+ 0 => Person_PhoneType.mobile,
+ 1 => Person_PhoneType.home,
+ 2 => Person_PhoneType.work,
+ _ => throw StateError('Unknown Person_PhoneType raw value $value.'),
+ };
+}
+```
+
+union 会生成带 `@ForyUnion` 注解的类，包含工厂构造器、case enum 以及自定义序列化器：
+
+```dart
+enum AnimalCase {
+ dog,
+ cat;
+
+ int get id => switch (this) {
+ AnimalCase.dog => 1,
+ AnimalCase.cat => 2,
+ };
+}
+
+@ForyUnion()
+final class Animal {
+ final AnimalCase _case;
+ final Object? _value;
+
+ const Animal._(this._case, this._value);
+
+ factory Animal.dog(Dog value) => Animal._(AnimalCase.dog, value);
+ factory Animal.cat(Cat value) => Animal._(AnimalCase.cat, value);
+
+ bool get isDog => _case == AnimalCase.dog;
+ Dog get dogValue => _value as Dog;
+ // ...
+}
+```
+
+嵌套类型使用扁平下划线命名（例如 `Person_PhoneNumber`、`Person_PhoneType`）。
+
+非 optional、非 ref 的原始类型列表会使用 typed array 以获得零拷贝性能（例如 `list<int32>` -> `Int32List`）。
+
+列表元素或 map value 上的引用跟踪通过 `@ListType` / `@MapType` 注解表达：
+
+```dart
+@ListType(element: ValueType.ref())
+@ForyField(id: 3)
+List<Node> children = <Node>[];
+
+@MapType(value: ValueType.ref())
+@ForyField(id: 2)
+Map<String, Node> byName = <String, Node>{};
+```
+
+### 注册
+
+每个 schema 都会生成一个注册辅助类，负责处理该文件中的所有类型，并传递性注册 import 进来的类型：
+
+```dart
+abstract final class ForyRegistration {
+ static void register(
+ Fory fory,
+ Type type, {
+ int? id,
+ String? namespace,
+ String? typeName,
+ }) {
+ if (type == Person) {
+ registerGeneratedStruct(fory, _personForyRegistration, id: id, namespace: namespace, typeName: typeName);
+ return;
+ }
+ // ... other types
+ }
+}
+```
+
+### 使用示例
+
+```dart
+import 'package:fory/fory.dart';
+import 'generated/addressbook/addressbook.dart';
+
+void main() {
+ final fory = Fory();
+ ForyRegistration.register(fory, Person, id: 100);
+ ForyRegistration.register(fory, Dog, id: 104);
+ // ...
+
+ final person = Person()
+ ..name = 'Alice'
+ ..id = Int32(1);
+
+ final bytes = fory.serialize(person);
+ final roundTrip = fory.deserialize<Person>(bytes);
+}
+```
+
## 跨语言说明
### 类型 ID 行为
@@ -695,20 +1010,28 @@ if err := restored.FromBytes(data); err != nil {
### 嵌套类型形态
-| 语言 | 嵌套类型形式 |
-| ------ | ---------------------------- |
-| Java | `Person.PhoneNumber` |
-| Python | `Person.PhoneNumber` |
-| Rust | `person::PhoneNumber` |
-| C++ | `Person::PhoneNumber` |
-| Go | `Person_PhoneNumber`（默认） |
+| 语言 | 嵌套类型形式 |
+| ---------- | ---------------------------- |
+| Java | `Person.PhoneNumber` |
+| Python | `Person.PhoneNumber` |
+| Rust | `person::PhoneNumber` |
+| C++ | `Person::PhoneNumber` |
+| Go | `Person_PhoneNumber`（默认） |
+| C# | `Person.PhoneNumber` |
+| JavaScript | `Person.PhoneNumber` |
+| Swift | `Person.PhoneNumber` |
+| Dart | `Person_PhoneNumber` |
### 字节辅助方法命名
-| 语言 | 辅助方法名称 |
-| ------ | ------------------------- |
-| Java | `toBytes` / `fromBytes` |
-| Python | `to_bytes` / `from_bytes` |
-| Rust | `to_bytes` / `from_bytes` |
-| C++ | `to_bytes` / `from_bytes` |
-| Go | `ToBytes` / `FromBytes` |
+| 语言 | 辅助方法名称 |
+| ---------- | ------------------------- |
+| Java | `toBytes` / `fromBytes` |
+| Python | `to_bytes` / `from_bytes` |
+| Rust | `to_bytes` / `from_bytes` |
+| C++ | `to_bytes` / `from_bytes` |
+| Go | `ToBytes` / `FromBytes` |
+| C# | `ToBytes` / `FromBytes` |
+| JavaScript | （通过 `fory.serialize()`） |
+| Swift | `toBytes` / `fromBytes` |
+| Dart | （通过 `fory.serialize()`） |
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/index.md
index 8e26cdd38..73caa1018 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/index.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/index.md
@@ -20,7 +20,7 @@ license: |
---
Fory IDL 是 Apache Fory 的 Schema 定义语言，可实现类型安全的跨语言序列化。
-你只需定义一次数据结构，即可为 Java、Python、Go、Rust 和 C++ 生成原生数据结构代码。
+你只需定义一次数据结构，即可为 Java、Python、Go、Rust、C++、C#、Swift、JavaScript 和 Dart 生成原生数据结构代码。
## 示例 Schema
@@ -99,6 +99,10 @@ union Animal [id=106] {
- Go：带 struct tag 的结构体
- Rust：带 `#[derive(ForyObject)]` 的结构体
- C++：带 `FORY_STRUCT` 宏的结构体
+- C#：带 `[ForyObject]` 的类及注册辅助函数
+- JavaScript：带注册函数的接口
+- Swift：带 `@ForyObject` 模型、`@ForyField` 元数据和注册辅助函数
+- Dart：带 `@ForyStruct` 类、`@ForyField` 注解和注册辅助函数
## 快速开始
@@ -136,7 +140,7 @@ message Person {
foryc example.fdl --output ./generated
# 为指定语言生成
-foryc example.fdl --lang java,python --output ./generated
+foryc example.fdl --lang java,python,csharp,javascript,swift,dart --output ./generated
```
### 4. 使用生成代码
@@ -191,11 +195,11 @@ message Example {
Fory IDL 类型会映射为各语言原生类型：
-| Fory IDL 类型 | Java | Python | Go | Rust | C++ |
-| ------------- | --------- | -------------- | -------- | -------- | ------------- |
-| `int32` | `int` | `pyfory.int32` | `int32` | `i32` | `int32_t` |
-| `string` | `String` | `str` | `string` | `String` | `std::string` |
-| `bool` | `boolean` | `bool` | `bool` | `bool` | `bool` |
+| Fory IDL 类型 | Java | Python | Go | Rust | C++ | C# | JavaScript | Swift | Dart |
+| ------------- | --------- | -------------- | -------- | -------- | ------------- | -------- | ---------- | -------- | -------- |
+| `int32` | `int` | `pyfory.int32` | `int32` | `i32` | `int32_t` | `int` | `number` | `Int32` | `Int32` |
+| `string` | `String` | `str` | `string` | `String` | `std::string` | `string` | `string` | `String` | `String` |
+| `bool` | `boolean` | `bool` | `bool` | `bool` | `bool` | `bool` | `boolean` | `Bool` | `bool` |
完整映射请参见 [类型系统](schema-idl.md#type-system)。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/schema-idl.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/schema-idl.md
index be6d5c6b2..8f56cbecd 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/schema-idl.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/schema-idl.md
@@ -91,13 +91,16 @@ package com.example.models alias models_v1;
语言映射：
-| 语言 | package 用法 |
-| ------ | ----------------------- |
-| Java | Java package |
-| Python | 模块名（`.` 转 `_`） |
-| Go | 包名（通常取最后一段） |
-| Rust | 模块名（`.` 转 `_`） |
-| C++ | 命名空间（`.` 转 `::`） |
+| 语言 | package 用法 |
+| ---------- | ------------------------- |
+| Java | Java package |
+| Python | 模块名（`.` 转 `_`） |
+| Go | 包名（通常取最后一段） |
+| Rust | 模块名（`.` 转 `_`） |
+| C++ | 命名空间（`.` 转 `::`） |
+| C# | 命名空间 |
+| JavaScript | 模块名（取最后一段） |
+| Dart | 库名（保留 package 各段） |
## 文件级选项
@@ -306,16 +309,30 @@ enum Status {
### 语言映射
-- Java：`enum`
-- Python：`IntEnum`
-- Go：`type + const`
-- Rust：`repr(i32)` 枚举
-- C++：`enum class`
+| 语言 | 实现形式 |
+| ---------- | -------------------------------------- |
+| Java | `enum Status { UNKNOWN, ACTIVE, ... }` |
+| Python | `class Status(IntEnum): UNKNOWN = 0` |
+| Go | `type Status int32` 配合常量 |
+| Rust | `#[repr(i32)] enum Status { Unknown }` |
+| C++ | `enum class Status : int32_t { ... }` |
+| JavaScript | `export enum Status { UNKNOWN, ... }` |
+| Dart | `enum Status { unknown, active, ... }` |
### 枚举前缀处理
针对 protobuf 风格 `TYPE_NAME_VALUE`，生成器通常会按语言习惯去除冗余前缀，使 API 更自然。
+| 语言 | 输出示例 | 风格 |
+| ---------- | ----------------------------------------- | ---------------- |
+| Java | `UNKNOWN, TIER1, TIER2` | 作用域枚举 |
+| Rust | `Unknown, Tier1, Tier2` | 作用域枚举 |
+| C++ | `UNKNOWN, TIER1, TIER2` | 作用域枚举 |
+| Python | `UNKNOWN, TIER1, TIER2` | 作用域 `IntEnum` |
+| Go | `DeviceTierUnknown, DeviceTierTier1, ...` | 非作用域常量 |
+| JavaScript | `UNKNOWN, TIER1, TIER2` | 作用域枚举 |
+| Dart | `unknown, tier1, tier2` | 作用域枚举 |
+
## Message 定义
### 基本语法
@@ -342,11 +359,15 @@ message User [id=100] {
### 语言映射
-- Java：类 / record（按选项）
-- Python：dataclass
-- Go：struct
-- Rust：struct
-- C++：class/struct + 宏元信息
+| 语言 | 实现形式 |
+| ---------- | --------------------------------- |
+| Java | 带 getter/setter 的 POJO |
+| Python | `@dataclass` 类 |
+| Go | 导出字段的 struct |
+| Rust | `#[derive(ForyObject)]` 的 struct |
+| C++ | 带 `FORY_STRUCT` 宏的 struct |
+| JavaScript | `export interface` 声明 |
+| Dart | `@ForyStruct` `final class` |
### 预留字段
@@ -397,13 +418,15 @@ message Person {
### 各语言生成形态
-| 语言 | 嵌套类型形态 |
-| ------ | --------------------- |
-| Java | `Outer.Inner` |
-| Python | `Outer.Inner` |
-| Rust | `outer::Inner` |
-| C++ | `Outer::Inner` |
-| Go | `Outer_Inner`（默认） |
+| 语言 | 嵌套类型形态 |
+| ---------- | ----------------------------------------------- |
+| Java | `Outer.Inner` |
+| Python | `Outer.Inner` |
+| Rust | `outer::Inner` |
+| C++ | `Outer::Inner` |
+| Go | `Outer_Inner`（默认，可配置为 camelcase） |
+| JavaScript | 扁平名称（如 `Result`） |
+| Dart | 带下划线的扁平类名（如 `SearchResponse_Result`） |
### 嵌套规则
@@ -466,6 +489,18 @@ message User {
建议在跨语言场景显式使用，以避免默认值差异。
+**生成代码：**
+
+| 语言 | 非 optional | optional |
+| ---------- | ------------------- | ----------------------------------------------- |
+| Java | `String name` | `String email` 配合 `@ForyField(nullable=true)` |
+| Python | `name: str` | `name: Optional[str]` |
+| Go | `Name string` | `Name *string` |
+| Rust | `name: String` | `name: Option<String>` |
+| C++ | `std::string name` | `std::optional<std::string> name` |
+| JavaScript | `name: string` | `name?: string \| null` |
+| Dart | `String name` | `String? email` |
+
#### `ref`
开启引用跟踪，用于共享对象与循环结构：
@@ -480,6 +515,18 @@ message Node {
当运行时全局 ref tracking 开启时，字段级 `ref` 才会生效。
+**生成代码：**
+
+| 语言 | 不使用 `ref` | 使用 `ref` |
+| ---------- | ---------------- | ------------------------------------------ |
+| Java | `Node parent` | `Node parent` 配合 `@ForyField(ref=true)` |
+| Python | `parent: Node` | `parent: Node = pyfory.field(ref=True)` |
+| Go | `Parent Node` | `Parent *Node` 配合 `fory:"ref"` |
+| Rust | `parent: Node` | `parent: Arc<Node>` |
+| C++ | `Node parent` | `std::shared_ptr<Node> parent` |
+| JavaScript | `parent: Node` | `parent: Node`（无额外 `ref` 区分） |
+| Dart | `Node parent` | `Node parent` 配合 `@ForyField(ref: true)` |
+
#### `list`
列表字段（`repeated` 为等价别名）：
@@ -490,6 +537,18 @@ message Group {
}
```
+**生成代码：**
+
+| 语言 | 类型 |
+| ---------- | -------------------------- |
+| Java | `List<String>` |
+| Python | `List[str]` |
+| Go | `[]string` |
+| Rust | `Vec<String>` |
+| C++ | `std::vector<std::string>` |
+| JavaScript | `string[]` |
+| Dart | `List<String>` |
+
### 组合修饰符
可组合使用：
@@ -530,10 +589,38 @@ Fory IDL 类型系统包括基础类型、命名类型和集合类型。
`bool` 表示布尔值。
+| 语言 | 类型 | 说明 |
+| ---------- | --------- | ---- |
+| Java | `boolean` | |
+| Python | `bool` | |
+| Go | `bool` | |
+| Rust | `bool` | |
+| C++ | `bool` | |
+| JavaScript | `boolean` | |
+| Dart | `bool` | |
+
#### Integer Types
支持有符号/无符号与不同位宽。跨语言场景建议明确编码策略并保持字段语义稳定。
+**有符号整数映射：**
+
+| Fory IDL | Java | Python | Go | Rust | C++ | JavaScript | Dart |
+| -------- | ------- | -------------- | ------- | ----- | --------- | ------------------ | ------- |
+| `int8` | `byte` | `pyfory.int8` | `int8` | `i8` | `int8_t` | `number` | `Int8` |
+| `int16` | `short` | `pyfory.int16` | `int16` | `i16` | `int16_t` | `number` | `Int16` |
+| `int32` | `int` | `pyfory.int32` | `int32` | `i32` | `int32_t` | `number` | `Int32` |
+| `int64` | `long` | `pyfory.int64` | `int64` | `i64` | `int64_t` | `bigint \| number` | `int` |
+
+**无符号整数映射：**
+
+| Fory IDL | Java | Python | Go | Rust | C++ | JavaScript | Dart |
+| -------- | ------- | --------------- | -------- | ----- | ---------- | ------------------ | -------- |
+| `uint8` | `short` | `pyfory.uint8` | `uint8` | `u8` | `uint8_t` | `number` | `UInt8` |
+| `uint16` | `int` | `pyfory.uint16` | `uint16` | `u16` | `uint16_t` | `number` | `UInt16` |
+| `uint32` | `long` | `pyfory.uint32` | `uint32` | `u32` | `uint32_t` | `number` | `UInt32` |
+| `uint64` | `long` | `pyfory.uint64` | `uint64` | `u64` | `uint64_t` | `bigint \| number` | `int` |
+
#### Integer Encoding Variants
常见编码：
@@ -547,28 +634,83 @@ Fory IDL 类型系统包括基础类型、命名类型和集合类型。
- `float32`
- `float64`
+| Fory IDL | Java | Python | Go | Rust | C++ | JavaScript | Dart |
+| --------- | -------- | ---------------- | --------- | ----- | -------- | ---------- | --------- |
+| `float32` | `float` | `pyfory.float32` | `float32` | `f32` | `float` | `number` | `Float32` |
+| `float64` | `double` | `pyfory.float64` | `float64` | `f64` | `double` | `number` | `double` |
+
#### String Type
`string` 使用 UTF-8 文本语义。
+| 语言 | 类型 | 说明 |
+| ---------- | ------------- | -------------------- |
+| Java | `String` | 不可变 |
+| Python | `str` | |
+| Go | `string` | 不可变 |
+| Rust | `String` | 所有权字符串，堆分配 |
+| C++ | `std::string` | |
+| JavaScript | `string` | |
+| Dart | `String` | |
+
#### Bytes Type
`bytes` 用于原始二进制载荷。
+| 语言 | 类型 | 说明 |
+| ---------- | ---------------------- | ------ |
+| Java | `byte[]` | |
+| Python | `bytes` | 不可变 |
+| Go | `[]byte` | |
+| Rust | `Vec<u8>` | |
+| C++ | `std::vector<uint8_t>` | |
+| JavaScript | `Uint8Array` | |
+| Dart | `Uint8List` | |
+
#### Temporal Types
##### Date
`date` 表示日期（不含时区时间部分）。
+| 语言 | 类型 | 说明 |
+| ---------- | --------------------------- | ----------------------- |
+| Java | `java.time.LocalDate` | |
+| Python | `datetime.date` | |
+| Go | `time.Time` | 会忽略时间部分 |
+| Rust | `chrono::NaiveDate` | 需依赖 `chrono` crate |
+| C++ | `fory::serialization::Date` | |
+| JavaScript | `Date` | |
+| Dart | `LocalDate` | Fory package 提供的类型 |
+
##### Timestamp
`timestamp` 表示时间点（跨语言应统一时间语义与精度预期）。
+| 语言 | 类型 | 说明 |
+| ---------- | -------------------------------- | ----------------------- |
+| Java | `java.time.Instant` | 基于 UTC |
+| Python | `datetime.datetime` | |
+| Go | `time.Time` | |
+| Rust | `chrono::NaiveDateTime` | 需依赖 `chrono` crate |
+| C++ | `fory::serialization::Timestamp` | |
+| JavaScript | `Date` | |
+| Dart | `Timestamp` | Fory package 提供的类型 |
+
#### Any
`any` 允许存储动态类型值。使用 `any` 时建议配合清晰的业务约束，避免滥用导致模型不稳定。
+| 语言 | 类型 | 说明 |
+| ---------- | -------------- | -------------- |
+| Java | `Object` | 写入运行时类型 |
+| Python | `Any` | 写入运行时类型 |
+| Go | `any` | 写入运行时类型 |
+| Rust | `Box<dyn Any>` | 写入运行时类型 |
+| C++ | `std::any` | 写入运行时类型 |
+| JavaScript | `any` | 写入运行时类型 |
+| Dart | `Object?` | 写入运行时类型 |
+
### Named Types
命名类型包括：
@@ -600,6 +742,11 @@ map<K, V>
- `K` 一般应为可稳定比较的标量类型
- `V` 可为任意支持类型
+| Fory IDL | Java | Python | Go | Rust | C++ | JavaScript | Dart |
+| -------------------- | ---------------------- | ----------------- | ------------------ | ----------------------- | -------------------------------- | --------------------- | -------------------- |
+| `map<string, int32>` | `Map<String, Integer>` | `Dict[str, int]` | `map[string]int32` | `HashMap<String, i32>` | `std::map<std::string, int32_t>` | `Map<string, number>` | `Map<String, Int32>` |
+| `map<string, User>` | `Map<String, User>` | `Dict[str, User]` | `map[string]User` | `HashMap<String, User>` | `std::map<std::string, User>` | `Map<string, User>` | `Map<String, User>` |
+
### Type Compatibility Matrix
跨语言建议：
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/cpp/_category_.json b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/cpp/_category_.json
index c543ab138..9660bafa8 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/cpp/_category_.json
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/cpp/_category_.json
@@ -1,6 +1,6 @@
{
"label": "C++",
- "position": 3,
+ "position": 4,
"collapsible": true,
"collapsed": true
}
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/scala/_category_.json b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/_category_.json
similarity index 76%
copy from i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/scala/_category_.json
copy to i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/_category_.json
index 6cc51ddde..c5e03ee3c 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/scala/_category_.json
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/_category_.json
@@ -1,5 +1,5 @@
{
- "label": "Scala",
+ "label": "C#",
"position": 7,
"collapsible": true,
"collapsed": true
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/basic-serialization.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/basic-serialization.md
new file mode 100644
index 000000000..ce8cd2e59
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/basic-serialization.md
@@ -0,0 +1,131 @@
+---
+title: 基础序列化
+sidebar_position: 1
+id: basic_serialization
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍 Apache Fory™ C# 的强类型序列化 API。
+
+## 对象图序列化
+
+在类或结构体上使用 `[ForyObject]`，并在使用前完成注册。
+
+```csharp
+using Apache.Fory;
+
+[ForyObject]
+public sealed class Address
+{
+ public string Street { get; set; } = string.Empty;
+ public int Zip { get; set; }
+}
+
+[ForyObject]
+public sealed class Person
+{
+ public long Id { get; set; }
+ public string Name { get; set; } = string.Empty;
+ public string? Nickname { get; set; }
+ public List<int> Scores { get; set; } = [];
+ public List<Address> Addresses { get; set; } = [];
+}
+
+Fory fory = Fory.Builder().Build();
+fory.Register<Address>(100);
+fory.Register<Person>(101);
+
+Person person = new()
+{
+ Id = 42,
+ Name = "Alice",
+ Nickname = null,
+ Scores = [10, 20, 30],
+ Addresses = [new Address { Street = "Main", Zip = 94107 }],
+};
+
+byte[] payload = fory.Serialize(person);
+Person decoded = fory.Deserialize<Person>(payload);
+```
+
+## 强类型 API
+
+### 使用字节数组进行 Serialize / Deserialize
+
+```csharp
+byte[] payload = fory.Serialize(value);
+MyType decoded = fory.Deserialize<MyType>(payload);
+```
+
+### 从 `ReadOnlySpan<byte>` 反序列化
+
+```csharp
+ReadOnlySpan<byte> span = payload;
+MyType decoded = fory.Deserialize<MyType>(span);
+```
+
+### 以流式方式消费帧
+
+```csharp
+using System.Buffers;
+
+ReadOnlySequence<byte> sequence = GetFramedSequence();
+MyType first = fory.Deserialize<MyType>(ref sequence);
+MyType second = fory.Deserialize<MyType>(ref sequence);
+```
+
+## 通过泛型对象 API 处理动态载荷
+
+当编译期类型未知或载荷包含异构对象时，可以配合 `object?` 使用泛型 API。
+
+```csharp
+Dictionary<object, object?> value = new()
+{
+ ["k1"] = 7,
+ [2] = "v2",
+ [true] = null,
+};
+
+byte[] payload = fory.Serialize<object?>(value);
+object? decoded = fory.Deserialize<object?>(payload);
+```
+
+## Buffer Writer API
+
+直接序列化到 `IBufferWriter<byte>` 目标。
+
+```csharp
+using System.Buffers;
+
+ArrayBufferWriter<byte> writer = new();
+fory.Serialize(writer, value);
+
+ArrayBufferWriter<byte> dynamicWriter = new();
+fory.Serialize<object?>(dynamicWriter, value);
+```
+
+## 说明
+
+- 复用同一个 `Fory` 或 `ThreadSafeFory` 实例可以获得更好的性能。
+- 基础类型和集合类型不需要用户手动注册。
+- 用户自定义的 `[ForyObject]` 类型和自定义序列化器类型应显式注册。
+
+## 相关主题
+
+- [类型注册](type-registration.md)
+- [支持的类型](supported-types.md)
+- [引用](references.md)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/configuration.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/configuration.md
new file mode 100644
index 000000000..9af3ce18e
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/configuration.md
@@ -0,0 +1,124 @@
+---
+title: 配置
+sidebar_position: 2
+id: configuration
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍 Apache Fory™ C# 的 `ForyBuilder` 选项和默认配置值。
+`Config` 是由 `ForyBuilder` 创建的不可变运行时快照。
+
+## 构建运行时
+
+```csharp
+using Apache.Fory;
+
+Fory fory = Fory.Builder().Build();
+ThreadSafeFory threadSafe = Fory.Builder().BuildThreadSafe();
+```
+
+## 默认配置
+
+`Fory.Builder().Build()` 使用以下默认值：
+
+| 选项 | 默认值 | 说明 |
+| -------------------- | -------- | ---------------------------------- |
+| `TrackRef` | `false` | 默认关闭引用跟踪 |
+| `Compatible` | `false` | Schema 一致模式，不写入演进元数据 |
+| `CheckStructVersion` | `false` | 默认关闭结构体 schema hash 校验 |
+| `MaxDepth` | `20` | 动态对象图的最大嵌套深度 |
+
+## 构建器选项
+
+C# 始终使用与 xlang 兼容的帧头，因此 `ForyBuilder` 不提供单独的 `Xlang(...)` 开关。
+
+### `TrackRef(bool enabled = false)`
+
+为共享对象图和循环对象图启用引用跟踪。
+
+```csharp
+Fory fory = Fory.Builder()
+ .TrackRef(true)
+ .Build();
+```
+
+### `Compatible(bool enabled = false)`
+
+启用 Schema 演进模式。
+
+```csharp
+Fory fory = Fory.Builder()
+ .Compatible(true)
+ .Build();
+```
+
+### `CheckStructVersion(bool enabled = false)`
+
+为生成的结构体序列化器启用严格的 schema hash 校验。
+
+```csharp
+Fory fory = Fory.Builder()
+ .CheckStructVersion(true)
+ .Build();
+```
+
+### `MaxDepth(int value)`
+
+设置动态对象图允许的最大嵌套深度。
+
+```csharp
+Fory fory = Fory.Builder()
+ .MaxDepth(32)
+ .Build();
+```
+
+`value` 必须大于 `0`。
+
+## 常见配置
+
+### 追求速度的 Schema 一致服务
+
+```csharp
+Fory fory = Fory.Builder()
+ .TrackRef(false)
+ .Compatible(false)
+ .Build();
+```
+
+### 兼容的跨语言服务
+
+```csharp
+Fory fory = Fory.Builder()
+ .Compatible(true)
+ .TrackRef(true)
+ .Build();
+```
+
+### 线程安全的服务实例
+
+```csharp
+ThreadSafeFory fory = Fory.Builder()
+ .Compatible(true)
+ .TrackRef(true)
+ .BuildThreadSafe();
+```
+
+## 相关主题
+
+- [基础序列化](basic_serialization)
+- [Schema 演进](schema_evolution)
+- [线程安全](thread_safety)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/cross-language.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/cross-language.md
new file mode 100644
index 000000000..1993b7112
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/cross-language.md
@@ -0,0 +1,105 @@
+---
+title: 跨语言序列化
+sidebar_position: 8
+id: cross_language
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Apache Fory™ C# 支持与其他 Fory 运行时进行跨语言序列化。
+
+## 跨语言运行时
+
+C# 始终会读写 xlang 帧头。它没有单独的 `Xlang(...)` 构建器选项，因此互操作代码只需要配置兼容模式、引用跟踪等其余运行时行为。
+
+```csharp
+Fory fory = Fory.Builder()
+ .Compatible(true)
+ .Build();
+```
+
+## 使用稳定 ID 注册
+
+```csharp
+[ForyObject]
+public sealed class Person
+{
+ public string Name { get; set; } = string.Empty;
+ public int Age { get; set; }
+}
+
+Fory fory = Fory.Builder()
+ .Compatible(true)
+ .Build();
+
+fory.Register<Person>(100);
+```
+
+请在所有语言中保持相同的 ID 映射。
+
+## 按命名空间和类型名注册
+
+```csharp
+fory.Register<Person>("com.example", "Person");
+```
+
+## 跨语言示例
+
+### C#（序列化端）
+
+```csharp
+Person person = new() { Name = "Alice", Age = 30 };
+byte[] payload = fory.Serialize(person);
+```
+
+### Java（反序列化端）
+
+```java
+Fory fory = Fory.builder()
+ .withLanguage(Language.XLANG)
+ .withRefTracking(true)
+ .build();
+
+fory.register(Person.class, 100);
+Person value = (Person) fory.deserialize(payloadFromCSharp);
+```
+
+### Python（反序列化端）
+
+```python
+import pyfory
+
+fory = pyfory.Fory(xlang=True, ref=True)
+fory.register_type(Person, type_id=100)
+value = fory.deserialize(payload_from_csharp)
+```
+
+## 类型映射参考
+
+完整映射请参见 [xlang 指南](../xlang/)。
+
+## 最佳实践
+
+1. 保持 type ID 稳定并做好文档记录。
+2. 在滚动升级时启用 `Compatible(true)`。
+3. 在读写两端都注册所有用户类型。
+4. 用真实载荷做端到端回环验证。
+
+## 相关主题
+
+- [类型注册](type_registration)
+- [Schema 演进](schema_evolution)
+- [支持的类型](supported_types)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/custom-serializers.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/custom-serializers.md
new file mode 100644
index 000000000..888b84d38
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/custom-serializers.md
@@ -0,0 +1,84 @@
+---
+title: 自定义序列化器
+sidebar_position: 4
+id: custom_serializers
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+当某个类型不是通过 `[ForyObject]` 生成，或者需要专门的编码方式时，可以使用自定义序列化器。
+
+## 实现 `Serializer<T>`
+
+```csharp
+using Apache.Fory;
+
+public sealed class Point
+{
+ public int X { get; set; }
+ public int Y { get; set; }
+}
+
+public sealed class PointSerializer : Serializer<Point>
+{
+ public override Point DefaultValue => new();
+
+ public override void WriteData(WriteContext context, in Point value, bool hasGenerics)
+ {
+ context.Writer.WriteVarInt32(value.X);
+ context.Writer.WriteVarInt32(value.Y);
+ }
+
+ public override Point ReadData(ReadContext context)
+ {
+ return new Point
+ {
+ X = context.Reader.ReadVarInt32(),
+ Y = context.Reader.ReadVarInt32(),
+ };
+ }
+}
+```
+
+## 注册序列化器
+
+```csharp
+Fory fory = Fory.Builder().Build();
+fory.Register<Point, PointSerializer>(200);
+
+Point value = new() { X = 10, Y = 20 };
+byte[] payload = fory.Serialize(value);
+Point decoded = fory.Deserialize<Point>(payload);
+```
+
+## 序列化器行为说明
+
+- `WriteData` / `ReadData` 只负责处理载荷内容。
+- 除非显式重写，否则引用标志和类型信息由基类 `Serializer<T>.Write` / `Read` 处理。
+- `DefaultValue` 用于空值或默认值回退路径。
+
+## 最佳实践
+
+1. 保持序列化器逻辑确定且读写对称。
+2. 对整数密集型载荷要有意识地选择 varint、fixed 或 tagged 编码。
+3. 在所有读写端都注册自定义序列化器。
+4. 对常规领域模型优先使用 `[ForyObject]` 生成的序列化器。
+
+## 相关主题
+
+- [类型注册](type-registration.md)
+- [字段配置](field-configuration.md)
+- [故障排查](troubleshooting.md)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/field-configuration.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/field-configuration.md
new file mode 100644
index 000000000..0b31b65b1
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/field-configuration.md
@@ -0,0 +1,75 @@
+---
+title: 字段配置
+sidebar_position: 5
+id: field_configuration
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍 C# 生成序列化器的字段级配置。
+
+## `[ForyObject]` 与 `[Field]`
+
+使用 `[ForyObject]` 启用 source generator 生成序列化器。使用 `[Field]` 可以为某个字段覆盖整数编码方式。
+
+```csharp
+using Apache.Fory;
+
+[ForyObject]
+public sealed class Metrics
+{
+ // 定长 32 位编码
+ [Field(Encoding = FieldEncoding.Fixed)]
+ public uint Count { get; set; }
+
+ // Tagged 64 位编码
+ [Field(Encoding = FieldEncoding.Tagged)]
+ public ulong TraceId { get; set; }
+
+ // 默认（varint）编码
+ public long LatencyMicros { get; set; }
+}
+```
+
+## 可用编码
+
+| 编码 | 含义 |
+| ---- | ---- |
+| `FieldEncoding.Varint` | 变长整数编码，默认值 |
+| `FieldEncoding.Fixed` | 定长整数编码 |
+| `FieldEncoding.Tagged` | Tagged 整数编码，仅支持 `long` / `ulong` |
+
+## 支持覆盖编码的字段类型
+
+`[Field(Encoding = ...)]` 当前可应用于：
+
+- `int`
+- `uint`
+- `long`
+- `ulong`
+
+可空值类型变体，例如 `long?`，也会由生成的序列化器处理。
+
+## 可空性与引用跟踪
+
+- 字段可空性来自 C# 类型的可空声明，例如 `string?`、可空值类型等。
+- 引用跟踪由运行时的 `ForyBuilder.TrackRef(...)` 控制。
+
+## 相关主题
+
+- [配置](configuration.md)
+- [Schema 演进](schema-evolution.md)
+- [支持的类型](supported-types.md)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/index.md
index 30f8b06dc..cf694ae62 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/index.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/index.md
@@ -85,17 +85,17 @@ User decoded = fory.Deserialize<User>(payload);
| 主题 | 说明 |
| --------------------------------------------- | ---------------------------------- |
-| [配置](https://fory.apache.org/docs/guide/csharp/configuration) | 构建器选项与运行时模式 |
-| [基础序列化](https://fory.apache.org/docs/guide/csharp/basic-serialization) | 强类型和动态序列化 API |
-| [类型注册](https://fory.apache.org/docs/guide/csharp/type-registration) | 注册用户类型和自定义序列化器 |
-| [自定义序列化器](https://fory.apache.org/docs/guide/csharp/custom-serializers) | 实现 `Serializer<T>` |
-| [字段配置](https://fory.apache.org/docs/guide/csharp/field-configuration) | `[Field]` 特性与整数编码选项 |
-| [引用](https://fory.apache.org/docs/guide/csharp/references) | 共享引用与循环引用处理 |
-| [Schema 演进](https://fory.apache.org/docs/guide/csharp/schema-evolution) | 兼容模式行为 |
-| [跨语言](https://fory.apache.org/docs/guide/csharp/cross-language) | 互操作性指导 |
-| [支持的类型](https://fory.apache.org/docs/guide/csharp/supported-types) | 内置类型与生成类型支持 |
-| [线程安全](https://fory.apache.org/docs/guide/csharp/thread-safety) | `Fory` 与 `ThreadSafeFory` 的用法 |
-| [故障排查](https://fory.apache.org/docs/guide/csharp/troubleshooting) | 常见错误与调试步骤 |
+| [配置](configuration.md) | 构建器选项与运行时模式 |
+| [基础序列化](basic-serialization.md) | 强类型和动态序列化 API |
+| [类型注册](type-registration.md) | 注册用户类型和自定义序列化器 |
+| [自定义序列化器](custom-serializers.md) | 实现 `Serializer<T>` |
+| [字段配置](field-configuration.md) | `[Field]` 特性与整数编码选项 |
+| [引用](references.md) | 共享引用与循环引用处理 |
+| [Schema 演进](schema-evolution.md) | 兼容模式行为 |
+| [跨语言](cross-language.md) | 互操作性指导 |
+| [支持的类型](supported-types.md) | 内置类型与生成类型支持 |
+| [线程安全](thread-safety.md) | `Fory` 与 `ThreadSafeFory` 的用法 |
+| [故障排查](troubleshooting.md) | 常见错误与调试步骤 |
## 相关资源
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/references.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/references.md
new file mode 100644
index 000000000..bdbf56d28
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/references.md
@@ -0,0 +1,72 @@
+---
+title: 引用
+sidebar_position: 6
+id: references
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+当启用 `TrackRef(true)` 时，Apache Fory™ C# 可以保留共享引用和循环引用。
+
+## 启用引用跟踪
+
+```csharp
+Fory fory = Fory.Builder()
+ .TrackRef(true)
+ .Build();
+```
+
+启用后：
+
+- 共享对象身份会被保留。
+- 循环对象图可以安全地序列化和反序列化。
+
+## 循环引用示例
+
+```csharp
+using Apache.Fory;
+
+[ForyObject]
+public sealed class Node
+{
+ public int Value { get; set; }
+ public Node? Next { get; set; }
+}
+
+Fory fory = Fory.Builder()
+ .TrackRef(true)
+ .Build();
+fory.Register<Node>(200);
+
+Node node = new() { Value = 7 };
+node.Next = node;
+
+byte[] payload = fory.Serialize(node);
+Node decoded = fory.Deserialize<Node>(payload);
+
+// The cycle is preserved.
+System.Diagnostics.Debug.Assert(object.ReferenceEquals(decoded, decoded.Next));
+```
+
+## 何时使用 `TrackRef(false)`
+
+对于树状、无环且不关心引用身份的数据，`TrackRef(false)` 往往更快。
+
+## 相关主题
+
+- [配置](configuration.md)
+- [基础序列化](basic-serialization.md)
+- [线程安全](thread-safety.md)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/schema-evolution.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/schema-evolution.md
new file mode 100644
index 000000000..6531eb540
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/schema-evolution.md
@@ -0,0 +1,90 @@
+---
+title: Schema 演进
+sidebar_position: 7
+id: schema_evolution
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Apache Fory™ C# 在 `Compatible(true)` 模式下支持 Schema 演进。
+
+## 兼容模式
+
+```csharp
+Fory fory = Fory.Builder()
+ .Compatible(true)
+ .Build();
+```
+
+兼容模式会写入类型元信息，使结构体定义不同的读写端也能互操作。
+
+## 示例：新增一个字段
+
+```csharp
+using Apache.Fory;
+
+[ForyObject]
+public sealed class OneStringField
+{
+ public string? F1 { get; set; }
+}
+
+[ForyObject]
+public sealed class TwoStringField
+{
+ public string F1 { get; set; } = string.Empty;
+ public string F2 { get; set; } = string.Empty;
+}
+
+Fory fory1 = Fory.Builder().Compatible(true).Build();
+fory1.Register<OneStringField>(200);
+
+Fory fory2 = Fory.Builder().Compatible(true).Build();
+fory2.Register<TwoStringField>(200);
+
+byte[] payload = fory1.Serialize(new OneStringField { F1 = "hello" });
+TwoStringField evolved = fory2.Deserialize<TwoStringField>(payload);
+
+// F2 falls back to default value on reader side.
+System.Diagnostics.Debug.Assert(evolved.F1 == "hello");
+System.Diagnostics.Debug.Assert(evolved.F2 == string.Empty);
+```
+
+## 带版本校验的 Schema 一致模式
+
+如果你需要严格的 Schema 身份校验，而不是演进行为：
+
+```csharp
+Fory strict = Fory.Builder()
+ .Compatible(false)
+ .CheckStructVersion(true)
+ .Build();
+```
+
+这种模式会在 schema hash 不匹配时抛出异常。
+
+## 最佳实践
+
+1. 对独立部署的服务启用 `Compatible(true)`。
+2. 在不同版本之间保持稳定的 type ID。
+3. 新增字段时提供安全的默认值。
+4. 如果要求严格匹配，使用 `CheckStructVersion(true)`。
+
+## 相关主题
+
+- [配置](configuration.md)
+- [类型注册](type-registration.md)
+- [故障排查](troubleshooting.md)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/supported-types.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/supported-types.md
new file mode 100644
index 000000000..20baf0b41
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/supported-types.md
@@ -0,0 +1,97 @@
+---
+title: 支持的类型
+sidebar_position: 9
+id: supported_types
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页汇总 Apache Fory™ C# 的内置类型支持和生成类型支持。
+
+## 基础类型
+
+| C# 类型 | 说明 |
+| ------- | ---- |
+| `bool` | 支持 |
+| `sbyte`, `short`, `int`, `long` | 支持 |
+| `byte`, `ushort`, `uint`, `ulong` | 支持 |
+| `float`, `double` | 支持 |
+| `string` | 支持 |
+| `byte[]` | 支持 |
+| 可空基础类型，例如 `int?` | 支持 |
+
+## 数组
+
+- 基础数值数组，例如 `bool[]`、`int[]`、`ulong[]`
+- `byte[]`
+- 通过集合序列化器支持的一般数组 `T[]`
+
+## 集合
+
+### 类 List
+
+- `List<T>`
+- `LinkedList<T>`
+- `Queue<T>`
+- `Stack<T>`
+
+### 类 Set
+
+- `HashSet<T>`
+- `SortedSet<T>`
+- `ImmutableHashSet<T>`
+
+### 类 Map
+
+- `Dictionary<TKey, TValue>`
+- `SortedDictionary<TKey, TValue>`
+- `SortedList<TKey, TValue>`
+- `ConcurrentDictionary<TKey, TValue>`
+- `NullableKeyDictionary<TKey, TValue>`
+
+## 时间类型
+
+| C# 类型 | 编码类型 |
+| ------- | -------- |
+| `DateOnly` | `Date` |
+| `DateTime` | `Timestamp` |
+| `DateTimeOffset` | `Timestamp` |
+| `TimeSpan` | `Duration` |
+
+## 用户类型
+
+- 通过 source generator 生成序列化器的 `[ForyObject]` 类、结构体、枚举
+- 通过 `Register<T, TSerializer>(...)` 注册的自定义序列化器类型
+- `Union` / `Union2<...>` 强类型联合支持
+
+## 动态类型
+
+通过 `Serialize<object?>` / `Deserialize<object?>` 处理动态对象载荷时，支持：
+
+- 基础值和对象值
+- 动态列表、集合、映射
+- 嵌套的动态结构
+
+## 说明
+
+- 用户自定义类型应显式注册。
+- 跨语言使用时，请遵循 [xlang 指南](../xlang/index.md)。
+
+## 相关主题
+
+- [基础序列化](basic-serialization.md)
+- [类型注册](type-registration.md)
+- [跨语言](cross-language.md)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/thread-safety.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/thread-safety.md
new file mode 100644
index 000000000..5c2a33917
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/thread-safety.md
@@ -0,0 +1,73 @@
+---
+title: 线程安全
+sidebar_position: 10
+id: thread_safety
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Apache Fory™ C# 提供两种运行时形态，它们的线程保证不同。
+
+## `Fory`（单线程运行时）
+
+`Fory` 针对单线程复用做了优化，不能被多个线程并发使用。
+
+```csharp
+Fory fory = Fory.Builder().Build();
+```
+
+如果你显式管理线程亲和性，可以为每个线程分配一个 `Fory` 实例。
+
+## `ThreadSafeFory`（并发封装）
+
+`ThreadSafeFory` 为每个线程封装一个 `Fory` 实例，并对外提供线程安全 API。
+
+```csharp
+using Apache.Fory;
+
+using ThreadSafeFory fory = Fory.Builder()
+ .Compatible(true)
+ .TrackRef(true)
+ .BuildThreadSafe();
+
+fory.Register<MyType>(100);
+
+Parallel.For(0, 64, i =>
+{
+ byte[] payload = fory.Serialize(i);
+ int decoded = fory.Deserialize<int>(payload);
+});
+```
+
+## 注册行为
+
+- `ThreadSafeFory.Register(...)` 会集中保存注册信息。
+- 已存在的线程内运行时会被更新。
+- 新线程会自动收到此前所有注册信息。
+
+## 释放资源
+
+`ThreadSafeFory` 实现了 `IDisposable`，在不再使用时应及时释放。
+
+```csharp
+using ThreadSafeFory fory = Fory.Builder().BuildThreadSafe();
+```
+
+## 相关主题
+
+- [配置](configuration.md)
+- [类型注册](type-registration.md)
+- [引用](references.md)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/troubleshooting.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/troubleshooting.md
new file mode 100644
index 000000000..0a9212b3d
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/troubleshooting.md
@@ -0,0 +1,92 @@
+---
+title: 故障排查
+sidebar_position: 11
+id: troubleshooting
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍常见的 C# 运行时问题及其解决方法。
+
+## `TypeNotRegisteredException`
+
+**现象**：`Type not registered: ...`
+
+**原因**：用户类型在没有注册的情况下被序列化或反序列化。
+
+**修复方式**：
+
+```csharp
+Fory fory = Fory.Builder().Build();
+fory.Register<MyType>(100);
+```
+
+请确保读写两端使用相同的 type-ID 或名称映射。
+
+## `InvalidDataException: xlang bitmap mismatch`
+
+**原因**：载荷不是 xlang Fory 帧，或者它来自不输出 C# 所要求 xlang 头的对端或运行时模式。
+
+**修复方式**：确保载荷由与 xlang 兼容的 Fory 运行时生成。C# 始终要求 xlang 头，并且不提供单独的 `Xlang(...)` 构建器选项。
+
+```csharp
+Fory writer = Fory.Builder().Compatible(true).Build();
+Fory reader = Fory.Builder().Compatible(true).Build();
+```
+
+## 严格模式下的 Schema 版本不匹配
+
+**现象**：反序列化生成的结构体类型时抛出 `InvalidDataException`。
+
+**原因**：`Compatible(false)` 配合 `CheckStructVersion(true)` 时会要求 schema hash 完全一致。
+
+**可选修复方式**：
+
+- 启用 `Compatible(true)` 以支持 Schema 演进。
+- 保持写端和读端的模型定义同步。
+
+## 循环引用失败
+
+**现象**：类似栈溢出的递归问题，或者对象图重建异常。
+
+**原因**：循环对象图在 `TrackRef(false)` 下运行。
+
+**修复方式**：
+
+```csharp
+Fory fory = Fory.Builder().TrackRef(true).Build();
+```
+
+## 并发问题
+
+**原因**：在多个线程之间共享同一个 `Fory` 实例。
+
+**修复方式**：改用 `BuildThreadSafe()`。
+
+## 验证命令
+
+从仓库根目录运行 C# 测试：
+
+```bash
+cd csharp
+dotnet test Fory.sln -c Release
+```
+
+## 相关主题
+
+- [配置](configuration)
+- [Schema 演进](schema_evolution)
+- [线程安全](thread_safety)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/type-registration.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/type-registration.md
new file mode 100644
index 000000000..1afbf05c6
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/csharp/type-registration.md
@@ -0,0 +1,82 @@
+---
+title: 类型注册
+sidebar_position: 3
+id: type_registration
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍如何在 Apache Fory™ C# 中注册用户类型。
+
+## 按数字 type ID 注册
+
+显式 ID 可以提供紧凑且稳定的跨服务映射。
+
+```csharp
+Fory fory = Fory.Builder().Build();
+fory.Register<User>(100);
+fory.Register<Order>(101);
+```
+
+## 按类型名注册
+
+如果你更倾向于使用符号化映射，可以按命名空间和类型名注册。
+
+```csharp
+Fory fory = Fory.Builder().Build();
+fory.Register<User>("com.example", "User");
+```
+
+也可以使用简写重载：
+
+```csharp
+fory.Register<User>("User");
+```
+
+## 注册自定义序列化器
+
+```csharp
+Fory fory = Fory.Builder().Build();
+fory.Register<MyType, MyTypeSerializer>(200);
+```
+
+同样支持基于命名空间的自定义序列化器注册：
+
+```csharp
+fory.Register<MyType, MyTypeSerializer>("com.example", "MyType");
+```
+
+## 线程安全注册
+
+`ThreadSafeFory` 提供相同的注册 API。注册信息会传播到各个线程内运行时。
+
+```csharp
+using ThreadSafeFory fory = Fory.Builder().BuildThreadSafe();
+fory.Register<User>(100);
+fory.Register<Order>(101);
+```
+
+## 注册规则
+
+- 在写端和读端都要注册用户定义类型。
+- 在服务和语言之间保持 ID 或名称映射一致。
+- 在高频序列化负载开始前完成注册，避免运行时缺失。
+
+## 相关主题
+
+- [基础序列化](basic-serialization.md)
+- [自定义序列化器](custom-serializers.md)
+- [跨语言](cross-language.md)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/go/_category_.json b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/go/_category_.json
index 796c0a4dd..e4d176a76 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/go/_category_.json
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/go/_category_.json
@@ -1,6 +1,6 @@
{
"label": "Go",
- "position": 4,
+ "position": 5,
"collapsible": true,
"collapsed": true
}
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/go/codegen.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/go/codegen.md
index 67c338e52..e9e7a2748 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/go/codegen.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/go/codegen.md
@@ -20,36 +20,36 @@ license: |
---
:::warning Experimental Feature
-Code generation is an **experimental** feature in Fory Go. The API and behavior may change in future releases. The reflection-based path remains the stable, recommended approach for most use cases.
+代码生成是 Fory Go 中的**实验性**特性。其 API 和行为可能会在后续版本中发生变化。标准运行时路径仍是大多数场景下稳定且推荐的做法。
:::
-Fory Go 为性能关键路径提供可选的 AOT 代码生成，可消除反射开销并提升编译期类型安全。
+Fory Go 为性能关键路径提供可选的 AOT 代码生成。它会提前生成专用序列化器，并增加编译期 shape 校验。
## 为什么使用代码生成？
-| Aspect | Reflection-Based | Code Generation |
-| ----------- | ------------------ | ---------------------- |
-| Setup | Zero configuration | Requires `go generate` |
-| Performance | Good | Better (no reflection) |
-| Type Safety | Runtime | Compile-time |
-| Maintenance | Automatic | Requires regeneration |
+| 方面 | 标准路径 | 代码生成 |
+| -------- | ---------------- | ---------------------- |
+| 接入成本 | 零配置 | 需要 `go generate` |
+| 性能 | 已经很优秀 | 热路径上更快 |
+| 类型安全 | 运行时校验 | 编译期校验 |
+| 维护成本 | 自动完成 | 需要重新生成 |
-**Use code generation when**:
+**适合使用代码生成的场景：**
-- Maximum performance is required
-- Compile-time type safety is important
-- Hot paths are performance-critical
+- 需要极致性能
+- 很看重编译期类型安全
+- 热路径对性能非常敏感
-**Use reflection when**:
+**适合继续使用标准路径的场景：**
-- Simple setup is preferred
-- Types change frequently
-- Dynamic typing is needed
-- Code generation complexity is undesirable
+- 更偏好简单接入
+- 类型经常变化
+- 需要动态类型
+- 不希望引入代码生成复杂度
## 安装
-Install the `fory` generator binary:
+安装 `fory` 生成器二进制：
```bash
go install github.com/apache/fory/go/fory/cmd/fory@latest
@@ -57,13 +57,13 @@ go install github.com/apache/fory/go/fory/cmd/fory@latest
GO111MODULE=on go get -u github.com/apache/fory/go/fory/cmd/fory
```
-Ensure `$GOBIN` or `$GOPATH/bin` is in your `PATH`.
+确保 `$GOBIN` 或 `$GOPATH/bin` 已加入 `PATH`。
## 基本用法
-### Step 1: Annotate Structs
+### 步骤 1：标注结构体
-Add the `//fory:generate` comment above structs:
+在结构体上方添加 `//fory:generate` 注释：
```go
package models
@@ -82,35 +82,35 @@ type Order struct {
}
```
-### Step 2: Add Go Generate Directive
+### 步骤 2：添加 Go Generate 指令
-Add a `go:generate` directive (once per file or package):
+添加 `go:generate` 指令（每个文件或每个包一次即可）：
```go
//go:generate fory -file models.go
```
-Or for the entire package:
+或者针对整个包：
```go
//go:generate fory -pkg .
```
-### Step 3: Run Code Generation
+### 步骤 3：执行代码生成
```bash
go generate ./...
```
-This creates `models_fory_gen.go` with generated serializers.
+这会生成包含序列化器代码的 `models_fory_gen.go` 文件。
-## 生成代码结构
+## 生成代码的结构
-The generator creates:
+生成器会输出以下内容：
-### Type Snapshot
+### 类型快照
-A compile-time check to detect struct changes:
+用于检测结构体变化的编译期检查：
```go
// Snapshot of User's underlying type at generation time
@@ -123,111 +123,121 @@ type _User_expected struct {
var _ = func(x User) { _ = _User_expected(x) }
```
-### Serializer Implementation
+### 序列化器实现
-Strongly-typed serialization methods:
+强类型的序列化方法：
```go
type User_ForyGenSerializer struct{}
-func (User_ForyGenSerializer) WriteTyped(f *fory.Fory, buf *fory.ByteBuffer, v *User) error {
+func NewSerializerFor_User() fory.Serializer {
+ return &User_ForyGenSerializer{}
+}
+
+func (User_ForyGenSerializer) WriteTyped(ctx *fory.WriteContext, v *User) error {
+ buf := ctx.Buffer()
buf.WriteInt64(v.ID)
- fory.WriteString(buf, v.Name)
+ ctx.WriteString(v.Name)
return nil
}
-func (User_ForyGenSerializer) ReadTyped(f *fory.Fory, buf *fory.ByteBuffer, v *User) error {
- v.ID = buf.ReadInt64()
- v.Name = fory.ReadString(buf)
+func (User_ForyGenSerializer) ReadTyped(ctx *fory.ReadContext, v *User) error {
+ err := ctx.Err()
+ buf := ctx.Buffer()
+ v.ID = buf.ReadInt64(err)
+ v.Name = ctx.ReadString()
+ if ctx.HasError() {
+ return ctx.TakeError()
+ }
return nil
}
```
-### Auto-Registration
+### 自动注册
-Serializers are registered in `init()`:
+序列化器会在 `init()` 中注册：
```go
func init() {
- fory.RegisterGenSerializer(User{}, User_ForyGenSerializer{})
+ fory.RegisterSerializerFactory((*User)(nil), NewSerializerFor_User)
}
```
-## Command-Line Options
+## 命令行选项
-### File-Based Generation
+### 按文件生成
-Generate for a specific file:
+为某个文件生成：
```bash
fory -file models.go
```
-### Package-Based Generation
+### 按包生成
-Generate for a package:
+为整个包生成：
```bash
fory -pkg ./models
```
-### Explicit Types (Legacy)
+### 显式指定类型（旧用法）
-Specify types explicitly:
+显式指定类型：
```bash
fory -pkg ./models -type "User,Order"
```
-### Force Regeneration
+### 强制重新生成
-Force regeneration even if up-to-date:
+即使看起来已经是最新，也强制重新生成：
```bash
fory --force -file models.go
```
-## When to Regenerate
+## 何时需要重新生成
-Regenerate when any of these change:
+出现以下任意变化时，都应重新生成：
-- Field additions, removals, or renames
-- Field type changes
-- Struct tag changes
-- New structs with `//fory:generate`
+- 字段新增、删除或重命名
+- 字段类型变化
+- 结构体 tag 变化
+- 新增带 `//fory:generate` 的结构体
-### Automatic Detection
+### 自动检测
-Fory includes a compile-time guard:
+Fory 内置了编译期守卫：
```go
// If struct changed, this fails to compile
var _ = func(x User) { _ = _User_expected(x) }
```
-If you forget to regenerate, the build fails with a clear message.
+如果忘记重新生成，构建会失败，并给出明确提示。
-### Auto-Retry
+### 自动重试
-When invoked via `go generate`, the generator detects stale code and retries:
+当通过 `go generate` 调用时，生成器会检测陈旧代码并自动重试：
-1. Detects compile error from guard
-2. Removes stale generated file
-3. Regenerates fresh code
+1. 发现守卫触发的编译错误
+2. 删除旧的生成文件
+3. 重新生成最新代码
-## Supported Types
+## 支持的类型
-Code generation supports:
+代码生成支持：
-- All primitive types (`bool`, `int*`, `uint*`, `float*`, `string`)
-- Slices of primitives and structs
-- Maps with supported key/value types
-- Nested structs (must also be generated)
-- Pointers to structs
+- 所有原始类型（`bool`、`int*`、`uint*`、`float*`、`string`）
+- 原始类型和结构体的 slice
+- 键和值类型受支持的 map
+- 嵌套结构体（这些结构体也必须生成）
+- 指向结构体的指针
-### Nested Structs
+### 嵌套结构体
-All nested structs must also have `//fory:generate`:
+所有嵌套结构体也必须带有 `//fory:generate`：
```go
//fory:generate
@@ -243,11 +253,11 @@ type Person struct {
}
```
-## CI/CD Integration
+## CI/CD 集成
-### Check In Generated Code
+### 提交生成代码
-**Recommended for libraries**:
+**推荐用于库项目：**
```bash
go generate ./...
@@ -255,12 +265,12 @@ git add *_fory_gen.go
git commit -m "Regenerate Fory serializers"
```
-**Pros**: Consumers can build without generator; reproducible builds
-**Cons**: Larger diffs; must remember to regenerate
+**优点**：使用者无需安装生成器即可构建；构建更可复现
+**缺点**：diff 更大；需要记得重新生成
-### Generate in Pipeline
+### 在流水线中生成
-**Recommended for applications**:
+**推荐用于应用项目：**
```yaml
steps:
@@ -269,9 +279,9 @@ steps:
- run: go build ./...
```
-## Usage with Generated Code
+## 与生成代码配合使用
-Generated code integrates transparently:
+生成代码可以透明接入：
```go
f := fory.New()
@@ -284,11 +294,11 @@ var result User
f.Deserialize(data, &result)
```
-No code changes needed - registration happens in `init()`.
+无需修改业务代码，注册会在 `init()` 中自动完成。
-## Mixing Generated and Non-Generated
+## 混用生成与非生成方式
-You can mix approaches:
+你可以混合使用两种方式：
```go
//fory:generate
@@ -297,69 +307,69 @@ type HotPathStruct struct {
}
type ColdPathStruct struct {
- // Not annotated, uses reflection
+ // Not annotated, uses the standard runtime serializer
}
```
-## Limitations
+## 限制
-### Experimental Status
+### 实验性状态
-- API may change
-- Not all edge cases tested
-- May have undiscovered bugs
+- API 可能变化
+- 尚未覆盖所有边界场景
+- 可能仍有未发现的缺陷
-### Not Supported
+### 暂不支持
-- Interface fields (dynamic types)
-- Recursive types without pointers
-- Private (unexported) fields
-- Custom serializers
+- 接口字段（动态类型）
+- 无指针的递归类型
+- 私有（未导出）字段
+- 自定义序列化器
-### Reflection Fallback
+### 标准路径回退
-If codegen fails, Fory falls back to reflection:
+如果生成的序列化器不可用，Fory 会自动回退到标准序列化路径：
```go
-// If User_ForyGenSerializer not found, uses reflection
+// If User_ForyGenSerializer is not linked in, Fory uses the standard path
f.Serialize(&User{})
```
-## Troubleshooting
+## 故障排查
-### "fory: command not found"
+### `"fory: command not found"`
-Ensure the binary is in PATH:
+确保二进制已经加入 `PATH`：
```bash
export PATH=$PATH:$(go env GOPATH)/bin
```
-### Compile Error After Struct Change
+### 结构体变更后出现编译错误
-Regenerate:
+重新生成：
```bash
go generate ./...
```
-Or force:
+或强制重新生成：
```bash
fory --force -file yourfile.go
```
-### Generated Code Out of Sync
+### 生成代码不同步
-The compile-time guard catches this:
+编译期守卫会捕获这种情况：
```
cannot use x (variable of type User) as type _User_expected in argument
```
-Run `go generate` to fix.
+运行 `go generate` 即可修复。
-## Example Project Structure
+## 示例项目结构
```
myproject/
@@ -371,7 +381,7 @@ myproject/
└── go.mod
```
-**models/generate.go**:
+**models/generate.go**：
```go
package models
@@ -379,7 +389,7 @@ package models
//go:generate fory -pkg .
```
-**models/models.go**:
+**models/models.go**：
```go
package models
@@ -393,28 +403,28 @@ type User struct {
## FAQ
-### Is codegen required?
+### 代码生成是必须的吗？
-No. Reflection-based serialization works without code generation.
+不是。标准序列化路径在不使用代码生成时也能正常工作。
-### Does generated code work across Go versions?
+### 生成代码能跨 Go 版本使用吗？
-Yes. Generated code is plain Go with no version-specific features.
+可以。生成代码就是普通 Go 代码，不依赖某个特定版本的语言特性。
-### Can I mix generated and non-generated types?
+### 可以混用生成和非生成类型吗？
-Yes. Fory automatically uses generated serializers when available.
+可以。只要生成的序列化器可用，Fory 会自动优先使用它。
-### How do I update generated code?
+### 如何更新生成代码？
-Run `go generate ./...` after struct changes.
+结构体变更后运行 `go generate ./...`。
-### Should I commit generated files?
+### 应该提交生成文件吗？
-For libraries: yes. For applications: either works.
+对于库项目：建议提交。对于应用项目：两种做法都可以。
## 相关主题
-- [Basic Serialization](basic-serialization.md)
-- [Configuration](configuration.md)
-- [Troubleshooting](troubleshooting.md)
+- [基础序列化](basic-serialization.md)
+- [配置](configuration.md)
+- [故障排查](troubleshooting.md)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/go/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/go/index.md
index a161c8360..759da6a16 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/go/index.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/go/index.md
@@ -27,7 +27,7 @@ Apache Fory Go 是一个面向 Go 的高性能跨语言序列化库。它支持
- **跨语言**：可与 Java、Python、C++、Rust、JavaScript 无缝交换数据
- **自动序列化**：无需 IDL 定义或 schema 编译
- **引用跟踪**：内置循环引用和共享对象支持
-- **类型安全**：强类型能力，并可选用代码生成实现编译期校验
+- **类型安全**：具备基于 schema 感知序列化器的强类型能力
- **Schema 演进**：兼容模式支持前向/后向兼容
- **线程安全选项**：提供基于池化的线程安全封装，适用于并发场景
@@ -84,23 +84,15 @@ func main() {
}
```
-## 架构
+## 默认序列化路径
-Fory Go 提供两条序列化路径：
-
-### 基于反射（默认）
-
-默认路径使用 Go 反射在运行时检查类型。它开箱即用，可处理任意结构体。虽然该模式依赖反射，但通过类型缓存和热点路径内联优化，在绝大多数场景下都能提供优秀性能：
+Fory Go 可直接作用于普通 Go 结构体。标准运行时路径会缓存类型元数据，并对热点序列化路径做优化，因此大多数应用都可以直接使用，而不需要额外的构建步骤：
```go
f := fory.New()
data, _ := f.Serialize(myStruct)
```
-### 代码生成（实验特性）
-
-对性能极其敏感的路径，可以使用可选的预编译代码生成，消除反射开销。详见 [代码生成](codegen.md)。
-
## 配置
Fory Go 使用函数式选项模式进行配置：
@@ -153,7 +145,6 @@ data, _ := f.Serialize(&User{ID: 1, Name: "Alice"})
| [Struct 标签](struct-tags.md) | 字段级配置 |
| [Schema 演进](schema-evolution.md) | 前向/后向兼容策略 |
| [跨语言](cross-language.md) | 多语言序列化 |
-| [代码生成](codegen.md) | 实验性的 AOT 代码生成 |
| [线程安全](thread-safety.md) | 并发使用模式 |
| [故障排查](troubleshooting.md) | 常见问题与解决方案 |
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/graalvm_guide.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/graalvm_guide.md
index 56a1dc7b1..cd466b6bf 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/graalvm_guide.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/graalvm_guide.md
@@ -40,6 +40,20 @@ Apache Fory™ 通过**使用代码生成而非反射**，可以完美地与 Gra
## 基础用法
+### 步骤 0：添加 GraalVM 支持依赖
+
+在构建 native image 时，请将 `fory-graalvm-feature` 添加到应用依赖中：
+
+```xml
+<dependency>
+ <groupId>org.apache.fory</groupId>
+ <artifactId>fory-graalvm-feature</artifactId>
+ <version>${fory.version}</version>
+</dependency>
+```
+
+该依赖已经在 `META-INF/native-image` 中携带 GraalVM feature 元数据，因此只要将它加入依赖，就会在 `native-image` 构建期间自动启用 `org.apache.fory.graalvm.feature.ForyGraalVMFeature`。
+
### 步骤 1：创建 Fory 并注册类
```java
@@ -72,37 +86,20 @@ public class Example {
Args = --initialize-at-build-time=com.example.Example
```
-## ForyGraalVMFeature（可选）
+## `fory-graalvm-feature` 会处理什么
-对于大多数具有公共构造函数的类型，上述基本设置就足够了。但是，一些高级情况需要反射注册：
+加入 `fory-graalvm-feature` 依赖后，Fory 会自动注册这些高级场景所需的额外 GraalVM 元数据：
- **私有构造函数**（没有可访问的无参构造函数的类）
- **私有内部类/记录**
- **动态代理序列化**
-`fory-graalvm-feature` 模块会自动处理这些情况，无需手动配置 `reflect-config.json`。
-
-### 添加依赖
-
-```xml
-<dependency>
- <groupId>org.apache.fory</groupId>
- <artifactId>fory-graalvm-feature</artifactId>
- <version>${fory.version}</version>
-</dependency>
-```
-
-### 启用功能
-
-将以下内容添加到您的 `native-image.properties`：
+这意味着在大多数应用中都不再需要手工维护 `reflect-config.json`。你自己的 `native-image.properties` 仍只需要配置在构建时初始化的引导类，例如：
```properties
-Args = --initialize-at-build-time=com.example.Example \
- --features=org.apache.fory.graalvm.feature.ForyGraalVMFeature
+Args = --initialize-at-build-time=com.example.Example
```
-### ForyGraalVMFeature 处理的内容
-
| 场景 | 不使用 Feature | 使用 Feature |
| ------------------------ | --------------------------- | ------------ |
| 具有无参构造函数的公共类 | ✅ 可工作 | ✅ 可工作 |
@@ -137,17 +134,23 @@ public class ProxyExample {
String execute();
}
+ public interface Audited {
+ String traceId();
+ }
+
static Fory fory;
static {
fory = Fory.builder().build();
- // 为序列化注册代理接口
- GraalvmSupport.registerProxySupport(MyService.class);
+ // 按照 Proxy.newProxyInstance(...) 的接口顺序精确注册
+ GraalvmSupport.registerProxySupport(MyService.class, Audited.class);
fory.ensureSerializersCompiled();
}
}
```
+对于只实现单个接口的代理，可以使用 `registerProxySupport(MyService.class)`。如果代理实现了多个接口，则应按创建代理时使用的相同顺序传入完整接口列表。只要 classpath 中包含 `fory-graalvm-feature`，这就可以替代这些代理形状对应的手工 `proxy-config.json` 配置。
+
## 线程安全的 Fory
对于多线程应用程序，使用 `ThreadLocalFory`：
@@ -163,8 +166,8 @@ public class ThreadSafeExample {
static ThreadSafeFory fory;
static {
- fory = new ThreadLocalFory(classLoader -> {
- Fory f = Fory.builder().build();
+ fory = new ThreadLocalFory(builder -> {
+ Fory f = builder.build();
f.register(Foo.class);
f.ensureSerializersCompiled();
return f;
@@ -198,7 +201,7 @@ fory.ensureSerializersCompiled();
如果该类具有私有构造函数，可以：
-1. 添加 `fory-graalvm-feature` 依赖，或
+1. 确保 `fory-graalvm-feature` 已经位于 native-image classpath 中，或
2. 为该特定类创建 `reflect-config.json`
## 框架集成
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/_category_.json b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/_category_.json
index 3cb119d37..3508cf900 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/_category_.json
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/_category_.json
@@ -1,6 +1,6 @@
{
"label": "Java",
- "position": 0,
+ "position": 1,
"collapsible": true,
"collapsed": true
}
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/advanced-features.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/advanced-features.md
index f7104ebf5..c98720d71 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/advanced-features.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/advanced-features.md
@@ -1,6 +1,6 @@
---
title: 高级特性
-sidebar_position: 7
+sidebar_position: 10
id: advanced_features
license: |
Licensed to the Apache Software Foundation (ASF) under one or more
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/configuration.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/configuration.md
index 12ab5c9f4..e1e34fd24 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/configuration.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/configuration.md
@@ -19,35 +19,35 @@ license: |
limitations under the License.
---
-本页记录通过 `ForyBuilder` 提供的所有配置选项。
+本页记录通过 `ForyBuilder` 提供的全部配置选项。
## ForyBuilder 选项
-| 选项名称 | 描述 | 默认值 |
-| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ |
-| `timeRefIgnored` | 当启用引用跟踪时，是否忽略在 `TimeSerializers` 中注册的所有时间类型及其子类的引用跟踪。如果忽略，可以通过调用 `Fory#registerSerializer(Class, Serializer)` 为每个时间类型启用引用跟踪。例如，`fory.registerSerializer(Date.class, new DateSerializer(fory, true))`。注意，启用引用跟踪应该在包含时间字段的任何类型的序列化器代码生成之前进行。否则，这些字段仍将跳过引用跟踪。 | `true` |
-| `compressInt` | 启用或禁用 int 压缩以获得更小的大小。 | `true` |
-| `compressLong` | 启用或禁用 long 压缩以获得更小的大小。 | `true` |
-| `compressIntArray` | 当值可以适配较小数据类型时，启用或禁用 int 数组的 SIMD 加速压缩。需要 Java 16+。 | `true` |
-| `compressLongArray` | 当值可以适配较小数据类型时，启用或禁用 long 数组的 SIMD 加速压缩。需要 Java 16+。 | `true` |
-| `compressString` | 启用或禁用字符串压缩以获得更小的大小。 | `false` |
-| `classLoader` | 不应更新类加载器；Fory 缓存类元数据。对于类加载器更新，请使用 `LoaderBinding` 或 `ThreadSafeFory`。 | `Thread.currentThread().getContextClassLoader()` |
-| `compatibleMode` | 类型前向/后向兼容性配置。也与 `checkClassVersion` 配置相关。`SCHEMA_CONSISTENT`：序列化端和反序列化端之间的类 schema 必须一致。`COMPATIBLE`：序列化端和反序列化端之间的类 schema 可以不同。它们可以独立添加/删除字段。[查看更多](schema-evolution.md)。 | `CompatibleMode.SCHEMA_CONSISTENT` |
-| `checkClassVersion` | 确定是否检查类 schema 的一致性。如果启用，Fory 会使用 `classVersionHash` 检查、写入和检查一致性。当启用 `CompatibleMode#COMPATIBLE` 时，它将自动禁用。除非你能确保类不会演化，否则不建议禁用。 | `false` |
-| `checkJdkClassSerializable` | 启用或禁用对 `java.*` 下的类的 `Serializable` 接口检查。如果 `java.*` 下的类不是 `Serializable`，Fory 将抛出 `UnsupportedOperationException`。 | `true` |
-| `registerGuavaTypes` | 是否预注册 Guava 类型，如 `RegularImmutableMap`/`RegularImmutableList`。这些类型不是公共 API，但似乎相当稳定。 | `true` |
-| `requireClassRegistration` | 禁用可能允许未知类被反序列化，可能导致安全风险。 | `true` |
-| `maxDepth` | 设置反序列化的最大深度，当深度超过时，将抛出异常。这可用于拒绝反序列化 DDOS 攻击。 | `50` |
-| `suppressClassRegistrationWarnings` | 是否抑制类注册警告。这些警告可用于安全审计，但可能很烦人，默认情况下将启用此抑制。 | `true` |
-| `metaShareEnabled` | 启用或禁用元数据共享模式。 | 如果设置了 `CompatibleMode.Compatible` 则为 `true`，否则为 false。 |
-| `scopedMetaShareEnabled` | 作用域元数据共享专注于单个序列化过程。在此过程中创建或识别的元数据是它专有的，不会与其他序列化共享。 | 如果设置了 `CompatibleMode.Compatible` 则为 `true`，否则为 false。 |
-| `metaCompressor` | 为元数据压缩设置压缩器。注意传递的 MetaCompressor 应该是线程安全的。默认情况下，将使用基于 `Deflater` 的压缩器 `DeflaterMetaCompressor`。用户可以传递其他压缩器，如 `zstd` 以获得更好的压缩率。 | `DeflaterMetaCompressor` |
-| `deserializeNonexistentClass` | 启用或禁用对不存在类的数据的反序列化/跳过。 | 如果设置了 `CompatibleMode.Compatible` 则为 `true`，否则为 false。 |
-| `codeGenEnabled` | 禁用可能导致更快的初始序列化，但后续序列化会更慢。 | `true` |
-| `asyncCompilationEnabled` | 如果启用，序列化首先使用解释器模式，在类的异步序列化器 JIT 完成后切换到 JIT 序列化。 | `false` |
-| `scalaOptimizationEnabled` | 启用或禁用 Scala 特定的序列化优化。 | `false` |
-| `copyRef` | 禁用时，拷贝性能会更好。但 Fory 深拷贝将忽略循环引用和共享引用。对象图的相同引用将在一次 `Fory#copy` 中被复制为不同的对象。 | `true` |
-| `serializeEnumByName` | 启用时，Fory 按名称而不是序数序列化枚举。 | `false` |
+| 选项名称 | 描述 | 默认值 |
+| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| `timeRefIgnored` | 当启用引用跟踪时，是否忽略 `TimeSerializers` 中已注册的所有时间类型及其子类的引用跟踪。如果忽略，也可以通过调用 `Fory#registerSerializer(Class, Serializer)` 为某个时间类型重新启用引用跟踪。例如：`fory.registerSerializer(Date.class, new DateSerializer(fory.getConfig(), true))`。注意，对包含时间字段的类型而言，启用引用跟踪必须发生在相应序列化器代码生成之前，否则这些字段仍会跳过引用跟踪。 | `true` |
+| `compressInt` | 启用或禁用 int 压缩以减小体积。 | `true` |
+| `compressLong` | 启用或禁用 long 压缩以减小体积。 | `true` |
+| `compressIntArray` | 当值可以装入更小数据类型时，启用或禁用对 int 数组的 SIMD 加速压缩。需要 Java 16+。 | `false` |
+| `compressLongArray` | 当值可以装入更小数据类型时，启用或禁用对 long 数组的 SIMD 加速压缩。需要 Java 16+。 | `false` |
+| `compressString` | 启用或禁用字符串压缩以减小体积。 | `false` |
+| `classLoader` | 每个 `Fory` 实例的类加载器在首次解析类之后就固定下来，因为 Fory 会缓存类元数据。若要使用不同的类加载器，请创建一个配置了该类加载器的新 `Fory` 或 `ThreadSafeFory`，或者在首次类解析前依赖线程上下文类加载器。 | `Thread.currentThread().getContextClassLoader()` |
+| `compatibleMode` | 类型前向/后向兼容性配置，也与 `checkClassVersion` 相关。`SCHEMA_CONSISTENT` 表示序列化端和反序列化端的类 schema 必须一致；`COMPATIBLE` 表示两端的类 schema 可以不同，可独立新增或删除字段。[查看更多](schema-evolution.md)。 | `CompatibleMode.SCHEMA_CONSISTENT` |
+| `checkClassVersion` | 是否检查类 schema 的一致性。启用后，Fory 会基于 `classVersionHash` 写入并校验一致性。当启用 `CompatibleMode#COMPATIBLE` 时，该选项会自动关闭。除非你能确保类不会演进，否则不建议关闭。 | `false` |
+| `checkJdkClassSerializable` | 启用或禁用对 `java.*` 下类型的 `Serializable` 接口检查。如果某个 `java.*` 类型未实现 `Serializable`，Fory 会抛出 `UnsupportedOperationException`。 | `true` |
+| `registerGuavaTypes` | 是否预注册 Guava 类型，例如 `RegularImmutableMap` / `RegularImmutableList`。这些类型不是公共 API，但看起来相当稳定。 | `true` |
+| `requireClassRegistration` | 关闭后可能允许未知类被反序列化，从而带来安全风险。 | `true` |
+| `maxDepth` | 设置反序列化的最大深度，超过时会抛出异常。可用于阻止反序列化 DDOS 攻击。 | `50` |
+| `suppressClassRegistrationWarnings` | 是否抑制类注册警告。这些警告可用于安全审计，但可能较为烦人，因此默认启用抑制。 | `true` |
+| `metaShareEnabled` | 启用或禁用元数据共享模式。 | 如果设置了 `CompatibleMode.COMPATIBLE` 则为 `true`，否则为 false。 |
+| `scopedMetaShareEnabled` | 作用域元数据共享只关注单次序列化过程。在该过程中创建或识别的元数据只归属于这次序列化，不会与其他序列化共享。 | 如果设置了 `CompatibleMode.COMPATIBLE` 则为 `true`，否则为 false。 |
+| `metaCompressor` | 设置元数据压缩器。注意传入的 `MetaCompressor` 必须是线程安全的。默认使用基于 `Deflater` 的 `DeflaterMetaCompressor`。用户也可以传入 `zstd` 等其他压缩器以获得更好的压缩率。 | `DeflaterMetaCompressor` |
+| `deserializeUnknownClass` | 启用或禁用对不存在或未知类数据的反序列化/跳过。 | 如果设置了 `CompatibleMode.COMPATIBLE` 则为 `true`，否则为 false。 |
+| `codeGenEnabled` | 关闭后可能让首次序列化更快，但后续序列化会变慢。 | `true` |
+| `asyncCompilationEnabled` | 如果启用，序列化会先使用解释执行模式，在某个类的异步序列化器 JIT 完成后切换到 JIT 序列化。 | `false` |
+| `scalaOptimizationEnabled` | 启用或禁用 Scala 专用序列化优化。 | `false` |
+| `copyRef` | 关闭后，拷贝性能会更好；但 Fory 深拷贝将忽略循环引用和共享引用。对象图中的同一个引用会在一次 `Fory#copy` 中被复制成不同对象。 | `false` |
+| `serializeEnumByName` | 启用后，Fory 会序列化枚举名称，而不是数值枚举 tag。未启用时，Fory 默认写入声明顺序对应的 ordinal，或者在枚举配置了 `@ForyEnumId` 时写入显式稳定 ID。 | `false` |
## 示例配置
@@ -55,23 +55,25 @@ license: |
Fory fory = Fory.builder()
.withLanguage(Language.JAVA)
// 启用引用跟踪以支持共享/循环引用。
- // 如果没有重复引用，禁用它会有更好的性能。
+ // 如果没有重复引用，关闭它通常会有更好的性能。
.withRefTracking(false)
- // 压缩 int 以获得更小的大小
+ // 压缩 int 以减小体积
.withIntCompressed(true)
- // 压缩 long 以获得更小的大小
+ // 压缩 long 以减小体积
.withLongCompressed(true)
.withCompatibleMode(CompatibleMode.SCHEMA_CONSISTENT)
// 启用类型前向/后向兼容性
- // 禁用它以获得更小的大小和更好的性能。
+ // 关闭它通常能得到更小体积和更好性能。
// .withCompatibleMode(CompatibleMode.COMPATIBLE)
- // 启用异步多线程编译。
+ // 启用异步多线程编译
.withAsyncCompilation(true)
.build();
```
## 相关主题
-- [Schema 演化](schema-evolution.md) - 兼容模式和元数据共享
+- [字段配置](field-configuration.md) - `@ForyField`、`@Ignore` 与整数编码注解
+- [枚举配置](enum-configuration.md) - `serializeEnumByName` 与 `@ForyEnumId`
+- [Schema 演进](schema-evolution.md) - 兼容模式与元数据共享
- [压缩](compression.md) - Int、long 和数组压缩详情
- [类型注册](type-registration.md) - 类注册选项
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/custom-serializers.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/custom-serializers.md
index 12c4e42e4..e18e0ac20 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/custom-serializers.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/custom-serializers.md
@@ -19,641 +19,202 @@ license: |
limitations under the License.
---
-本页介绍如何为你的类型实现自定义序列化器。
+本页介绍当前 Java 自定义序列化器 API。
-## 基本自定义序列化器
+## 构造函数输入
-在某些情况下，你可能想为你的类型实现序列化器，特别是对于使用 JDK `writeObject/writeReplace/readObject/readResolve` 自定义序列化的类，这非常低效。
+自定义序列化器不应该持有 `Fory`。
-例如，如果你不想调用以下 `Foo#writeObject`，你可以实现自定义序列化器：
+- 当序列化器只依赖不可变配置、并且可共享时，使用 `Config`。
+- 当序列化器需要类型元信息、泛型或嵌套动态分派时，使用 `TypeResolver`。
+- 如果序列化器持有 `TypeResolver`，它通常就不可共享，也不应实现 `Shareable`。
-```java
-class Foo {
- public long f1;
+## 基础序列化器
- private void writeObject(ObjectOutputStream s) throws IOException {
- System.out.println(f1);
- s.defaultWriteObject();
- }
-}
+运行时状态应通过 `WriteContext` 和 `ReadContext` 传递。只有在确实要做多次读写时，才把 buffer 提取到局部变量中。
-class FooSerializer extends Serializer<Foo> {
- public FooSerializer(Fory fory) {
- super(fory, Foo.class);
+```java
+import org.apache.fory.config.Config;
+import org.apache.fory.context.ReadContext;
+import org.apache.fory.context.WriteContext;
+import org.apache.fory.memory.MemoryBuffer;
+import org.apache.fory.serializer.Serializer;
+import org.apache.fory.serializer.Shareable;
+
+public final class FooSerializer extends Serializer<Foo> implements Shareable {
+ public FooSerializer(Config config) {
+ super(config, Foo.class);
}
@Override
- public void write(MemoryBuffer buffer, Foo value) {
- buffer.writeInt64(value.f1);
+ public void write(WriteContext writeContext, Foo value) {
+ writeContext.getBuffer().writeInt64(value.f1);
+ writeContext.writeString(value.f2);
}
@Override
- public Foo read(MemoryBuffer buffer) {
+ public Foo read(ReadContext readContext) {
+ MemoryBuffer buffer = readContext.getBuffer();
Foo foo = new Foo();
foo.f1 = buffer.readInt64();
+ foo.f2 = readContext.readString(buffer);
return foo;
}
}
```
-### 注册序列化器
+如果序列化器可共享，就使用基于 `Config` 的构造方式注册：
```java
-Fory fory = getFory();
-fory.registerSerializer(Foo.class, new FooSerializer(fory));
+Fory fory = Fory.builder().build();
+fory.registerSerializer(Foo.class, new FooSerializer(fory.getConfig()));
```
-除了注册序列化器，你还可以为类实现 `java.io.Externalizable` 来自定义序列化逻辑。这种类型将由 Fory 的 `ExternalizableSerializer` 序列化。
-
-## 集合序列化器
-
-在为自定义集合类型实现序列化器时，你必须扩展 `CollectionSerializer` 或 `CollectionLikeSerializer`。主要区别是 `CollectionLikeSerializer` 可以序列化具有类似集合结构但不是 Java Collection 子类型的类。
-
-### supportCodegenHook 参数
+## 嵌套对象
-这个特殊参数控制序列化行为：
-
-**当为 `true` 时：**
-
-- 启用对集合元素的优化访问和 JIT 编译以获得更好的性能
-- 直接序列化调用和内联集合项，无需动态序列化器分派成本
-- 对标准集合类型有更好的性能
-- 对大多数集合推荐
-
-**当为 `false` 时：**
-
-- 使用基于接口的元素访问和元素的动态序列化器分派（成本更高）
-- 对自定义集合类型更灵活
-- 当集合有特殊序列化需求时需要
-- 处理复杂的集合实现
-
-### 带 JIT 支持的集合序列化器
-
-在实现带 JIT 支持的集合序列化器时，利用 Fory 现有的二进制格式和集合序列化基础设施：
+如果序列化器需要写入或读取嵌套对象，请使用 context helper，而不要持有 `Fory`：
```java
-public class CustomCollectionSerializer<T extends Collection> extends CollectionSerializer<T> {
- public CustomCollectionSerializer(Fory fory, Class<T> cls) {
- // supportCodegenHook 控制是否使用 JIT 编译
- super(fory, cls, true);
- }
-
- @Override
- public Collection onCollectionWrite(MemoryBuffer buffer, T value) {
- // 写入集合大小
- buffer.writeVarUint32Small7(value.size());
- // 写入任何额外的集合元数据
- return value;
- }
-
- @Override
- public Collection newCollection(MemoryBuffer buffer) {
- // 创建新的集合实例
- Collection collection = super.newCollection(buffer);
- // 读取并设置集合大小
- int numElements = getAndClearNumElements();
- setNumElements(numElements);
- return collection;
- }
-}
-```
-
-注意：在实现 `newCollection` 时调用 `setNumElements`，让 Fory 知道要反序列化多少元素。
-
-### 不带 JIT 的自定义集合序列化器
-
-对于使用原始数组或有特殊要求的集合，实现禁用 JIT 的序列化器：
+import org.apache.fory.config.Config;
+import org.apache.fory.context.ReadContext;
+import org.apache.fory.context.WriteContext;
+import org.apache.fory.serializer.Serializer;
+
+public final class EnvelopeSerializer extends Serializer<Envelope> {
+ public EnvelopeSerializer(Config config) {
+ super(config, Envelope.class);
+ }
-```java
-class IntList extends AbstractCollection<Integer> {
- private final int[] elements;
- private final int size;
-
- public IntList(int size) {
- this.elements = new int[size];
- this.size = size;
- }
-
- public IntList(int[] elements, int size) {
- this.elements = elements;
- this.size = size;
- }
-
- @Override
- public Iterator<Integer> iterator() {
- return new Iterator<Integer>() {
- private int index = 0;
-
- @Override
- public boolean hasNext() {
- return index < size;
- }
-
- @Override
- public Integer next() {
- if (!hasNext()) {
- throw new NoSuchElementException();
- }
- return elements[index++];
- }
- };
- }
-
- @Override
- public int size() {
- return size;
- }
-
- public int get(int index) {
- if (index >= size) {
- throw new IndexOutOfBoundsException();
- }
- return elements[index];
- }
-
- public void set(int index, int value) {
- if (index >= size) {
- throw new IndexOutOfBoundsException();
- }
- elements[index] = value;
- }
-
- public int[] getElements() {
- return elements;
- }
-}
+ @Override
+ public void write(WriteContext writeContext, Envelope value) {
+ writeContext.writeRef(value.header);
+ writeContext.writeRef(value.payload);
+ }
-class IntListSerializer extends CollectionLikeSerializer<IntList> {
- public IntListSerializer(Fory fory) {
- // 禁用 JIT，因为我们直接处理序列化
- super(fory, IntList.class, false);
- }
-
- @Override
- public void write(MemoryBuffer buffer, IntList value) {
- // 写入大小
- buffer.writeVarUint32Small7(value.size());
-
- // 直接将元素写为原始 int
- int[] elements = value.getElements();
- for (int i = 0; i < value.size(); i++) {
- buffer.writeVarInt32(elements[i]);
- }
- }
-
- @Override
- public IntList read(MemoryBuffer buffer) {
- // 读取大小
- int size = buffer.readVarUint32Small7();
-
- // 创建数组并读取元素
- int[] elements = new int[size];
- for (int i = 0; i < size; i++) {
- elements[i] = buffer.readVarInt32();
- }
-
- return new IntList(elements, size);
- }
-
- // 当禁用 JIT 时不使用这些方法
- @Override
- public Collection onCollectionWrite(MemoryBuffer buffer, IntList value) {
- throw new UnsupportedOperationException();
- }
-
- @Override
- public Collection newCollection(MemoryBuffer buffer) {
- throw new UnsupportedOperationException();
- }
-
- @Override
- public IntList onCollectionRead(Collection collection) {
- throw new UnsupportedOperationException();
- }
+ @Override
+ public Envelope read(ReadContext readContext) {
+ Envelope envelope = new Envelope();
+ envelope.header = (Header) readContext.readRef();
+ envelope.payload = readContext.readRef();
+ return envelope;
+ }
}
```
-**何时使用此方法：**
+由于它不保留任何运行时局部可变状态，因此该序列化器可以实现 `Shareable`。
+
+## 集合序列化器
-- 处理原始类型
-- 需要最大性能
-- 想要最小化内存开销
-- 有特殊的序列化需求
+对于 Java 集合，请继承 `CollectionSerializer` 或 `CollectionLikeSerializer`。
-### 类集合类型序列化器
+- `CollectionSerializer` 用于真正的 `Collection` 实现。
+- `CollectionLikeSerializer` 用于形态像集合、但并未实现 `Collection` 的类型。
+- 当集合可以使用标准元素代码生成路径时，保持 `supportCodegenHook == true`。
+- 只有在你需要完全控制元素 IO 时，才把 `supportCodegenHook` 设为 `false`。
-对于行为类似集合但不是标准 Java 集合的类型：
+示例：
```java
-class CustomCollectionLike {
- private final Object[] elements;
- private final int size;
-
- public CustomCollectionLike(int size) {
- this.elements = new Object[size];
- this.size = 0;
- }
-
- public CustomCollectionLike(Object[] elements, int size) {
- this.elements = elements;
- this.size = size;
- }
-
- public Object get(int index) {
- if (index >= size) {
- throw new IndexOutOfBoundsException();
- }
- return elements[index];
- }
-
- public int size() {
- return size;
- }
-
- public Object[] getElements() {
- return elements;
- }
-}
+import java.util.ArrayList;
+import java.util.Collection;
+import org.apache.fory.context.ReadContext;
+import org.apache.fory.context.WriteContext;
+import org.apache.fory.memory.MemoryBuffer;
+import org.apache.fory.resolver.TypeResolver;
+import org.apache.fory.serializer.collection.CollectionSerializer;
+
+public final class CustomCollectionSerializer<T extends Collection<?>>
+ extends CollectionSerializer<T> {
+ public CustomCollectionSerializer(TypeResolver typeResolver, Class<T> type) {
+ super(typeResolver, type, true);
+ }
-class CollectionView extends AbstractCollection<Object> {
- private final Object[] elements;
- private final int size;
- private int writeIndex;
-
- public CollectionView(CustomCollectionLike collection) {
- this.elements = collection.getElements();
- this.size = collection.size();
- }
-
- public CollectionView(int size) {
- this.size = size;
- this.elements = new Object[size];
- }
-
- @Override
- public Iterator<Object> iterator() {
- return new Iterator<Object>() {
- private int index = 0;
-
- @Override
- public boolean hasNext() {
- return index < size;
- }
-
- @Override
- public Object next() {
- if (!hasNext()) {
- throw new NoSuchElementException();
- }
- return elements[index++];
- }
- };
- }
-
- @Override
- public boolean add(Object element) {
- if (writeIndex >= size) {
- throw new IllegalStateException("Collection is full");
- }
- elements[writeIndex++] = element;
- return true;
- }
-
- @Override
- public int size() {
- return size;
- }
-
- public Object[] getElements() {
- return elements;
- }
-}
+ @Override
+ public Collection onCollectionWrite(WriteContext writeContext, T value) {
+ writeContext.getBuffer().writeVarUint32Small7(value.size());
+ return value;
+ }
+
+ @Override
+ public T onCollectionRead(Collection collection) {
+ return (T) collection;
+ }
-class CustomCollectionSerializer extends CollectionLikeSerializer<CustomCollectionLike> {
- public CustomCollectionSerializer(Fory fory) {
- super(fory, CustomCollectionLike.class, true);
- }
-
- @Override
- public Collection onCollectionWrite(MemoryBuffer buffer, CustomCollectionLike value) {
- buffer.writeVarUint32Small7(value.size());
- return new CollectionView(value);
- }
-
- @Override
- public Collection newCollection(MemoryBuffer buffer) {
- int numElements = buffer.readVarUint32Small7();
- setNumElements(numElements);
- return new CollectionView(numElements);
- }
-
- @Override
- public CustomCollectionLike onCollectionRead(Collection collection) {
- CollectionView view = (CollectionView) collection;
- return new CustomCollectionLike(view.getElements(), view.size());
- }
+ @Override
+ public Collection newCollection(ReadContext readContext) {
+ MemoryBuffer buffer = readContext.getBuffer();
+ int numElements = buffer.readVarUint32Small7();
+ setNumElements(numElements);
+ return new ArrayList(numElements);
+ }
}
```
## Map 序列化器
-在为自定义 Map 类型实现序列化器时，扩展 `MapSerializer` 或 `MapLikeSerializer`。主要区别是 `MapLikeSerializer` 可以序列化具有类似 map 结构但不是 Java Map 子类型的类。
-
-### 带 JIT 支持的 Map 序列化器
+对于 Java map，请继承 `MapSerializer` 或 `MapLikeSerializer`。
```java
-public class CustomMapSerializer<T extends Map> extends MapSerializer<T> {
- public CustomMapSerializer(Fory fory, Class<T> cls) {
- // supportCodegenHook 是决定序列化行为的关键参数
- super(fory, cls, true);
- }
-
- @Override
- public Map onMapWrite(MemoryBuffer buffer, T value) {
- // 写入 map 大小
- buffer.writeVarUint32Small7(value.size());
- // 在这里写入任何额外的 map 元数据
- return value;
- }
-
- @Override
- public Map newMap(MemoryBuffer buffer) {
- // 读取 map 大小
- int numElements = buffer.readVarUint32Small7();
- setNumElements(numElements);
- // 创建并返回新的 map 实例
- T map = (T) new HashMap(numElements);
- fory.getRefResolver().reference(map);
- return map;
- }
-}
-```
-
-注意：在实现 `newMap` 时调用 `setNumElements`，让 Fory 知道要反序列化多少元素。
-
-### 不带 JIT 的自定义 Map 序列化器
+import java.util.LinkedHashMap;
+import java.util.Map;
+import org.apache.fory.memory.MemoryBuffer;
+import org.apache.fory.context.ReadContext;
+import org.apache.fory.context.WriteContext;
+import org.apache.fory.resolver.TypeResolver;
+import org.apache.fory.serializer.collection.MapSerializer;
+
+public final class CustomMapSerializer<T extends Map<?, ?>> extends MapSerializer<T> {
+ public CustomMapSerializer(TypeResolver typeResolver, Class<T> type) {
+ super(typeResolver, type, true);
+ }
-对于完全控制序列化过程：
+ @Override
+ public Map onMapWrite(WriteContext writeContext, T value) {
+ writeContext.getBuffer().writeVarUint32Small7(value.size());
+ return value;
+ }
-```java
-class FixedValueMap extends AbstractMap<String, Integer> {
- private final Set<String> keys;
- private final int fixedValue;
-
- public FixedValueMap(Set<String> keys, int fixedValue) {
- this.keys = keys;
- this.fixedValue = fixedValue;
- }
-
- @Override
- public Set<Entry<String, Integer>> entrySet() {
- Set<Entry<String, Integer>> entries = new HashSet<>();
- for (String key : keys) {
- entries.add(new SimpleEntry<>(key, fixedValue));
- }
- return entries;
- }
-
- @Override
- public Integer get(Object key) {
- return keys.contains(key) ? fixedValue : null;
- }
-
- public Set<String> getKeys() {
- return keys;
- }
-
- public int getFixedValue() {
- return fixedValue;
- }
-}
+ @Override
+ public T onMapRead(Map map) {
+ return (T) map;
+ }
-class FixedValueMapSerializer extends MapLikeSerializer<FixedValueMap> {
- public FixedValueMapSerializer(Fory fory) {
- // 禁用 codegen，因为我们直接处理序列化
- super(fory, FixedValueMap.class, false);
- }
-
- @Override
- public void write(MemoryBuffer buffer, FixedValueMap value) {
- // 写入固定值
- buffer.writeInt32(value.getFixedValue());
- // 写入键的数量
- buffer.writeVarUint32Small7(value.getKeys().size());
- // 写入每个键
- for (String key : value.getKeys()) {
- buffer.writeString(key);
- }
- }
-
- @Override
- public FixedValueMap read(MemoryBuffer buffer) {
- // 读取固定值
- int fixedValue = buffer.readInt32();
- // 读取键的数量
- int size = buffer.readVarUint32Small7();
- Set<String> keys = new HashSet<>(size);
- for (int i = 0; i < size; i++) {
- keys.add(buffer.readString());
- }
- return new FixedValueMap(keys, fixedValue);
- }
-
- // 当 supportCodegenHook 为 false 时不使用这些方法
- @Override
- public Map onMapWrite(MemoryBuffer buffer, FixedValueMap value) {
- throw new UnsupportedOperationException();
- }
-
- @Override
- public FixedValueMap onMapRead(Map map) {
- throw new UnsupportedOperationException();
- }
-
- @Override
- public FixedValueMap onMapCopy(Map map) {
- throw new UnsupportedOperationException();
- }
+ @Override
+ public Map newMap(ReadContext readContext) {
+ MemoryBuffer buffer = readContext.getBuffer();
+ int numElements = buffer.readVarUint32Small7();
+ setNumElements(numElements);
+ return new LinkedHashMap(numElements);
+ }
}
```
-### 类 Map 类型序列化器
-
-对于行为类似 map 但不是标准 Java Map 的类型：
+## 注册
```java
-class CustomMapLike {
- private final Object[] keyArray;
- private final Object[] valueArray;
- private final int size;
-
- public CustomMapLike(int initialCapacity) {
- this.keyArray = new Object[initialCapacity];
- this.valueArray = new Object[initialCapacity];
- this.size = 0;
- }
-
- public CustomMapLike(Object[] keyArray, Object[] valueArray, int size) {
- this.keyArray = keyArray;
- this.valueArray = valueArray;
- this.size = size;
- }
-
- public Integer get(String key) {
- for (int i = 0; i < size; i++) {
- if (key.equals(keyArray[i])) {
- return (Integer) valueArray[i];
- }
- }
- return null;
- }
-
- public int size() {
- return size;
- }
-
- public Object[] getKeyArray() {
- return keyArray;
- }
-
- public Object[] getValueArray() {
- return valueArray;
- }
-}
-
-class MapView extends AbstractMap<Object, Object> {
- private final Object[] keyArray;
- private final Object[] valueArray;
- private final int size;
- private int writeIndex;
-
- public MapView(CustomMapLike mapLike) {
- this.size = mapLike.size();
- this.keyArray = mapLike.getKeyArray();
- this.valueArray = mapLike.getValueArray();
- }
-
- public MapView(int size) {
- this.size = size;
- this.keyArray = new Object[size];
- this.valueArray = new Object[size];
- }
-
- @Override
- public Set<Entry<Object, Object>> entrySet() {
- return new AbstractSet<Entry<Object, Object>>() {
- @Override
- public Iterator<Entry<Object, Object>> iterator() {
- return new Iterator<Entry<Object, Object>>() {
- private int index = 0;
-
- @Override
- public boolean hasNext() {
- return index < size;
- }
-
- @Override
- public Entry<Object, Object> next() {
- if (!hasNext()) {
- throw new NoSuchElementException();
- }
- final int currentIndex = index++;
- return new SimpleEntry<>(
- keyArray[currentIndex],
- valueArray[currentIndex]
- );
- }
- };
- }
-
- @Override
- public int size() {
- return size;
- }
- };
- }
-
- @Override
- public Object put(Object key, Object value) {
- if (writeIndex >= size) {
- throw new IllegalStateException("Map is full");
- }
- keyArray[writeIndex] = key;
- valueArray[writeIndex] = value;
- writeIndex++;
- return null;
- }
-
- public Object[] getKeyArray() {
- return keyArray;
- }
-
- public Object[] getValueArray() {
- return valueArray;
- }
-
- public int size() {
- return size;
- }
-}
-
-class CustomMapLikeSerializer extends MapLikeSerializer<CustomMapLike> {
- public CustomMapLikeSerializer(Fory fory) {
- super(fory, CustomMapLike.class, true);
- }
-
- @Override
- public Map onMapWrite(MemoryBuffer buffer, CustomMapLike value) {
- buffer.writeVarUint32Small7(value.size());
- return new MapView(value);
- }
-
- @Override
- public Map newMap(MemoryBuffer buffer) {
- int numElements = buffer.readVarUint32Small7();
- setNumElements(numElements);
- return new MapView(numElements);
- }
-
- @Override
- public CustomMapLike onMapRead(Map map) {
- MapView view = (MapView) map;
- return new CustomMapLike(view.getKeyArray(), view.getValueArray(), view.size());
- }
-
- @Override
- public CustomMapLike onMapCopy(Map map) {
- MapView view = (MapView) map;
- return new CustomMapLike(view.getKeyArray(), view.getValueArray(), view.size());
- }
-}
+Fory fory = Fory.builder().build();
+
+fory.registerSerializer(Foo.class, new FooSerializer(fory.getConfig()));
+fory.registerSerializer(
+ CustomMap.class, new CustomMapSerializer<>(fory.getTypeResolver(), CustomMap.class));
+fory.registerSerializer(
+ CustomCollection.class,
+ new CustomCollectionSerializer<>(fory.getTypeResolver(), CustomCollection.class));
```
-## 注册自定义序列化器
+如果希望 Fory 按需懒加载地构造序列化器，可以注册工厂：
```java
-Fory fory = Fory.builder()
- .withLanguage(Language.JAVA)
- .build();
-
-// 注册 map 序列化器
-fory.registerSerializer(CustomMap.class, new CustomMapSerializer<>(fory, CustomMap.class));
-
-// 注册集合序列化器
-fory.registerSerializer(CustomCollection.class, new CustomCollectionSerializer<>(fory, CustomCollection.class));
+fory.registerSerializer(
+ CustomMap.class, resolver -> new CustomMapSerializer<>(resolver, CustomMap.class));
```
-## 关键点
-
-实现自定义 map 或集合序列化器时：
+## 可共享性
-1. 始终扩展适当的基类（map 使用 `MapSerializer`/`MapLikeSerializer`，集合使用 `CollectionSerializer`/`CollectionLikeSerializer`）
-2. 考虑 `supportCodegenHook` 对性能和功能的影响
-3. 如果需要，适当处理引用跟踪
-4. 当 `supportCodegenHook` 为 `true` 时，使用 `setNumElements` 和 `getAndClearNumElements` 实现适当的大小管理
+当某个序列化器能够在等价运行时之间以及并发操作中安全复用时，就应实现 `Shareable` 标记接口。可共享序列化器不能保留操作状态、运行时局部可变状态，也不能在多次调用之间复用可变 scratch buffer。使用者可以通过 `serializer instanceof Shareable` 来判断其是否可共享。
-## 相关主题
+在实践中：
-- [类型注册](type-registration.md) - 注册序列化器
-- [Schema 演化](schema-evolution.md) - 兼容模式考虑
-- [配置选项](configuration.md) - 序列化选项
+- 只依赖 `Config` 的序列化器通常是可共享的。
+- 基于 `TypeResolver` 的序列化器通常不可共享。
+- 操作状态应放在 `WriteContext`、`ReadContext` 和 `CopyContext` 中，而不是放在序列化器字段里。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/field-configuration.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/field-configuration.md
index 2f21ab6c6..62251bb8b 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/field-configuration.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/field-configuration.md
@@ -600,6 +600,7 @@ public class User {
## 相关主题
-- [基础序列化](basic_serialization) - 快速上手 Fory 序列化
-- [Schema 演进](schema_evolution) - 兼容模式与 schema 演进
-- [跨语言](cross_language) - 与 Python、Rust、C++、Go 互操作
+- [基础序列化](basic-serialization.md) - 快速上手 Fory 序列化
+- [配置选项](configuration.md) - 运行时构建器选项
+- [枚举配置](enum-configuration.md) - `@ForyEnumId` 以及按名称/按 tag 的枚举行为
+- [Schema 演进](schema-evolution.md) - 兼容模式与 Schema 演进
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/index.md
index ce0300cce..4888dee0e 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/index.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/index.md
@@ -82,22 +82,16 @@ public class Example {
### 多线程使用
```java
-import java.util.List;
-import java.util.Arrays;
-
import org.apache.fory.*;
import org.apache.fory.config.*;
public class Example {
public static void main(String[] args) {
SomeClass object = new SomeClass();
- // 注意 Fory 实例应该在多次不同对象的序列化之间复用。
- ThreadSafeFory fory = new ThreadLocalFory(classLoader -> {
- Fory f = Fory.builder().withLanguage(Language.JAVA)
- .withClassLoader(classLoader).build();
- f.register(SomeClass.class, 1);
- return f;
- });
+ ThreadSafeFory fory = Fory.builder()
+ .withLanguage(Language.JAVA)
+ .buildThreadSafeFory();
+ fory.register(SomeClass.class, 1);
byte[] bytes = fory.serialize(object);
System.out.println(fory.deserialize(bytes));
}
@@ -107,20 +101,17 @@ public class Example {
### Fory 实例复用模式
```java
-import java.util.List;
-import java.util.Arrays;
-
import org.apache.fory.*;
import org.apache.fory.config.*;
public class Example {
- // 复用 fory。
- private static final ThreadSafeFory fory = new ThreadLocalFory(classLoader -> {
- Fory f = Fory.builder().withLanguage(Language.JAVA)
- .withClassLoader(classLoader).build();
- f.register(SomeClass.class, 1);
- return f;
- });
+ private static final ThreadSafeFory fory = Fory.builder()
+ .withLanguage(Language.JAVA)
+ .buildThreadSafeFory();
+
+ static {
+ fory.register(SomeClass.class, 1);
+ }
public static void main(String[] args) {
SomeClass object = new SomeClass();
@@ -132,26 +123,39 @@ public class Example {
## 线程安全
-Fory 提供多种线程安全序列化选项：
+Fory 提供两种线程安全运行时风格：
+
+### `buildThreadSafeFory`
+
+这是默认选择。它会构建一个固定大小的共享 `ThreadPoolFory`，其大小为 `4 * availableProcessors()`，也是虚拟线程工作负载下的首选运行时：
+
+```java
+ThreadSafeFory fory = Fory.builder()
+ .withLanguage(Language.JAVA)
+ .withRefTracking(false)
+ .withCompatibleMode(CompatibleMode.SCHEMA_CONSISTENT)
+ .withAsyncCompilation(true)
+ .buildThreadSafeFory();
+```
+
+更多细节请参见 [虚拟线程](virtual-threads.md)。
### ThreadLocalFory
-使用线程本地存储为每个线程维护独立的 Fory 实例：
+仅当你明确希望为每个长期存在的平台线程分配一个 `Fory` 实例，或者无论 JDK 版本如何都要固定采用这种方式时，才使用 `buildThreadLocalFory()`：
```java
-ThreadSafeFory fory = new ThreadLocalFory(classLoader -> {
- Fory f = Fory.builder().withLanguage(Language.JAVA)
- .withClassLoader(classLoader).build();
- f.register(SomeClass.class, 1);
- return f;
-});
+ThreadSafeFory fory = Fory.builder()
+ .withLanguage(Language.JAVA)
+ .buildThreadLocalFory();
+fory.register(SomeClass.class, 1);
byte[] bytes = fory.serialize(object);
System.out.println(fory.deserialize(bytes));
```
-### ThreadSafeForyPool
+### `buildThreadSafeForyPool`
-对于虚拟线程或不适合使用线程本地存储的环境，使用 `buildThreadSafeForyPool`：
+如果你希望显式指定固定共享池大小，请使用 `buildThreadSafeForyPool(poolSize)`。它会预先创建 `poolSize` 个 `Fory` 实例，把它们放在共享固定槽位中，然后让任意调用方通过与线程无关的快速路径借用实例。只有当池中所有实例都在使用时，调用才会阻塞；运行时不会按照线程身份缓存实例：
```java
ThreadSafeFory fory = Fory.builder()
@@ -159,11 +163,9 @@ ThreadSafeFory fory = Fory.builder()
.withRefTracking(false)
.withCompatibleMode(CompatibleMode.SCHEMA_CONSISTENT)
.withAsyncCompilation(true)
- .buildThreadSafeForyPool(minPoolSize, maxPoolSize);
+ .buildThreadSafeForyPool(poolSize);
```
-注意，在 `ForyBuilder` 上调用 `buildThreadSafeFory()` 将创建 `ThreadLocalFory` 实例。这在使用虚拟线程的环境中可能不合适，因为每个线程都会创建自己的 Fory 实例，这是一个相对昂贵的操作。对于虚拟线程，另一种选择是使用 `buildThreadSafeForyPool`。
-
### Builder 方法
```java
@@ -175,19 +177,28 @@ Fory fory = Fory.builder()
.withAsyncCompilation(true)
.build();
-// 线程安全 Fory (ThreadLocalFory)
+// 线程安全 Fory（由 Fory 实例池支撑）
ThreadSafeFory fory = Fory.builder()
.withLanguage(Language.JAVA)
.withRefTracking(false)
.withCompatibleMode(CompatibleMode.SCHEMA_CONSISTENT)
.withAsyncCompilation(true)
.buildThreadSafeFory();
+
+// 显式线程本地运行时
+ThreadSafeFory threadLocalFory = Fory.builder()
+ .withLanguage(Language.JAVA)
+ .buildThreadLocalFory();
```
## 后续步骤
- [配置选项](configuration.md) - 了解 ForyBuilder 选项
+- [字段配置](field-configuration.md) - `@ForyField`、`@Ignore` 和整数编码注解
+- [枚举配置](enum-configuration.md) - `serializeEnumByName` 与 `@ForyEnumId`
- [基础序列化](basic-serialization.md) - 详细的序列化模式
+- [压缩](compression.md) - 整数、long 和数组压缩选项
+- [虚拟线程](virtual-threads.md) - 虚拟线程使用方式与池大小建议
- [类型注册](type-registration.md) - 类注册和安全性
- [自定义序列化器](custom-serializers.md) - 实现自定义序列化器
- [跨语言序列化](cross-language.md) - 为其他语言序列化数据
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/migration.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/migration.md
index d794ab848..f1510c7ac 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/migration.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/migration.md
@@ -1,6 +1,6 @@
---
title: 迁移指南
-sidebar_position: 10
+sidebar_position: 13
id: migration
license: |
Licensed to the Apache Software Foundation (ASF) under one or more
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/schema-evolution.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/schema-evolution.md
index 4ec49c718..bff6bd0e4 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/schema-evolution.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/schema-evolution.md
@@ -1,6 +1,6 @@
---
-title: Schema 演化
-sidebar_position: 5
+title: Schema 演进
+sidebar_position: 9
id: schema_evolution
license: |
Licensed to the Apache Software Foundation (ASF) under one or more
@@ -62,13 +62,13 @@ Fory 支持在上下文（例如 TCP 连接）中的多次序列化之间共享
// .withMetaContextShare(true)
// 非线程安全 fory。
-MetaContext context = xxx;
-fory.getSerializationContext().setMetaContext(context);
+MetaWriteContext writeContext = xxx;
+fory.setMetaWriteContext(writeContext);
byte[] bytes = fory.serialize(o);
// 非线程安全 fory。
-MetaContext context = xxx;
-fory.getSerializationContext().setMetaContext(context);
+MetaReadContext readContext = xxx;
+fory.setMetaReadContext(readContext);
fory.deserialize(bytes);
```
@@ -76,37 +76,35 @@ fory.deserialize(bytes);
```java
// 线程安全 fory
-fory.setClassLoader(beanA.getClass().getClassLoader());
byte[] serialized = fory.execute(
f -> {
- f.getSerializationContext().setMetaContext(context);
+ f.setMetaWriteContext(writeContext);
return f.serialize(beanA);
}
);
// 线程安全 fory
-fory.setClassLoader(beanA.getClass().getClassLoader());
Object newObj = fory.execute(
f -> {
- f.getSerializationContext().setMetaContext(context);
+ f.setMetaReadContext(readContext);
return f.deserialize(serialized);
}
);
```
-**注意**：`MetaContext` 不是线程安全的，不能在 Fory 实例或多个线程之间重用。在多线程情况下，必须为每个 Fory 实例创建单独的 `MetaContext`。
+**注意**：`MetaWriteContext` 和 `MetaReadContext` 都不是线程安全的，不能在多个 Fory 实例或多个线程之间重用。在多线程场景下，必须为每个 Fory 实例创建一对独立的 meta context。如果你需要不同的类加载器，请创建一个配置了该类加载器的独立 `Fory` 或 `ThreadSafeFory`，而不是在已有实例上切换类加载器。
有关更多详细信息，请参阅 [元数据共享规范](https://fory.apache.org/docs/specification/fory_java_serialization_spec#meta-share)。
-## 反序列化不存在的类
+## 反序列化未知类
-Fory 支持反序列化不存在的类。此功能可以通过 `ForyBuilder#deserializeNonexistentClass(true)` 启用。
+Fory 支持反序列化不存在或未知的类。此功能可通过 `ForyBuilder#deserializeUnknownClass(true)` 启用。
-启用时，如果启用了元数据共享，Fory 将把此类型的反序列化数据存储在 Map 的延迟子类中。通过使用 Fory 实现的延迟映射，可以避免反序列化期间填充映射的重新平衡成本，从而进一步提高性能。
+启用后，如果同时启用了元数据共享，Fory 会把这类数据存放在 `Map` 的惰性子类中。通过使用 Fory 实现的惰性 map，可以避免反序列化过程中填充 map 的重平衡成本，从而进一步提升性能。
-如果此数据被发送到另一个进程，并且该类在此过程中存在，则数据将被反序列化为此类型的对象，而不会丢失任何信息。
+如果这些数据被发送到另一个进程，并且该进程中存在相应类，那么这些数据就会被反序列化为该类型的对象，而不会丢失信息。
-如果未启用元数据共享，新类数据将被跳过，并返回 `NonexistentSkipClass` 存根对象。
+如果没有启用元数据共享，新类数据会被跳过，并返回 `UnknownSkipClass` 存根对象。
## 将对象从一种类型复制/映射到另一种类型
@@ -159,7 +157,7 @@ public class StructMappingExample {
## 将 POJO 反序列化为另一种类型
-Fory 允许你序列化一个 POJO 并将其反序列化为另一个 POJO。不同的 POJO 意味着 schema 不一致。用户必须将 Fory 配置为 `CompatibleMode` 设置为 `org.apache.fory.config.CompatibleMode.COMPATIBLE`。
+Fory 允许你序列化一个 POJO，并将其反序列化为另一个不同的 POJO。不同的 POJO 意味着 schema 不一致。用户必须将 Fory 配置为 `CompatibleMode.COMPATIBLE`。
```java
public class DeserializeIntoType {
@@ -184,8 +182,8 @@ public class DeserializeIntoType {
public static void main(String[] args) {
Struct1 struct1 = new Struct1(10, "abc");
- byte[] data = fory.serializeJavaObject(struct1);
- Struct2 struct2 = (Struct2) fory.deserializeJavaObject(bytes, Struct2.class);
+ byte[] data = fory.serialize(struct1);
+ Struct2 struct2 = fory.deserialize(data, Struct2.class);
}
}
```
@@ -198,7 +196,7 @@ public class DeserializeIntoType {
| `checkClassVersion` | 检查类 schema 一致性 | `false` |
| `metaShareEnabled` | 启用元数据共享 | 如果是兼容模式则为 `true` |
| `scopedMetaShareEnabled` | 每次序列化的作用域元数据共享 | 如果是兼容模式则为 `true` |
-| `deserializeNonexistentClass` | 处理不存在的类 | 如果是兼容模式则为 `true` |
+| `deserializeUnknownClass` | 处理不存在或未知的类 | 如果是兼容模式则为 `true` |
| `metaCompressor` | 元数据压缩的压缩器 | `DeflaterMetaCompressor` |
## 最佳实践
@@ -212,4 +210,4 @@ public class DeserializeIntoType {
- [配置选项](configuration.md) - 所有 ForyBuilder 选项
- [跨语言序列化](cross-language.md) - XLANG 模式
-- [故障排除](troubleshooting.md) - 常见 schema 问题
+- [故障排查](troubleshooting.md) - 常见 Schema 问题
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/troubleshooting.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/troubleshooting.md
index f9265f23d..3b85463e8 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/troubleshooting.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/troubleshooting.md
@@ -1,6 +1,6 @@
---
-title: 故障排除
-sidebar_position: 11
+title: 故障排查
+sidebar_position: 14
id: troubleshooting
license: |
Licensed to the Apache Software Foundation (ASF) under one or more
@@ -21,11 +21,11 @@ license: |
本页介绍常见问题及其解决方案。
-## 类不一致和类版本检查
+## 类不一致与类版本检查
-如果你创建 Fory 时没有将 `CompatibleMode` 设置为 `org.apache.fory.config.CompatibleMode.COMPATIBLE`，并且遇到奇怪的序列化错误，这可能是由于序列化端和反序列化端之间的类不一致造成的。
+如果你创建 Fory 时没有将 `CompatibleMode` 设为 `org.apache.fory.config.CompatibleMode.COMPATIBLE`，并且遇到奇怪的序列化错误，那么原因可能是序列化端和反序列化端之间的类不一致。
-在这种情况下，你可以调用 `ForyBuilder#withClassVersionCheck` 来创建 Fory 以验证它。如果反序列化抛出 `org.apache.fory.exception.ClassNotCompatibleException`，则表示类不一致，你应该使用 `ForyBuilder#withCompatibleMode(CompatibleMode.COMPATIBLE)` 创建 Fory。
+在这种情况下，你可以调用 `ForyBuilder#withClassVersionCheck` 来创建 Fory 进行校验。如果反序列化抛出 `org.apache.fory.exception.ClassNotCompatibleException`，就说明类不一致，此时应改为使用 `ForyBuilder#withCompatibleMode(CompatibleMode.COMPATIBLE)` 创建 Fory。
```java
// 启用类版本检查以诊断问题
@@ -34,54 +34,44 @@ Fory fory = Fory.builder()
.withClassVersionCheck(true)
.build();
-// 如果抛出 ClassNotCompatibleException，使用兼容模式
+// 如果抛出 ClassNotCompatibleException，则改用兼容模式
Fory fory = Fory.builder()
.withLanguage(Language.JAVA)
.withCompatibleMode(CompatibleMode.COMPATIBLE)
.build();
```
-**注意**：`CompatibleMode.COMPATIBLE` 有更多的性能和空间成本。如果你的类在序列化和反序列化之间始终一致，请不要默认设置它。
+**注意**：`CompatibleMode.COMPATIBLE` 会带来更多的性能和空间开销。如果序列化端和反序列化端的类始终一致，就不要默认开启它。
-## 使用错误的反序列化 API
+## 使用了错误的反序列化 API
-确保使用匹配的 API 对：
+请将 `serialize` 与某个 `deserialize` 重载搭配使用：
-| 序列化 API | 反序列化 API |
-| ---------------------------------- | ------------------------------------ |
-| `Fory#serialize` | `Fory#deserialize` |
-| `Fory#serializeJavaObject` | `Fory#deserializeJavaObject` |
-| `Fory#serializeJavaObjectAndClass` | `Fory#deserializeJavaObjectAndClass` |
+| 序列化 API | 反序列化 API |
+| ----------------- | ----------------- |
+| `Fory#serialize` | `Fory#deserialize` |
-**错误使用示例：**
+**错误示例：**
```java
-// ❌ 错误：使用 serialize 序列化，使用 deserializeJavaObject 反序列化
-byte[] bytes = fory.serialize(object);
-Object result = fory.deserializeJavaObject(bytes, MyClass.class); // 错误！
-
-// ❌ 错误：使用 serializeJavaObject 序列化，使用 deserialize 反序列化
-byte[] bytes = fory.serializeJavaObject(object);
-Object result = fory.deserialize(bytes); // 错误！
+// ❌ 错误：使用不兼容的目标类型做反序列化
+byte[] bytes = fory.serialize(struct1);
+Struct2 result = fory.deserialize(bytes, Struct2.class); // 可能抛出 ClassCastException
```
-**正确使用：**
+**正确示例：**
```java
-// ✅ 正确：匹配的 API 对
byte[] bytes = fory.serialize(object);
Object result = fory.deserialize(bytes);
-byte[] bytes = fory.serializeJavaObject(object);
-MyClass result = fory.deserializeJavaObject(bytes, MyClass.class);
-
-byte[] bytes = fory.serializeJavaObjectAndClass(object);
-Object result = fory.deserializeJavaObjectAndClass(bytes);
+byte[] typedBytes = fory.serialize(object);
+MyClass typedResult = fory.deserialize(typedBytes, MyClass.class);
```
## 将 POJO 反序列化为另一种类型
-如果你想序列化一个 POJO 并将其反序列化为另一个 POJO 类型，你必须使用 `CompatibleMode.COMPATIBLE`：
+如果你想序列化一个 POJO，然后把它反序列化为另一种 POJO 类型，就必须使用 `CompatibleMode.COMPATIBLE`：
```java
public class DeserializeIntoType {
@@ -106,19 +96,19 @@ public class DeserializeIntoType {
public static void main(String[] args) {
Struct1 struct1 = new Struct1(10, "abc");
- byte[] data = fory.serializeJavaObject(struct1);
- Struct2 struct2 = (Struct2) fory.deserializeJavaObject(data, Struct2.class);
+ byte[] data = fory.serialize(struct1);
+ Struct2 struct2 = fory.deserialize(data, Struct2.class);
}
}
```
## 常见错误消息
-### "Class not registered"
+### `"Class not registered"`
-**原因**：需要类注册，但类未注册。
+**原因**：启用了类注册要求，但该类没有注册。
-**解决方案**：在序列化之前注册类：
+**解决方案**：在序列化前注册该类：
```java
fory.register(MyClass.class);
@@ -126,9 +116,9 @@ fory.register(MyClass.class);
fory.register(MyClass.class, 100);
```
-### "ClassNotCompatibleException"
+### `"ClassNotCompatibleException"`
-**原因**：序列化和反序列化之间的类 schema 不同。
+**原因**：序列化端和反序列化端之间的类 schema 不一致。
**解决方案**：使用兼容模式：
@@ -138,33 +128,33 @@ Fory fory = Fory.builder()
.build();
```
-### "Max depth exceeded"
+### `"Max depth exceeded"`
-**原因**：对象图太深，可能表示循环引用攻击。
+**原因**：对象图过深，可能意味着循环引用攻击。
-**解决方案**：如果是合法的，增加最大深度，或检查恶意数据：
+**解决方案**：如果数据本身合法，就提高最大深度；否则检查是否存在恶意数据：
```java
Fory fory = Fory.builder()
- .withMaxDepth(100) // 从默认的 50 增加
+ .withMaxDepth(100) // 相比默认值 50 提高上限
.build();
```
-### "Serializer not found"
+### `"Serializer not found"`
-**原因**：未为该类型注册序列化器。
+**原因**：该类型没有注册对应的序列化器。
**解决方案**：注册自定义序列化器：
```java
-fory.registerSerializer(MyClass.class, new MyClassSerializer(fory));
+fory.registerSerializer(MyClass.class, new MyClassSerializer(fory.getTypeResolver()));
```
## 性能问题
-### 初始序列化慢
+### 首次序列化较慢
-**原因**：JIT 编译在第一次序列化时发生。
+**原因**：第一次序列化时发生了 JIT 编译。
**解决方案**：启用异步编译：
@@ -174,32 +164,32 @@ Fory fory = Fory.builder()
.build();
```
-### 内存使用高
+### 内存使用过高
-**原因**：大对象图或引用跟踪开销。
+**原因**：对象图较大，或引用跟踪带来额外开销。
**解决方案**：
-- 如果不需要，禁用引用跟踪：`.withRefTracking(false)`
-- 使用自定义内存分配器进行池化
-- 考虑对大数据集使用行格式
+- 如果不需要，关闭引用跟踪：`.withRefTracking(false)`
+- 使用自定义内存分配器做池化
+- 对大数据集考虑使用行格式
-### 序列化大小大
+### 序列化结果偏大
-**原因**：元数据开销或未压缩的数据。
+**原因**：元数据开销过大，或数据未压缩。
**解决方案**：
- 启用压缩：`.withIntCompressed(true)`、`.withLongCompressed(true)`
-- 仅在需要时使用兼容模式
-- 注册类以避免类名序列化
+- 只在真正需要时使用兼容模式
+- 注册类以避免写入类名
## 调试技巧
-1. **启用类版本检查**以诊断 schema 问题
-2. **检查 API 配对** - 确保序列化/反序列化 API 匹配
-3. **验证注册顺序** - 必须在各端之间保持一致
-4. **启用日志记录**以查看内部操作：
+1. **启用类版本检查** 来诊断 Schema 问题。
+2. **检查 API 是否正确配对**，确保 serialize/deserialize 组合正确。
+3. **核对注册顺序**，两端必须保持一致。
+4. **启用日志** 观察内部行为：
```java
LoggerFactory.setLogLevel(LogLevel.DEBUG_LEVEL);
@@ -207,7 +197,7 @@ LoggerFactory.setLogLevel(LogLevel.DEBUG_LEVEL);
## 相关主题
-- [配置选项](configuration.md) - 所有 ForyBuilder 选项
-- [Schema 演化](schema-evolution.md) - 兼容模式详情
+- [配置](configuration.md) - 所有 ForyBuilder 选项
+- [Schema 演进](schema-evolution.md) - 兼容模式详情
- [类型注册](type-registration.md) - 注册最佳实践
- [迁移指南](migration.md) - 升级 Fory 版本
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/type-registration.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/type-registration.md
index 73a90fa59..88baec0ce 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/type-registration.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/type-registration.md
@@ -19,19 +19,19 @@ license: |
limitations under the License.
---
-本页介绍类注册机制和安全配置。
+本页介绍类注册机制与安全配置。
## 类注册
-`ForyBuilder#requireClassRegistration` 可用于禁用类注册。这将允许反序列化未知类型的对象，这更灵活但**如果类包含恶意代码可能不安全**。
+`ForyBuilder#requireClassRegistration` 可用于关闭类注册要求。这会允许反序列化未知类型的对象，灵活性更高，但**如果这些类包含恶意代码，就可能不安全**。
-**除非你能确保环境是安全的，否则不要禁用类注册**。当禁用此选项时，反序列化未知/不受信任的类型时，`init/equals/hashCode` 中的恶意代码可能会被执行。
+**除非你能确保运行环境安全，否则不要关闭类注册。** 当这个选项被关闭时，反序列化未知或不受信任的类型时，`init/equals/hashCode` 中的恶意代码可能被执行。
-类注册不仅可以降低安全风险，还可以避免类名序列化成本。
+类注册不仅可以降低安全风险，也能避免写入类名带来的额外开销。
### 按 ID 注册
-你可以使用 API `Fory#register` 注册类：
+你可以通过 `Fory#register` 注册类：
```java
Fory fory = xxx;
@@ -39,56 +39,57 @@ fory.register(SomeClass.class);
fory.register(SomeClass1.class, 1);
```
-注意，类注册顺序很重要。序列化和反序列化端应该具有相同的注册顺序。
+注意，类注册顺序很重要。序列化端和反序列化端应该保持相同的注册顺序。
+
+内部类型 ID 的 `0-32` 预留给内置 xlang 类型。Java 原生内建类型从 `Types.NONE + 1` 开始，用户 ID 的编码形式是 `(user_id << 8) | internal_type_id`。
### 按名称注册
-按 ID 注册类会有更好的性能和更小的空间开销。但在某些情况下，管理一堆类型 ID 很复杂。在这种情况下，建议使用 API `register(Class<?> cls, String namespace, String typeName)` 按名称注册类：
+按 ID 注册有更好的性能和更小的空间开销。但在某些场景下，维护大量 type ID 也很复杂。这时，推荐使用 `register(Class<?> cls, String namespace, String typeName)` 按名称注册类：
```java
fory.register(Foo.class, "demo", "Foo");
```
-如果类型没有重复的名称，`namespace` 可以留空以减少序列化大小。
+如果类型名称不会冲突，可以将 `namespace` 留空以减小序列化体积。
-**不要使用此 API 注册类，因为与按 ID 注册类相比，它会大大增加序列化大小。**
+**不要在应追求紧凑编码的场景中优先使用这个 API，因为它相比按 ID 注册会显著增加序列化体积。**
## 安全配置
-### 类检查器
+### Type Checker
-如果你调用 `ForyBuilder#requireClassRegistration(false)` 来禁用类注册检查，你可以通过 `ClassResolver#setClassChecker` 设置 `org.apache.fory.resolver.ClassChecker` 来控制哪些类允许序列化。
+如果你调用 `ForyBuilder#requireClassRegistration(false)` 来关闭类注册检查，就可以通过 `ForyBuilder#withTypeChecker` 或 `TypeResolver#setTypeChecker` 配置 `org.apache.fory.resolver.TypeChecker`，从而控制哪些类允许被序列化。
-例如，你可以允许以 `org.example.*` 开头的类：
+例如，你可以允许所有以 `org.example.*` 开头的类：
```java
-Fory fory = xxx;
-fory.getClassResolver().setClassChecker(
- (classResolver, className) -> className.startsWith("org.example."));
+Fory fory = Fory.builder()
+ .requireClassRegistration(false)
+ .withTypeChecker((typeResolver, className) -> className.startsWith("org.example."))
+ .build();
```
### AllowListChecker
-Fory 提供了 `org.apache.fory.resolver.AllowListChecker`，这是一个基于允许/禁止列表的检查器，用于简化类检查机制的自定义：
+Fory 提供了 `org.apache.fory.resolver.AllowListChecker`，这是一个基于允许/禁止列表的检查器，可简化类检查机制的定制：
```java
AllowListChecker checker = new AllowListChecker(AllowListChecker.CheckLevel.STRICT);
-ThreadSafeFory fory = new ThreadLocalFory(classLoader -> {
- Fory f = Fory.builder().requireClassRegistration(true).withClassLoader(classLoader).build();
- f.getClassResolver().setClassChecker(checker);
- checker.addListener(f.getClassResolver());
- return f;
-});
checker.allowClass("org.example.*");
+ThreadSafeFory fory = Fory.builder()
+ .requireClassRegistration(false)
+ .withTypeChecker(checker)
+ .buildThreadSafeFory();
```
-你可以使用此检查器或自己实现更复杂的检查器。
+`withTypeChecker` 会在每个新建运行时上立即安装检查器，这也能避免在关闭类注册却没有配置检查器时产生通用启动警告。如果你需要在构建之后替换检查器，仍然可以继续使用 `TypeResolver#setTypeChecker` 或 `ThreadSafeFory#setTypeChecker`。
## 限制最大反序列化深度
-Fory 提供 `ForyBuilder#withMaxDepth` 来限制最大反序列化深度。默认最大深度为 50。
+Fory 提供 `ForyBuilder#withMaxDepth` 用于限制最大反序列化深度。默认最大深度为 50。
-如果达到最大深度，Fory 将抛出 `ForyException`。这可用于防止恶意数据导致堆栈溢出或其他问题。
+当达到最大深度时，Fory 会抛出 `ForyException`。这可用于防止恶意数据导致的栈溢出等问题。
```java
Fory fory = Fory.builder()
@@ -99,14 +100,14 @@ Fory fory = Fory.builder()
## 最佳实践
-1. **在生产环境中始终启用类注册**：使用 `requireClassRegistration(true)`
-2. **使用基于 ID 的注册以获得性能**：数字 ID 比字符串名称更快
-3. **保持一致的注册顺序**：序列化和反序列化端的顺序相同
-4. **设置适当的最大深度**：防止堆栈溢出攻击
-5. **使用 AllowListChecker 进行细粒度控制**：当你需要灵活的类过滤时
+1. **生产环境始终启用类注册**：使用 `requireClassRegistration(true)`。
+2. **优先使用按 ID 注册**：数字 ID 比字符串名称更快。
+3. **保持注册顺序一致**：序列化端和反序列化端必须相同。
+4. **设置合适的最大深度**：防止栈溢出攻击。
+5. **需要细粒度控制时使用 AllowListChecker**：适合灵活的类过滤场景。
## 相关主题
-- [配置选项](configuration.md) - ForyBuilder 安全选项
+- [配置](configuration.md) - ForyBuilder 的安全相关选项
- [自定义序列化器](custom-serializers.md) - 注册自定义序列化器
-- [故障排除](troubleshooting.md) - 常见注册问题
+- [故障排查](troubleshooting.md) - 常见注册问题
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/kotlin/_category_.json b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/kotlin/_category_.json
index bd051cc65..18540b480 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/kotlin/_category_.json
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/kotlin/_category_.json
@@ -1,6 +1,6 @@
{
"label": "Kotlin",
- "position": 8,
+ "position": 11,
"collapsible": true,
"collapsed": true
}
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/kotlin/fory-creation.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/kotlin/fory-creation.md
index 178bf9f61..62bb9f0f2 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/kotlin/fory-creation.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/kotlin/fory-creation.md
@@ -63,18 +63,14 @@ object ForyHolder {
```kotlin
import org.apache.fory.Fory
import org.apache.fory.ThreadSafeFory
-import org.apache.fory.ThreadLocalFory
import org.apache.fory.serializer.kotlin.KotlinSerializers
object ForyHolder {
- val fory: ThreadSafeFory = ThreadLocalFory { classLoader ->
- Fory.builder()
- .withClassLoader(classLoader)
- .requireClassRegistration(true)
- .build().also {
- KotlinSerializers.registerSerializers(it)
- }
- }
+ val fory: ThreadSafeFory = Fory.builder()
+ .requireClassRegistration(true)
+ .buildThreadSafeFory().also {
+ KotlinSerializers.registerSerializers(it)
+ }
}
```
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/python/_category_.json b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/python/_category_.json
index a964bce6e..b37a31907 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/python/_category_.json
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/python/_category_.json
@@ -1,6 +1,6 @@
{
"label": "Python",
- "position": 1,
+ "position": 2,
"collapsible": true,
"collapsed": true
}
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/python/custom-serializers.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/python/custom-serializers.md
index bbc973c71..96fb8fe7d 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/python/custom-serializers.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/python/custom-serializers.md
@@ -23,7 +23,7 @@ license: |
## 实现自定义序列化器
-为 Python 模式覆盖 `write/read`，为跨语言模式覆盖 `xwrite/xread`：
+在 Python 模式和跨语言模式下，都只需实现一套 `write/read`：
```python
import pyfory
@@ -36,30 +36,22 @@ class Foo:
f2: str
class FooSerializer(Serializer):
- def __init__(self, fory, cls):
- super().__init__(fory, cls)
+ def __init__(self, type_resolver, cls):
+ super().__init__(type_resolver, cls)
- def write(self, buffer, obj: Foo):
+ def write(self, write_context, obj: Foo):
# 自定义序列化逻辑
- buffer.write_varint32(obj.f1)
- buffer.write_string(obj.f2)
+ write_context.write_varint32(obj.f1)
+ write_context.write_string(obj.f2)
- def read(self, buffer):
+ def read(self, read_context):
# 自定义反序列化逻辑
- f1 = buffer.read_varint32()
- f2 = buffer.read_string()
+ f1 = read_context.read_varint32()
+ f2 = read_context.read_string()
return Foo(f1, f2)
- # 用于跨语言模式
- def xwrite(self, buffer, obj: Foo):
- buffer.write_int32(obj.f1)
- buffer.write_string(obj.f2)
-
- def xread(self, buffer):
- return Foo(buffer.read_int32(), buffer.read_string())
-
f = pyfory.Fory()
-f.register(Foo, type_id=100, serializer=FooSerializer(f, Foo))
+f.register(Foo, type_id=100, serializer=FooSerializer(f.type_resolver, Foo))
# 现在 Foo 使用自定义序列化器
data = f.dumps(Foo(42, "hello"))
@@ -133,10 +125,10 @@ value = buffer.read_bool()
fory = pyfory.Fory()
# 使用 type_id 注册
-fory.register(MyClass, type_id=100, serializer=MySerializer(fory, MyClass))
+fory.register(MyClass, type_id=100, serializer=MySerializer(fory.type_resolver, MyClass))
# 使用 typename 注册（用于 xlang）
-fory.register(MyClass, typename="com.example.MyClass", serializer=MySerializer(fory, MyClass))
+fory.register(MyClass, typename="com.example.MyClass", serializer=MySerializer(fory.type_resolver, MyClass))
```
## 相关主题
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/python/type-registration.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/python/type-registration.md
index b9d80885b..b8a929ec4 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/python/type-registration.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/python/type-registration.md
@@ -71,7 +71,7 @@ fory.register(MyClass, typename="com.example.MyClass")
### 模式 3：使用自定义序列化器
```python
-fory.register(MyClass, type_id=100, serializer=MySerializer(fory, MyClass))
+fory.register(MyClass, type_id=100, serializer=MySerializer(fory.type_resolver, MyClass))
```
### 模式 4：批量注册
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/rust/_category_.json b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/rust/_category_.json
index 845d58f46..e89108621 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/rust/_category_.json
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/rust/_category_.json
@@ -1,6 +1,6 @@
{
"label": "Rust",
- "position": 2,
+ "position": 3,
"collapsible": true,
"collapsed": true
}
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/scala/_category_.json b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/scala/_category_.json
index 6cc51ddde..a0191e287 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/scala/_category_.json
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/scala/_category_.json
@@ -1,6 +1,6 @@
{
"label": "Scala",
- "position": 7,
+ "position": 10,
"collapsible": true,
"collapsed": true
}
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/scala/fory-creation.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/scala/fory-creation.md
index feba91dd4..6245d7996 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/scala/fory-creation.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/scala/fory-creation.md
@@ -98,19 +98,16 @@ object ForyHolder {
对于多线程应用程序，使用 `ThreadSafeFory`：
```scala
+import org.apache.fory.Fory
import org.apache.fory.ThreadSafeFory
-import org.apache.fory.ThreadLocalFory
import org.apache.fory.serializer.scala.ScalaSerializers
object ForyHolder {
- val fory: ThreadSafeFory = new ThreadLocalFory(classLoader => {
- val f = Fory.builder()
- .withScalaOptimizationEnabled(true)
- .withClassLoader(classLoader)
- .build()
- ScalaSerializers.registerSerializers(f)
- f
- })
+ val fory: ThreadSafeFory = Fory.builder()
+ .withScalaOptimizationEnabled(true)
+ .buildThreadSafeFory()
+
+ ScalaSerializers.registerSerializers(fory)
}
```
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/kotlin/_category_.json b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/swift/_category_.json
similarity index 75%
copy from i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/kotlin/_category_.json
copy to i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/swift/_category_.json
index bd051cc65..dfdaf5996 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/kotlin/_category_.json
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/swift/_category_.json
@@ -1,5 +1,5 @@
{
- "label": "Kotlin",
+ "label": "Swift",
"position": 8,
"collapsible": true,
"collapsed": true
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/swift/basic-serialization.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/swift/basic-serialization.md
new file mode 100644
index 000000000..a51088f67
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/swift/basic-serialization.md
@@ -0,0 +1,114 @@
+---
+title: 基础序列化
+sidebar_position: 1
+id: basic_serialization
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍 Swift 中的对象图序列化和核心 API 用法。
+
+## 对象图序列化
+
+在结构体、类或枚举上使用 `@ForyObject`，注册类型后即可进行序列化和反序列化。
+
+```swift
+import Foundation
+import Fory
+
+@ForyObject
+struct Address: Equatable {
+ var street: String = ""
+ var zip: Int32 = 0
+}
+
+@ForyObject
+struct Person: Equatable {
+ var id: Int64 = 0
+ var name: String = ""
+ var nickname: String? = nil
+ var tags: Set<String> = []
+ var scores: [Int32] = []
+ var addresses: [Address] = []
+ var metadata: [Int8: Int32?] = [:]
+}
+
+let fory = Fory()
+fory.register(Address.self, id: 100)
+fory.register(Person.self, id: 101)
+
+let person = Person(
+ id: 42,
+ name: "Alice",
+ nickname: nil,
+ tags: ["swift", "xlang"],
+ scores: [10, 20, 30],
+ addresses: [Address(street: "Main", zip: 94107)],
+ metadata: [1: 100, 2: nil]
+)
+
+let data = try fory.serialize(person)
+let decoded: Person = try fory.deserialize(data)
+assert(decoded == person)
+```
+
+## 与已有缓冲区配合使用
+
+你可以把序列化结果追加到现有 `Data`，也可以从 `ByteBuffer` 反序列化。
+
+```swift
+var output = Data()
+try fory.serialize(person, to: &output)
+
+let inputBuffer = ByteBuffer(data: output)
+let fromBuffer: Person = try fory.deserialize(from: inputBuffer)
+assert(fromBuffer == person)
+```
+
+## 内置支持的类型
+
+### 基础标量类型
+
+- `Bool`
+- `Int8`、`Int16`、`Int32`、`Int64`、`Int`
+- `UInt8`、`UInt16`、`UInt32`、`UInt64`、`UInt`
+- `Float`、`Double`
+- `String`
+- `Data`
+
+### 日期与时间类型
+
+- `Date`
+- `ForyDate`
+- `ForyTimestamp`
+
+### 集合类型
+
+- `[T]`，其中 `T: Serializer`
+- `Set<T>`，其中 `T: Serializer & Hashable`
+- `[K: V]`，其中 `K: Serializer & Hashable`、`V: Serializer`
+- 可选值变体 `T?`
+
+### 动态类型
+
+- `Any`
+- `AnyObject`
+- `any Serializer`
+- `AnyHashable`
+- `[Any]`
+- `[String: Any]`
+- `[Int32: Any]`
+- `[AnyHashable: Any]`
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/swift/configuration.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/swift/configuration.md
new file mode 100644
index 000000000..108e2785f
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/swift/configuration.md
@@ -0,0 +1,99 @@
+---
+title: 配置
+sidebar_position: 2
+id: configuration
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍 `ForyConfig` 以及推荐的运行时配置。
+
+## ForyConfig
+
+`Fory` 的配置结构如下：
+
+```swift
+public struct ForyConfig {
+ public var xlang: Bool
+ public var trackRef: Bool
+ public var compatible: Bool
+}
+```
+
+默认配置：
+
+```swift
+let fory = Fory() // xlang=true, trackRef=false, compatible=false
+```
+
+## 线程模型
+
+`Fory` 是单线程运行时，会在调用线程上复用一组读写上下文。建议每个线程复用一个实例，不要把同一个实例并发共享给多个线程。
+
+## 配置项
+
+### `xlang`
+
+控制是否启用跨语言协议模式。
+
+- `true`：使用 xlang 编码格式，默认值
+- `false`：使用 Swift 原生模式
+
+```swift
+let fory = Fory(xlang: true)
+```
+
+### `trackRef`
+
+为可跟踪引用的类型启用共享引用和循环引用跟踪。
+
+- `false`：不维护引用表，适合无环或纯值对象图
+- `true`：保留类对象图中的身份关系
+
+```swift
+let fory = Fory(xlang: true, trackRef: true)
+```
+
+### `compatible`
+
+启用跨版本的兼容 Schema 模式。
+
+- `false`：Schema 一致模式，更严格，元信息开销更低
+- `true`：兼容模式，支持字段新增、删除和重排
+
+```swift
+let fory = Fory(xlang: true, trackRef: false, compatible: true)
+```
+
+## 推荐配置
+
+### 本地严格 Schema
+
+```swift
+let fory = Fory(xlang: false, trackRef: false, compatible: false)
+```
+
+### 跨语言服务载荷
+
+```swift
+let fory = Fory(xlang: true, trackRef: false, compatible: true)
+```
+
+### 需要对象身份的图结构载荷
+
+```swift
+let fory = Fory(xlang: true, trackRef: true, compatible: true)
+```
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/swift/cross-language.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/swift/cross-language.md
new file mode 100644
index 000000000..3134324a6
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/swift/cross-language.md
@@ -0,0 +1,97 @@
+---
+title: 跨语言序列化
+sidebar_position: 9
+id: cross_language
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Fory Swift 可以通过 xlang 协议与其他 Fory 运行时交换载荷。
+
+## 推荐的跨语言配置
+
+```swift
+let fory = Fory(xlang: true, trackRef: false, compatible: true)
+```
+
+## 用共享身份注册类型
+
+### 基于 ID 的注册
+
+```swift
+@ForyObject
+struct Order {
+ var id: Int64 = 0
+ var amount: Double = 0
+}
+
+let fory = Fory(xlang: true, compatible: true)
+fory.register(Order.self, id: 100)
+```
+
+### 基于名称的注册
+
+```swift
+try fory.register(Order.self, namespace: "com.example", name: "Order")
+```
+
+## 跨语言规则
+
+- 在不同语言之间保持一致的类型注册映射
+- 对独立演进的 Schema 使用兼容模式
+- 对动态字段 `Any` 和 `any Serializer` 中涉及的用户定义具体类型，也要完成注册
+
+## Swift IDL 工作流
+
+可直接从 Fory IDL / Proto / FBS 输入生成 Swift 模型：
+
+```bash
+foryc schema.fdl --swift_out ./Sources/Generated
+```
+
+生成的 Swift 代码包括：
+
+- 带 `@ForyObject` 与 `@ForyField(id: ...)` 元数据的模型
+- tagged union 枚举
+- 支持传递式导入注册的 `ForyRegistration.register(_:)` 辅助方法
+- 生成类型上的 `toBytes` / `fromBytes` 帮助方法
+
+在跨语言序列化之前，先调用生成的注册逻辑：
+
+```swift
+let fory = Fory(xlang: true, trackRef: true, compatible: true)
+try Addressbook.ForyRegistration.register(fory)
+
+let payload = try fory.serialize(book)
+let decoded: Addressbook.AddressBook = try fory.deserialize(payload)
+```
+
+### 运行 Swift IDL 集成测试
+
+```bash
+cd integration_tests/idl_tests
+./run_swift_tests.sh
+```
+
+这会执行 Swift 端 roundtrip 矩阵测试，以及与 Java 对端的 roundtrip 校验，使用 `IDL_PEER_LANG=swift`。
+
+## 调试跨语言测试
+
+运行 xlang 测试时可以开启调试输出：
+
+```bash
+ENABLE_FORY_DEBUG_OUTPUT=1 FORY_SWIFT_JAVA_CI=1 mvn -T16 test -Dtest=org.apache.fory.xlang.SwiftXlangTest
+```
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/swift/custom-serializers.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/swift/custom-serializers.md
new file mode 100644
index 000000000..e5c47e340
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/swift/custom-serializers.md
@@ -0,0 +1,84 @@
+---
+title: 自定义序列化器
+sidebar_position: 4
+id: custom_serializers
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+对于不适合使用 `@ForyObject` 的类型，或需要特殊编码逻辑的场景，可以手动实现 `Serializer`。
+
+## 适用场景
+
+- 外部类型需要严格的编码兼容性
+- 需要更紧凑或特殊的编码布局
+- 旧载荷迁移路径
+- 性能敏感的热点路径
+
+## 实现 `Serializer`
+
+```swift
+import Foundation
+import Fory
+
+struct UUIDBox: Serializer, Equatable {
+ var value: UUID = UUID(uuidString: "00000000-0000-0000-0000-000000000000")!
+
+ static func foryDefault() -> UUIDBox {
+ UUIDBox()
+ }
+
+ static var staticTypeId: ForyTypeId {
+ .ext
+ }
+
+ func foryWriteData(_ context: WriteContext, hasGenerics: Bool) throws {
+ _ = hasGenerics
+ try value.uuidString.foryWriteData(context, hasGenerics: false)
+ }
+
+ static func foryReadData(_ context: ReadContext) throws -> UUIDBox {
+ let raw = try String.foryReadData(context)
+ guard let uuid = UUID(uuidString: raw) else {
+ throw ForyError.invalidData("invalid UUID string: \\(raw)")
+ }
+ return UUIDBox(value: uuid)
+ }
+}
+```
+
+## 注册并使用
+
+```swift
+let fory = Fory()
+fory.register(UUIDBox.self, id: 300)
+
+let input = UUIDBox(value: UUID())
+let data = try fory.serialize(input)
+let output: UUIDBox = try fory.deserialize(data)
+
+assert(input == output)
+```
+
+## 如何选择 `staticTypeId`
+
+手动实现的自定义类型，需要让 `staticTypeId` 与实际编码形态匹配。
+
+常见选择：
+
+- `.structType`：常规结构化对象
+- `.enumType` / `.typedUnion`：枚举或联合类型
+- `.ext`：扩展或自定义类型
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/swift/field-configuration.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/swift/field-configuration.md
new file mode 100644
index 000000000..bbbb3c730
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/swift/field-configuration.md
@@ -0,0 +1,92 @@
+---
+title: 字段配置
+sidebar_position: 5
+id: field_configuration
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍 Swift 宏层面的字段配置。
+
+## 可用的宏属性
+
+- 作用于 struct/class/enum 的 `@ForyObject`
+- 作用于数值字段的 `@ForyField(encoding: ...)`
+
+## `@ForyField(encoding:)`
+
+用 `@ForyField` 覆盖整数编码策略。
+
+```swift
+@ForyObject
+struct Metrics: Equatable {
+ @ForyField(encoding: .fixed)
+ var u32Fixed: UInt32 = 0
+
+ @ForyField(encoding: .tagged)
+ var u64Tagged: UInt64 = 0
+}
+```
+
+### 支持的组合
+
+| Swift 类型 | 支持的编码值 | 默认编码 |
+| ---------- | ------------ | -------- |
+| `Int32` | `.varint`、`.fixed` | `.varint` |
+| `UInt32` | `.varint`、`.fixed` | `.varint` |
+| `Int64` | `.varint`、`.fixed`、`.tagged` | `.varint` |
+| `UInt64` | `.varint`、`.fixed`、`.tagged` | `.varint` |
+| `Int` | `.varint`、`.fixed`、`.tagged` | `.varint` |
+| `UInt` | `.varint`、`.fixed`、`.tagged` | `.varint` |
+
+编译期会拒绝不受支持的组合，例如给 `Int32` 使用 `.tagged`。
+
+## `@ForyObject` 的要求
+
+### struct 和 class 字段
+
+- 存储属性必须声明显式类型
+- 计算属性会被忽略
+- 静态属性和类属性会被忽略
+
+### 类类型要求
+
+被 `@ForyObject` 标记的类必须提供 `required init()` 以支持默认构造。
+
+```swift
+@ForyObject
+final class Node {
+ var value: Int32 = 0
+ var next: Node? = nil
+
+ required init() {}
+}
+```
+
+## 宏类型中的动态 Any 字段
+
+`@ForyObject` 支持以下动态字段和嵌套容器：
+
+- `Any`、`AnyObject`、`any Serializer`
+- `AnyHashable`
+- `[Any]`
+- `[String: Any]`
+- `[Int32: Any]`
+- `[AnyHashable: Any]`
+
+当前限制：
+
+- `Dictionary<K, Any>` 仅在 `K` 为 `String`、`Int32` 或 `AnyHashable` 时受支持
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/swift/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/swift/index.md
new file mode 100644
index 000000000..d2797bfe4
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/swift/index.md
@@ -0,0 +1,84 @@
+---
+title: Swift 序列化指南
+sidebar_position: 0
+id: serialization_index
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Apache Fory Swift 提供高性能对象图序列化，同时具备强类型安全、基于宏的代码生成、Schema 演进能力以及跨语言兼容性。
+
+## 为什么选择 Fory Swift？
+
+- 面向 Swift 值类型和引用类型的高性能二进制序列化
+- 使用 `@ForyObject` 宏，几乎无需样板代码即可让模型支持序列化
+- 通过 `xlang` 协议与 Java、Rust、Go、Python 等运行时互通
+- 通过兼容模式支持跨版本 Schema 演进
+- 内置支持动态值，例如 `Any`、`AnyObject`、`any Serializer`、`AnyHashable`
+- 支持共享引用和循环引用跟踪，类类型还支持 `weak` 引用场景
+
+## 安装
+
+通过 Apache Fory GitHub 仓库将 Fory Swift 添加到 Swift Package Manager：
+
+```swift
+dependencies: [
+ .package(url: "https://github.com/apache/fory.git", exact: "$version")
+],
+targets: [
+ .target(
+ name: "MyApp",
+ dependencies: [
+ .product(name: "Fory", package: "fory")
+ ]
+ )
+]
+```
+
+## 指南目录
+
+- [配置](configuration.md)
+- [基础序列化](basic-serialization.md)
+- [类型注册](type-registration.md)
+- [自定义序列化器](custom-serializers.md)
+- [字段配置](field-configuration.md)
+- [共享引用与循环引用](references.md)
+- [多态与动态类型](polymorphism.md)
+- [Schema 演进](schema-evolution.md)
+- [跨语言序列化](cross-language.md)
+- [Row Format 状态](row-format.md)
+- [故障排查](troubleshooting.md)
+
+## 快速示例
+
+```swift
+import Fory
+
+@ForyObject
+struct User: Equatable {
+ var name: String = ""
+ var age: Int32 = 0
+}
+
+let fory = Fory()
+fory.register(User.self, id: 1)
+
+let input = User(name: "alice", age: 30)
+let data = try fory.serialize(input)
+let output: User = try fory.deserialize(data)
+
+assert(input == output)
+```
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/swift/polymorphism.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/swift/polymorphism.md
new file mode 100644
index 000000000..b84c0906a
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/swift/polymorphism.md
@@ -0,0 +1,80 @@
+---
+title: 多态与动态类型
+sidebar_position: 7
+id: polymorphism
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Fory Swift 支持对 `Any`、`AnyObject` 和 `any Serializer` 进行动态序列化。
+
+## 顶层动态 API
+
+```swift
+let fory = Fory()
+
+let dynamic: Any = Int32(7)
+let data = try fory.serialize(dynamic)
+let decoded: Any = try fory.deserialize(data)
+```
+
+还提供了等价重载，可用于：
+
+- `AnyObject`
+- `any Serializer`
+- `AnyHashable`
+- `[Any]`
+- `[String: Any]`
+- `[Int32: Any]`
+- `[AnyHashable: Any]`
+
+## `@ForyObject` 类型中的动态字段
+
+```swift
+@ForyObject
+struct DynamicHolder {
+ var value: Any = ForyAnyNullValue()
+ var list: [Any] = []
+ var byName: [String: Any] = [:]
+ var byId: [Int32: Any] = [:]
+ var byDynamicKey: [AnyHashable: Any] = [:]
+}
+```
+
+## 仍然需要注册具体类型
+
+如果动态值中包含用户定义的运行时类型，仍然需要注册这些具体类型。
+
+```swift
+@ForyObject
+struct Address {
+ var street: String = ""
+ var zip: Int32 = 0
+}
+
+let fory = Fory()
+fory.register(Address.self, id: 100)
+```
+
+## 空值语义
+
+- `Any` 的空值表示：`ForyAnyNullValue`
+- `AnyObject` 的空值表示：`NSNull`
+- 可选动态值在反序列化后会映射到相应的空值表示
+
+## 当前限制
+
+- `AnyHashable` 键所包裹的运行时值，必须同时满足 `Hashable` 和 Fory 动态序列化支持
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/swift/references.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/swift/references.md
new file mode 100644
index 000000000..c44287952
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/swift/references.md
@@ -0,0 +1,110 @@
+---
+title: 共享引用与循环引用
+sidebar_position: 6
+id: references
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Swift 中的引用跟踪由 `ForyConfig.trackRef` 控制。
+
+## 启用引用跟踪
+
+```swift
+let fory = Fory(xlang: true, trackRef: true, compatible: false)
+```
+
+启用后，可跟踪引用的类型会保留对象身份和循环结构。
+
+## 共享引用示例
+
+```swift
+import Fory
+
+@ForyObject
+final class Animal {
+ var name: String = ""
+
+ required init() {}
+
+ init(name: String) {
+ self.name = name
+ }
+}
+
+@ForyObject
+final class AnimalPair {
+ var first: Animal? = nil
+ var second: Animal? = nil
+
+ required init() {}
+
+ init(first: Animal? = nil, second: Animal? = nil) {
+ self.first = first
+ self.second = second
+ }
+}
+
+let fory = Fory(xlang: true, trackRef: true)
+fory.register(Animal.self, id: 200)
+fory.register(AnimalPair.self, id: 201)
+
+let shared = Animal(name: "cat")
+let input = AnimalPair(first: shared, second: shared)
+
+let data = try fory.serialize(input)
+let decoded: AnimalPair = try fory.deserialize(data)
+
+assert(decoded.first === decoded.second)
+```
+
+## 循环引用示例：使用 `weak`
+
+`trackRef` 会保留引用图，但不会改变 ARC 的所有权规则。为了避免内存泄漏，循环边至少有一侧应使用 `weak`。
+
+```swift
+import Fory
+
+@ForyObject
+final class Node {
+ var value: Int32 = 0
+ weak var next: Node? = nil
+
+ required init() {}
+
+ init(value: Int32, next: Node? = nil) {
+ self.value = value
+ self.next = next
+ }
+}
+
+let fory = Fory(xlang: true, trackRef: true)
+fory.register(Node.self, id: 300)
+
+let node = Node(value: 7)
+node.next = node
+
+let data = try fory.serialize(node)
+let decoded: Node = try fory.deserialize(data)
+
+assert(decoded.next === decoded)
+```
+
+## 说明
+
+- 值类型，例如 `struct` 和基础值，不具备对象身份语义
+- `trackRef` 控制的是序列化时的引用图身份，而不是 ARC 内存管理
+- 纯值载荷可使用 `trackRef=false` 以减少开销
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/swift/row-format.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/swift/row-format.md
new file mode 100644
index 000000000..741f7b98a
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/swift/row-format.md
@@ -0,0 +1,38 @@
+---
+title: Row Format
+sidebar_position: 10
+id: row_format
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Swift 当前主要聚焦于对象图序列化，也就是 `Fory.serialize` / `Fory.deserialize`。
+
+## 当前状态
+
+- 对象图序列化：已支持
+- 跨语言 xlang 对象协议：已支持
+- Swift Row Format API：暂未公开
+
+## 当前推荐做法
+
+- 应用层载荷优先使用对象序列化
+- 跨服务版本演进使用兼容模式
+- 需要与其他 Fory 运行时互通时启用 xlang 模式
+
+## 后续方向
+
+Swift 将来可以在不改变现有对象序列化 API 的前提下补充 Row Format 支持。在此之前，可视为 Swift 运行时暂不提供 Row Format 功能。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/swift/schema-evolution.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/swift/schema-evolution.md
new file mode 100644
index 000000000..2795ee699
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/swift/schema-evolution.md
@@ -0,0 +1,77 @@
+---
+title: Schema 演进
+sidebar_position: 8
+id: schema_evolution
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Fory 通过兼容模式支持 Schema 演进。
+
+## 启用兼容模式
+
+```swift
+let fory = Fory(xlang: true, trackRef: false, compatible: true)
+```
+
+## 示例：结构体演进
+
+```swift
+import Fory
+
+@ForyObject
+struct PersonV1 {
+ var name: String = ""
+ var age: Int32 = 0
+ var address: String = ""
+}
+
+@ForyObject
+struct PersonV2 {
+ var name: String = ""
+ var age: Int32 = 0
+ var phone: String? = nil // 新增字段
+}
+
+let writer = Fory(xlang: true, compatible: true)
+writer.register(PersonV1.self, id: 1)
+
+let reader = Fory(xlang: true, compatible: true)
+reader.register(PersonV2.self, id: 1)
+
+let v1 = PersonV1(name: "alice", age: 30, address: "main st")
+let bytes = try writer.serialize(v1)
+let v2: PersonV2 = try reader.deserialize(bytes)
+
+assert(v2.name == "alice")
+assert(v2.age == 30)
+assert(v2.phone == nil)
+```
+
+## 兼容模式下安全的变更
+
+- 新增字段
+- 删除旧字段
+- 重排字段顺序
+
+## 不安全的变更
+
+- 任意修改既有字段的类型，例如从 `Int32` 改成 `String`
+- 对端之间使用不一致的注册映射
+
+## Schema 一致模式的行为
+
+当 `compatible=false` 时，Fory 会校验 schema hash，并在不匹配时快速失败。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/swift/troubleshooting.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/swift/troubleshooting.md
new file mode 100644
index 000000000..febed0a27
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/swift/troubleshooting.md
@@ -0,0 +1,92 @@
+---
+title: 故障排查
+sidebar_position: 11
+id: troubleshooting
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍 Swift 中常见的问题及调试方法。
+
+## 常见运行时错误
+
+### `Type not registered: ...`
+
+原因：当前 `Fory` 实例没有注册用户类型。
+
+修复方式：
+
+```swift
+fory.register(MyType.self, id: 100)
+```
+
+### `Type mismatch: expected ..., got ...`
+
+原因：对端之间的注册映射或字段类型信息不一致。
+
+修复方式：
+
+- 确保两端使用相同的 type ID 或名称映射
+- 检查字段类型是否兼容
+
+### `Invalid data: xlang bitmap mismatch`
+
+原因：序列化端和反序列化端使用了不同的 `xlang` 配置。
+
+修复方式：确保双方使用相同的 `xlang` 模式。
+
+### `Invalid data: class version hash mismatch`
+
+原因：在 `compatible=false` 下发生了 schema 变更。
+
+修复方式：
+
+- 为需要演进的 schema 启用兼容模式
+- 或保持严格的 schema 一致性
+
+## 常见宏阶段错误
+
+### `@ForyObject requires explicit types for stored properties`
+
+为所有存储属性补充显式类型声明。
+
+### `@ForyObject enum associated values cannot have default values`
+
+移除枚举关联值上的默认值。
+
+### `Set<...> with Any elements is not supported by @ForyObject yet`
+
+改用 `[Any]` 或明确元素类型的集合。
+
+### `Dictionary<..., ...> with Any values is only supported for String, Int32, or AnyHashable keys`
+
+把 key 类型改为 `String`、`Int32` 或 `AnyHashable`，或者避免在 map value 中使用动态 `Any`。
+
+## 调试命令
+
+运行 Swift 测试：
+
+```bash
+cd swift
+ENABLE_FORY_DEBUG_OUTPUT=1 swift test
+```
+
+运行由 Java 驱动的 Swift xlang 测试：
+
+```bash
+cd java/fory-core
+ENABLE_FORY_DEBUG_OUTPUT=1 FORY_SWIFT_JAVA_CI=1 mvn -T16 test -Dtest=org.apache.fory.xlang.SwiftXlangTest
+```
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/swift/type-registration.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/swift/type-registration.md
new file mode 100644
index 000000000..5fccad9fa
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/swift/type-registration.md
@@ -0,0 +1,76 @@
+---
+title: 类型注册
+sidebar_position: 3
+id: type_registration
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍用户定义类型的注册 API。
+
+## 为什么必须注册
+
+用户类型，例如 `struct`、`class`、enum/union 和 ext 类型，在序列化和反序列化前必须先注册。
+
+如果缺少注册，反序列化会失败，并抛出：
+
+- `Type not registered: ...`
+
+## 按数值 ID 注册
+
+请为序列化端和反序列化端使用同一个稳定 ID。
+
+```swift
+@ForyObject
+struct User {
+ var name: String = ""
+ var age: Int32 = 0
+}
+
+let fory = Fory()
+fory.register(User.self, id: 1)
+```
+
+## 按名称注册
+
+### 使用全限定名
+
+```swift
+try fory.register(User.self, name: "com.example.User")
+```
+
+`name` 会按 `.` 拆分：
+
+- namespace: `com.example`
+- type name: `User`
+
+### 显式指定命名空间和类型名
+
+```swift
+try fory.register(User.self, namespace: "com.example", name: "User")
+```
+
+## 一致性规则
+
+在不同对端之间保持注册映射一致：
+
+- ID 模式：同一个逻辑类型在所有对端都使用相同数值 ID
+- 名称模式：同一个逻辑类型在所有对端都使用相同 namespace 和 type name
+- 不要对同一逻辑类型在不同服务里混用 ID 映射和名称映射
+
+## 动态类型与注册
+
+当你序列化 `Any`、`AnyObject`、`any Serializer` 这类动态值，且其中包含用户定义类型时，具体运行时类型仍然需要提前注册。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/xlang/_category_.json b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/xlang/_category_.json
index bd191529c..ab2d183de 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/xlang/_category_.json
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/xlang/_category_.json
@@ -1,6 +1,6 @@
{
"label": "Cross Language",
- "position": 9,
+ "position": 12,
"collapsible": true,
"collapsed": true
}
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/specification/java_serialization_spec.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/specification/java_serialization_spec.md
index 959eeb2b6..8bf9b6ec1 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/specification/java_serialization_spec.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/specification/java_serialization_spec.md
@@ -299,7 +299,9 @@ namespace、type name、field name 复用 xlang 的 meta string 编码。
### Enum
- `serializeEnumByName=true`：写 enum 名称（meta string）
-- 否则：写 ordinal（varuint32 small7）
+- 否则：写 enum tag（`varuint32 small7`）
+ - 默认情况下，tag 就是声明顺序对应的 ordinal。
+ - 如果 enum 配置了 `@ForyEnumId`，则写入其配置的稳定 ID。Java 支持恰好标注一个 ID 字段、一个无参 ID getter，或为每个 enum 常量显式指定 tag 值。
### Binary (byte[])
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/specification/xlang_implementation_guide.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/specification/xlang_implementation_guide.md
index 9e1e2dea3..641a6ebed 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/specification/xlang_implementation_guide.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/specification/xlang_implementation_guide.md
@@ -19,233 +19,402 @@ license: |
limitations under the License.
---
-## 实现建议
-
-### 如何减少内存读写开销
-
-- 尽量把多次 byte 写入合并为 int/long 写入，降低内存 IO 与边界检查成本。
-- 读取时可一次读取 int/long，再拆分字节，减少内存访问次数。
-- 尽可能把 flag 与 length 合并到同一个 varint/long，减少字节数与 IO。
-- 在分支数量可控的前提下，分支开销通常小于内存 IO 开销。
-
-### 静态语言（无运行时代码生成）如何做高性能反序列化
-
-在类型演进场景，序列化数据会携带 type meta。反序列化端会比较“数据内 meta”与“本地类 meta”，根据差异执行字段映射。
-
-对 Java/Javascript/Python，可在运行时根据 diff 动态生成并加载反序列化逻辑，从而接近 schema-consistent 模式性能。
-
-对 C++/Rust，通常无法在运行时动态生成 serializer，只能在编译期元编程生成。此时无法提前知道对端 schema，
-因此需要在运行时根据字段元信息逐个判断“赋值或跳过”。
-
-可行优化：将字符串字段匹配尽量提前转换为 `field id`，再在反序列化路径用 `switch` 处理，利用连续 case 的跳转优化。
-
-思路：
-
-- 假设本地类型字段数为 `n`，对端字段数为 `n1`
-- 编译期先为本地排序字段分配连续 `field id`（从 0 开始）
-- 运行时比较对端 type meta：同名字段复用本地 id，不同字段分配从 `n` 开始的新 id，并缓存映射
-- 反序列化遍历对端字段时对 `field_id` 做 `switch`，命中则赋值，未命中则跳过
-
-示例：A 进程持有 `Foo1`，B 进程持有演进后的 `Foo2`：
-
-```c++
-// class Foo with version 1
-class Foo1 {
- int32_t v1; // id 0
- std::string v2; // id 1
-};
-// class Foo with version 2
-class Foo2 {
- // id 0, but will have id 2 in process A
- bool v0;
- // id 1, but will have id 0 in process A
- int32_t v1;
- // id 2, but will have id 3 in process A
- int64_t long_value;
- // id 3, but will have id 1 in process A
- std::string v2;
- // id 4, but will have id 4 in process A
- std::vector<std::string> list;
-};
-```
+## 概览
-A 收到 B 发送的 `Foo2` 数据后，可按 `field_id` 快速分发：
-
-```c++
-Foo1 foo1 = ...;
-const std::vector<fory::FieldInfo> &field_infos = type_meta.field_infos;
-for (const auto &field_info : field_infos) {
- switch (field_info.field_id) {
- case 0:
- foo1.v1 = buffer.read_varint32();
- break;
- case 1:
- foo1.v2 = fory.read_string();
- break;
- default:
- fory.skip_data(field_info);
- }
-}
-```
+本指南描述当前 xlang 运行时的所有权模型。该模型由参考 Java
+运行时采用，并由 Dart 运行时重写版本镜像实现。
+
+编码格式由 [Xlang Serialization Spec](xlang_serialization_spec.md)
+定义。本文关注的是服务边界、操作流程与内部所有权。新运行时不必使用相同的类名，
+但应保持相同的控制流：
+
+- 根级操作留在运行时门面上
+- 嵌套载荷处理留在显式的读写上下文中
+- 类型元信息留在类型解析层
+- serializer 只关注载荷本身
+
+如果本指南与编码格式规范冲突，应以
+`docs/specification/xlang_serialization_spec.md` 为准；如果与某个语言运行时的实现细节冲突，则以该语言当前运行时代码为准。
+
+## 事实来源
+
+按以下顺序使用这些来源：
+
+1. `docs/specification/xlang_serialization_spec.md`
+2. 该语言当前的运行时实现
+3. `integration_tests/` 下的跨语言测试
+
+对于 Dart，运行时形态主要围绕以下组件展开：
+
+- `Fory`
+- `WriteContext`
+- `ReadContext`
+- `RefWriter`
+- `RefReader`
+- `TypeResolver`
+- `StructCodec`
+
+## 运行时所有权模型
+
+### `Fory` 是根操作门面
+
+`Fory` 持有一个运行时实例可复用的运行时服务。
+
+在 Dart 中，`Fory` 恰好持有四个运行时成员：
+
+- `Buffer`
+- `WriteContext`
+- `ReadContext`
+- `TypeResolver`
+
+在 Java 中，`Fory` 还持有 `JITContext`、`CopyContext`
+等运行时本地服务，但所有权规则相同：`Fory`
+是根级门面，而不是嵌套 serializer 执行工作的地方。
+
+`Fory` 负责：
+
+- 为根级操作准备共享 buffer
+- 写入和读取根级 xlang 头部位图
+- 将嵌套值编码委托给 `WriteContext`
+- 将嵌套值解码委托给 `ReadContext`
+- 通过 `TypeResolver` 持有注册能力
+- 在顶层 `finally` 中重置操作级上下文状态
+
+嵌套 serializer 不得回调根级 `serialize(...)` 或 `deserialize(...)`
+入口。
+
+### `WriteContext` 和 `ReadContext` 持有操作级状态
+
+`WriteContext` 与 `ReadContext`
+由 `Fory` 为一次根级操作准备，并在复用前由 `Fory`
+在 `finally` 块中重置。
+
+`prepare(...)` 应只绑定当前 buffer 和根级操作输入。`reset()`
+应清理操作级可变状态。
+
+这些操作级状态包括：
+
+- 当前 buffer
+- 当前活动的 `RefWriter` 或 `RefReader`
+- meta string 状态
+- 共享 TypeDef 状态
+- 以对象 identity 为键的操作级临时状态
+- compatible struct slot 状态
+- 逻辑对象图深度
+
+无论是生成的还是手写的 serializer，都应把这些 context
+视为操作级服务的唯一来源。serializer
+不得把环境运行时状态保存在 thread local、全局变量或 serializer
+实例字段中。
+
+### `WriteContext`
+
+`WriteContext` 持有写侧的全部操作级状态：
+
+- 当前 `Buffer`
+- `RefWriter`
+- `MetaStringWriter`
+- 共享 TypeDef 写入状态
+- 根级 `trackRef` 模式
+- 递归深度与限制
+- compatible 写入使用的本地 struct slot 状态
+
+它暴露一组一次性基础类型 helper，例如：
+
+- `writeBool`
+- `writeInt32`
+- `writeVarUint32`
+
+这些 helper 只是便捷方法。若 serializer
+需要执行大量重复的基础类型 IO，应缓存 `final buffer = context.buffer;`
+并直接调用 buffer 方法。
+
+### `ReadContext`
+
+`ReadContext` 持有读侧的全部操作级状态：
+
+- 当前 `Buffer`
+- `RefReader`
+- `MetaStringReader`
+- 共享 TypeDef 读取状态
+- 递归深度与限制
+- compatible 读取使用的本地 struct slot 状态
+
+它暴露对应的一次性基础类型 helper，例如：
+
+- `readBool`
+- `readInt32`
+- `readVarUint32`
+
+生成的 struct serializer 在构造目标实例后，应立即调用
+`context.reference(value)`，这样回引用才能解析到该对象。
+
+## 引用跟踪
+
+引用处理被拆分到两个显式服务之后：
+
+- `RefWriter` 写入 null、ref 与 new-value 标记，并按对象 identity
+ 记住已经写出的对象。
+- `RefReader` 解码这些标记，预留读取侧引用 ID，并解析已经实例化过的对象。
+
+xlang 的引用标记如下：
+
+- `NULL_FLAG (-3)`
+- `REF_FLAG (-2)`
+- `NOT_NULL_VALUE_FLAG (-1)`
+- `REF_VALUE_FLAG (0)`
+
+关键行为：
-## 新语言实现检查清单
+- 基础值永远不使用引用跟踪
+- 生成的 struct 内部由字段元信息控制引用行为
+- 根级 `trackRef` 只用于顶层对象图以及没有字段元信息的容器根对象
+- 若 serializer 在所有嵌套读取完成之前就分配了对象，则必须通过
+ `context.reference(...)` 尽早绑定该对象
-本节给出在新语言中落地 Fory xlang 序列化的阶段性清单。
-
-### 阶段 1：核心基础设施
+## 类型解析
-1. **Buffer 实现**
- - [ ] 提供带读写游标的字节缓冲区
- - [ ] 所有多字节读写统一使用 little-endian
- - [ ] 实现 `write_int8/int16/int32/int64`
- - [ ] 实现 `write_float32/write_float64`
- - [ ] 实现对应 `read_*` 方法
- - [ ] 实现缓冲区扩容策略（如倍增）
+`TypeResolver` 持有：
-2. **Varint 编码**
- - [ ] `write_varuint32/read_varuint32`
- - [ ] `write_varint32/read_varint32`（含 ZigZag）
- - [ ] `write_varuint64/read_varuint64`
- - [ ] `write_varint64/read_varint64`（含 ZigZag）
- - [ ] `write_varuint36_small/read_varuint36_small`（字符串头使用）
- - [ ] 可选：实现 int64 Hybrid 编码（TAGGED_INT64/TAGGED_UINT64）
+- 内建类型解析
+- 按数值 ID 或 `namespace + typeName` 注册
+- serializer 查找
+- struct 元数据查找
+- 类型元信息编码与解码
+- 包名、类型名、字段名的规范化编码 meta string
+- 用于 named 类型解析的已编码名称查找
+- struct、compatible struct、enum、ext、union 等形式的编码类型判定
-3. **头部处理**
- - [ ] 读写 bitmap flags（null、xlang、oob）
+在 Java xlang 模式中，具体实现是 `XtypeResolver`。在 Dart 中，相同的所有权仍由内部 `TypeResolver` 持有。
-### 阶段 2：基础类型序列化
+serializer 自身不负责解析类元数据。它们通过当前 context
+请求读写嵌套值，再由 context 将类型相关工作委托给 `TypeResolver`。
-4. **基础类型**
- - [ ] bool（1 字节：0/1）
- - [ ] int8/int16/int32/int64（little-endian）
- - [ ] float32/float64（IEEE 754，little-endian）
+## 根帧职责
-5. **字符串序列化**
- - [ ] 实现字符串头：`(byte_length << 2) | encoding`
- - [ ] 支持 UTF-8（xlang 必需）
- - [ ] 可选支持 LATIN1 与 UTF-16
+每个根载荷都以一个 1-byte 位图开头，该位图由 `Fory`
+自身写入和读取，而不是由 serializer 负责。
-6. **时间类型**
- - [ ] Duration（seconds + nanoseconds）
- - [ ] Timestamp（epoch 以来 seconds + nanoseconds）
- - [ ] Date（epoch 以来天数）
+当前 xlang 根级位定义如下：
-7. **引用跟踪**
- - [ ] 写侧对象跟踪（object -> ref_id）
- - [ ] 读侧对象跟踪（ref_id -> object）
- - [ ] 支持 4 种引用标记：NULL(-3)、REF(-2)、NOT_NULL(-1)、REF_VALUE(0)
- - [ ] 支持按类型或全局关闭引用跟踪
+| Bit | Meaning |
+| --- | -------------------------- |
+| `0` | null root payload |
+| `1` | xlang payload |
+| `2` | out-of-band buffers in use |
-### 阶段 3：集合类型
+应将根级位图与逐对象引用标记区分开：
-8. **List/Array**
- - [ ] 长度写为 varuint32
- - [ ] 写 elements header byte
- - [ ] 处理同构/异构元素
- - [ ] 处理 null 元素
+- 根级位图描述整个载荷
+- 引用标记一次只描述一个嵌套值
-9. **Map**
- - [ ] 总大小写为 varuint32
- - [ ] 实现分块格式（每块最多 255 对）
- - [ ] 每块写 KV header
- - [ ] 处理 key/value 类型变化
+## 序列化流程
-10. **Set**
- - [ ] 与 List 复用同一套实现
+### 根级写路径
-### 阶段 4：Meta String 编码
+当前根级写流程如下：
-meta string 用于 enum/struct 的字段名、类型名、命名空间编码。
+1. `Fory.serialize(...)` 或 `serializeTo(...)` 准备目标 buffer。
+2. `Fory` 调用 `writeContext.prepare(...)`。
+3. `Fory` 写入根级位图。
+4. `Fory` 将根对象委托给 `WriteContext`。
+5. `writeContext.reset()` 在 `finally` 中执行。
-11. **Meta String 压缩**
- - [ ] LOWER_SPECIAL（5 bits/char）
- - [ ] LOWER_UPPER_DIGIT_SPECIAL（6 bits/char）
- - [ ] FIRST_TO_LOWER_SPECIAL
- - [ ] ALL_TO_LOWER_SPECIAL
- - [ ] 编码选择算法
- - [ ] meta string 去重
+对于非空根值，`WriteContext.writeRootValue(...)` 会执行：
-### 阶段 5：Enum 序列化
+1. 引用/null 包装
+2. 类型元信息写入
+3. 载荷写入
-12. **Enum**
- - [ ] ordinal 写为 varuint32
- - [ ] 支持命名 enum（namespace + typename）
+载荷 serializer 只负责自身类型的载荷。它们不写根级位图，也不负责注册或类型头编码。
-### 阶段 6：Struct 序列化
+### 嵌套写入使用 `WriteContext`
-13. **类型注册**
- - [ ] 支持按数值 ID 注册
- - [ ] 支持按 namespace + typename 注册
- - [ ] 维护 type -> serializer 映射
- - [ ] 生成 type ID：先写 internal type ID，再写 `user_type_id(varuint32)`
+重要规则：
-14. **字段排序**
- - [ ] 实现规范定义的分组与排序（primitive/boxed/builtin、collections/maps、other）
- - [ ] 组内使用稳定比较器（type ID + name）
- - [ ] 指纹字段标识使用 tag ID 或 snake_case 字段名
+- 当嵌套 serializer 需要引用处理或类型元信息时，必须使用
+ `WriteContext` 的 helper，例如 `writeRef(...)`、`writeNonRef(...)`
+ 以及容器 helper
+- 重复的基础类型写入应直接走 buffer
+- 嵌套 serializer 的流程应保持直线式，不要仅为了清理操作级状态而添加内部
+ `try/finally`
+- 顶层 `Fory.serialize(...)` 持有操作重置所需的 `finally`
-15. **Schema Consistent 模式**
- - [ ] 开启类版本校验时，按字段标识计算 schema hash
- - [ ] 在字段前写 4-byte schema hash
- - [ ] 按 Fory 字段顺序序列化
+## 反序列化流程
-16. **Compatible/Meta Share 模式**
- - [ ] 实现共享 TypeDef 流（新 TypeDef 内联，已存在用索引）
- - [ ] 按字段名或 tag ID 做映射，未知字段跳过
- - [ ] 按 TypeDef 元信息应用 nullable/ref 规则
-
-### 阶段 7：其他类型
-
-17. **Binary/Array**
-
-- [ ] 基础类型数组支持直接 buffer copy
-- [ ] 多维数组按嵌套 list 表达（不做 tensor 专用编码）
+### 根级读路径
-### 测试策略
+当前根级读流程与写流程对称：
-18. **跨语言兼容测试**
- - [ ] 新语言写 -> Java/Python 读
- - [ ] Java/Python 写 -> 新语言读
- - [ ] 覆盖所有基础类型
- - [ ] 覆盖不同字符串编码
- - [ ] 覆盖集合（空、单元素、多元素）
- - [ ] 覆盖不同 key/value map
- - [ ] 覆盖嵌套 struct
- - [ ] 覆盖循环引用（若支持）
+1. `Fory.deserialize(...)` 或 `deserializeFrom(...)` 读取根级位图。
+2. 若根值为 null，立即返回。
+3. `Fory` 校验 xlang 模式与其他根帧要求。
+4. `Fory` 调用 `readContext.prepare(...)`。
+5. `Fory` 委托给 `ReadContext`。
+6. `readContext.reset()` 在 `finally` 中执行。
-## 各语言实现备注
+### `ReadContext` 持有引用预留与载荷实例化
-### Java
+`ReadContext.readRef()` 执行标准的 xlang 读取序列：
-- 通过运行时代码生成（JIT）获得高性能
-- 支持完整引用跟踪模式
-- 利用 String coder 做编码选择
-- 可通过 `ThreadSafeFory` 提供线程安全封装
+1. 消费下一个引用标记
+2. 在适当情况下立即返回 `null` 或回引用
+3. 为新的可引用值预留新的读取侧引用 ID
+4. 读取类型元信息
+5. 读取载荷
+6. 将预留的读取侧引用 ID 绑定到完成构造的对象
-### Python
+基础类型和类字符串的热点路径应直接从 buffer 读取；复杂载荷则委托给解析出的 serializer。
-- 提供纯 Python（调试）与 Cython（性能）两种模式
-- 使用 `id(obj)` 做引用跟踪
-- xlang 模式支持 LATIN1/UTF-16/UTF-8
-- 通过代码生成增强 `dataclass` 支持
+### 嵌套读取使用 `ReadContext`
-### C++
+重要规则：
-- 通过宏（`FORY_STRUCT`）做编译期反射
-- 模板元编程进行类型分发与 serializer 选择
-- 使用 `std::shared_ptr` 支持引用跟踪
-- 编译期字段排序
-- 不依赖运行时代码生成
+- 若 serializer 会提前分配结果对象，则必须在读取可能回指它的嵌套子对象之前调用
+ `context.reference(obj)`
+- 嵌套 serializer 的流程应保持直线式，不要添加内部 `try/finally`
+ 来恢复操作级状态
+- 顶层 `Fory.deserialize(...)` 持有操作重置所需的 `finally`
-### Rust
+## 深度跟踪
-- 使用 derive 宏自动生成序列化代码（`#[derive(ForyObject)]`）
-- 使用 `Rc<T>`/`Arc<T>` 做引用跟踪
-- 通过线程本地上下文缓存优化性能
-- 编译期字段排序
+`WriteContext` 与 `ReadContext` 会显式跟踪逻辑对象深度。`increaseDepth()`
+负责执行 `Config.maxDepth` 限制。
-### Go
+深度应显式保存在 context 上，而不是只依赖原生调用栈。同时，深度清理也不应依赖散落在 serializer
+代码中的嵌套 `try/finally`。顶层 context reset
+必须能够在失败后恢复操作级状态。
-- 支持反射模式与代码生成模式
-- 通过 struct tag 提供字段元信息
-- 通过接口类型支持多态语义
+## Struct 兼容性
+
+struct 专属的 schema/version 包装与 compatible-field staging
+应归属在 struct serializer 层，而不是 `Fory` 上，也不是公共 serializer API
+上。
+
+在 Dart 中，这个内部所有者是 `StructCodec`。
+
+`StructCodec` 负责：
+
+- 在兼容模式关闭且版本校验开启时写入 schema hash 包装
+- 在兼容模式开启时执行 compatible struct 字段重映射
+- 缓存 compatible 写布局与读布局
+- 为生成的 serializer 提供 compatible 读写 slot 状态
+- 在读取成功后记住远端 struct 元数据
+
+当 `Config.compatible` 启用且 struct 被标记为 evolving 时：
+
+- 编码类型使用 compatible struct 形式
+- 运行时写入共享 TypeDef 元数据
+- 读取侧按标识符映射输入字段，并跳过未知字段
+
+当 `compatible` 关闭而 `checkStructVersion` 启用时：
+
+- 运行时会在 struct 载荷前写入 schema hash
+- 读取侧会在读字段之前检查该 hash
+
+## Meta string 与共享类型元信息
+
+xlang 类型元信息由两类显式状态支撑：
+
+- `MetaStringWriter` 和 `MetaStringReader`
+ 负责去重与解码命名空间和类型名字串
+- 共享 TypeDef 的读写状态负责跟踪已声明的 compatible struct 元数据
+
+所有权规则：
+
+- 规范化后的编码名称由 `TypeResolver` 持有
+- 每次操作的动态 meta string ID 由 `MetaStringWriter` 和
+ `MetaStringReader` 持有
+- 共享类型定义表属于操作级 context 状态
+
+## Xlang 模式下的 enum
+
+在 xlang 模式中，enum 按数值 tag 序列化，而不是按名称序列化。
+
+在 Java 中：
+
+- 默认 tag 是声明顺序对应的 ordinal
+- `@ForyEnumId` 可将其覆盖为稳定的显式 tag
+- `serializeEnumByName(true)` 影响的是 Java native 模式，而不是 xlang 模式
+
+即便配置接口或注解形式不同，其他运行时也应保持相同的编码规则。
+
+## Out-Of-Band Buffer Object
+
+buffer object 的处理也遵循同样的拆分原则：
+
+- 一个根级 bit 声明当前是否使用 out-of-band buffer
+- 嵌套 buffer object 载荷仍按单个值决定是 in-band 还是 out-of-band
+- serializer 应使用读写 context helper，而不是绕过运行时
+
+## 代码生成
+
+Dart 的常规集成路径如下：
+
+1. 使用 `@ForyStruct` 标注 struct
+2. 使用 `@ForyField` 标注字段覆盖
+3. 运行 `build_runner`
+4. 在源码库中私有绑定生成的元数据，并通过 `Fory.register(...)`
+ 注册生成的类型
+
+生成代码应产出：
+
+- 私有 serializer 类
+- 私有元数据常量
+- 每个被标注库对应的私有生成安装 helper
+- 保持 serializer factory 私有的生成绑定安装逻辑
+
+生成代码不应创建公共全局 registry，也不应创建第二套公共 API
+族。
+
+## 目录布局
+
+在每个 Dart package 的 `lib/` 树下，只允许一层嵌套源码目录。
+
+允许：
+
+- `lib/fory.dart`
+- `lib/src/<file>.dart`
+- `lib/src/<area>/<file>.dart`
+
+不允许：
+
+- `lib/src/<area>/<subarea>/<file>.dart`
+
+## 新运行时的 serializer 设计规则
+
+任何新的 xlang 运行时都应遵循以下规则，即便其表面 API
+有所不同：
+
+1. 根级操作保留在运行时门面上，嵌套载荷处理放在显式读写 context 中。
+2. 引用跟踪放在专门的读侧/写侧服务之后，使禁用引用跟踪的路径保持低成本。
+3. 让 serializer 只负责载荷。类型元信息、注册与根帧包装属于运行时与类型解析层。
+4. 显式跟踪操作级状态。不要依赖隐式 thread-local 运行时状态。
+5. 在实例化新对象之前预留读取侧引用 ID，并在嵌套子对象可能回指它时尽早绑定部分构造对象。
+6. 将操作准备与操作清理分离。`prepare(...)` 负责绑定当前操作输入，`reset()`
+ 负责清理操作级状态。
+7. 保持根级位图、逐对象引用标记、类型头与载荷字节之间的边界清晰。
+8. 内部命名应停留在序列化领域。优先使用 `codec`、`binding`、`layout`、
+ `slots` 这类词，避免使用 `session` 这类 RPC 风格术语，或 `plan`
+ 这类含义模糊的控制流词汇。
+9. 每次 xlang 协议或所有权模型变更后，都要运行跨语言测试矩阵，并同时更新本指南与
+ [Xlang Serialization Spec](xlang_serialization_spec.md)。
+
+## 验证
+
+对于 Dart 运行时改动，至少运行：
+
+```bash
+cd dart
+dart run build_runner build --delete-conflicting-outputs
+dart analyze
+dart test
+```
+
+若要覆盖生成代码的使用方，也应运行：
+
+```bash
+cd dart/packages/fory-test
+dart run build_runner build --delete-conflicting-outputs
+dart test
+```
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/specification/xlang_serialization_spec.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/specification/xlang_serialization_spec.md
index 1a1800bbc..4e2bfdcc7 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/specification/xlang_serialization_spec.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/specification/xlang_serialization_spec.md
@@ -451,7 +451,7 @@ header 位描述 key/value 的：
### enum
-enum 可按 ordinal 或名称编码（取决于配置与目标兼容要求）。
+enum 以无符号 varint tag 进行序列化。对于普通 enum，这个 tag 通常就是声明顺序对应的 ordinal。某些实现或代码生成出的 enum 形式也可能改用显式的稳定 enum value 或 variant ID。若编码依赖声明顺序，重新排列 enum 值会导致反序列化结果不再符合用户预期。在这种情况下，用户应优先采用基于显式稳定 ID 的编码，或注册自定义 enum serializer，在禁用 unique hash 的前提下写入稳定的字符串表示。
### timestamp
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/specification/xlang_type_mapping.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/specification/xlang_type_mapping.md
index 59b117183..21d3229c5 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/specification/xlang_type_mapping.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/specification/xlang_type_mapping.md
@@ -69,7 +69,7 @@ license: |
| var_uint64 | 14 | long/Long | int/pyfory.uint64 | Type.varUInt64() | uint64_t | uint64 | u64 |
| tagged_uint64 | 15 | long/Long | int/pyfory.tagged_uint64 | Type.taggedUInt64() | uint64_t | uint64 | u64 |
| float8 | 16 | / | / | / | / | / | / |
-| float16 | 17 | float/Float | float/pyfory.float16 | Type.float16() | fory::float16_t | fory.float16 | fory::f16 |
+| float16 | 17 | Float16 | float/pyfory.float16 | Type.float16() | fory::float16_t | fory.float16 | fory::f16 |
| bfloat16 | 18 | / | / | / | / | / | / |
| float32 | 19 | float/Float | float/pyfory.float32 | Type.float32() | float | float32 | f32 |
| float64 | 20 | double/Double | float/pyfory.float64 | Type.float64() | double | float64 | f64 |
@@ -103,7 +103,7 @@ license: |
| uint32_array | 50 | long[] | ndarray(uint32) | / | `uint32_t[n]/vector<T>` | `[n]uint32/[]T` | `Vec<u32>` |
| uint64_array | 51 | long[] | ndarray(uint64) | / | `uint64_t[n]/vector<T>` | `[n]uint64/[]T` | `Vec<u64>` |
| float8_array | 52 | / | / | / | / | / | / |
-| float16_array | 53 | float[] | ndarray(float16) | / | `fory::float16_t[n]/vector<T>` | `[n]float16/[]T` | `Vec<fory::f16>` |
+| float16_array | 53 | Float16List | ndarray(float16) | / | `fory::float16_t[n]/vector<T>` | `[n]float16/[]T` | `Vec<fory::f16>` |
| bfloat16_array | 54 | / | / | / | / | / | / |
| float32_array | 55 | float[] | ndarray(float32) | / | `float[n]/vector<T>` | `[n]float32/[]T` | `Vec<f32>` |
| float64_array | 56 | double[] | ndarray(float64) | / | `double[n]/vector<T>` | `[n]float64/[]T` | `Vec<f64>` |
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/usage.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/usage.md
index f1a27c31d..4799bf809 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/usage.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/usage.md
@@ -172,7 +172,7 @@ let result: Person = try fory.deserialize(data)
print("\(result.name) \(result.age)")
```
-关于多态、Schema 演进和常见问题排查，请参见 [Swift 指南](../guide/swift/index.md)。
+关于多态、Schema 演进和常见问题排查，请参见 [Swift 指南](../guide/swift/)。
### Rust 序列化
@@ -496,7 +496,7 @@ print("\(result.name) \(result.age)")
- [跨语言序列化指南](../guide/xlang/index.md)
- [Go 指南 - 跨语言](../guide/go/cross-language.md)
- [C# 指南 - 跨语言](../guide/csharp/cross-language.md)
-- [Swift 指南 - 跨语言](../guide/swift/cross-language.md)
+- [Swift 指南 - 跨语言](../guide/swift/cross_language)
## Row Format 编码
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/cpp/README.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/cpp/README.md
index a2be4452e..1dc362e9d 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/cpp/README.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/cpp/README.md
@@ -1,60 +1,104 @@
# C++ 基准性能报告
-_生成时间：2025-12-15 23:03:06_
+_生成于 2026-02-19 10:20:08_
## 如何生成本报告
```bash
-cd benchmarks/cpp_benchmark/build
+cd benchmarks/cpp/build
./fory_benchmark --benchmark_format=json --benchmark_out=benchmark_results.json
cd ..
python benchmark_report.py --json-file build/benchmark_results.json --output-dir report
```
-## 硬件与系统信息
+## 硬件与操作系统信息
-| Key | Value |
+| 键 | 值 |
| -------------------------- | ------------------------- |
-| OS | Darwin 24.6.0 |
-| Machine | arm64 |
-| Processor | arm |
-| CPU Cores (Physical) | 12 |
-| CPU Cores (Logical) | 12 |
-| Total RAM (GB) | 48.0 |
-| Benchmark Date | 2025-12-15T23:02:49+08:00 |
-| CPU Cores (from benchmark) | 12 |
+| 操作系统 | Darwin 24.6.0 |
+| 机器架构 | arm64 |
+| 处理器 | arm |
+| CPU 核心数（物理） | 12 |
+| CPU 核心数（逻辑） | 12 |
+| 总内存（GB） | 48.0 |
+| 基准日期 | 2026-02-19T10:19:31+08:00 |
+| CPU 核心数（基准采集） | 12 |
## 基准图表
+下列各类图表均展示吞吐量（ops/sec）。
+
+### 总吞吐量
+
+### Mediacontent
+
+
+
+### Mediacontentlist
+
+
+
+### Sample
+
+
+
+### Samplelist
+
+
+
+### Struct
+
+
+
+### Structlist
+
+
+
## 基准结果
-### 耗时结果（纳秒）
+### 延迟结果（纳秒）
-| Datatype | Operation | Fory (ns) | Protobuf (ns) | Faster |
-| ------------ | ----------- | --------- | ------------- | ----------- |
-| Mediacontent | Serialize | 443.5 | 1982.5 | Fory (4.5x) |
-| Mediacontent | Deserialize | 1349.0 | 2525.2 | Fory (1.9x) |
-| Sample | Serialize | 235.4 | 309.7 | Fory (1.3x) |
-| Sample | Deserialize | 1068.7 | 1397.0 | Fory (1.3x) |
-| Struct | Serialize | 109.4 | 170.0 | Fory (1.6x) |
-| Struct | Deserialize | 129.1 | 161.2 | Fory (1.2x) |
+| 数据类型 | 操作 | fory (ns) | protobuf (ns) | msgpack (ns) | 最快 |
+| ---------------- | ----------- | --------- | ------------- | ------------ | ------- |
+| MediaContent | Serialize | 120.4 | 863.8 | 281.1 | fory |
+| MediaContent | Deserialize | 397.9 | 1197.9 | 2768.6 | fory |
+| MediaContentList | Serialize | 480.9 | 4744.3 | 1407.5 | fory |
+| MediaContentList | Deserialize | 2022.1 | 6426.0 | 13595.9 | fory |
+| Sample | Serialize | 72.8 | 92.0 | 296.1 | fory |
+| Sample | Deserialize | 328.2 | 641.2 | 2642.9 | fory |
+| SampleList | Serialize | 287.3 | 4761.2 | 1506.7 | fory |
+| SampleList | Deserialize | 1711.8 | 4875.2 | 13232.0 | fory |
+| Struct | Serialize | 27.3 | 32.4 | 55.2 | fory |
+| Struct | Deserialize | 21.4 | 25.0 | 747.3 | fory |
+| StructList | Serialize | 69.4 | 419.8 | 285.9 | fory |
+| StructList | Deserialize | 129.4 | 334.4 | 3385.8 | fory |
### 吞吐结果（ops/sec）
-| Datatype | Operation | Fory TPS | Protobuf TPS | Faster |
-| ------------ | ----------- | --------- | ------------ | ----------- |
-| Mediacontent | Serialize | 2,254,915 | 504,410 | Fory (4.5x) |
-| Mediacontent | Deserialize | 741,303 | 396,013 | Fory (1.9x) |
-| Sample | Serialize | 4,248,973 | 3,229,102 | Fory (1.3x) |
-| Sample | Deserialize | 935,709 | 715,837 | Fory (1.3x) |
-| Struct | Serialize | 9,143,618 | 5,881,005 | Fory (1.6x) |
-| Struct | Deserialize | 7,746,787 | 6,202,164 | Fory (1.2x) |
+| 数据类型 | 操作 | fory TPS | protobuf TPS | msgpack TPS | 最快 |
+| ---------------- | ----------- | ---------- | ------------ | ----------- | ------- |
+| MediaContent | Serialize | 8,306,128 | 1,157,712 | 3,557,700 | fory |
+| MediaContent | Deserialize | 2,513,488 | 834,808 | 361,190 | fory |
+| MediaContentList | Serialize | 2,079,229 | 210,777 | 710,492 | fory |
+| MediaContentList | Deserialize | 494,523 | 155,617 | 73,551 | fory |
+| Sample | Serialize | 13,745,041 | 10,871,787 | 3,377,292 | fory |
+| Sample | Deserialize | 3,047,224 | 1,559,633 | 378,369 | fory |
+| SampleList | Serialize | 3,481,110 | 210,029 | 663,693 | fory |
+| SampleList | Deserialize | 584,168 | 205,121 | 75,574 | fory |
+| Struct | Serialize | 36,672,581 | 30,900,039 | 18,114,682 | fory |
+| Struct | Deserialize | 46,637,124 | 39,947,557 | 1,338,225 | fory |
+| StructList | Serialize | 14,419,548 | 2,381,886 | 3,497,903 | fory |
+| StructList | Deserialize | 7,729,173 | 2,990,652 | 295,353 | fory |
### 序列化数据大小（字节）
-| Datatype | Fory | Protobuf |
-| -------- | ---- | -------- |
-| Struct | 32 | 61 |
-| Sample | 384 | 375 |
+| 数据类型 | fory | protobuf | msgpack |
+| ---------------- | ---- | -------- | ------- |
+| Struct | 58 | 61 | 55 |
+| Sample | 446 | 375 | 530 |
+| MediaContent | 365 | 301 | 480 |
+| StructList | 184 | 315 | 289 |
+| SampleList | 1980 | 1890 | 2664 |
+| MediaContentList | 1535 | 1520 | 2421 |
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/dart/README.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/dart/README.md
index 090c930bf..6b8055d7d 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/dart/README.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/dart/README.md
@@ -1,26 +1,26 @@
-# Fory Dart Benchmark
+# Fory Dart 基准
-This benchmark compares serialization and deserialization throughput for Apache Fory and Protocol Buffers in Dart.
+该基准用于比较 Apache Fory 和 Protocol Buffers 在 Dart 中的序列化与反序列化吞吐量。
-## Hardware and Runtime Info
+## 硬件与运行时信息
-| Key | Value |
+| 键 | 值 |
| --------------------- | ---------------------------------------------------------------- |
-| Timestamp | 2026-04-13T21:55:28.456625Z |
-| OS | Version 26.2 (Build 25C56) |
-| Host | Macbook-Air.local |
-| CPU Cores (Logical) | 8 |
-| Memory (GB) | 8.00 |
+| 时间戳 | 2026-04-13T21:55:28.456625Z |
+| 操作系统 | Version 26.2 (Build 25C56) |
+| 主机 | Macbook-Air.local |
+| CPU 核心数（逻辑） | 8 |
+| 内存（GB） | 8.00 |
| Dart | 3.10.4 (stable) (Tue Dec 9 00:01:55 2025 -0800) on "macos_arm64" |
-| Samples per case | 5 |
-| Warmup per case (s) | 1.0 |
-| Duration per case (s) | 1.5 |
+| 每个用例的采样次数 | 5 |
+| 每个用例的预热时长（秒） | 1.0 |
+| 每个用例的持续时长（秒） | 1.5 |
-## Throughput Results
+## 吞吐结果
-| Datatype | Operation | Fory TPS | Protobuf TPS | Fastest |
+| 数据类型 | 操作 | Fory TPS | Protobuf TPS | 最快 |
| ---------------- | ----------- | --------: | -----------: | ------------ |
| Struct | Serialize | 3,989,432 | 1,884,653 | fory (2.12x) |
| Struct | Deserialize | 5,828,197 | 4,199,680 | fory (1.39x) |
@@ -35,9 +35,9 @@ This benchmark compares serialization and deserialization throughput for Apache
| MediaContentList | Serialize | 186,870 | 77,029 | fory (2.43x) |
| MediaContentList | Deserialize | 330,293 | 128,215 | fory (2.58x) |
-## Serialized Size (bytes)
+## 序列化大小（字节）
-| Datatype | Fory | Protobuf |
+| 数据类型 | Fory | Protobuf |
| ---------------- | ---: | -------: |
| Struct | 58 | 61 |
| Sample | 446 | 377 |
@@ -46,7 +46,7 @@ This benchmark compares serialization and deserialization throughput for Apache
| SampleList | 1980 | 1900 |
| MediaContentList | 1535 | 1550 |
-## Per-workload Plots
+## 各工作负载图表
### Struct
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/javascript/README.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/javascript/README.md
index f51899233..9aa5ca43a 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/javascript/README.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/javascript/README.md
@@ -1,34 +1,34 @@
-# JavaScript Benchmark Performance Report
+# JavaScript 基准性能报告
-_Generated on 2026-04-14 17:11:43_
+_生成于 2026-04-14 17:11:43_
-## How to Generate This Report
+## 如何生成本报告
```bash
cd benchmarks/javascript
./run.sh
```
-## Hardware & OS Info
+## 硬件与操作系统信息
-| Key | Value |
+| 键 | 值 |
| -------------------------- | ------------------------ |
-| OS | Darwin 24.6.0 |
-| Machine | arm64 |
-| Processor | arm |
-| CPU Cores (Physical) | 12 |
-| CPU Cores (Logical) | 12 |
-| Total RAM (GB) | 48.0 |
-| Benchmark Date | 2026-04-14T09:09:51.959Z |
-| CPU Cores (from benchmark) | 12 |
+| 操作系统 | Darwin 24.6.0 |
+| 机器架构 | arm64 |
+| 处理器 | arm |
+| CPU 核心数（物理） | 12 |
+| CPU 核心数（逻辑） | 12 |
+| 总内存（GB） | 48.0 |
+| 基准日期 | 2026-04-14T09:09:51.959Z |
+| CPU 核心数（基准采集） | 12 |
| Node.js | v22.20.0 |
| V8 | 12.4.254.21-node.33 |
-## Benchmark Plots
+## 基准图表
-All class-level plots below show throughput (ops/sec).
+下列各类图表均展示吞吐量（ops/sec）。
-### Throughput
+### 总吞吐量
@@ -56,11 +56,11 @@ All class-level plots below show throughput (ops/sec).
-## Benchmark Results
+## 基准结果
-### Timing Results (nanoseconds)
+### 延迟结果（纳秒）
-| Datatype | Operation | fory (ns) | protobuf (ns) | json (ns) | Fastest |
+| 数据类型 | 操作 | fory (ns) | protobuf (ns) | json (ns) | 最快 |
| ---------------- | ----------- | --------- | ------------- | --------- | ------- |
| Struct | Serialize | 118.3 | 525.3 | 327.0 | fory |
| Struct | Deserialize | 103.0 | 121.5 | 259.0 | fory |
@@ -75,9 +75,9 @@ All class-level plots below show throughput (ops/sec).
| MediaContentList | Serialize | 3495.9 | 6712.4 | 3540.5 | fory |
| MediaContentList | Deserialize | 2653.7 | 4087.9 | 5258.9 | fory |
-### Throughput Results (ops/sec)
+### 吞吐结果（ops/sec）
-| Datatype | Operation | fory TPS | protobuf TPS | json TPS | Fastest |
+| 数据类型 | 操作 | fory TPS | protobuf TPS | json TPS | 最快 |
| ---------------- | ----------- | --------- | ------------ | --------- | ------- |
| Struct | Serialize | 8,453,950 | 1,903,706 | 3,058,232 | fory |
| Struct | Deserialize | 9,705,287 | 8,233,664 | 3,860,538 | fory |
@@ -92,9 +92,9 @@ All class-level plots below show throughput (ops/sec).
| MediaContentList | Serialize | 286,053 | 148,977 | 282,445 | fory |
| MediaContentList | Deserialize | 376,826 | 244,622 | 190,155 | fory |
-### Serialized Data Sizes (bytes)
+### 序列化数据大小（字节）
-| Datatype | fory | protobuf | json |
+| 数据类型 | fory | protobuf | json |
| ---------------- | ---- | -------- | ---- |
| Struct | 58 | 61 | 103 |
| Sample | 446 | 377 | 724 |
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/python/README.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/python/README.md
index 0cf659028..053db4c42 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/python/README.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/python/README.md
@@ -1,6 +1,6 @@
# Python 基准性能报告
-_生成于 2026-03-03 13:42:38_
+_生成于 2026-04-14 14:53:18_
## 如何生成本报告
@@ -39,89 +39,75 @@ cd benchmarks/python
### 总吞吐量
-<p align="center">
-<img src="throughput.png" width="90%" />
-</p>
+
-### `MediaContent` 基准
+### Mediacontent
-<p align="center">
-<img src="mediacontent.png" width="90%" />
-</p>
+
-### `MediaContentList` 基准
+### Mediacontentlist
-<p align="center">
-<img src="mediacontentlist.png" width="90%" />
-</p>
+
### Sample
-<p align="center">
-<img src="sample.png" width="90%" />
-</p>
+
### Samplelist
-<p align="center">
-<img src="samplelist.png" width="90%" />
-</p>
+
### Struct
-<p align="center">
-<img src="struct.png" width="90%" />
-</p>
+
### Structlist
-<p align="center">
-<img src="structlist.png" width="90%" />
-</p>
+
## 基准结果
### 延迟结果（纳秒）
-| 数据类型 | 操作 | fory (ns) | pickle (ns) | protobuf (ns) | 最快 |
-| ---------------- | ----------- | --------- | ----------- | ------------- | ------- |
-| Struct | Serialize | 417.9 | 868.9 | 548.9 | fory |
-| Struct | Deserialize | 516.1 | 910.6 | 742.4 | fory |
-| Sample | Serialize | 828.1 | 1663.5 | 2383.7 | fory |
-| Sample | Deserialize | 1282.4 | 2296.3 | 3992.7 | fory |
-| MediaContent | Serialize | 1139.9 | 2859.7 | 2867.1 | fory |
-| MediaContent | Deserialize | 1719.5 | 2854.3 | 3236.1 | fory |
-| StructList | Serialize | 1009.1 | 2630.6 | 3281.6 | fory |
-| StructList | Deserialize | 1387.2 | 2651.9 | 3547.9 | fory |
-| SampleList | Serialize | 2828.3 | 5541.0 | 15256.6 | fory |
-| SampleList | Deserialize | 5043.4 | 8144.7 | 18912.5 | fory |
-| MediaContentList | Serialize | 3417.9 | 9341.9 | 15853.2 | fory |
-| MediaContentList | Deserialize | 6138.7 | 8435.3 | 16442.6 | fory |
+| 数据类型 | 操作 | fory (ns) | pickle (ns) | protobuf (ns) | 最快 |
+| ---------------- | ----------- | --------- | ----------- | ------------- | -------- |
+| Struct | Serialize | 431.3 | 963.9 | 604.3 | fory |
+| Struct | Deserialize | 476.6 | 925.1 | 804.8 | fory |
+| Sample | Serialize | 4966.3 | 12725.1 | 4396.0 | protobuf |
+| Sample | Deserialize | 4362.9 | 6409.2 | 6620.1 | fory |
+| MediaContent | Serialize | 1213.1 | 4263.1 | 3173.7 | fory |
+| MediaContent | Deserialize | 1620.7 | 4625.8 | 4306.3 | fory |
+| StructList | Serialize | 1072.0 | 2798.6 | 3759.0 | fory |
+| StructList | Deserialize | 1334.7 | 2756.7 | 3963.5 | fory |
+| SampleList | Serialize | 23866.8 | 33484.5 | 18711.7 | protobuf |
+| SampleList | Deserialize | 17347.5 | 22999.0 | 36077.1 | fory |
+| MediaContentList | Serialize | 3526.9 | 11258.1 | 17670.6 | fory |
+| MediaContentList | Deserialize | 6241.1 | 10209.5 | 21440.7 | fory |
### 吞吐结果（ops/sec）
-| 数据类型 | 操作 | fory TPS | pickle TPS | protobuf TPS | 最快 |
-| ---------------- | ----------- | --------- | ---------- | ------------ | ------- |
-| Struct | Serialize | 2,393,086 | 1,150,946 | 1,821,982 | fory |
-| Struct | Deserialize | 1,937,707 | 1,098,170 | 1,346,915 | fory |
-| Sample | Serialize | 1,207,542 | 601,144 | 419,511 | fory |
-| Sample | Deserialize | 779,789 | 435,489 | 250,460 | fory |
-| MediaContent | Serialize | 877,300 | 349,688 | 348,780 | fory |
-| MediaContent | Deserialize | 581,563 | 350,354 | 309,018 | fory |
-| StructList | Serialize | 991,017 | 380,145 | 304,732 | fory |
-| StructList | Deserialize | 720,901 | 377,081 | 281,855 | fory |
-| SampleList | Serialize | 353,574 | 180,473 | 65,545 | fory |
-| SampleList | Deserialize | 198,280 | 122,780 | 52,875 | fory |
-| MediaContentList | Serialize | 292,578 | 107,045 | 63,079 | fory |
-| MediaContentList | Deserialize | 162,902 | 118,550 | 60,818 | fory |
+| 数据类型 | 操作 | fory TPS | pickle TPS | protobuf TPS | 最快 |
+| ---------------- | ----------- | --------- | ---------- | ------------ | -------- |
+| Struct | Serialize | 2,318,598 | 1,037,429 | 1,654,700 | fory |
+| Struct | Deserialize | 2,098,391 | 1,081,003 | 1,242,545 | fory |
+| Sample | Serialize | 201,358 | 78,585 | 227,479 | protobuf |
+| Sample | Deserialize | 229,204 | 156,026 | 151,056 | fory |
+| MediaContent | Serialize | 824,338 | 234,569 | 315,087 | fory |
+| MediaContent | Deserialize | 616,999 | 216,177 | 232,216 | fory |
+| StructList | Serialize | 932,803 | 357,322 | 266,029 | fory |
+| StructList | Deserialize | 749,212 | 362,753 | 252,301 | fory |
+| SampleList | Serialize | 41,899 | 29,865 | 53,442 | protobuf |
+| SampleList | Deserialize | 57,645 | 43,480 | 27,718 | fory |
+| MediaContentList | Serialize | 283,535 | 88,825 | 56,591 | fory |
+| MediaContentList | Deserialize | 160,227 | 97,948 | 46,640 | fory |
### 序列化数据大小（字节）
| 数据类型 | fory | pickle | protobuf |
| ---------------- | ---- | ------ | -------- |
-| Struct | 72 | 126 | 61 |
-| Sample | 517 | 793 | 375 |
-| MediaContent | 470 | 586 | 301 |
-| StructList | 205 | 420 | 315 |
-| SampleList | 1810 | 2539 | 1890 |
-| MediaContentList | 1756 | 1377 | 1520 |
+| Struct | 58 | 126 | 61 |
+| Sample | 446 | 1176 | 375 |
+| MediaContent | 391 | 624 | 301 |
+| StructList | 184 | 420 | 315 |
+| SampleList | 1980 | 3546 | 1890 |
+| MediaContentList | 1665 | 1415 | 1520 |
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/README.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/README.md
index fdaa812b8..d09f26abf 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/README.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/benchmarks/rust/README.md
@@ -1,104 +1,103 @@
-## 性能对比报告
+# Rust 基准性能报告
-_生成时间：2025-10-26 18:36:41_
+_生成于 2026-03-20 18:40:46_
-如何生成性能报告：
+## 如何生成本报告
```bash
-cd benchmarks/rust_benchmark
-cargo bench 2>&1 | tee cargo_bench.log
-python benchmark_report.py --log-file cargo_bench.log --output-dir=report_output
+cd benchmarks/rust
+cargo bench --bench serialization_bench 2>&1 | tee results/cargo_bench.log
+cargo run --release --bin fory_profiler -- --print-all-serialized-sizes | tee results/serialized_sizes.txt
+python benchmark_report.py --log-file results/cargo_bench.log --size-file results/serialized_sizes.txt --output-dir results
```
-### 硬件与系统信息
-
-| Key | Value |
-| -------------------- | ------------- |
-| OS | Darwin 24.5.0 |
-| Machine | arm64 |
-| Processor | arm |
-| CPU Cores (Physical) | 12 |
-| CPU Cores (Logical) | 12 |
-| Total RAM (GB) | 48.0 |
-
-### 基准图表
-
-**company**
-
-
-
-**ecommerce_data**
-
-
-
-**person**
-
-
-
-**simple_list**
-
-
-
-**simple_map**
-
-
-
-**simple_struct**
-
-
-
-**system_data**
-
-
-
-### 序列化结果
-
-| Datatype | Size | Operation | Fory TPS | JSON TPS | Protobuf TPS | Fastest |
-| -------------- | ------ | --------- | ---------- | ---------- | ------------ | ------- |
-| company | small | serialize | 10,063,906 | 761,673 | 896,620 | fory |
-| company | medium | serialize | 412,507 | 33,835 | 37,590 | fory |
-| company | large | serialize | 9,183 | 793 | 880 | fory |
-| ecommerce_data | small | serialize | 2,350,729 | 206,262 | 256,970 | fory |
-| ecommerce_data | medium | serialize | 59,977 | 4,699 | 5,242 | fory |
-| ecommerce_data | large | serialize | 3,727 | 266 | 295 | fory |
-| person | small | serialize | 13,632,522 | 1,345,189 | 1,475,035 | fory |
-| person | medium | serialize | 3,839,656 | 337,610 | 369,031 | fory |
-| person | large | serialize | 907,853 | 79,631 | 91,408 | fory |
-| simple_list | small | serialize | 27,726,945 | 4,874,957 | 4,643,172 | fory |
-| simple_list | medium | serialize | 4,770,765 | 401,558 | 397,551 | fory |
-| simple_list | large | serialize | 606,061 | 41,061 | 44,565 | fory |
-| simple_map | small | serialize | 22,862,369 | 3,888,025 | 2,695,999 | fory |
-| simple_map | medium | serialize | 2,128,973 | 204,319 | 193,132 | fory |
-| simple_map | large | serialize | 177,847 | 18,419 | 18,668 | fory |
-| simple_struct | small | serialize | 35,729,598 | 10,167,045 | 8,633,342 | fory |
-| simple_struct | medium | serialize | 34,988,279 | 9,737,098 | 6,433,350 | fory |
-| simple_struct | large | serialize | 31,801,558 | 4,545,041 | 7,420,049 | fory |
-| system_data | small | serialize | 5,382,131 | 468,033 | 569,930 | fory |
-| system_data | medium | serialize | 174,240 | 11,896 | 14,753 | fory |
-| system_data | large | serialize | 10,671 | 876 | 1,040 | fory |
-
-### 反序列化结果
-
-| Datatype | Size | Operation | Fory TPS | JSON TPS | Protobuf TPS | Fastest |
-| -------------- | ------ | ----------- | ---------- | ---------- | ------------ | ------- |
-| company | small | deserialize | 1,145,593 | 718,597 | 917,431 | fory |
-| company | medium | deserialize | 35,195 | 24,474 | 25,057 | fory |
-| company | large | deserialize | 836 | 623 | 623 | fory |
-| ecommerce_data | small | deserialize | 278,427 | 183,237 | 241,109 | fory |
-| ecommerce_data | medium | deserialize | 5,622 | 3,820 | 4,249 | fory |
-| ecommerce_data | large | deserialize | 298 | 204 | 217 | fory |
-| person | small | deserialize | 1,924,372 | 1,214,388 | 1,675,631 | fory |
-| person | medium | deserialize | 371,016 | 265,280 | 266,333 | fory |
-| person | large | deserialize | 84,839 | 63,975 | 61,820 | fory |
-| simple_list | small | deserialize | 6,129,329 | 3,599,582 | 4,429,286 | fory |
-| simple_list | medium | deserialize | 460,745 | 305,409 | 337,336 | fory |
-| simple_list | large | deserialize | 54,348 | 33,962 | 38,776 | fory |
-| simple_map | small | deserialize | 3,686,364 | 3,090,426 | 3,477,051 | fory |
-| simple_map | medium | deserialize | 171,774 | 126,638 | 119,323 | fory |
-| simple_map | large | deserialize | 16,501 | 10,920 | 10,853 | fory |
-| simple_struct | small | deserialize | 31,476,235 | 12,948,168 | 28,280,543 | fory |
-| simple_struct | medium | deserialize | 30,077,902 | 10,431,118 | 23,012,841 | fory |
-| simple_struct | large | deserialize | 28,201,585 | 8,955,759 | 23,528,858 | fory |
-| system_data | small | deserialize | 644,870 | 421,106 | 549,209 | fory |
-| system_data | medium | deserialize | 14,322 | 9,205 | 10,565 | fory |
-| system_data | large | deserialize | 961 | 634 | 706 | fory |
+## 硬件与操作系统信息
+
+| 键 | 值 |
+| --------------------- | ------------------- |
+| 操作系统 | Darwin 24.6.0 |
+| 机器架构 | arm64 |
+| 处理器 | arm |
+| CPU 核心数（物理） | 12 |
+| CPU 核心数（逻辑） | 12 |
+| 总内存（GB） | 48.0 |
+| 基准日期 | 2026-03-20T18:40:44 |
+
+## 基准图表
+
+下列各类图表均展示吞吐量（ops/sec）。
+
+### 总吞吐量
+
+
+
+### MediaContent
+
+
+
+### MediaContentList
+
+
+
+### Sample
+
+
+
+### SampleList
+
+
+
+### Struct
+
+
+
+### StructList
+
+
+
+## 基准结果
+
+### 延迟结果（纳秒）
+
+| 数据类型 | 操作 | fory (ns) | protobuf (ns) | 最快 |
+| ---------------- | ----------- | --------- | ------------- | ------- |
+| Struct | Serialize | 69.6 | 76.8 | fory |
+| Struct | Deserialize | 27.0 | 70.4 | fory |
+| Sample | Serialize | 148.5 | 584.3 | fory |
+| Sample | Deserialize | 350.9 | 983.1 | fory |
+| MediaContent | Serialize | 277.8 | 553.2 | fory |
+| MediaContent | Deserialize | 472.3 | 706.4 | fory |
+| StructList | Serialize | 170.4 | 385.4 | fory |
+| StructList | Deserialize | 96.8 | 294.7 | fory |
+| SampleList | Serialize | 356.2 | 3155.7 | fory |
+| SampleList | Deserialize | 1644.1 | 4361.0 | fory |
+| MediaContentList | Serialize | 657.4 | 2844.0 | fory |
+| MediaContentList | Deserialize | 2397.7 | 3696.6 | fory |
+
+### 吞吐结果（ops/sec）
+
+| 数据类型 | 操作 | fory TPS | protobuf TPS | 最快 |
+| ---------------- | ----------- | ---------- | ------------ | ------- |
+| Struct | Serialize | 14,366,165 | 13,022,359 | fory |
+| Struct | Deserialize | 37,065,866 | 14,202,528 | fory |
+| Sample | Serialize | 6,734,914 | 1,711,537 | fory |
+| Sample | Deserialize | 2,849,409 | 1,017,201 | fory |
+| MediaContent | Serialize | 3,600,230 | 1,807,664 | fory |
+| MediaContent | Deserialize | 2,117,433 | 1,415,689 | fory |
+| StructList | Serialize | 5,866,823 | 2,595,043 | fory |
+| StructList | Deserialize | 10,330,152 | 3,393,051 | fory |
+| SampleList | Serialize | 2,807,333 | 316,887 | fory |
+| SampleList | Deserialize | 608,236 | 229,305 | fory |
+| MediaContentList | Serialize | 1,521,098 | 351,617 | fory |
+| MediaContentList | Deserialize | 417,066 | 270,519 | fory |
+
+### 序列化数据大小（字节）
+
+| 数据类型 | fory | protobuf |
+| ---------------- | ---- | -------- |
+| Struct | 58 | 61 |
+| Sample | 446 | 375 |
+| MediaContent | 365 | 301 |
+| StructList | 184 | 315 |
+| SampleList | 1980 | 1890 |
+| MediaContentList | 1535 | 1520 |
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/compiler/compiler-guide.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/compiler/compiler-guide.md
index 0046cbcd3..54e888663 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/compiler/compiler-guide.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/compiler/compiler-guide.md
@@ -63,7 +63,11 @@ foryc --scan-generated [OPTIONS]
| `--cpp_out=DST_DIR` | 将 C++ 代码输出到 `DST_DIR` | （无） |
| `--go_out=DST_DIR` | 将 Go 代码输出到 `DST_DIR` | （无） |
| `--rust_out=DST_DIR` | 将 Rust 代码输出到 `DST_DIR` | （无） |
+| `--javascript_out=DST_DIR` | 将 JavaScript 代码输出到 `DST_DIR` | （无） |
+| `--swift_out=DST_DIR` | 将 Swift 代码输出到 `DST_DIR` | （无） |
+| `--dart_out=DST_DIR` | 将 Dart 代码输出到 `DST_DIR` | （无） |
| `--go_nested_type_style` | Go 嵌套类型命名风格：`camelcase` 或 `underscore` | schema/默认值 |
+| `--swift_namespace_style` | Swift 命名空间风格：`enum` 或 `flatten` | `enum` |
| `--emit-fdl` | 对非 `.fdl` 输入打印转换后的 Fory IDL | `false` |
| `--emit-fdl-path` | 将转换后的 Fory IDL 写入文件或目录 | （stdout） |
@@ -108,7 +112,7 @@ foryc schema.fdl
**为指定语言编译：**
```bash
-foryc schema.fdl --lang java,python
+foryc schema.fdl --lang java,python,csharp,javascript,swift,dart
```
**指定输出目录：**
@@ -129,6 +133,12 @@ foryc schema.fdl --package com.myapp.models
foryc user.fdl order.fdl product.fdl --output ./generated
```
+**编译包含 service 定义的简单 schema（生成 Java + Python 模型）：**
+
+```bash
+foryc compiler/examples/service.fdl --java_out=./generated/java --python_out=./generated/python
+```
+
**使用 import 搜索路径：**
```bash
@@ -155,7 +165,7 @@ foryc src/main.fdl -I libs/common,libs/types --proto_path third_party/
foryc schema.fdl --java_out=./src/main/java
# 多语言分别输出到不同目录
-foryc schema.fdl --java_out=./java/gen --python_out=./python/src --go_out=./go/gen
+foryc schema.fdl --java_out=./java/gen --python_out=./python/src --go_out=./go/gen --csharp_out=./csharp/gen --javascript_out=./javascript/src --swift_out=./swift/gen --dart_out=./dart/gen
# 结合 import 路径
foryc schema.fdl --java_out=./gen/java -I proto/ -I common/
@@ -224,13 +234,16 @@ Compiling src/main.fdl...
## 支持语言
-| 语言 | 标记 | 输出后缀 | 说明 |
-| ------ | -------- | -------- | ---------------------- |
-| Java | `java` | `.java` | 带 Fory 注解的 POJO |
-| Python | `python` | `.py` | 带类型提示的 dataclass |
-| Go | `go` | `.go` | 带 struct tag 的结构体 |
-| Rust | `rust` | `.rs` | 带 derive 宏的结构体 |
-| C++ | `cpp` | `.h` | 带 FORY 宏的结构体 |
+| 语言 | 标记 | 输出后缀 | 说明 |
+| ---------- | ------------ | -------- | ------------------------- |
+| Java | `java` | `.java` | 带 Fory 注解的 POJO |
+| Python | `python` | `.py` | 带类型提示的 dataclass |
+| Go | `go` | `.go` | 带 struct tag 的结构体 |
+| Rust | `rust` | `.rs` | 带 derive 宏的结构体 |
+| C++ | `cpp` | `.h` | 带 FORY 宏的结构体 |
+| JavaScript | `javascript` | `.ts` | 带注册函数的接口 |
+| Swift | `swift` | `.swift` | `@ForyObject` Swift 模型 |
+| Dart | `dart` | `.dart` | 带注解的 `@ForyStruct` 类 |
## 输出结构
@@ -300,6 +313,35 @@ generated/
- 命名空间与 package 对齐（点号转换为 `::`）
- 自动包含 header guard 与前向声明
+### JavaScript
+
+```
+generated/
+└── javascript/
+ └── example.ts
+```
+
+- 每个 schema 生成一个 `.ts` 文件
+- message 生成为 `export interface`
+- enum 生成为 `export enum`
+- union 生成为带 case enum 的判别联合
+- 文件内包含注册辅助函数
+
+### Dart
+
+```
+generated/
+└── dart/
+ └── package/
+ ├── package.dart
+ └── package.fory.dart
+```
+
+- 每个 schema 生成两个文件：带注解类型的主 `.dart` 文件，以及带序列化器的 `.fory.dart` part 文件
+- package 各段映射为目录层级（例如 `demo.foo` -> `demo/foo/`）
+- 注册辅助类位于 part 文件中
+- 非可空、非 `ref` 的基础类型列表会使用类型化数组（例如 `Int32List`）
+
## 构建系统集成
### Maven (Java)
@@ -488,6 +530,30 @@ cc_library(
)
```
+### Dart / Flutter
+
+在 `pubspec.yaml` 中加入 Fory 依赖：
+
+```yaml
+dependencies:
+ fory: ^0.1.0
+
+dev_dependencies:
+ build_runner: ^2.4.0
+```
+
+用编译器生成 schema 类型：
+
+```bash
+foryc schema.fdl --dart_out=lib/generated
+```
+
+随后运行 `build_runner` 生成序列化器：
+
+```bash
+dart run build_runner build
+```
+
## 错误处理
### 语法错误
@@ -496,6 +562,18 @@ cc_library(
Error: Line 5, Column 12: Expected ';' after field declaration
```
+### 未知类型引用
+
+```
+Error: Unknown type 'Address' in Customer.address
+```
+
+修复方式：先定义被引用的类型，或检查拼写是否正确。
+
+service RPC 的请求和响应类型也按同样规则校验。例如
+`rpc SayHello (HelloRequest) returns (HelloReply);`
+中的类型必须已定义；否则校验器会在 RPC 所在行报出 `Unknown type '...'` 错误。
+
修复方式：检查对应行是否缺少分号或存在语法问题。
### 类型名重复
@@ -653,3 +731,10 @@ fory = "x.y.z"
```
**C++：** 确保编译器 include 路径可找到 Fory 头文件。
+
+**Dart：** 确保 `pubspec.yaml` 中包含 fory 依赖：
+
+```yaml
+dependencies:
+ fory: ^0.1.0
+```
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/compiler/generated-code.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/compiler/generated-code.md
index cadf241ab..a8fda3eda 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/compiler/generated-code.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/compiler/generated-code.md
@@ -685,6 +685,321 @@ if err := restored.FromBytes(data); err != nil {
}
```
+## C#
+
+### 输出布局
+
+C# 输出通常是每个 schema 对应一个 `.cs` 文件，例如：
+
+- `<csharp_out>/addressbook/addressbook.cs`
+
+### 类型生成
+
+message 会生成带 `[ForyObject]` 的类、C# 属性以及字节辅助方法：
+
+```csharp
+[ForyObject]
+public sealed partial class Person
+{
+ public string Name { get; set; } = string.Empty;
+ public int Id { get; set; }
+ public List<Person.PhoneNumber> Phones { get; set; } = new();
+ public Animal Pet { get; set; } = null!;
+
+ public byte[] ToBytes() { ... }
+ public static Person FromBytes(byte[] data) { ... }
+}
+```
+
+union 会生成带类型化 case 辅助方法的 `Union` 子类：
+
+```csharp
+public sealed class Animal : Union
+{
+ public static Animal Dog(Dog value) { ... }
+ public static Animal Cat(Cat value) { ... }
+ public bool IsDog => ...;
+ public Dog DogValue() { ... }
+}
+```
+
+### 注册
+
+每个 schema 都会生成一个注册辅助类：
+
+```csharp
+public static class AddressbookForyRegistration
+{
+ public static void Register(Fory fory)
+ {
+ fory.Register<addressbook.Animal>((uint)106);
+ fory.Register<addressbook.Person>((uint)100);
+ // ...
+ }
+}
+```
+
+若未显式提供类型 ID，生成的注册代码会像其他目标语言一样使用计算得到的数值 ID。
+
+## JavaScript
+
+### 输出布局
+
+JavaScript 输出通常是每个 schema 对应一个 `.ts` 文件，例如：
+
+- `<javascript_out>/addressbook.ts`
+
+### 类型生成
+
+message 会生成使用 camelCase 字段名的 `export interface` 声明：
+
+```typescript
+export interface Person {
+ name: string;
+ id: number;
+ phones: PhoneNumber[];
+ pet?: Animal | null;
+}
+```
+
+enum 会生成 `export enum` 声明：
+
+```typescript
+export enum PhoneType {
+ MOBILE = 0,
+ HOME = 1,
+ WORK = 2,
+}
+```
+
+union 会生成带 case enum 的判别联合类型：
+
+```typescript
+export enum AnimalCase {
+ DOG = 1,
+ CAT = 2,
+}
+
+export type Animal =
+ | { case: AnimalCase.DOG; value: Dog }
+ | { case: AnimalCase.CAT; value: Cat };
+```
+
+## Swift
+
+### 输出布局
+
+Swift 输出通常是每个 schema 对应一个 `.swift` 文件，例如：
+
+- `<swift_out>/addressbook/addressbook.swift`
+
+### 类型生成
+
+生成器会创建带 `@ForyObject` 和字段 ID 的 Swift 模型。
+
+当 package/namespace 非空时，命名空间形态由 `swift_namespace_style` 控制：
+
+- `enum`（默认）：生成嵌套 enum 命名空间包装
+- `flatten`：在顶层类型名上加上由 package 派生的前缀（例如 `Demo_Foo_User`）
+
+当 package/namespace 为空时，不会生成 enum 包装或 flatten 前缀。
+
+对于非空 package 且使用默认 `enum` 风格时：
+
+```swift
+public enum Addressbook {
+ @ForyObject
+ public enum Animal: Equatable {
+ @ForyField(id: 1)
+ case dog(Addressbook.Dog)
+ @ForyField(id: 2)
+ case cat(Addressbook.Cat)
+ }
+
+ @ForyObject
+ public struct Person: Equatable {
+ @ForyField(id: 1)
+ public var name: String = ""
+ @ForyField(id: 8)
+ public var pet: Addressbook.Animal = .foryDefault()
+ }
+}
+```
+
+对于非空 package 且使用 `flatten` 风格时：
+
+```swift
+@ForyObject
+public struct Addressbook_Person: Equatable { ... }
+```
+
+当命令行和 schema 选项同时设置时，CLI 参数 `--swift_namespace_style` 会覆盖 schema 中的 `swift_namespace_style`。
+
+union 会生成带关联值的标记 Swift enum。
+带 `ref`/`weak_ref` 字段的 message 会生成 `final class` 模型，以保留引用语义。
+
+### 注册
+
+每个 schema 都会生成带传递性 import 注册的辅助类：
+
+```swift
+public enum ForyRegistration {
+ public static func register(_ fory: Fory) throws {
+ try ComplexPb.ForyRegistration.register(fory)
+ fory.register(Addressbook.Person.self, id: 100)
+ fory.register(Addressbook.Animal.self, id: 106)
+ }
+}
+```
+
+对于非空 package 且使用 `flatten` 风格时，辅助类名称也会带前缀（例如 `Addressbook_ForyRegistration`）。
+
+若未显式提供 `[id=...]`，注册会使用计算得到的数值 ID。
+若设置 `option enable_auto_type_id = false;`，则生成代码会改用基于名称的注册 API。
+
+## Dart
+
+### 输出布局
+
+Dart 输出通常是每个 schema 对应两个文件：一个带注解类型的主 `.dart` 文件，以及一个包含生成序列化器和注册辅助逻辑的 `.fory.dart` part 文件。
+
+- `<dart_out>/package/package.dart`
+- `<dart_out>/package/package.fory.dart`
+
+### 类型生成
+
+message 会生成带 `@ForyStruct` 注解的 `final class`，并在每个字段上加 `@ForyField`：
+
+```dart
+@ForyStruct()
+final class Person {
+ Person();
+
+ @ForyField(id: 1)
+ String name = '';
+
+ @ForyField(id: 2)
+ Int32 id = Int32(0);
+
+ @ForyField(id: 7)
+ List<Person_PhoneNumber> phones = <Person_PhoneNumber>[];
+
+ @ForyField(id: 8)
+ Animal pet = Animal._empty();
+}
+```
+
+enum 会生成带 `rawValue` getter 和 `fromRawValue` factory 的 Dart `enum`：
+
+```dart
+enum Person_PhoneType {
+ mobile,
+ home,
+ work;
+
+ int get rawValue => switch (this) {
+ Person_PhoneType.mobile => 0,
+ Person_PhoneType.home => 1,
+ Person_PhoneType.work => 2,
+ };
+
+ static Person_PhoneType fromRawValue(int value) => switch (value) {
+ 0 => Person_PhoneType.mobile,
+ 1 => Person_PhoneType.home,
+ 2 => Person_PhoneType.work,
+ _ => throw StateError('Unknown Person_PhoneType raw value $value.'),
+ };
+}
+```
+
+union 会生成带 `@ForyUnion` 注解的类，包含工厂构造器、case enum 以及自定义序列化器：
+
+```dart
+enum AnimalCase {
+ dog,
+ cat;
+
+ int get id => switch (this) {
+ AnimalCase.dog => 1,
+ AnimalCase.cat => 2,
+ };
+}
+
+@ForyUnion()
+final class Animal {
+ final AnimalCase _case;
+ final Object? _value;
+
+ const Animal._(this._case, this._value);
+
+ factory Animal.dog(Dog value) => Animal._(AnimalCase.dog, value);
+ factory Animal.cat(Cat value) => Animal._(AnimalCase.cat, value);
+
+ bool get isDog => _case == AnimalCase.dog;
+ Dog get dogValue => _value as Dog;
+ // ...
+}
+```
+
+嵌套类型使用扁平下划线命名（例如 `Person_PhoneNumber`、`Person_PhoneType`）。
+
+非 optional、非 ref 的原始类型列表会使用 typed array 以获得零拷贝性能（例如 `list<int32>` -> `Int32List`）。
+
+列表元素或 map value 上的引用跟踪通过 `@ListType` / `@MapType` 注解表达：
+
+```dart
+@ListType(element: ValueType.ref())
+@ForyField(id: 3)
+List<Node> children = <Node>[];
+
+@MapType(value: ValueType.ref())
+@ForyField(id: 2)
+Map<String, Node> byName = <String, Node>{};
+```
+
+### 注册
+
+每个 schema 都会生成一个注册辅助类，负责处理该文件中的所有类型，并传递性注册 import 进来的类型：
+
+```dart
+abstract final class ForyRegistration {
+ static void register(
+ Fory fory,
+ Type type, {
+ int? id,
+ String? namespace,
+ String? typeName,
+ }) {
+ if (type == Person) {
+ registerGeneratedStruct(fory, _personForyRegistration, id: id, namespace: namespace, typeName: typeName);
+ return;
+ }
+ // ... other types
+ }
+}
+```
+
+### 使用示例
+
+```dart
+import 'package:fory/fory.dart';
+import 'generated/addressbook/addressbook.dart';
+
+void main() {
+ final fory = Fory();
+ ForyRegistration.register(fory, Person, id: 100);
+ ForyRegistration.register(fory, Dog, id: 104);
+ // ...
+
+ final person = Person()
+ ..name = 'Alice'
+ ..id = Int32(1);
+
+ final bytes = fory.serialize(person);
+ final roundTrip = fory.deserialize<Person>(bytes);
+}
+```
+
## 跨语言说明
### 类型 ID 行为
@@ -695,20 +1010,28 @@ if err := restored.FromBytes(data); err != nil {
### 嵌套类型形态
-| 语言 | 嵌套类型形式 |
-| ------ | ---------------------------- |
-| Java | `Person.PhoneNumber` |
-| Python | `Person.PhoneNumber` |
-| Rust | `person::PhoneNumber` |
-| C++ | `Person::PhoneNumber` |
-| Go | `Person_PhoneNumber`（默认） |
+| 语言 | 嵌套类型形式 |
+| ---------- | ---------------------------- |
+| Java | `Person.PhoneNumber` |
+| Python | `Person.PhoneNumber` |
+| Rust | `person::PhoneNumber` |
+| C++ | `Person::PhoneNumber` |
+| Go | `Person_PhoneNumber`（默认） |
+| C# | `Person.PhoneNumber` |
+| JavaScript | `Person.PhoneNumber` |
+| Swift | `Person.PhoneNumber` |
+| Dart | `Person_PhoneNumber` |
### 字节辅助方法命名
-| 语言 | 辅助方法名称 |
-| ------ | ------------------------- |
-| Java | `toBytes` / `fromBytes` |
-| Python | `to_bytes` / `from_bytes` |
-| Rust | `to_bytes` / `from_bytes` |
-| C++ | `to_bytes` / `from_bytes` |
-| Go | `ToBytes` / `FromBytes` |
+| 语言 | 辅助方法名称 |
+| ---------- | ------------------------- |
+| Java | `toBytes` / `fromBytes` |
+| Python | `to_bytes` / `from_bytes` |
+| Rust | `to_bytes` / `from_bytes` |
+| C++ | `to_bytes` / `from_bytes` |
+| Go | `ToBytes` / `FromBytes` |
+| C# | `ToBytes` / `FromBytes` |
+| JavaScript | （通过 `fory.serialize()`） |
+| Swift | `toBytes` / `fromBytes` |
+| Dart | （通过 `fory.serialize()`） |
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/compiler/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/compiler/index.md
index 8e26cdd38..73caa1018 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/compiler/index.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/compiler/index.md
@@ -20,7 +20,7 @@ license: |
---
Fory IDL 是 Apache Fory 的 Schema 定义语言，可实现类型安全的跨语言序列化。
-你只需定义一次数据结构，即可为 Java、Python、Go、Rust 和 C++ 生成原生数据结构代码。
+你只需定义一次数据结构，即可为 Java、Python、Go、Rust、C++、C#、Swift、JavaScript 和 Dart 生成原生数据结构代码。
## 示例 Schema
@@ -99,6 +99,10 @@ union Animal [id=106] {
- Go：带 struct tag 的结构体
- Rust：带 `#[derive(ForyObject)]` 的结构体
- C++：带 `FORY_STRUCT` 宏的结构体
+- C#：带 `[ForyObject]` 的类及注册辅助函数
+- JavaScript：带注册函数的接口
+- Swift：带 `@ForyObject` 模型、`@ForyField` 元数据和注册辅助函数
+- Dart：带 `@ForyStruct` 类、`@ForyField` 注解和注册辅助函数
## 快速开始
@@ -136,7 +140,7 @@ message Person {
foryc example.fdl --output ./generated
# 为指定语言生成
-foryc example.fdl --lang java,python --output ./generated
+foryc example.fdl --lang java,python,csharp,javascript,swift,dart --output ./generated
```
### 4. 使用生成代码
@@ -191,11 +195,11 @@ message Example {
Fory IDL 类型会映射为各语言原生类型：
-| Fory IDL 类型 | Java | Python | Go | Rust | C++ |
-| ------------- | --------- | -------------- | -------- | -------- | ------------- |
-| `int32` | `int` | `pyfory.int32` | `int32` | `i32` | `int32_t` |
-| `string` | `String` | `str` | `string` | `String` | `std::string` |
-| `bool` | `boolean` | `bool` | `bool` | `bool` | `bool` |
+| Fory IDL 类型 | Java | Python | Go | Rust | C++ | C# | JavaScript | Swift | Dart |
+| ------------- | --------- | -------------- | -------- | -------- | ------------- | -------- | ---------- | -------- | -------- |
+| `int32` | `int` | `pyfory.int32` | `int32` | `i32` | `int32_t` | `int` | `number` | `Int32` | `Int32` |
+| `string` | `String` | `str` | `string` | `String` | `std::string` | `string` | `string` | `String` | `String` |
+| `bool` | `boolean` | `bool` | `bool` | `bool` | `bool` | `bool` | `boolean` | `Bool` | `bool` |
完整映射请参见 [类型系统](schema-idl.md#type-system)。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/compiler/schema-idl.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/compiler/schema-idl.md
index be6d5c6b2..8f56cbecd 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/compiler/schema-idl.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/compiler/schema-idl.md
@@ -91,13 +91,16 @@ package com.example.models alias models_v1;
语言映射：
-| 语言 | package 用法 |
-| ------ | ----------------------- |
-| Java | Java package |
-| Python | 模块名（`.` 转 `_`） |
-| Go | 包名（通常取最后一段） |
-| Rust | 模块名（`.` 转 `_`） |
-| C++ | 命名空间（`.` 转 `::`） |
+| 语言 | package 用法 |
+| ---------- | ------------------------- |
+| Java | Java package |
+| Python | 模块名（`.` 转 `_`） |
+| Go | 包名（通常取最后一段） |
+| Rust | 模块名（`.` 转 `_`） |
+| C++ | 命名空间（`.` 转 `::`） |
+| C# | 命名空间 |
+| JavaScript | 模块名（取最后一段） |
+| Dart | 库名（保留 package 各段） |
## 文件级选项
@@ -306,16 +309,30 @@ enum Status {
### 语言映射
-- Java：`enum`
-- Python：`IntEnum`
-- Go：`type + const`
-- Rust：`repr(i32)` 枚举
-- C++：`enum class`
+| 语言 | 实现形式 |
+| ---------- | -------------------------------------- |
+| Java | `enum Status { UNKNOWN, ACTIVE, ... }` |
+| Python | `class Status(IntEnum): UNKNOWN = 0` |
+| Go | `type Status int32` 配合常量 |
+| Rust | `#[repr(i32)] enum Status { Unknown }` |
+| C++ | `enum class Status : int32_t { ... }` |
+| JavaScript | `export enum Status { UNKNOWN, ... }` |
+| Dart | `enum Status { unknown, active, ... }` |
### 枚举前缀处理
针对 protobuf 风格 `TYPE_NAME_VALUE`，生成器通常会按语言习惯去除冗余前缀，使 API 更自然。
+| 语言 | 输出示例 | 风格 |
+| ---------- | ----------------------------------------- | ---------------- |
+| Java | `UNKNOWN, TIER1, TIER2` | 作用域枚举 |
+| Rust | `Unknown, Tier1, Tier2` | 作用域枚举 |
+| C++ | `UNKNOWN, TIER1, TIER2` | 作用域枚举 |
+| Python | `UNKNOWN, TIER1, TIER2` | 作用域 `IntEnum` |
+| Go | `DeviceTierUnknown, DeviceTierTier1, ...` | 非作用域常量 |
+| JavaScript | `UNKNOWN, TIER1, TIER2` | 作用域枚举 |
+| Dart | `unknown, tier1, tier2` | 作用域枚举 |
+
## Message 定义
### 基本语法
@@ -342,11 +359,15 @@ message User [id=100] {
### 语言映射
-- Java：类 / record（按选项）
-- Python：dataclass
-- Go：struct
-- Rust：struct
-- C++：class/struct + 宏元信息
+| 语言 | 实现形式 |
+| ---------- | --------------------------------- |
+| Java | 带 getter/setter 的 POJO |
+| Python | `@dataclass` 类 |
+| Go | 导出字段的 struct |
+| Rust | `#[derive(ForyObject)]` 的 struct |
+| C++ | 带 `FORY_STRUCT` 宏的 struct |
+| JavaScript | `export interface` 声明 |
+| Dart | `@ForyStruct` `final class` |
### 预留字段
@@ -397,13 +418,15 @@ message Person {
### 各语言生成形态
-| 语言 | 嵌套类型形态 |
-| ------ | --------------------- |
-| Java | `Outer.Inner` |
-| Python | `Outer.Inner` |
-| Rust | `outer::Inner` |
-| C++ | `Outer::Inner` |
-| Go | `Outer_Inner`（默认） |
+| 语言 | 嵌套类型形态 |
+| ---------- | ----------------------------------------------- |
+| Java | `Outer.Inner` |
+| Python | `Outer.Inner` |
+| Rust | `outer::Inner` |
+| C++ | `Outer::Inner` |
+| Go | `Outer_Inner`（默认，可配置为 camelcase） |
+| JavaScript | 扁平名称（如 `Result`） |
+| Dart | 带下划线的扁平类名（如 `SearchResponse_Result`） |
### 嵌套规则
@@ -466,6 +489,18 @@ message User {
建议在跨语言场景显式使用，以避免默认值差异。
+**生成代码：**
+
+| 语言 | 非 optional | optional |
+| ---------- | ------------------- | ----------------------------------------------- |
+| Java | `String name` | `String email` 配合 `@ForyField(nullable=true)` |
+| Python | `name: str` | `name: Optional[str]` |
+| Go | `Name string` | `Name *string` |
+| Rust | `name: String` | `name: Option<String>` |
+| C++ | `std::string name` | `std::optional<std::string> name` |
+| JavaScript | `name: string` | `name?: string \| null` |
+| Dart | `String name` | `String? email` |
+
#### `ref`
开启引用跟踪，用于共享对象与循环结构：
@@ -480,6 +515,18 @@ message Node {
当运行时全局 ref tracking 开启时，字段级 `ref` 才会生效。
+**生成代码：**
+
+| 语言 | 不使用 `ref` | 使用 `ref` |
+| ---------- | ---------------- | ------------------------------------------ |
+| Java | `Node parent` | `Node parent` 配合 `@ForyField(ref=true)` |
+| Python | `parent: Node` | `parent: Node = pyfory.field(ref=True)` |
+| Go | `Parent Node` | `Parent *Node` 配合 `fory:"ref"` |
+| Rust | `parent: Node` | `parent: Arc<Node>` |
+| C++ | `Node parent` | `std::shared_ptr<Node> parent` |
+| JavaScript | `parent: Node` | `parent: Node`（无额外 `ref` 区分） |
+| Dart | `Node parent` | `Node parent` 配合 `@ForyField(ref: true)` |
+
#### `list`
列表字段（`repeated` 为等价别名）：
@@ -490,6 +537,18 @@ message Group {
}
```
+**生成代码：**
+
+| 语言 | 类型 |
+| ---------- | -------------------------- |
+| Java | `List<String>` |
+| Python | `List[str]` |
+| Go | `[]string` |
+| Rust | `Vec<String>` |
+| C++ | `std::vector<std::string>` |
+| JavaScript | `string[]` |
+| Dart | `List<String>` |
+
### 组合修饰符
可组合使用：
@@ -530,10 +589,38 @@ Fory IDL 类型系统包括基础类型、命名类型和集合类型。
`bool` 表示布尔值。
+| 语言 | 类型 | 说明 |
+| ---------- | --------- | ---- |
+| Java | `boolean` | |
+| Python | `bool` | |
+| Go | `bool` | |
+| Rust | `bool` | |
+| C++ | `bool` | |
+| JavaScript | `boolean` | |
+| Dart | `bool` | |
+
#### Integer Types
支持有符号/无符号与不同位宽。跨语言场景建议明确编码策略并保持字段语义稳定。
+**有符号整数映射：**
+
+| Fory IDL | Java | Python | Go | Rust | C++ | JavaScript | Dart |
+| -------- | ------- | -------------- | ------- | ----- | --------- | ------------------ | ------- |
+| `int8` | `byte` | `pyfory.int8` | `int8` | `i8` | `int8_t` | `number` | `Int8` |
+| `int16` | `short` | `pyfory.int16` | `int16` | `i16` | `int16_t` | `number` | `Int16` |
+| `int32` | `int` | `pyfory.int32` | `int32` | `i32` | `int32_t` | `number` | `Int32` |
+| `int64` | `long` | `pyfory.int64` | `int64` | `i64` | `int64_t` | `bigint \| number` | `int` |
+
+**无符号整数映射：**
+
+| Fory IDL | Java | Python | Go | Rust | C++ | JavaScript | Dart |
+| -------- | ------- | --------------- | -------- | ----- | ---------- | ------------------ | -------- |
+| `uint8` | `short` | `pyfory.uint8` | `uint8` | `u8` | `uint8_t` | `number` | `UInt8` |
+| `uint16` | `int` | `pyfory.uint16` | `uint16` | `u16` | `uint16_t` | `number` | `UInt16` |
+| `uint32` | `long` | `pyfory.uint32` | `uint32` | `u32` | `uint32_t` | `number` | `UInt32` |
+| `uint64` | `long` | `pyfory.uint64` | `uint64` | `u64` | `uint64_t` | `bigint \| number` | `int` |
+
#### Integer Encoding Variants
常见编码：
@@ -547,28 +634,83 @@ Fory IDL 类型系统包括基础类型、命名类型和集合类型。
- `float32`
- `float64`
+| Fory IDL | Java | Python | Go | Rust | C++ | JavaScript | Dart |
+| --------- | -------- | ---------------- | --------- | ----- | -------- | ---------- | --------- |
+| `float32` | `float` | `pyfory.float32` | `float32` | `f32` | `float` | `number` | `Float32` |
+| `float64` | `double` | `pyfory.float64` | `float64` | `f64` | `double` | `number` | `double` |
+
#### String Type
`string` 使用 UTF-8 文本语义。
+| 语言 | 类型 | 说明 |
+| ---------- | ------------- | -------------------- |
+| Java | `String` | 不可变 |
+| Python | `str` | |
+| Go | `string` | 不可变 |
+| Rust | `String` | 所有权字符串，堆分配 |
+| C++ | `std::string` | |
+| JavaScript | `string` | |
+| Dart | `String` | |
+
#### Bytes Type
`bytes` 用于原始二进制载荷。
+| 语言 | 类型 | 说明 |
+| ---------- | ---------------------- | ------ |
+| Java | `byte[]` | |
+| Python | `bytes` | 不可变 |
+| Go | `[]byte` | |
+| Rust | `Vec<u8>` | |
+| C++ | `std::vector<uint8_t>` | |
+| JavaScript | `Uint8Array` | |
+| Dart | `Uint8List` | |
+
#### Temporal Types
##### Date
`date` 表示日期（不含时区时间部分）。
+| 语言 | 类型 | 说明 |
+| ---------- | --------------------------- | ----------------------- |
+| Java | `java.time.LocalDate` | |
+| Python | `datetime.date` | |
+| Go | `time.Time` | 会忽略时间部分 |
+| Rust | `chrono::NaiveDate` | 需依赖 `chrono` crate |
+| C++ | `fory::serialization::Date` | |
+| JavaScript | `Date` | |
+| Dart | `LocalDate` | Fory package 提供的类型 |
+
##### Timestamp
`timestamp` 表示时间点（跨语言应统一时间语义与精度预期）。
+| 语言 | 类型 | 说明 |
+| ---------- | -------------------------------- | ----------------------- |
+| Java | `java.time.Instant` | 基于 UTC |
+| Python | `datetime.datetime` | |
+| Go | `time.Time` | |
+| Rust | `chrono::NaiveDateTime` | 需依赖 `chrono` crate |
+| C++ | `fory::serialization::Timestamp` | |
+| JavaScript | `Date` | |
+| Dart | `Timestamp` | Fory package 提供的类型 |
+
#### Any
`any` 允许存储动态类型值。使用 `any` 时建议配合清晰的业务约束，避免滥用导致模型不稳定。
+| 语言 | 类型 | 说明 |
+| ---------- | -------------- | -------------- |
+| Java | `Object` | 写入运行时类型 |
+| Python | `Any` | 写入运行时类型 |
+| Go | `any` | 写入运行时类型 |
+| Rust | `Box<dyn Any>` | 写入运行时类型 |
+| C++ | `std::any` | 写入运行时类型 |
+| JavaScript | `any` | 写入运行时类型 |
+| Dart | `Object?` | 写入运行时类型 |
+
### Named Types
命名类型包括：
@@ -600,6 +742,11 @@ map<K, V>
- `K` 一般应为可稳定比较的标量类型
- `V` 可为任意支持类型
+| Fory IDL | Java | Python | Go | Rust | C++ | JavaScript | Dart |
+| -------------------- | ---------------------- | ----------------- | ------------------ | ----------------------- | -------------------------------- | --------------------- | -------------------- |
+| `map<string, int32>` | `Map<String, Integer>` | `Dict[str, int]` | `map[string]int32` | `HashMap<String, i32>` | `std::map<std::string, int32_t>` | `Map<string, number>` | `Map<String, Int32>` |
+| `map<string, User>` | `Map<String, User>` | `Dict[str, User]` | `map[string]User` | `HashMap<String, User>` | `std::map<std::string, User>` | `Map<string, User>` | `Map<String, User>` |
+
### Type Compatibility Matrix
跨语言建议：
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/cpp/_category_.json b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/cpp/_category_.json
index c543ab138..9660bafa8 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/cpp/_category_.json
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/cpp/_category_.json
@@ -1,6 +1,6 @@
{
"label": "C++",
- "position": 3,
+ "position": 4,
"collapsible": true,
"collapsed": true
}
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/scala/_category_.json b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/csharp/_category_.json
similarity index 76%
copy from i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/scala/_category_.json
copy to i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/csharp/_category_.json
index 6cc51ddde..c5e03ee3c 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/scala/_category_.json
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/csharp/_category_.json
@@ -1,5 +1,5 @@
{
- "label": "Scala",
+ "label": "C#",
"position": 7,
"collapsible": true,
"collapsed": true
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/csharp/basic-serialization.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/csharp/basic-serialization.md
new file mode 100644
index 000000000..ce8cd2e59
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/csharp/basic-serialization.md
@@ -0,0 +1,131 @@
+---
+title: 基础序列化
+sidebar_position: 1
+id: basic_serialization
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍 Apache Fory™ C# 的强类型序列化 API。
+
+## 对象图序列化
+
+在类或结构体上使用 `[ForyObject]`，并在使用前完成注册。
+
+```csharp
+using Apache.Fory;
+
+[ForyObject]
+public sealed class Address
+{
+ public string Street { get; set; } = string.Empty;
+ public int Zip { get; set; }
+}
+
+[ForyObject]
+public sealed class Person
+{
+ public long Id { get; set; }
+ public string Name { get; set; } = string.Empty;
+ public string? Nickname { get; set; }
+ public List<int> Scores { get; set; } = [];
+ public List<Address> Addresses { get; set; } = [];
+}
+
+Fory fory = Fory.Builder().Build();
+fory.Register<Address>(100);
+fory.Register<Person>(101);
+
+Person person = new()
+{
+ Id = 42,
+ Name = "Alice",
+ Nickname = null,
+ Scores = [10, 20, 30],
+ Addresses = [new Address { Street = "Main", Zip = 94107 }],
+};
+
+byte[] payload = fory.Serialize(person);
+Person decoded = fory.Deserialize<Person>(payload);
+```
+
+## 强类型 API
+
+### 使用字节数组进行 Serialize / Deserialize
+
+```csharp
+byte[] payload = fory.Serialize(value);
+MyType decoded = fory.Deserialize<MyType>(payload);
+```
+
+### 从 `ReadOnlySpan<byte>` 反序列化
+
+```csharp
+ReadOnlySpan<byte> span = payload;
+MyType decoded = fory.Deserialize<MyType>(span);
+```
+
+### 以流式方式消费帧
+
+```csharp
+using System.Buffers;
+
+ReadOnlySequence<byte> sequence = GetFramedSequence();
+MyType first = fory.Deserialize<MyType>(ref sequence);
+MyType second = fory.Deserialize<MyType>(ref sequence);
+```
+
+## 通过泛型对象 API 处理动态载荷
+
+当编译期类型未知或载荷包含异构对象时，可以配合 `object?` 使用泛型 API。
+
+```csharp
+Dictionary<object, object?> value = new()
+{
+ ["k1"] = 7,
+ [2] = "v2",
+ [true] = null,
+};
+
+byte[] payload = fory.Serialize<object?>(value);
+object? decoded = fory.Deserialize<object?>(payload);
+```
+
+## Buffer Writer API
+
+直接序列化到 `IBufferWriter<byte>` 目标。
+
+```csharp
+using System.Buffers;
+
+ArrayBufferWriter<byte> writer = new();
+fory.Serialize(writer, value);
+
+ArrayBufferWriter<byte> dynamicWriter = new();
+fory.Serialize<object?>(dynamicWriter, value);
+```
+
+## 说明
+
+- 复用同一个 `Fory` 或 `ThreadSafeFory` 实例可以获得更好的性能。
+- 基础类型和集合类型不需要用户手动注册。
+- 用户自定义的 `[ForyObject]` 类型和自定义序列化器类型应显式注册。
+
+## 相关主题
+
+- [类型注册](type-registration.md)
+- [支持的类型](supported-types.md)
+- [引用](references.md)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/csharp/configuration.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/csharp/configuration.md
new file mode 100644
index 000000000..9af3ce18e
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/csharp/configuration.md
@@ -0,0 +1,124 @@
+---
+title: 配置
+sidebar_position: 2
+id: configuration
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍 Apache Fory™ C# 的 `ForyBuilder` 选项和默认配置值。
+`Config` 是由 `ForyBuilder` 创建的不可变运行时快照。
+
+## 构建运行时
+
+```csharp
+using Apache.Fory;
+
+Fory fory = Fory.Builder().Build();
+ThreadSafeFory threadSafe = Fory.Builder().BuildThreadSafe();
+```
+
+## 默认配置
+
+`Fory.Builder().Build()` 使用以下默认值：
+
+| 选项 | 默认值 | 说明 |
+| -------------------- | -------- | ---------------------------------- |
+| `TrackRef` | `false` | 默认关闭引用跟踪 |
+| `Compatible` | `false` | Schema 一致模式，不写入演进元数据 |
+| `CheckStructVersion` | `false` | 默认关闭结构体 schema hash 校验 |
+| `MaxDepth` | `20` | 动态对象图的最大嵌套深度 |
+
+## 构建器选项
+
+C# 始终使用与 xlang 兼容的帧头，因此 `ForyBuilder` 不提供单独的 `Xlang(...)` 开关。
+
+### `TrackRef(bool enabled = false)`
+
+为共享对象图和循环对象图启用引用跟踪。
+
+```csharp
+Fory fory = Fory.Builder()
+ .TrackRef(true)
+ .Build();
+```
+
+### `Compatible(bool enabled = false)`
+
+启用 Schema 演进模式。
+
+```csharp
+Fory fory = Fory.Builder()
+ .Compatible(true)
+ .Build();
+```
+
+### `CheckStructVersion(bool enabled = false)`
+
+为生成的结构体序列化器启用严格的 schema hash 校验。
+
+```csharp
+Fory fory = Fory.Builder()
+ .CheckStructVersion(true)
+ .Build();
+```
+
+### `MaxDepth(int value)`
+
+设置动态对象图允许的最大嵌套深度。
+
+```csharp
+Fory fory = Fory.Builder()
+ .MaxDepth(32)
+ .Build();
+```
+
+`value` 必须大于 `0`。
+
+## 常见配置
+
+### 追求速度的 Schema 一致服务
+
+```csharp
+Fory fory = Fory.Builder()
+ .TrackRef(false)
+ .Compatible(false)
+ .Build();
+```
+
+### 兼容的跨语言服务
+
+```csharp
+Fory fory = Fory.Builder()
+ .Compatible(true)
+ .TrackRef(true)
+ .Build();
+```
+
+### 线程安全的服务实例
+
+```csharp
+ThreadSafeFory fory = Fory.Builder()
+ .Compatible(true)
+ .TrackRef(true)
+ .BuildThreadSafe();
+```
+
+## 相关主题
+
+- [基础序列化](basic_serialization)
+- [Schema 演进](schema_evolution)
+- [线程安全](thread_safety)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/csharp/cross-language.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/csharp/cross-language.md
new file mode 100644
index 000000000..1993b7112
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/csharp/cross-language.md
@@ -0,0 +1,105 @@
+---
+title: 跨语言序列化
+sidebar_position: 8
+id: cross_language
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Apache Fory™ C# 支持与其他 Fory 运行时进行跨语言序列化。
+
+## 跨语言运行时
+
+C# 始终会读写 xlang 帧头。它没有单独的 `Xlang(...)` 构建器选项，因此互操作代码只需要配置兼容模式、引用跟踪等其余运行时行为。
+
+```csharp
+Fory fory = Fory.Builder()
+ .Compatible(true)
+ .Build();
+```
+
+## 使用稳定 ID 注册
+
+```csharp
+[ForyObject]
+public sealed class Person
+{
+ public string Name { get; set; } = string.Empty;
+ public int Age { get; set; }
+}
+
+Fory fory = Fory.Builder()
+ .Compatible(true)
+ .Build();
+
+fory.Register<Person>(100);
+```
+
+请在所有语言中保持相同的 ID 映射。
+
+## 按命名空间和类型名注册
+
+```csharp
+fory.Register<Person>("com.example", "Person");
+```
+
+## 跨语言示例
+
+### C#（序列化端）
+
+```csharp
+Person person = new() { Name = "Alice", Age = 30 };
+byte[] payload = fory.Serialize(person);
+```
+
+### Java（反序列化端）
+
+```java
+Fory fory = Fory.builder()
+ .withLanguage(Language.XLANG)
+ .withRefTracking(true)
+ .build();
+
+fory.register(Person.class, 100);
+Person value = (Person) fory.deserialize(payloadFromCSharp);
+```
+
+### Python（反序列化端）
+
+```python
+import pyfory
+
+fory = pyfory.Fory(xlang=True, ref=True)
+fory.register_type(Person, type_id=100)
+value = fory.deserialize(payload_from_csharp)
+```
+
+## 类型映射参考
+
+完整映射请参见 [xlang 指南](../xlang/)。
+
+## 最佳实践
+
+1. 保持 type ID 稳定并做好文档记录。
+2. 在滚动升级时启用 `Compatible(true)`。
+3. 在读写两端都注册所有用户类型。
+4. 用真实载荷做端到端回环验证。
+
+## 相关主题
+
+- [类型注册](type_registration)
+- [Schema 演进](schema_evolution)
+- [支持的类型](supported_types)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/csharp/custom-serializers.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/csharp/custom-serializers.md
new file mode 100644
index 000000000..888b84d38
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/csharp/custom-serializers.md
@@ -0,0 +1,84 @@
+---
+title: 自定义序列化器
+sidebar_position: 4
+id: custom_serializers
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+当某个类型不是通过 `[ForyObject]` 生成，或者需要专门的编码方式时，可以使用自定义序列化器。
+
+## 实现 `Serializer<T>`
+
+```csharp
+using Apache.Fory;
+
+public sealed class Point
+{
+ public int X { get; set; }
+ public int Y { get; set; }
+}
+
+public sealed class PointSerializer : Serializer<Point>
+{
+ public override Point DefaultValue => new();
+
+ public override void WriteData(WriteContext context, in Point value, bool hasGenerics)
+ {
+ context.Writer.WriteVarInt32(value.X);
+ context.Writer.WriteVarInt32(value.Y);
+ }
+
+ public override Point ReadData(ReadContext context)
+ {
+ return new Point
+ {
+ X = context.Reader.ReadVarInt32(),
+ Y = context.Reader.ReadVarInt32(),
+ };
+ }
+}
+```
+
+## 注册序列化器
+
+```csharp
+Fory fory = Fory.Builder().Build();
+fory.Register<Point, PointSerializer>(200);
+
+Point value = new() { X = 10, Y = 20 };
+byte[] payload = fory.Serialize(value);
+Point decoded = fory.Deserialize<Point>(payload);
+```
+
+## 序列化器行为说明
+
+- `WriteData` / `ReadData` 只负责处理载荷内容。
+- 除非显式重写，否则引用标志和类型信息由基类 `Serializer<T>.Write` / `Read` 处理。
+- `DefaultValue` 用于空值或默认值回退路径。
+
+## 最佳实践
+
+1. 保持序列化器逻辑确定且读写对称。
+2. 对整数密集型载荷要有意识地选择 varint、fixed 或 tagged 编码。
+3. 在所有读写端都注册自定义序列化器。
+4. 对常规领域模型优先使用 `[ForyObject]` 生成的序列化器。
+
+## 相关主题
+
+- [类型注册](type-registration.md)
+- [字段配置](field-configuration.md)
+- [故障排查](troubleshooting.md)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/csharp/field-configuration.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/csharp/field-configuration.md
new file mode 100644
index 000000000..0b31b65b1
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/csharp/field-configuration.md
@@ -0,0 +1,75 @@
+---
+title: 字段配置
+sidebar_position: 5
+id: field_configuration
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍 C# 生成序列化器的字段级配置。
+
+## `[ForyObject]` 与 `[Field]`
+
+使用 `[ForyObject]` 启用 source generator 生成序列化器。使用 `[Field]` 可以为某个字段覆盖整数编码方式。
+
+```csharp
+using Apache.Fory;
+
+[ForyObject]
+public sealed class Metrics
+{
+ // 定长 32 位编码
+ [Field(Encoding = FieldEncoding.Fixed)]
+ public uint Count { get; set; }
+
+ // Tagged 64 位编码
+ [Field(Encoding = FieldEncoding.Tagged)]
+ public ulong TraceId { get; set; }
+
+ // 默认（varint）编码
+ public long LatencyMicros { get; set; }
+}
+```
+
+## 可用编码
+
+| 编码 | 含义 |
+| ---- | ---- |
+| `FieldEncoding.Varint` | 变长整数编码，默认值 |
+| `FieldEncoding.Fixed` | 定长整数编码 |
+| `FieldEncoding.Tagged` | Tagged 整数编码，仅支持 `long` / `ulong` |
+
+## 支持覆盖编码的字段类型
+
+`[Field(Encoding = ...)]` 当前可应用于：
+
+- `int`
+- `uint`
+- `long`
+- `ulong`
+
+可空值类型变体，例如 `long?`，也会由生成的序列化器处理。
+
+## 可空性与引用跟踪
+
+- 字段可空性来自 C# 类型的可空声明，例如 `string?`、可空值类型等。
+- 引用跟踪由运行时的 `ForyBuilder.TrackRef(...)` 控制。
+
+## 相关主题
+
+- [配置](configuration.md)
+- [Schema 演进](schema-evolution.md)
+- [支持的类型](supported-types.md)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/csharp/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/csharp/index.md
index 30f8b06dc..cf694ae62 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/csharp/index.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/csharp/index.md
@@ -85,17 +85,17 @@ User decoded = fory.Deserialize<User>(payload);
| 主题 | 说明 |
| --------------------------------------------- | ---------------------------------- |
-| [配置](https://fory.apache.org/docs/guide/csharp/configuration) | 构建器选项与运行时模式 |
-| [基础序列化](https://fory.apache.org/docs/guide/csharp/basic-serialization) | 强类型和动态序列化 API |
-| [类型注册](https://fory.apache.org/docs/guide/csharp/type-registration) | 注册用户类型和自定义序列化器 |
-| [自定义序列化器](https://fory.apache.org/docs/guide/csharp/custom-serializers) | 实现 `Serializer<T>` |
-| [字段配置](https://fory.apache.org/docs/guide/csharp/field-configuration) | `[Field]` 特性与整数编码选项 |
-| [引用](https://fory.apache.org/docs/guide/csharp/references) | 共享引用与循环引用处理 |
-| [Schema 演进](https://fory.apache.org/docs/guide/csharp/schema-evolution) | 兼容模式行为 |
-| [跨语言](https://fory.apache.org/docs/guide/csharp/cross-language) | 互操作性指导 |
-| [支持的类型](https://fory.apache.org/docs/guide/csharp/supported-types) | 内置类型与生成类型支持 |
-| [线程安全](https://fory.apache.org/docs/guide/csharp/thread-safety) | `Fory` 与 `ThreadSafeFory` 的用法 |
-| [故障排查](https://fory.apache.org/docs/guide/csharp/troubleshooting) | 常见错误与调试步骤 |
+| [配置](configuration.md) | 构建器选项与运行时模式 |
+| [基础序列化](basic-serialization.md) | 强类型和动态序列化 API |
+| [类型注册](type-registration.md) | 注册用户类型和自定义序列化器 |
+| [自定义序列化器](custom-serializers.md) | 实现 `Serializer<T>` |
+| [字段配置](field-configuration.md) | `[Field]` 特性与整数编码选项 |
+| [引用](references.md) | 共享引用与循环引用处理 |
+| [Schema 演进](schema-evolution.md) | 兼容模式行为 |
+| [跨语言](cross-language.md) | 互操作性指导 |
+| [支持的类型](supported-types.md) | 内置类型与生成类型支持 |
+| [线程安全](thread-safety.md) | `Fory` 与 `ThreadSafeFory` 的用法 |
+| [故障排查](troubleshooting.md) | 常见错误与调试步骤 |
## 相关资源
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/csharp/references.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/csharp/references.md
new file mode 100644
index 000000000..bdbf56d28
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/csharp/references.md
@@ -0,0 +1,72 @@
+---
+title: 引用
+sidebar_position: 6
+id: references
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+当启用 `TrackRef(true)` 时，Apache Fory™ C# 可以保留共享引用和循环引用。
+
+## 启用引用跟踪
+
+```csharp
+Fory fory = Fory.Builder()
+ .TrackRef(true)
+ .Build();
+```
+
+启用后：
+
+- 共享对象身份会被保留。
+- 循环对象图可以安全地序列化和反序列化。
+
+## 循环引用示例
+
+```csharp
+using Apache.Fory;
+
+[ForyObject]
+public sealed class Node
+{
+ public int Value { get; set; }
+ public Node? Next { get; set; }
+}
+
+Fory fory = Fory.Builder()
+ .TrackRef(true)
+ .Build();
+fory.Register<Node>(200);
+
+Node node = new() { Value = 7 };
+node.Next = node;
+
+byte[] payload = fory.Serialize(node);
+Node decoded = fory.Deserialize<Node>(payload);
+
+// The cycle is preserved.
+System.Diagnostics.Debug.Assert(object.ReferenceEquals(decoded, decoded.Next));
+```
+
+## 何时使用 `TrackRef(false)`
+
+对于树状、无环且不关心引用身份的数据，`TrackRef(false)` 往往更快。
+
+## 相关主题
+
+- [配置](configuration.md)
+- [基础序列化](basic-serialization.md)
+- [线程安全](thread-safety.md)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/csharp/schema-evolution.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/csharp/schema-evolution.md
new file mode 100644
index 000000000..6531eb540
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/csharp/schema-evolution.md
@@ -0,0 +1,90 @@
+---
+title: Schema 演进
+sidebar_position: 7
+id: schema_evolution
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Apache Fory™ C# 在 `Compatible(true)` 模式下支持 Schema 演进。
+
+## 兼容模式
+
+```csharp
+Fory fory = Fory.Builder()
+ .Compatible(true)
+ .Build();
+```
+
+兼容模式会写入类型元信息，使结构体定义不同的读写端也能互操作。
+
+## 示例：新增一个字段
+
+```csharp
+using Apache.Fory;
+
+[ForyObject]
+public sealed class OneStringField
+{
+ public string? F1 { get; set; }
+}
+
+[ForyObject]
+public sealed class TwoStringField
+{
+ public string F1 { get; set; } = string.Empty;
+ public string F2 { get; set; } = string.Empty;
+}
+
+Fory fory1 = Fory.Builder().Compatible(true).Build();
+fory1.Register<OneStringField>(200);
+
+Fory fory2 = Fory.Builder().Compatible(true).Build();
+fory2.Register<TwoStringField>(200);
+
+byte[] payload = fory1.Serialize(new OneStringField { F1 = "hello" });
+TwoStringField evolved = fory2.Deserialize<TwoStringField>(payload);
+
+// F2 falls back to default value on reader side.
+System.Diagnostics.Debug.Assert(evolved.F1 == "hello");
+System.Diagnostics.Debug.Assert(evolved.F2 == string.Empty);
+```
+
+## 带版本校验的 Schema 一致模式
+
+如果你需要严格的 Schema 身份校验，而不是演进行为：
+
+```csharp
+Fory strict = Fory.Builder()
+ .Compatible(false)
+ .CheckStructVersion(true)
+ .Build();
+```
+
+这种模式会在 schema hash 不匹配时抛出异常。
+
+## 最佳实践
+
+1. 对独立部署的服务启用 `Compatible(true)`。
+2. 在不同版本之间保持稳定的 type ID。
+3. 新增字段时提供安全的默认值。
+4. 如果要求严格匹配，使用 `CheckStructVersion(true)`。
+
+## 相关主题
+
+- [配置](configuration.md)
+- [类型注册](type-registration.md)
+- [故障排查](troubleshooting.md)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/csharp/supported-types.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/csharp/supported-types.md
new file mode 100644
index 000000000..20baf0b41
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/csharp/supported-types.md
@@ -0,0 +1,97 @@
+---
+title: 支持的类型
+sidebar_position: 9
+id: supported_types
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页汇总 Apache Fory™ C# 的内置类型支持和生成类型支持。
+
+## 基础类型
+
+| C# 类型 | 说明 |
+| ------- | ---- |
+| `bool` | 支持 |
+| `sbyte`, `short`, `int`, `long` | 支持 |
+| `byte`, `ushort`, `uint`, `ulong` | 支持 |
+| `float`, `double` | 支持 |
+| `string` | 支持 |
+| `byte[]` | 支持 |
+| 可空基础类型，例如 `int?` | 支持 |
+
+## 数组
+
+- 基础数值数组，例如 `bool[]`、`int[]`、`ulong[]`
+- `byte[]`
+- 通过集合序列化器支持的一般数组 `T[]`
+
+## 集合
+
+### 类 List
+
+- `List<T>`
+- `LinkedList<T>`
+- `Queue<T>`
+- `Stack<T>`
+
+### 类 Set
+
+- `HashSet<T>`
+- `SortedSet<T>`
+- `ImmutableHashSet<T>`
+
+### 类 Map
+
+- `Dictionary<TKey, TValue>`
+- `SortedDictionary<TKey, TValue>`
+- `SortedList<TKey, TValue>`
+- `ConcurrentDictionary<TKey, TValue>`
+- `NullableKeyDictionary<TKey, TValue>`
+
+## 时间类型
+
+| C# 类型 | 编码类型 |
+| ------- | -------- |
+| `DateOnly` | `Date` |
+| `DateTime` | `Timestamp` |
+| `DateTimeOffset` | `Timestamp` |
+| `TimeSpan` | `Duration` |
+
+## 用户类型
+
+- 通过 source generator 生成序列化器的 `[ForyObject]` 类、结构体、枚举
+- 通过 `Register<T, TSerializer>(...)` 注册的自定义序列化器类型
+- `Union` / `Union2<...>` 强类型联合支持
+
+## 动态类型
+
+通过 `Serialize<object?>` / `Deserialize<object?>` 处理动态对象载荷时，支持：
+
+- 基础值和对象值
+- 动态列表、集合、映射
+- 嵌套的动态结构
+
+## 说明
+
+- 用户自定义类型应显式注册。
+- 跨语言使用时，请遵循 [xlang 指南](../xlang/index.md)。
+
+## 相关主题
+
+- [基础序列化](basic-serialization.md)
+- [类型注册](type-registration.md)
+- [跨语言](cross-language.md)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/csharp/thread-safety.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/csharp/thread-safety.md
new file mode 100644
index 000000000..5c2a33917
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/csharp/thread-safety.md
@@ -0,0 +1,73 @@
+---
+title: 线程安全
+sidebar_position: 10
+id: thread_safety
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Apache Fory™ C# 提供两种运行时形态，它们的线程保证不同。
+
+## `Fory`（单线程运行时）
+
+`Fory` 针对单线程复用做了优化，不能被多个线程并发使用。
+
+```csharp
+Fory fory = Fory.Builder().Build();
+```
+
+如果你显式管理线程亲和性，可以为每个线程分配一个 `Fory` 实例。
+
+## `ThreadSafeFory`（并发封装）
+
+`ThreadSafeFory` 为每个线程封装一个 `Fory` 实例，并对外提供线程安全 API。
+
+```csharp
+using Apache.Fory;
+
+using ThreadSafeFory fory = Fory.Builder()
+ .Compatible(true)
+ .TrackRef(true)
+ .BuildThreadSafe();
+
+fory.Register<MyType>(100);
+
+Parallel.For(0, 64, i =>
+{
+ byte[] payload = fory.Serialize(i);
+ int decoded = fory.Deserialize<int>(payload);
+});
+```
+
+## 注册行为
+
+- `ThreadSafeFory.Register(...)` 会集中保存注册信息。
+- 已存在的线程内运行时会被更新。
+- 新线程会自动收到此前所有注册信息。
+
+## 释放资源
+
+`ThreadSafeFory` 实现了 `IDisposable`，在不再使用时应及时释放。
+
+```csharp
+using ThreadSafeFory fory = Fory.Builder().BuildThreadSafe();
+```
+
+## 相关主题
+
+- [配置](configuration.md)
+- [类型注册](type-registration.md)
+- [引用](references.md)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/csharp/troubleshooting.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/csharp/troubleshooting.md
new file mode 100644
index 000000000..0a9212b3d
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/csharp/troubleshooting.md
@@ -0,0 +1,92 @@
+---
+title: 故障排查
+sidebar_position: 11
+id: troubleshooting
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍常见的 C# 运行时问题及其解决方法。
+
+## `TypeNotRegisteredException`
+
+**现象**：`Type not registered: ...`
+
+**原因**：用户类型在没有注册的情况下被序列化或反序列化。
+
+**修复方式**：
+
+```csharp
+Fory fory = Fory.Builder().Build();
+fory.Register<MyType>(100);
+```
+
+请确保读写两端使用相同的 type-ID 或名称映射。
+
+## `InvalidDataException: xlang bitmap mismatch`
+
+**原因**：载荷不是 xlang Fory 帧，或者它来自不输出 C# 所要求 xlang 头的对端或运行时模式。
+
+**修复方式**：确保载荷由与 xlang 兼容的 Fory 运行时生成。C# 始终要求 xlang 头，并且不提供单独的 `Xlang(...)` 构建器选项。
+
+```csharp
+Fory writer = Fory.Builder().Compatible(true).Build();
+Fory reader = Fory.Builder().Compatible(true).Build();
+```
+
+## 严格模式下的 Schema 版本不匹配
+
+**现象**：反序列化生成的结构体类型时抛出 `InvalidDataException`。
+
+**原因**：`Compatible(false)` 配合 `CheckStructVersion(true)` 时会要求 schema hash 完全一致。
+
+**可选修复方式**：
+
+- 启用 `Compatible(true)` 以支持 Schema 演进。
+- 保持写端和读端的模型定义同步。
+
+## 循环引用失败
+
+**现象**：类似栈溢出的递归问题，或者对象图重建异常。
+
+**原因**：循环对象图在 `TrackRef(false)` 下运行。
+
+**修复方式**：
+
+```csharp
+Fory fory = Fory.Builder().TrackRef(true).Build();
+```
+
+## 并发问题
+
+**原因**：在多个线程之间共享同一个 `Fory` 实例。
+
+**修复方式**：改用 `BuildThreadSafe()`。
+
+## 验证命令
+
+从仓库根目录运行 C# 测试：
+
+```bash
+cd csharp
+dotnet test Fory.sln -c Release
+```
+
+## 相关主题
+
+- [配置](configuration)
+- [Schema 演进](schema_evolution)
+- [线程安全](thread_safety)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/csharp/type-registration.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/csharp/type-registration.md
new file mode 100644
index 000000000..1afbf05c6
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/csharp/type-registration.md
@@ -0,0 +1,82 @@
+---
+title: 类型注册
+sidebar_position: 3
+id: type_registration
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍如何在 Apache Fory™ C# 中注册用户类型。
+
+## 按数字 type ID 注册
+
+显式 ID 可以提供紧凑且稳定的跨服务映射。
+
+```csharp
+Fory fory = Fory.Builder().Build();
+fory.Register<User>(100);
+fory.Register<Order>(101);
+```
+
+## 按类型名注册
+
+如果你更倾向于使用符号化映射，可以按命名空间和类型名注册。
+
+```csharp
+Fory fory = Fory.Builder().Build();
+fory.Register<User>("com.example", "User");
+```
+
+也可以使用简写重载：
+
+```csharp
+fory.Register<User>("User");
+```
+
+## 注册自定义序列化器
+
+```csharp
+Fory fory = Fory.Builder().Build();
+fory.Register<MyType, MyTypeSerializer>(200);
+```
+
+同样支持基于命名空间的自定义序列化器注册：
+
+```csharp
+fory.Register<MyType, MyTypeSerializer>("com.example", "MyType");
+```
+
+## 线程安全注册
+
+`ThreadSafeFory` 提供相同的注册 API。注册信息会传播到各个线程内运行时。
+
+```csharp
+using ThreadSafeFory fory = Fory.Builder().BuildThreadSafe();
+fory.Register<User>(100);
+fory.Register<Order>(101);
+```
+
+## 注册规则
+
+- 在写端和读端都要注册用户定义类型。
+- 在服务和语言之间保持 ID 或名称映射一致。
+- 在高频序列化负载开始前完成注册，避免运行时缺失。
+
+## 相关主题
+
+- [基础序列化](basic-serialization.md)
+- [自定义序列化器](custom-serializers.md)
+- [跨语言](cross-language.md)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/go/_category_.json b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/go/_category_.json
index 796c0a4dd..e4d176a76 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/go/_category_.json
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/go/_category_.json
@@ -1,6 +1,6 @@
{
"label": "Go",
- "position": 4,
+ "position": 5,
"collapsible": true,
"collapsed": true
}
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/go/codegen.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/go/codegen.md
index 67c338e52..e9e7a2748 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/go/codegen.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/go/codegen.md
@@ -20,36 +20,36 @@ license: |
---
:::warning Experimental Feature
-Code generation is an **experimental** feature in Fory Go. The API and behavior may change in future releases. The reflection-based path remains the stable, recommended approach for most use cases.
+代码生成是 Fory Go 中的**实验性**特性。其 API 和行为可能会在后续版本中发生变化。标准运行时路径仍是大多数场景下稳定且推荐的做法。
:::
-Fory Go 为性能关键路径提供可选的 AOT 代码生成，可消除反射开销并提升编译期类型安全。
+Fory Go 为性能关键路径提供可选的 AOT 代码生成。它会提前生成专用序列化器，并增加编译期 shape 校验。
## 为什么使用代码生成？
-| Aspect | Reflection-Based | Code Generation |
-| ----------- | ------------------ | ---------------------- |
-| Setup | Zero configuration | Requires `go generate` |
-| Performance | Good | Better (no reflection) |
-| Type Safety | Runtime | Compile-time |
-| Maintenance | Automatic | Requires regeneration |
+| 方面 | 标准路径 | 代码生成 |
+| -------- | ---------------- | ---------------------- |
+| 接入成本 | 零配置 | 需要 `go generate` |
+| 性能 | 已经很优秀 | 热路径上更快 |
+| 类型安全 | 运行时校验 | 编译期校验 |
+| 维护成本 | 自动完成 | 需要重新生成 |
-**Use code generation when**:
+**适合使用代码生成的场景：**
-- Maximum performance is required
-- Compile-time type safety is important
-- Hot paths are performance-critical
+- 需要极致性能
+- 很看重编译期类型安全
+- 热路径对性能非常敏感
-**Use reflection when**:
+**适合继续使用标准路径的场景：**
-- Simple setup is preferred
-- Types change frequently
-- Dynamic typing is needed
-- Code generation complexity is undesirable
+- 更偏好简单接入
+- 类型经常变化
+- 需要动态类型
+- 不希望引入代码生成复杂度
## 安装
-Install the `fory` generator binary:
+安装 `fory` 生成器二进制：
```bash
go install github.com/apache/fory/go/fory/cmd/fory@latest
@@ -57,13 +57,13 @@ go install github.com/apache/fory/go/fory/cmd/fory@latest
GO111MODULE=on go get -u github.com/apache/fory/go/fory/cmd/fory
```
-Ensure `$GOBIN` or `$GOPATH/bin` is in your `PATH`.
+确保 `$GOBIN` 或 `$GOPATH/bin` 已加入 `PATH`。
## 基本用法
-### Step 1: Annotate Structs
+### 步骤 1：标注结构体
-Add the `//fory:generate` comment above structs:
+在结构体上方添加 `//fory:generate` 注释：
```go
package models
@@ -82,35 +82,35 @@ type Order struct {
}
```
-### Step 2: Add Go Generate Directive
+### 步骤 2：添加 Go Generate 指令
-Add a `go:generate` directive (once per file or package):
+添加 `go:generate` 指令（每个文件或每个包一次即可）：
```go
//go:generate fory -file models.go
```
-Or for the entire package:
+或者针对整个包：
```go
//go:generate fory -pkg .
```
-### Step 3: Run Code Generation
+### 步骤 3：执行代码生成
```bash
go generate ./...
```
-This creates `models_fory_gen.go` with generated serializers.
+这会生成包含序列化器代码的 `models_fory_gen.go` 文件。
-## 生成代码结构
+## 生成代码的结构
-The generator creates:
+生成器会输出以下内容：
-### Type Snapshot
+### 类型快照
... 3472 lines suppressed ...
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@fory.apache.org
For additional commands, e-mail: commits-help@fory.apache.org
(fory-site) 04/09: Bump current docs to 0.17.0
Posted by ch...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
chaokunyang pushed a commit to branch release_0.17.0
in repository https://gitbox.apache.org/repos/asf/fory-site.git
commit 60dec090804a03c7ce8279fe9168b23cdbd61290
Author: 慕白 <ch...@antgroup.com>
AuthorDate: Sun Apr 19 22:58:36 2026 +0800
Bump current docs to 0.17.0
---
docs/guide/cpp/index.md | 8 ++++----
docs/guide/csharp/index.md | 2 +-
docs/guide/java/compression.md | 2 +-
docs/guide/kotlin/index.md | 4 ++--
docs/guide/rust/index.md | 2 +-
docs/guide/scala/index.md | 2 +-
docs/guide/xlang/getting-started.md | 6 +++---
docs/start/install.md | 30 +++++++++++++++---------------
8 files changed, 28 insertions(+), 28 deletions(-)
diff --git a/docs/guide/cpp/index.md b/docs/guide/cpp/index.md
index 344820bb0..193cb7a8b 100644
--- a/docs/guide/cpp/index.md
+++ b/docs/guide/cpp/index.md
@@ -59,7 +59,7 @@ include(FetchContent)
FetchContent_Declare(
fory
GIT_REPOSITORY https://github.com/apache/fory.git
- GIT_TAG v0.15.0
+ GIT_TAG v0.17.0
SOURCE_SUBDIR cpp
)
FetchContent_MakeAvailable(fory)
@@ -89,11 +89,11 @@ module(
bazel_dep(name = "rules_cc", version = "0.1.1")
-bazel_dep(name = "fory", version = "0.16.0")
+bazel_dep(name = "fory", version = "0.17.0")
git_override(
module_name = "fory",
remote = "https://github.com/apache/fory.git",
- commit = "v0.15.0", # Or use a specific commit hash for reproducibility
+ commit = "v0.17.0", # Or use a specific commit hash for reproducibility
)
```
@@ -117,7 +117,7 @@ bazel run //:my_app
For local development, you can use `local_path_override` instead:
```bazel
-bazel_dep(name = "fory", version = "0.16.0")
+bazel_dep(name = "fory", version = "0.17.0")
local_path_override(
module_name = "fory",
path = "/path/to/fory",
diff --git a/docs/guide/csharp/index.md b/docs/guide/csharp/index.md
index 8aac393f5..95bcac2ac 100644
--- a/docs/guide/csharp/index.md
+++ b/docs/guide/csharp/index.md
@@ -43,7 +43,7 @@ Reference the single `Apache.Fory` package. It includes the runtime and the sour
```xml
<ItemGroup>
- <PackageReference Include="Apache.Fory" Version="0.16.0" />
+ <PackageReference Include="Apache.Fory" Version="0.17.0" />
</ItemGroup>
```
diff --git a/docs/guide/java/compression.md b/docs/guide/java/compression.md
index 88cfb70a6..cbe344f00 100644
--- a/docs/guide/java/compression.md
+++ b/docs/guide/java/compression.md
@@ -84,7 +84,7 @@ CompressedArraySerializers.registerSerializers(fory);
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-simd</artifactId>
- <version>0.16.0</version>
+ <version>0.17.0</version>
</dependency>
```
diff --git a/docs/guide/kotlin/index.md b/docs/guide/kotlin/index.md
index 16254686a..1fcee0430 100644
--- a/docs/guide/kotlin/index.md
+++ b/docs/guide/kotlin/index.md
@@ -50,14 +50,14 @@ See [Java Features](../java/index.md#features) for complete feature list.
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-kotlin</artifactId>
- <version>0.16.0</version>
+ <version>0.17.0</version>
</dependency>
```
### Gradle
```kotlin
-implementation("org.apache.fory:fory-kotlin:0.16.0")
+implementation("org.apache.fory:fory-kotlin:0.17.0")
```
## Quick Start
diff --git a/docs/guide/rust/index.md b/docs/guide/rust/index.md
index d52a45d52..7e17d6adc 100644
--- a/docs/guide/rust/index.md
+++ b/docs/guide/rust/index.md
@@ -47,7 +47,7 @@ Add Apache Fory™ to your `Cargo.toml`:
```toml
[dependencies]
-fory = "0.13"
+fory = "0.17.0"
```
### Basic Example
diff --git a/docs/guide/scala/index.md b/docs/guide/scala/index.md
index f99782d54..60d5da14c 100644
--- a/docs/guide/scala/index.md
+++ b/docs/guide/scala/index.md
@@ -48,7 +48,7 @@ See [Java Features](../java/index.md#features) for complete feature list.
Add the dependency with sbt:
```sbt
-libraryDependencies += "org.apache.fory" %% "fory-scala" % "0.16.0"
+libraryDependencies += "org.apache.fory" %% "fory-scala" % "0.17.0"
```
## Quick Start
diff --git a/docs/guide/xlang/getting-started.md b/docs/guide/xlang/getting-started.md
index e6a4964ff..039a00a3a 100644
--- a/docs/guide/xlang/getting-started.md
+++ b/docs/guide/xlang/getting-started.md
@@ -31,14 +31,14 @@ This guide covers installation and basic setup for cross-language serialization
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-core</artifactId>
- <version>0.16.0</version>
+ <version>0.17.0</version>
</dependency>
```
**Gradle:**
```gradle
-implementation 'org.apache.fory:fory-core:0.16.0'
+implementation 'org.apache.fory:fory-core:0.17.0'
```
### Python
@@ -57,7 +57,7 @@ go get github.com/apache/fory/go/fory
```toml
[dependencies]
-fory = "0.13"
+fory = "0.17.0"
```
### JavaScript
diff --git a/docs/start/install.md b/docs/start/install.md
index 3c93af80d..5c3d3e37f 100644
--- a/docs/start/install.md
+++ b/docs/start/install.md
@@ -16,14 +16,14 @@ Use Maven to add Apache Fory™:
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-core</artifactId>
- <version>0.16.0</version>
+ <version>0.17.0</version>
</dependency>
<!-- Optional row format support -->
<!--
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-format</artifactId>
- <version>0.16.0</version>
+ <version>0.17.0</version>
</dependency>
-->
<!-- SIMD acceleration for array compression (Java 16+) -->
@@ -31,7 +31,7 @@ Use Maven to add Apache Fory™:
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-simd</artifactId>
- <version>0.16.0</version>
+ <version>0.17.0</version>
</dependency>
-->
```
@@ -44,7 +44,7 @@ Scala 2.13 with Maven:
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-scala_2.13</artifactId>
- <version>0.16.0</version>
+ <version>0.17.0</version>
</dependency>
```
@@ -54,20 +54,20 @@ Scala 3 with Maven:
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-scala_3</artifactId>
- <version>0.16.0</version>
+ <version>0.17.0</version>
</dependency>
```
Scala 2.13 with sbt:
```sbt
-libraryDependencies += "org.apache.fory" % "fory-scala_2.13" % "0.16.0"
+libraryDependencies += "org.apache.fory" % "fory-scala_2.13" % "0.17.0"
```
Scala 3 with sbt:
```sbt
-libraryDependencies += "org.apache.fory" % "fory-scala_3" % "0.16.0"
+libraryDependencies += "org.apache.fory" % "fory-scala_3" % "0.17.0"
```
## Kotlin
@@ -78,7 +78,7 @@ Add Apache Fory™ Kotlin with Maven:
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-kotlin</artifactId>
- <version>0.16.0</version>
+ <version>0.17.0</version>
</dependency>
```
@@ -86,7 +86,7 @@ Add Apache Fory™ Kotlin with Maven:
```bash
python -m pip install --upgrade pip
-pip install pyfory==0.16.0
+pip install pyfory==0.17.0
```
## Go
@@ -94,7 +94,7 @@ pip install pyfory==0.16.0
Use the full Go module path `github.com/apache/fory/go/fory`:
```bash
-go get github.com/apache/fory/go/fory@v0.16.0
+go get github.com/apache/fory/go/fory@v0.17.0
```
If your Go proxy has not picked up the new submodule tag yet, retry later or use `GOPROXY=direct` temporarily.
@@ -103,13 +103,13 @@ If your Go proxy has not picked up the new submodule tag yet, retry later or use
```toml
[dependencies]
-fory = "0.16.0"
+fory = "0.17.0"
```
Or use `cargo add`:
```bash
-cargo add fory@0.16.0
+cargo add fory@0.17.0
```
## JavaScript
@@ -139,12 +139,12 @@ npm run build
Install the `Apache.Fory` NuGet package. It includes both the runtime and the source generator for `[ForyObject]` types.
```bash
-dotnet add package Apache.Fory --version 0.16.0
+dotnet add package Apache.Fory --version 0.17.0
```
```xml
<ItemGroup>
- <PackageReference Include="Apache.Fory" Version="0.16.0" />
+ <PackageReference Include="Apache.Fory" Version="0.17.0" />
</ItemGroup>
```
@@ -154,7 +154,7 @@ Add Apache Fory™ from the GitHub repository with Swift Package Manager:
```swift
dependencies: [
- .package(url: "https://github.com/apache/fory.git", exact: "0.16.0")
+ .package(url: "https://github.com/apache/fory.git", exact: "0.17.0")
],
targets: [
.target(
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@fory.apache.org
For additional commands, e-mail: commits-help@fory.apache.org