This is an automated email from the ASF dual-hosted git repository.
chaokunyang pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/fory-site.git
The following commit(s) were added to refs/heads/main by this push:
new f50f8af3fb docs(zh-CN): refresh Fory Rust framework blog (#478)
f50f8af3fb is described below
commit f50f8af3fb36e4d1c5ee9fc77052055a07cb76da
Author: Shawn Yang <[email protected]>
AuthorDate: Fri Jul 31 18:01:39 2026 +0800
docs(zh-CN): refresh Fory Rust framework blog (#478)
---
...-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: "[email protected]".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: [email protected]
For additional commands, e-mail: [email protected]