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: 慕白 <[email protected]> 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 = "[email protected]", +}; + +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/[email protected] +go get github.com/apache/fory/go/[email protected] ``` -如果你的 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 [email protected] +cargo add [email protected] ``` ## 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: [email protected] For additional commands, e-mail: [email protected]
