This is an automated email from the ASF dual-hosted git repository. chaokunyang pushed a commit to branch release_1.0.0 in repository https://gitbox.apache.org/repos/asf/fory-site.git
commit 27c6d4fa966dad35697709541116db7eb1b5ba6d Author: 慕白 <[email protected]> AuthorDate: Thu May 21 15:50:33 2026 +0800 Refresh Fory homepage introduction --- docs/introduction/overview.md | 74 ++++++++++----- docusaurus.config.ts | 2 +- i18n/zh-CN/code.json | 72 ++++++++++----- .../current/introduction/overview.md | 72 +++++++++------ src/pages/home/components/HomePageLanguageCard.tsx | 17 +++- src/pages/home/components/HomepageFeatures.tsx | 100 +++++++++++++++++---- 6 files changed, 244 insertions(+), 93 deletions(-) diff --git a/docs/introduction/overview.md b/docs/introduction/overview.md index fe4b542cd9..2a2db5acfb 100644 --- a/docs/introduction/overview.md +++ b/docs/introduction/overview.md @@ -9,7 +9,13 @@ sidebar_position: 1 <img width="65%" alt="Apache Fory logo" src="/img/fory-logo-light.png" class="themed-logo-light"/> </div> -**Apache Fory™** is a blazingly-fast multi-language serialization framework powered by **JIT compilation**, **zero-copy** techniques, and **advanced code generation**, achieving up to **170x performance improvement** while maintaining simplicity and ease of use. +**Apache Fory™** is a blazingly-fast multi-language serialization framework for +idiomatic domain objects, schema IDL, and cross-language data exchange. + +Fory is built for compact, high-throughput serialization across languages and +runtimes. It works directly with application objects, supports shared schemas +when you need a stable contract, and preserves object graph features such as +shared references, circular references, and polymorphic runtime types. ## Quick Example @@ -59,34 +65,54 @@ print(decoded) # User(name='Alice', age=30) ## Key Features -### High-Performance Serialization +### Efficient Cross-Language Encoding + +The **[xlang serialization format](../specification/xlang_serialization_spec.md)** +exchanges compact binary payloads across supported languages: + +- **Compact metadata**: Type metadata and field information are packed to keep payloads small. +- **Schema evolution**: Compatible mode supports forward and backward evolution for application schemas. +- **Object graph semantics**: Shared references, circular references, and polymorphic runtime types are preserved across runtimes. +- **Type mapping**: Language-specific values are mapped through the shared [type mapping](../specification/xlang_type_mapping.md). + +### Domain Objects First + +Fory serializes host-language models directly instead of forcing applications +through wrapper types: + +- Java classes, Scala/Kotlin types, and GraalVM native image workloads. +- Python dataclasses and Python-native object graphs. +- Go structs, Rust structs, C++ structs, C# models, Swift types, Dart models, and JavaScript/TypeScript values. +- Generated or annotated model types when a shared contract is preferred. + +### Reference-Aware Schema IDL -Apache Fory™ delivers exceptional performance through advanced optimization techniques: +**[Fory IDL and the compiler](../compiler/index.md)** let teams define schemas +once and generate native domain objects for each target language: -- **JIT Compilation**: Runtime code generation for Java eliminates virtual method calls and inlines hot paths -- **Static Code Generation**: Compile-time code generation for Rust, C++, and Go delivers peak performance without runtime overhead -- **Zero-Copy Operations**: Direct memory access without intermediate buffer copies; row format enables random access and partial serialization -- **Intelligent Encoding**: Variable-length compression for integers and strings; SIMD acceleration for arrays (Java 16+) -- **Meta Sharing**: Class metadata packing reduces redundant type information across serializations +- Model numbers, strings, lists, maps, arrays, enums, structs, and unions. +- Express shared and circular references directly in the schema. +- Generate idiomatic host-language code without introducing transport-specific wrapper types into user code. +- Use schema IDL when services need a stable contract across independently maintained runtimes. -### Cross-Language Serialization +### Row-Format Random Access -The **[xlang serialization format](../specification/xlang_serialization_spec.md)** enables seamless data exchange across programming languages: +A cache-friendly **[row format](../specification/row_format_spec.md)** is +optimized for analytics and partial-read workloads: -- **Automatic Type Mapping**: Intelligent conversion between language-specific types ([type mapping](../specification/xlang_type_mapping.md)) -- **Reference Preservation**: Shared and circular references work correctly across languages -- **Polymorphism**: Objects serialize/deserialize with their actual runtime types -- **Schema Evolution**: Optional forward/backward compatibility for evolving schemas -- **Automatic Serialization**: No IDL or schema definitions required; serialize any object directly without code generation +- **Zero-copy random access**: Read fields, arrays, and nested values without rebuilding whole objects. +- **Partial operations**: Read only the values needed for a query or pipeline stage. +- **Apache Arrow integration**: Convert to columnar data for analytics pipelines. +- **Multi-language support**: Use row format from Java, Python, Rust, and C++. -### Row Format +### Optimized Runtimes -A cache-friendly **[row format](../specification/row_format_spec.md)** optimized for analytics workloads: +Fory keeps hot paths fast without making every runtime use the same implementation strategy: -- **Zero-Copy Random Access**: Read individual fields without deserializing entire objects -- **Partial Operations**: Selective field serialization and deserialization for efficiency -- **Apache Arrow Integration**: Seamless conversion to columnar format for analytics pipelines -- **Multi-Language**: Available in Java, Python, Rust and C++ +- **Java JIT serializers**: Runtime code generation eliminates reflection overhead and inlines hot paths. +- **Generated and static serializers**: Other runtimes use generated or static serializers where appropriate. +- **Zero-copy paths**: Row format and out-of-band buffers avoid unnecessary copies for large values. +- **Metadata sharing**: Repeated type information is shared or packed to reduce serialization overhead. ### Security & Production-Readiness @@ -104,7 +130,7 @@ Apache Fory™ implements multiple binary protocols optimized for different scen | Protocol | Use Case | Key Features | | ----------------------------------------------------------------------- | ------------------------------ | ------------------------------------------------------ | | **[Xlang Serialization](../specification/xlang_serialization_spec.md)** | Cross-language object exchange | Automatic serialization, references, polymorphism | -| **[Java Serialization](../specification/java_serialization_spec.md)** | High-performance Java-only | Drop-in JDK serialization replacement, 100x faster | +| **[Java Serialization](../specification/java_serialization_spec.md)** | High-performance Java-only | Java-native object graphs, JDK hooks, optimized runtime | | **[Row Format](../specification/row_format_spec.md)** | Analytics and data processing | Zero-copy random access, Arrow compatibility | | **Python Native** | Python-specific serialization | Pickle/cloudpickle replacement with better performance | @@ -147,7 +173,9 @@ Apache Fory™ supports class schema forward/backward compatibility across **Jav ### Binary Compatibility -**Current Status**: Binary compatibility is **not guaranteed** between Fory major releases as the protocol continues to evolve. However, compatibility **is guaranteed** between minor versions (e.g., 0.13.x). +**Current Status**: Fory 1.0 is the first stable major line. Treat the major +version as the compatibility boundary and keep producers and consumers on +compatible protocol versions. **Recommendations**: diff --git a/docusaurus.config.ts b/docusaurus.config.ts index e8e58fd13b..aae9ae97e7 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -4,7 +4,7 @@ import type * as Preset from '@docusaurus/preset-classic'; const config: Config = { title: 'Apache Fory™', - tagline: 'A blazing-fast cross-language serialization framework powered by just-in-time compilation and zero-copy', + tagline: 'A blazingly-fast multi-language serialization framework for idiomatic domain objects, schema IDL, and cross-language data exchange', favicon: 'img/favicon.ico', // Set the production url of your site here diff --git a/i18n/zh-CN/code.json b/i18n/zh-CN/code.json index 72901f5dd9..4c16b7c2a1 100644 --- a/i18n/zh-CN/code.json +++ b/i18n/zh-CN/code.json @@ -279,7 +279,7 @@ "description": "The title displayed in the homepage hero section" }, "homepage.hero.subtitle": { - "message": "Apache Fory™ 一个基于动态代码生成和零拷贝技术的多语言序列化框架，实现了无需IDL编译的原生多语言编程范式，并提供最高170倍的性能和极致的易用性。大幅提升大规模数据传输、高并发RPC、分布式系统、云原生中间件等场景的性能，显著降低多语言系统的研发成本。", + "message": "面向惯用领域对象、Schema IDL 和跨语言数据交换的极速多语言序列化框架。", "description": "The subtitle displayed in the homepage hero section" }, "homepage.githubButton": { @@ -287,31 +287,63 @@ "description": "The GitHub button label on the homepage" }, "homepage.getStartedButton": { - "message": "Get Started", + "message": "开始使用", "description": "The Get Started button label on the homepage" }, - "feature.highPerformance.title": { - "message": "高性能", - "description": "The title for the high performance feature" + "homepage.quickStart.title": { + "message": "快速开始", + "description": "The title for the homepage quick start language picker" }, - "feature.highPerformance.description": { - "message": "相比其他序列化框架，性能最高提升20~170倍", - "description": "Description for the high performance feature" + "homepage.quickStart.description": { + "message": "选择运行时并打开对应的快速开始指南。", + "description": "The description for the homepage quick start language picker" }, - "feature.easyToUse.title": { - "message": "易于使用", - "description": "The title for the easy to use feature" + "feature.crossLanguageEncoding.title": { + "message": "跨语言编码", + "description": "The title for the cross-language encoding feature" }, - "feature.easyToUse.description": { - "message": "无需编写IDL定义Schema，您可以使用Fory自动序列化自定义类型对象", - "description": "Description for the easy to use feature" + "feature.crossLanguageEncoding.description": { + "message": "用紧凑二进制载荷跨运行时交换数据，并支持 Schema 演进、共享引用、循环引用和多态运行时类型。", + "description": "Description for the cross-language encoding feature" }, - "feature.multiLanguages.title": { - "message": "多语言", - "description": "The title for the multi-languages feature" + "feature.domainObjects.title": { + "message": "领域对象优先", + "description": "The title for the domain objects feature" }, - "feature.multiLanguages.description": { - "message": "支持Java、Scala、Python、C++、Golang、Javascript、Rust等编程语言", - "description": "Description for the multi-languages feature" + "feature.domainObjects.description": { + "message": "直接序列化 Java 类、Python dataclass、Go struct、Rust/C++ struct，以及生成或注解过的模型类型。", + "description": "Description for the domain objects feature" + }, + "feature.schemaIdl.title": { + "message": "感知引用的 Schema IDL", + "description": "The title for the schema IDL feature" + }, + "feature.schemaIdl.description": { + "message": "一次定义 Schema，并在其中表达共享引用和循环引用，再为各语言生成原生领域对象，无需包装类型。", + "description": "Description for the schema IDL feature" + }, + "feature.rowFormat.title": { + "message": "行格式随机访问", + "description": "The title for the row format feature" + }, + "feature.rowFormat.description": { + "message": "无需重建完整对象即可读取字段、数组和嵌套值，支持零拷贝访问、部分读取和 Arrow 集成。", + "description": "Description for the row format feature" + }, + "feature.optimizedRuntimes.title": { + "message": "优化运行时", + "description": "The title for the optimized runtimes feature" + }, + "feature.optimizedRuntimes.description": { + "message": "Java JIT 序列化器，以及其他运行时的生成式或静态序列化器，让热点路径保持高速并压缩序列化数据。", + "description": "Description for the optimized runtimes feature" + }, + "feature.platformSupport.title": { + "message": "广泛平台支持", + "description": "The title for the platform support feature" + }, + "feature.platformSupport.description": { + "message": "支持 Java、Python、C++、Go、Rust、JavaScript/TypeScript、C#、Swift、Dart、Scala、Kotlin、GraalVM、Flutter、Node.js 和浏览器。", + "description": "Description for the platform support feature" } } diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/introduction/overview.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/introduction/overview.md index 28e4be89a5..6bb75e4334 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/introduction/overview.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/introduction/overview.md @@ -9,7 +9,9 @@ sidebar_position: 1 <img width="65%" alt="Apache Fory logo" src="/img/fory-logo-light.png" class="themed-logo-light"/> </div> -**Apache Fory™** 是一个由 **JIT 编译**、**零拷贝** 技术和 **高级代码生成** 驱动的超高性能多语言序列化框架，可实现高达 **170 倍性能提升**，同时保持简洁易用。 +**Apache Fory™** 是一个面向惯用领域对象、Schema IDL 和跨语言数据交换的极速多语言序列化框架。 + +Fory 面向跨语言、跨运行时的紧凑高吞吐序列化而构建。它可以直接处理应用中的对象；当需要稳定契约时，也可以使用共享 Schema；同时保留对象图中的共享引用、循环引用和多态运行时类型等语义。 ## 快速示例 @@ -59,34 +61,50 @@ print(decoded) # User(name='Alice', age=30) ## 核心特性 -### 高性能序列化 +### 高效跨语言编码 + +**[xlang 序列化格式](../specification/xlang_serialization_spec.md)** 可以在支持的语言之间交换紧凑二进制载荷： + +- **紧凑元数据**：打包类型元信息和字段信息，降低载荷体积。 +- **Schema 演进**：兼容模式支持应用 Schema 的向前和向后演进。 +- **对象图语义**：跨运行时保留共享引用、循环引用和多态运行时类型。 +- **类型映射**：语言特定值通过共享的[类型映射](../specification/xlang_type_mapping.md)进行转换。 + +### 领域对象优先 -Apache Fory™ 通过先进的优化技术提供卓越性能： +Fory 直接序列化宿主语言模型，而不是要求应用引入包装类型： -- **JIT 编译**：Java 运行时代码生成消除虚方法调用并内联热路径 -- **静态代码生成**：Rust、C++ 和 Go 的编译时代码生成，无运行时开销即可达到峰值性能 -- **零拷贝操作**：无需中间缓冲区复制的直接内存访问；行格式支持随机访问和部分序列化 -- **智能编码**：整数和字符串的变长压缩；数组的 SIMD 加速（Java 16+） -- **元数据共享**：类元数据打包减少跨序列化的冗余类型信息 +- Java 类、Scala/Kotlin 类型，以及 GraalVM native image 工作负载。 +- Python dataclass 和 Python 原生对象图。 +- Go struct、Rust struct、C++ struct、C# 模型、Swift 类型、Dart 模型，以及 JavaScript/TypeScript 值。 +- 当需要共享契约时，也支持生成或注解过的模型类型。 -### 跨语言序列化 +### 感知引用的 Schema IDL -**[xlang 序列化格式](../specification/xlang_serialization_spec.md)** 支持跨编程语言的无缝数据交换： +**[Fory IDL 和编译器](../compiler/index.md)** 允许团队一次定义 Schema，并为每种目标语言生成原生领域对象： -- **自动类型映射**：语言特定类型之间的智能转换（[类型映射](../specification/xlang_type_mapping.md)） -- **引用保持**：共享和循环引用在跨语言时正确工作 -- **多态支持**：对象以其实际运行时类型进行序列化/反序列化 -- **Schema 演进**：可选的向前/向后兼容性支持 Schema 演进 -- **自动序列化**：无需 IDL 或 Schema 定义；直接序列化任何对象，无需代码生成 +- 建模数字、字符串、list、map、array、enum、struct 和 union。 +- 在 Schema 中直接表达共享引用和循环引用。 +- 生成惯用的宿主语言代码，不把传输专用包装类型引入用户代码。 +- 当服务需要在独立维护的运行时之间共享稳定契约时，可以使用 Schema IDL。 -### 行格式 +### 行格式随机访问 -针对分析工作负载优化的缓存友好型 **[行格式](../specification/row_format_spec.md)**： +缓存友好的 **[行格式](../specification/row_format_spec.md)** 面向分析和部分读取工作负载优化： -- **零拷贝随机访问**：无需反序列化整个对象即可读取单个字段 -- **部分操作**：选择性字段序列化和反序列化以提高效率 -- **Apache Arrow 集成**：无缝转换为列格式以用于分析流水线 -- **多语言支持**：可用于 Java、Python、Rust 和 C++ +- **零拷贝随机访问**：无需重建完整对象即可读取字段、数组和嵌套值。 +- **部分操作**：只读取查询或流水线阶段需要的值。 +- **Apache Arrow 集成**：转换为列式数据，用于分析流水线。 +- **多语言支持**：可在 Java、Python、Rust 和 C++ 中使用行格式。 + +### 优化运行时 + +Fory 让热点路径保持高速，同时不要求所有运行时采用相同实现策略： + +- **Java JIT 序列化器**：运行时代码生成消除反射开销，并内联热点路径。 +- **生成式和静态序列化器**：其他运行时在合适场景下使用生成式或静态序列化器。 +- **零拷贝路径**：行格式和带外 buffer 可避免大值的不必要复制。 +- **元数据共享**：复用或打包重复类型信息，降低序列化开销。 ### 安全性与生产就绪 @@ -104,7 +122,7 @@ Apache Fory™ 实现了针对不同场景优化的多个二进制协议： | 协议 | 使用场景 | 核心特性 | | ---------------------------------------------------------------- | ----------------- | --------------------------------- | | **[跨语言序列化](../specification/xlang_serialization_spec.md)** | 跨语言对象交换 | 自动序列化、引用、多态 | -| **[Java 序列化](../specification/java_serialization_spec.md)** | 高性能 Java 专用 | JDK 序列化的直接替代，快 100 倍 | +| **[Java 序列化](../specification/java_serialization_spec.md)** | 高性能 Java 专用 | Java 原生对象图、JDK 钩子、优化运行时 | | **[行格式](../specification/row_format_spec.md)** | 分析和数据处理 | 零拷贝随机访问、Arrow 兼容 | | **Python 原生** | Python 专用序列化 | Pickle/cloudpickle 替代，性能更好 | @@ -147,15 +165,13 @@ Apache Fory™ 支持 **Java、Python、Rust 和 Golang** 的类 Schema 向前/ ### 二进制兼容性 -**当前状态**：由于协议持续演进，Fory 主要版本之间**不保证**二进制兼容性。但是，次要版本之间（例如 0.13.x）**保证**兼容性。 +**当前状态**：Fory 1.0 是第一个稳定主版本线。请把主版本作为兼容性边界，并让生产端和消费端使用兼容的协议版本。 **建议**： -- 按 Fory 主要版本对序列化数据进行版本控制 -- 升级主要版本时规划迁移策略 -- 详见[升级指南](../guide/java/troubleshooting.md) - -**未来**：从 Fory 1.0 版本开始将保证二进制兼容性。 +- 对跨语言载荷和运行时共享的 Schema 使用 xlang 模式 +- 当运行时支持且流量只在同一语言内流转时，使用 native 模式 +- Java Schema 独立变更时，使用 [Schema 演进](../guide/java/schema-evolution.md) ## 安全 diff --git a/src/pages/home/components/HomePageLanguageCard.tsx b/src/pages/home/components/HomePageLanguageCard.tsx index d9cfd97212..3825cd2000 100644 --- a/src/pages/home/components/HomePageLanguageCard.tsx +++ b/src/pages/home/components/HomePageLanguageCard.tsx @@ -3,6 +3,7 @@ import useBaseUrl from "@docusaurus/useBaseUrl"; import "../css/tailwind.css"; import { imageUrls } from "../../../constants"; import styles from "../css/HomePageLanguageCard.module.css"; +import Translate from "@docusaurus/Translate"; export default function HomePageLanguageCard() { const [locale, setLocale] = useState("en-US"); @@ -30,9 +31,21 @@ export default function HomePageLanguageCard() { return ( <div className="text-center p-8"> - <h2 className="text-3xl font-bold mb-4 dark:text-white">Quick Start!</h2> + <h2 className="text-3xl font-bold mb-4 dark:text-white"> + <Translate + id="homepage.quickStart.title" + description="The title for the homepage quick start language picker" + > + Quick Start + </Translate> + </h2> <p className="text-lg mb-8 text-gray-600 dark:text-gray-400"> - Choose a language to get started. + <Translate + id="homepage.quickStart.description" + description="The description for the homepage quick start language picker" + > + Choose a runtime to open the matching quick start guide. + </Translate> </p> <div className="max-w-4xl mx-auto"> <div className="grid md:grid-cols-3 sm:grid-cols-1 gap-6"> diff --git a/src/pages/home/components/HomepageFeatures.tsx b/src/pages/home/components/HomepageFeatures.tsx index f86729b6be..20ea7c35b6 100644 --- a/src/pages/home/components/HomepageFeatures.tsx +++ b/src/pages/home/components/HomepageFeatures.tsx @@ -13,58 +13,120 @@ const FeatureList: FeatureItem[] = [ { title: ( <Translate - id="feature.highPerformance.title" - description="The title for the high performance feature" + id="feature.crossLanguageEncoding.title" + description="The title for the cross-language encoding feature" > - High performance + Cross-language encoding </Translate> ), Svg: require("@site/static/img/performance.svg").default, description: ( <Translate - id="feature.highPerformance.description" - description="Description for the high performance feature" + id="feature.crossLanguageEncoding.description" + description="Description for the cross-language encoding feature" > - Compared to other serialization frameworks, there is a 20~170x speed up. + Exchange compact binary payloads across runtimes with schema evolution, + shared and circular references, and polymorphic runtime types. </Translate> ), }, { title: ( <Translate - id="feature.easyToUse.title" - description="The title for the easy to use feature" + id="feature.domainObjects.title" + description="The title for the domain objects feature" > - Easy to use + Domain objects first </Translate> ), Svg: require("@site/static/img/happy.svg").default, description: ( <Translate - id="feature.easyToUse.description" - description="Description for the easy to use feature" + id="feature.domainObjects.description" + description="Description for the domain objects feature" > - No need for DSL, you can use Fory effectively with your intuition. + Serialize Java classes, Python dataclasses, Go structs, Rust and C++ + structs, and generated model types directly in application code. </Translate> ), }, { title: ( <Translate - id="feature.multiLanguages.title" - description="The title for the multi-languages feature" + id="feature.schemaIdl.title" + description="The title for the schema IDL feature" > - Multi-languages + Reference-aware Schema IDL </Translate> ), Svg: require("@site/static/img/multi.svg").default, description: ( <Translate - id="feature.multiLanguages.description" - description="Description for the multi-languages feature" + id="feature.schemaIdl.description" + description="Description for the schema IDL feature" > - Supports popular programming languages such as Java, Python, C++, - Golang, Javascript, Rust, and more will be added in the future. + Define schemas once, including shared and circular references, then + generate native domain objects without wrapper types. + </Translate> + ), + }, + { + title: ( + <Translate + id="feature.rowFormat.title" + description="The title for the row format feature" + > + Row-format random access + </Translate> + ), + Svg: require("@site/static/img/rocket.svg").default, + description: ( + <Translate + id="feature.rowFormat.description" + description="Description for the row format feature" + > + Read fields, arrays, and nested values without rebuilding whole + objects, with zero-copy access, partial reads, and Arrow integration. + </Translate> + ), + }, + { + title: ( + <Translate + id="feature.optimizedRuntimes.title" + description="The title for the optimized runtimes feature" + > + Optimized runtimes + </Translate> + ), + Svg: require("@site/static/img/performance.svg").default, + description: ( + <Translate + id="feature.optimizedRuntimes.description" + description="Description for the optimized runtimes feature" + > + Java JIT serializers and generated or static serializers in other + runtimes keep hot paths fast and serialized data compact. + </Translate> + ), + }, + { + title: ( + <Translate + id="feature.platformSupport.title" + description="The title for the platform support feature" + > + Broad platform support + </Translate> + ), + Svg: require("@site/static/img/multi.svg").default, + description: ( + <Translate + id="feature.platformSupport.description" + description="Description for the platform support feature" + > + Use Fory from Java, Python, C++, Go, Rust, JavaScript/TypeScript, C#, + Swift, Dart, Scala, Kotlin, GraalVM, Flutter, Node.js, and browsers. </Translate> ), }, --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
