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/07/31 10:00:57 UTC
(fory-site) branch udpate-rust_zh_blog created (now ed57b330b5)
This is an automated email from the ASF dual-hosted git repository.
chaokunyang pushed a change to branch udpate-rust_zh_blog
in repository https://gitbox.apache.org/repos/asf/fory-site.git
at ed57b330b5 docs(zh-CN): refresh Fory Rust framework blog
This branch includes the following new commits:
new ed57b330b5 docs(zh-CN): refresh Fory Rust framework blog
The 1 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) 01/01: docs(zh-CN): refresh Fory Rust framework blog
Posted by ch...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
chaokunyang pushed a commit to branch udpate-rust_zh_blog
in repository https://gitbox.apache.org/repos/asf/fory-site.git
commit ed57b330b5494c6c2cd4b660d200e0db854a76ec
Author: chaokunyang <sh...@gmail.com>
AuthorDate: Fri Jul 31 18:00:36 2026 +0800
docs(zh-CN): refresh Fory Rust framework blog
---
...-fory_rust_versatile_serialization_framework.md | 560 +++++++++++----------
1 file changed, 294 insertions(+), 266 deletions(-)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-blog/2025-10-29-fory_rust_versatile_serialization_framework.md b/i18n/zh-CN/docusaurus-plugin-content-blog/2025-10-29-fory_rust_versatile_serialization_framework.md
index bd36818345..68dc72c0e4 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-blog/2025-10-29-fory_rust_versatile_serialization_framework.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-blog/2025-10-29-fory_rust_versatile_serialization_framework.md
@@ -1,358 +1,413 @@
---
slug: fory_rust_versatile_serialization_framework
-title: "重磅发布：Apache Fory™ Rust，面向现代开发的全能序列化框架"
+title: "隆重推出 Apache Fory™ Rust：面向现代应用的全能序列化框架"
authors: [chaokunyang]
tags: [fory, rust]
---
-**TL;DR**：Apache Fory Rust 让跨语言序列化同时拥有顶级性能与顺滑开发体验。它以 Rust 的安全模型为基础，通过零拷贝、自动引用管理和自适应 schema 演进，处理循环引用、trait 对象、多语言互通等棘手场景而无需额外样板代码。
+**TL;DR**：Apache Fory Rust 是一个速度极快的跨语言序列化框架，在提供**超高序列化性能**的同时，支持**共享与循环引用、trait 对象、Schema 演进、行格式访问和外部类型**。它以 Rust 的安全保证和编译期代码生成为基础，专为不愿在性能与开发体验之间妥协的开发者而设计。
- 🐙 GitHub: https://github.com/apache/fory
- 📦 Crate: https://crates.io/crates/fory
-
+<img src="/img/fory-logo-light.png" width="50%"/>
---
-## 序列化的三难选择
+## 序列化困境
-后台工程师迟早会撞上这堵墙：系统里充满嵌套结构、循环引用、运行时多态，你却只能在以下三种糟糕方案里挑一个：
+每一位后端工程师都遇到过这样的时刻：应用需要序列化嵌套对象、循环引用、多态类型等复杂数据结构，却不得不在三种糟糕的方案中做出选择：
-1. **速度快却脆弱**：手写二进制协议，一遇到 schema 变动就整体崩塌
-2. **灵活却迟钝**：JSON、Protocol Buffers 性能动辄慢一个数量级
-3. **功能全却掣肘**：现成框架不理解你语言里的高级抽象
+1. **快但脆弱**：手写二进制格式，一旦 Schema 变化就可能失效
+2. **灵活但缓慢**：文本格式会带来显著的运行时开销
+3. **复杂且受限**：现有方案无法支持语言中的高级特性
-Apache Fory Rust 把这个难题彻底推翻：不需要 IDL、不用同步 schema，也无需牺牲吞吐量，就能把复杂对象牢牢握在手里。
+Apache Fory Rust 终结了这种非此即彼的选择。它在处理现代应用复杂性的同时提供出色性能：Rust 原生开发可直接派生 Schema；当团队需要跨语言生成类型时，也可以选择共享 IDL。
-## Apache Fory Rust 的独到之处
+## Apache Fory Rust 有何不同？
### 1. **真正的跨语言互操作**
-Fory Rust 与 Java、Python、C++、Go 等官方实现走的是同一套二进制协议。Rust 里写入、Python 里读出，二进制直接通用，无需生成代码，也不存在版本错配。
+Apache Fory Rust 与 Java、Python、C++、Go、C#、Swift、Dart 等语言实现使用同一套二进制协议。只需在两端注册匹配的 Schema，就可以在 Rust 中序列化数据，再由另一种语言通过同一种紧凑二进制格式完成反序列化。
```rust
-// Rust: Serialize
+use fory::{Fory, ForyStruct};
+use std::collections::HashMap;
+
+#[derive(ForyStruct)]
+struct User {
+ name: String,
+ age: i32,
+ metadata: HashMap<String, String>,
+}
+
+let mut fory = Fory::builder().xlang(true).build();
+fory.register::<User>(100)?;
+
let user = User {
name: "Alice".to_string(),
age: 30,
- metadata: HashMap::from([("role", "admin")]),
+ metadata: HashMap::from([(
+ "role".to_string(),
+ "admin".to_string(),
+ )]),
};
-let bytes = fory.serialize(&user);
-
-// Python: Deserialize (same binary format!)
-user = fory.deserialize(bytes) # Just works!
+let bytes = fory.serialize(&user)?;
+// 在另一种 Fory 运行时中注册匹配类型，然后反序列化 `bytes`。
```
-跨语言序列化因此变成产品级的可靠能力，而非勉强达成的工程妥协。
+这不只是使用方便，它还会改变我们构建多语言微服务架构的方式。数字 ID 能提供更紧凑的类型元信息，而稳定的注册名称则便于彼此独立的服务团队进行协调。
-### 2. **共享与循环引用一网打尽**
+### 2. **自动处理共享与循环引用**
-多数序列化库遇到循环引用就报错。Fory 会在编解码阶段自动追踪引用关系，既保留共享对象，也保持指针身份。
+许多序列化框架遇到循环引用时会直接报错。Apache Fory 能自动跟踪并保留引用身份：
-**Shared Reference：**
+**共享引用**：
```rust
use fory::Fory;
use std::rc::Rc;
-let fory = Fory::default();
+let fory = Fory::builder()
+ .xlang(false)
+ .track_ref(true)
+ .build();
-// Create a shared value
+// 创建一个共享值
let shared = Rc::new(String::from("shared_value"));
-// Reference it multiple times
+// 多次引用同一个值
let data = vec![shared.clone(), shared.clone(), shared.clone()];
-// The shared value is serialized only once
-let bytes = fory.serialize(&data);
+// 共享值只会被序列化一次
+let bytes = fory.serialize(&data)?;
let decoded: Vec<Rc<String>> = fory.deserialize(&bytes)?;
-// Verify reference identity is preserved
+// 验证引用身份得到保留
assert_eq!(decoded.len(), 3);
assert_eq!(*decoded[0], "shared_value");
-// All three Rc pointers point to the same object
+// 三个 Rc 指针都指向同一个对象
assert!(Rc::ptr_eq(&decoded[0], &decoded[1]));
assert!(Rc::ptr_eq(&decoded[1], &decoded[2]));
```
-**Circular Reference：**
+**循环引用**：
```rust
-use fory::{ForyObject, RcWeak};
+use fory::{Fory, ForyStruct, RcWeak};
+use std::{cell::RefCell, rc::Rc};
-#[derive(ForyObject)]
+#[derive(ForyStruct)]
struct Node {
value: i32,
- parent: RcWeak<RefCell<Node>>, // Weak pointer breaks cycles
- children: Vec<Rc<RefCell<Node>>>, // Strong references tracked
+ parent: RcWeak<RefCell<Node>>, // 弱指针打破循环
+ children: Vec<Rc<RefCell<Node>>>, // 跟踪强引用
}
-// Build a parent-child tree with circular references
+let mut fory = Fory::builder()
+ .xlang(false)
+ .track_ref(true)
+ .build();
+fory.register::<Node>(100)?;
+
+// 构建包含循环引用的父子树
let parent = Rc::new(RefCell::new(Node { ... }));
let child = Rc::new(RefCell::new(Node {
- parent: RcWeak::from(&parent), // Points back to parent
+ parent: RcWeak::from(&parent), // 反向指向父节点
...
}));
parent.borrow_mut().children.push(child.clone());
-// Serialization handles the cycle automatically
-let bytes = fory.serialize(&parent);
+// 序列化会自动处理循环
+let bytes = fory.serialize(&parent)?;
let decoded: Rc<RefCell<Node>> = fory.deserialize(&bytes)?;
-// Reference relationships preserved!
-assert!(Rc::ptr_eq(&decoded, &decoded.borrow().children[0].borrow().parent.upgrade().unwrap()));
+// 引用关系得到保留
+let decoded_child = decoded.borrow().children[0].clone();
+let decoded_parent = decoded_child.borrow().parent.upgrade().unwrap();
+assert!(Rc::ptr_eq(&decoded, &decoded_parent));
```
-图数据库、ORM、复杂领域模型都因此受益，工程团队再也不用为保留指针身份写边角逻辑。
+这不仅是一项锦上添花的功能，更是图数据库、对象关系映射和复杂领域模型不可或缺的能力。
-### 3. **Trait 对象序列化终于不再折腾**
+### 3. **Trait 对象序列化**
-Rust 的抽象力来自 trait，但 `Box<dyn Trait>` 序列化一直被视为难题。Fory 内建类型注册机制，处理起来轻松自然。
+Rust 的 trait 系统提供了强大的抽象能力，但序列化 `Box<dyn Trait>` 一直十分棘手。Apache Fory 让这件事变得简单：
```rust
-use fory::{ForyObject, Serializer, register_trait_type};
+use fory::{register_trait_type, Fory, ForyObject, ForyStruct};
-trait Animal: Serializer {
+trait Animal: ForyObject {
fn speak(&self) -> String;
}
-#[derive(ForyObject)]
+#[derive(ForyStruct)]
struct Dog { name: String, breed: String }
-#[derive(ForyObject)]
+impl Animal for Dog {
+ fn speak(&self) -> String {
+ "Woof!".to_string()
+ }
+}
+
+#[derive(ForyStruct)]
struct Cat { name: String, color: String }
-// Register implementations
+impl Animal for Cat {
+ fn speak(&self) -> String {
+ "Meow!".to_string()
+ }
+}
+
+// 注册具体实现
register_trait_type!(Animal, Dog, Cat);
-// Serialize heterogeneous collections
+let mut fory = Fory::builder().xlang(false).build();
+fory.register::<Dog>(100)?;
+fory.register::<Cat>(101)?;
+
+// 序列化异构集合
let animals: Vec<Box<dyn Animal>> = vec![
Box::new(Dog { ... }),
Box::new(Cat { ... }),
];
-let bytes = fory.serialize(&animals);
+let bytes = fory.serialize(&animals)?;
let decoded: Vec<Box<dyn Animal>> = fory.deserialize(&bytes)?;
-// Polymorphism preserved!
+// 多态行为得到保留
decoded[0].speak(); // "Woof!"
decoded[1].speak(); // "Meow!"
```
-**无需注册，直接使用 `dyn Any` 的写法：**
+**另一种选择：无需注册 trait，直接使用 `dyn Any`**：
```rust
use std::rc::Rc;
use std::any::Any;
-// No trait definition or registration needed
+// 无需定义或注册 trait
let dog: Rc<dyn Any> = Rc::new(Dog { name: "Rex".to_string(), breed: "Labrador".to_string() });
let cat: Rc<dyn Any> = Rc::new(Cat { name: "Whiskers".to_string(), color: "Orange".to_string() });
-let bytes = fory.serialize(&dog);
+let bytes = fory.serialize(&dog)?;
let decoded: Rc<dyn Any> = fory.deserialize(&bytes)?;
-// Downcast to concrete type
+// 向下转换为具体类型
let unwrapped = decoded.downcast_ref::<Dog>().unwrap();
assert_eq!(unwrapped.name, "Rex");
```
-支持面向 `Box`、`Rc`、`Arc` 的 trait 对象，以及 `Rc<dyn Any>` / `Arc<dyn Any>` 等运行时多态场景，为插件系统、异构集合和可扩展架构打开新的空间。
+**支持范围**：
-### 4. **Schema 演进无需同步发布**
+- `Box<dyn Trait>`：拥有所有权的 trait 对象
+- `Rc<dyn Trait>` / `Arc<dyn Trait>`：引用计数的 trait 对象
+- `Rc<dyn Any>` / `Arc<dyn Any + Send + Sync>`：无需应用 trait 的运行时类型派发
+- 为 `Rc<dyn Trait>` 和 `Arc<dyn Trait>` 生成根序列化器
-微服务独立迭代时，最怕 schema 不一致。Fory 的 **Compatible 模式** 允许你放心升级字段，老版本数据依旧读得出来。
+这为插件系统、异构集合和可扩展架构打开了新的可能，也让过去难以序列化的模型变得切实可用。
+
+### 4. **不破坏兼容性的 Schema 演进**
+
+微服务往往独立演进。Apache Fory 的**兼容模式**允许服务在无需同步协调的情况下调整 Schema：
```rust
-use fory::{Fory, ForyObject};
+use fory::{Fory, ForyStruct};
+use std::collections::HashMap;
-// Service A: Version 1
-#[derive(ForyObject)]
-struct User {
+// 服务 A：版本 1
+#[derive(ForyStruct)]
+struct UserV1 {
name: String,
age: i32,
address: String,
}
-let mut fory_v1 = Fory::default().compatible(true);
-fory_v1.register::<User>(1);
+let mut fory_v1 = Fory::builder().xlang(false).build();
+fory_v1.register::<UserV1>(1)?;
-// Service B: Version 2 (evolved independently)
-#[derive(ForyObject)]
-struct User {
+// 服务 B：独立演进后的版本 2
+#[derive(ForyStruct)]
+struct UserV2 {
name: String,
age: i32,
- // address removed
- phone: Option<String>, // New field
- metadata: HashMap<String, String>, // Another new field
+ // 删除 address
+ phone: Option<String>, // 新增字段
+ metadata: HashMap<String, String>, // 另一个新增字段
}
-let mut fory_v2 = Fory::default().compatible(true);
-fory_v2.register::<User>(1);
+let mut fory_v2 = Fory::builder().xlang(false).build();
+fory_v2.register::<UserV2>(1)?;
-// V1 data deserializes into V2 structure
-let v1_bytes = fory_v1.serialize(&user_v1);
-let user_v2: User = fory_v2.deserialize(&v1_bytes)?;
-// Missing fields get default values automatically
+// 将 V1 数据反序列化为 V2 结构
+let v1_bytes = fory_v1.serialize(&user_v1)?;
+let user_v2: UserV2 = fory_v2.deserialize(&v1_bytes)?;
+// 缺失字段会自动使用默认值
```
-**兼容策略概览：**
+**兼容性规则**：
-- ✅ 新增字段会被自动赋默认值
-- ✅ 删除字段时旧数据会被跳过
-- ✅ 字段顺序可随意调整，按名称对齐
-- ✅ 可空性 (`T` ↔ `Option<T>`) 可互换
-- ❌ 字段类型不可直接改动（可空性除外）
+- ✅ 新增字段（应用默认值）
+- ✅ 删除字段（反序列化时跳过）
+- ✅ 调整字段顺序（按名称匹配）
+- ✅ 改变可空性（`T` ↔ `Option<T>`）
+- ✅ 在转换无损时调整部分标量字段类型
+- ❌ 有损或不兼容的类型变更
-零停机上新、跨团队协同和多语言部署都能依赖这一机制。
+这对于零停机部署和多语言微服务至关重要。
-## 技术基石
+### 5. **外部类型序列化**
+
+Rust 的孤儿规则通常不允许你为另一个 crate 所拥有的类型派生序列化 trait。Apache Fory 无需把包装对象引入应用模型，就能解决这一问题：
+
+```rust
+use fory::{Fory, ForyStruct};
+
+#[derive(ForyStruct)]
+#[fory(target = third_party::User)]
+struct UserSerializer {
+ name: String,
+ age: u32,
+}
+
+let mut fory = Fory::builder().xlang(true).build();
+fory.register::<UserSerializer>(100)?;
+
+let user = third_party::User {
+ name: "Alice".to_string(),
+ age: 30,
+};
+
+let bytes = fory.serialize_with::<UserSerializer>(&user)?;
+let decoded: third_party::User =
+ fory.deserialize_with::<UserSerializer>(&bytes)?;
+```
+
+`UserSerializer` 是一项编译期 Schema 和代码生成声明，而不是运行时创建的镜像值。Fory 会直接读取 `third_party::User` 的字段，并直接重建该类型。字段可以通过 `#[fory(with = UserSerializer)]` 选择同一个序列化器，`VecSerializer<UserSerializer>` 等承载序列化器则能把这种能力扩展到集合根节点。
+
+对于包含私有字段或需要维持不变量的不透明类型，可以改为实现 Fory 的 `Serializer` trait。这两条路径让第三方类型无需修改源代码或增加转换层，也能成为一等序列化对象。
+
+## 技术基础
### 协议设计
-Fory 的二进制协议兼顾吞吐与灵活度：
+Apache Fory 使用了一套兼顾性能与灵活性的二进制协议：
```
| fory header | reference meta | type meta | value data |
```
-四项关键设计：
+**关键创新**：
-1. **紧凑编码**：可变长整数、精简类型 ID、位级标志位
-2. **引用追踪**：共享对象只写一次，此后以引用替代
-3. **元信息压缩**：meta-sharing 模式下对类型描述做 gzip 压缩
-4. **小端布局**：适配现代 CPU 的缓存与对齐策略
+1. **高效编码**：可变长整数、紧凑类型 ID 和位打包标志
+2. **引用跟踪**：自动去除共享对象的重复数据，只序列化一次，后续写入引用
+3. **紧凑元信息**：高效编码并去除类型元信息中的重复内容
+4. **小端序布局**：针对现代 CPU 架构优化
### 编译期代码生成
-Fory 通过过程宏在编译期生成序列化逻辑，避开运行时反射开销。
+不同于基于反射的框架，Apache Fory 通过过程宏在编译期生成序列化代码：
```rust
-use fory::ForyObject;
+use fory::ForyStruct;
-#[derive(ForyObject)]
+#[derive(ForyStruct)]
struct Person {
name: String,
age: i32,
address: Address,
}
-// Macro generates:
-// - fory_write_data() for serialization
-// - fory_read_data() for deserialization
-// - fory_reserved_space() for buffer pre-allocation
-// - fory_get_type_id() for type registration
+// derive 宏会生成序列化器实现和 Schema 元数据。
```
-因此：
+**优势**：
-- ⚡ 没有运行时分派或反射
-- 🛡️ 类型不匹配在编译期即会被捕获
-- 📦 只生成实际用到的序列化代码
-- 🔍 IDE 推导体验完整保留
+- ⚡ **零运行时开销**：无需反射，也不需要虚表查找
+- 🛡️ **类型安全**：在编译期发现错误，而不是在运行时 panic
+- 📦 **更小的二进制体积**：只为实际使用的类型生成代码
+- 🔍 **IDE 支持**：完整保留自动补全和错误检查能力
-### 组件划分
+### 架构
-整个 Rust 实现由三个 crate 组成，职责分明：
+Apache Fory Rust 由三个职责明确的 crate 组成：
```
-fory/ # 高阶 API
- └─ 常用封装与 derive 重导出
+fory/ # 公共 API 门面
+ └─ 运行时与 derive 重导出
-fory-core/ # 核心序列化内核
- ├─ fory.rs # 入口模块
- ├─ buffer.rs # 零拷贝缓冲区
- ├─ serializer/ # 针对类型的序列化器
+fory-core/ # 核心序列化引擎
+ ├─ fory.rs # 主入口
+ ├─ buffer.rs # 零拷贝二进制 I/O
+ ├─ serializer/ # 特定类型的序列化器
├─ resolver/ # 类型注册与派发
- ├─ meta/ # 元信息压缩
- └─ row/ # Row format 实现
+ ├─ meta/ # 元字符串压缩
+ ├─ types/ # Fory 内置类型
+ └─ row/ # 行格式实现
-fory-derive/ # 过程宏集合
- ├─ object/ # ForyObject derive 宏
+fory-derive/ # 过程宏
+ ├─ object/ # ForyStruct/ForyEnum/ForyUnion derive 宏
└─ fory_row.rs # ForyRow derive 宏
```
-模块化设计让团队能够放心演进性能和功能，而无需担心耦合。
-
-## 基准：真实业务下的吞吐
-
-<img src="/img/benchmarks/rust/ecommerce_data.png" width="90%"/>
-<img src="/img/benchmarks/rust/system_data.png" width="90%"/>
-
-| 数据类型 | 数据规模 | 操作类型 | Fory TPS | JSON TPS | Protobuf TPS | 最快 |
-| -------------- | -------- | --------- | ---------- | ---------- | ------------ | ---- |
-| 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 |
-
-可以通过 https://github.com/apache/fory/tree/v0.16.0/benchmarks/rust 查看更多 Rust Benchmark 代码和数据。
-
-## 适用与不适用的场景
-
-### ✅ 最佳落地案例
-
-1. **多语言微服务体系**
- - 团队间使用不同语言
- - 无 schema 文件的跨语言通信
- - 独立升级却要保持兼容
-
-2. **高吞吐数据流水线**
+这种模块化设计实现了清晰的职责分离，也让代码库更易维护。
+
+## 基准测试：真实场景下的性能
+
+当前 Rust 基准测试套件覆盖了具有代表性的原始类型、集合、结构体和嵌套对象负载，同时测量序列化与反序列化吞吐量。测试在同一套已提交的基准框架下，对比 Apache Fory、Prost Protocol Buffers 和 MessagePack。
+
+
+
+这张图展示了 Fory 为何适合性能敏感型系统：代码生成的序列化器、紧凑二进制布局和专门优化的集合路径，可以在不牺牲复杂 Rust 应用所需能力的前提下提供高吞吐量。完整的环境信息、负载定义、载荷大小和详细结果，请参阅[完整 Rust 基准测试报告](/docs/benchmarks/rust/)。
+
+## 何时使用 Apache Fory Rust
+
+### ✅ **理想使用场景**
+
+1. **多语言团队构建的微服务**
+ - 不同服务使用不同编程语言
+ - 需要通过共享协议紧凑地交换数据
+ - 独立部署之间需要 Schema 演进
+
+2. **高性能数据管道**
- 每秒处理数百万条记录
- - 内存紧张，可借助 row format
- - 分析场景需要按字段解码
+ - 内存受限的环境（使用行格式）
+ - 需要选择性访问字段的分析负载
-3. **结构复杂的领域模型**
- - 父子引用、图结构、循环依赖
- - trait 对象、多态层次丰富
- - 共享引用必须原样保留
+3. **复杂领域模型**
+ - 循环引用（父子关系、图结构）
+ - 多态类型（trait 对象、继承层次）
+ - 包含共享引用的丰富对象图
-4. **低延迟系统**
- - 序列化开销要求低于 1ms
- - 借助内存映射文件
- - 强调零拷贝读写
+4. **实时系统**
+ - 对序列化延迟要求严格
+ - 需要重复访问大型结构化数据集
+ - 需要零拷贝的行格式字段访问
-### ⚠️ 可以考虑其他方案的情况
+### ⚠️ **以下情况可考虑其他方案**
-1. **调试必须可读**：直接使用 JSON/YAML
-2. **长期存档**：面向数据湖的 Parquet 更合适
-3. **数据结构极其简单**：`serde` + `bincode` 成本最低
+1. **需要人类可读的数据**：使用 JSON/YAML 便于调试
+2. **需要长期存储格式**：数据湖场景可使用 Parquet
+3. **数据非常简单**：对于基础类型，serde + bincode 更简单
## 五分钟快速上手
-### 安装依赖
+### 安装
-在 `Cargo.toml` 中加入：
+在 `Cargo.toml` 中添加：
```toml
[dependencies]
-fory = "0.13"
+fory = "1.5.0"
```
-### 首个对象的读写
+### 基础对象序列化
```rust
-use fory::{Fory, Error, ForyObject};
+use fory::{Error, Fory, ForyStruct};
-#[derive(ForyObject, Debug, PartialEq)]
+#[derive(ForyStruct, Debug, PartialEq)]
struct User {
name: String,
age: i32,
@@ -360,99 +415,72 @@ struct User {
}
fn main() -> Result<(), Error> {
- let mut fory = Fory::default();
- fory.register::<User>(1); // Register with unique ID
+ let mut fory = Fory::builder().xlang(false).build();
+ fory.register::<User>(1)?; // 使用唯一 ID 注册
let user = User {
name: "Alice".to_string(),
age: 30,
email: "alice@example.com".to_string(),
};
- // Serialize
- let bytes = fory.serialize(&user);
- // Deserialize
+ // 序列化
+ let bytes = fory.serialize(&user)?;
+ // 反序列化
let decoded: User = fory.deserialize(&bytes)?;
assert_eq!(user, decoded);
Ok(())
}
```
-### 跨语言互通配置
+### 跨语言序列化
```rust
use fory::Fory;
-// Enable cross-language mode
-let mut fory = Fory::default().compatible(true).xlang(true);
+// 启用跨语言模式
+let mut fory = Fory::builder().xlang(true).build();
-// Register with id/namespace for cross-language compatibility
-fory.register_by_namespace::<User>(1);
-// fory.register_by_namespace::<User>("example", "User");
+// 在每种语言中使用 ID 或名称注册同一个逻辑类型
+fory.register::<User>(100)?;
+// fory.register_by_name::<User>("example.User")?;
-let bytes = fory.serialize(&user);
-// This can now be deserialized in Java, Python, Go, etc.
+let bytes = fory.serialize(&user)?;
+// 现在可以在 Java、Python、Go 等语言中反序列化这些数据
```
-请确保所有语言实现都以一致的 ID 或名称注册类型：
+请在所有语言中使用**一致的 ID 或名称**注册类型：
-- **使用 ID**（`fory.register::<User>(1)`）：编码最紧凑、吞吐最好，但需要跨团队协调 ID
-- **使用名称**（`fory.register_by_name::<User>("example.User")`）：更易管理、冲突风险低，代价是编码稍大
+- **按 ID 注册**（`fory.register::<User>(1)`）：序列化速度更快、编码更紧凑，但需要协调以避免 ID 冲突
+- **按名称注册**（`fory.register_by_name::<User>("example.User")`）：更灵活、更不容易冲突，也更便于跨团队管理，但编码会稍大
-## 支持的类型族群
+## 支持的类型
-Fory Rust 支持体系涵盖：
+Apache Fory Rust 支持完整而丰富的类型体系：
-**原生类型**：`bool`、`i8`、`i16`、`i32`、`i64`、`f32`、`f64`、`String`
+**原始类型**：`bool`、`i8`、`i16`、`i32`、`i64`、`f32`、`f64`、`String`
-**集合容器**：`Vec<T>`、`HashMap<K,V>`、`BTreeMap<K,V>`、`HashSet<T>`、`Option<T>`
+**集合**：`Vec<T>`、`VecDeque<T>`、`LinkedList<T>`、`HashMap<K,V>`、`BTreeMap<K,V>`、`HashSet<T>`、`BTreeSet<T>`、`BinaryHeap<T>`、`Option<T>`
**智能指针**：`Box<T>`、`Rc<T>`、`Arc<T>`、`RcWeak<T>`、`ArcWeak<T>`、`RefCell<T>`、`Mutex<T>`
-**日期时间**：`chrono::NaiveDate`、`chrono::NaiveDateTime`
-
-**自定义类型**：对象图使用 `ForyObject`，行式存储使用 `ForyRow`
-
-**Trait 对象**：`Box<dyn T>`、`Rc<dyn T>`、`Arc<dyn T>`、`Rc<dyn Any>`、`Arc<dyn Any>`
-
-## 路线图：现在与未来
-
-Fory Rust 已经稳定可用于生产，同时仍保持高速演进。
-
-### ✅ v0.13 已完成
+**日期/时间**：`Date`、`Timestamp`、`Duration` 以及受支持的 `chrono` 类型
-- ✅ 过程宏驱动的静态代码生成
-- ✅ 零拷贝 row format 编解码
-- ✅ 跨语言对象图序列化
-- ✅ 自动追踪共享与循环引用
-- ✅ `RcWeak`、`ArcWeak` 等弱指针支持
-- ✅ `Box` / `Rc` / `Arc` trait 对象序列化
-- ✅ Compatible 模式支持 schema 演进
+**自定义类型**：为对象图派生 `ForyStruct`、`ForyEnum` 或 `ForyUnion`，为行格式派生 `ForyRow`
-### 🚧 研发中
+**Trait 对象**：`Box<dyn T>`、`Rc<dyn T>`、`Arc<dyn T>`、`Rc<dyn Any>`、`Arc<dyn Any + Send + Sync>`
-- [ ] **跨语言引用序列化**：`Rc/Arc` 跨语言互通
-- [ ] **Row format 局部更新**：原地更新部分字段
+## 生产环境注意事项
-### 🎯 社区期待
+### 线程安全
-欢迎加入并贡献：
-
-- **性能优化**：深挖热点路径
-- **文档补完**：案例、指南、教学
-- **测试覆盖**：基准、性质、边界场景
-
-## 生产级别的考量
-
-### 线程安全模式
-
-完成所有类型注册后，`Fory` 即具备线程安全特性。此时用 `Arc` 包装、分发到多个线程，既能并发序列化，也能并发解码。
+完成注册后，`Fory` 就可以安全地在线程之间共享。所有类型注册完成后（注册需要 `&mut Fory`），将实例包装在 `Arc` 中，即可由多个工作线程并发执行序列化和反序列化。
```rust
use fory::Fory;
use std::{sync::Arc, thread};
-let mut fory = Fory::default();
+let mut fory = Fory::builder().xlang(false).build();
fory.register::<Item>(1)?;
-let fory = Arc::new(fory); // `Fory` is Send + Sync once registration is done
+let fory = Arc::new(fory); // 注册完成后，`Fory` 实现了 Send + Sync
let item = Item::default();
let handles: Vec<_> = (0..4)
@@ -460,7 +488,7 @@ let handles: Vec<_> = (0..4)
let fory = Arc::clone(&fory);
let input = item.clone();
thread::spawn(move || {
- let bytes = fory.serialize(&input);
+ let bytes = fory.serialize(&input).expect("serialization succeeds");
let decoded: Item = fory.deserialize(&bytes).expect("valid data");
(bytes, decoded)
})
@@ -469,70 +497,70 @@ let handles: Vec<_> = (0..4)
for handle in handles {
let (bytes, decoded) = handle.join().expect("thread finished");
- // work with `bytes` / `decoded`
+ // 使用 `bytes` / `decoded`
}
```
-### 错误处理方式
+### 错误处理
-所有可失败操作都返回 `Result<T, Error>`，与 Rust 生态保持一致。
+Apache Fory 的所有可失败操作都使用 `Result<T, Error>`：
```rust
-use fory::Error;
-
match fory.deserialize::<User>(&bytes) {
Ok(user) => process_user(user),
- Err(Error::TypeMismatch) => log::error!("Schema mismatch"),
- Err(Error::BufferTooShort) => log::error!("Incomplete data"),
Err(e) => log::error!("Deserialization failed: {}", e),
}
```
-## 文档与资源
+## 文档
-- Apache Fory Rust 指南：[📖 查看](https://fory.apache.org/docs/docs/guide/rust_serialization)
-- Apache Fory Rust API：[📖 查看](https://docs.rs/fory/latest/fory/)
-- Apache Fory Xlang 协议规范：[📖 查看](https://fory.apache.org/docs/specification/fory_xlang_serialization_spec/)
+- Apache Fory Rust 指南：[📖 查看](https://fory.apache.org/docs/guide/rust/)
+- Apache Fory 外部类型序列化：[📖 查看](https://fory.apache.org/docs/guide/rust/external_types)
+- Apache Fory Rust 基准测试：[📊 查看](https://fory.apache.org/docs/benchmarks/rust/)
+- Apache Fory Rust API 文档：[📖 查看](https://docs.rs/fory/latest/fory/)
+- Apache Fory 跨语言序列化规范：[📖 查看](https://fory.apache.org/docs/specification/fory_xlang_serialization_spec/)
-## 社区与共建
+## 社区与贡献
-Apache Fory 隶属于 **Apache 软件基金会**，社区活跃并持续壮大：
+Apache Fory 是一个 **Apache 软件基金会**项目，拥有活跃且不断成长的社区：
- **GitHub**：[apache/fory](https://github.com/apache/fory)
-- **文档站**：[fory.apache.org](https://fory.apache.org)
+- **文档**：[fory.apache.org](https://fory.apache.org)
- **Slack**：[加入社区](https://join.slack.com/t/fory-project/shared_invite/zt-1u8soj4qc-ieYEu7ciHOqA2mo47llS8A)
- **Issue Tracker**：[GitHub Issues](https://github.com/apache/fory/issues)
-### 如何参与贡献
+### 如何贡献
+
+我们欢迎各种形式的贡献：
-1. **代码**：实现路线图上的功能点
-2. **文档**：补充教程、示例与实践
-3. **测试**：完善基准、模糊与集成测试
-4. **反馈**：提交 Bug、需求或使用经验
+1. **代码**：实现新功能并改进现有能力
+2. **文档**：编写教程、示例和指南
+3. **测试**：添加基准测试、模糊测试和集成测试
+4. **反馈**：报告 Bug、提出功能需求或分享使用场景
-详见 [CONTRIBUTING.md](https://github.com/apache/fory/blob/main/CONTRIBUTING.md)。
+贡献指南请参阅 [CONTRIBUTING.md](https://github.com/apache/fory/blob/main/CONTRIBUTING.md)。
### 许可证
-项目使用 **Apache License 2.0**，允许商业应用、修改和再发行。
+Apache Fory 采用 **Apache License 2.0**，这是一项允许商业使用、修改和分发的宽松开源许可证。
-## 收官
+## 结语
-Apache Fory Rust 把性能、灵活度和开发者体验重新排列组合：
+Apache Fory Rust 为序列化带来了一次范式转变：
-- **性能与灵活性并行**，不再二选一
-- **复杂样板自动化**，derive 宏替你完成繁琐实现
-- **天然支持多态与引用**，跨语言协作不再吃力
+- **不再权衡取舍**：同时获得性能与灵活性
+- **不再编写样板代码**：derive 宏负责处理复杂细节
+- **不再增加转换层**：外部类型序列化器直接处理第三方类型值
-如果你正在构建微服务、高速数据管线或实时系统，Fory Rust 值得马上试用。
+无论你正在构建微服务、数据管道还是实时系统，Apache Fory Rust 都能以出色的易用性提供所需性能。
-**立即体验：**
+**立即体验**：
```bash
cargo add fory
```
-**加入社区：**
+**加入社区**：
```bash
git clone https://github.com/apache/fory.git
@@ -540,8 +568,8 @@ cd fory/rust
cargo test --features tests
```
-**分享经验：**
+**分享你的经验**：
-- 写一篇实践文章
-- 在 Rust Meetup 做场分享
-- 提交与你业务相关的基准数据
+- 撰写博客介绍你的使用场景
+- 在本地 Rust Meetup 上进行分享
+- 提交来自你所在领域的基准测试
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@fory.apache.org
For additional commands, e-mail: commits-help@fory.apache.org