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 <[email protected]> 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: "[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]
