跳到主要内容
版本：1.1.0

Xlang 序列化指南

Apache Fory™ xlang 序列化是跨语言载荷的默认编码格式。你可以在一种语言中序列化数据，并在另一种语言中反序列化，无需手动转换。对于小型契约，可以直接使用语言模型类型；当更适合 schema-first 工作流时，也可以使用 Fory IDL 和代码生成。

特性​

  • 无需 IDL：直接使用语言模型类型序列化对象。
  • 多语言支持：Java、Python、C++、Go、Rust、JavaScript/TypeScript、C#、Swift、Dart、Scala 和 Kotlin 可通过同一 xlang 格式互操作。
  • 引用支持：在各语言运行时启用引用跟踪后，共享引用和循环引用可以跨语言边界工作。
  • Schema 演进：兼容模式是 xlang 的默认设置，因此读取方可以容忍字段新增、删除或重排。
  • 带外缓冲区：语言运行时可以为大型二进制数据暴露零拷贝缓冲区路径。
  • 高性能：可用时，运行时会使用生成的序列化器、JIT 序列化器或优化代码路径。

支持的语言​

语言状态包或目标
Java支持org.apache.fory:fory-core
Python支持pyfory
C++支持Bazel/CMake build
Go支持github.com/apache/fory/go/fory
Rust支持fory crate
JavaScript/TypeScript支持@apache-fory/core
C#支持Apache.Fory
Swift支持Swift Package Manager target
Dart支持fory package
Scala支持org.apache.fory:fory-scala
Kotlin支持org.apache.fory:fory-kotlin

何时使用 Xlang 模式​

在以下场景使用 xlang 模式：

  • 构建多语言微服务
  • 创建多语言数据管道
  • 在前端 JavaScript/TypeScript 与 Java、Python、Go、C#、Scala 或 Kotlin 等后端运行时之间共享数据

对于 Java、Scala、Kotlin、Python、C++、Go 或 Rust 中的同语言流量，请使用原生模式：

  • 所有序列化/反序列化都发生在同一语言中
  • 需要 Python pickle 风格对象或 Java 序列化钩子等语言特定功能
  • 希望为同语言服务使用原生模式的 schema-consistent 载荷

快速示例​

Java（生产者）​

import org.apache.fory.*;
import org.apache.fory.config.*;

public class Person {
    public String name;
    public int age;
}

Fory fory = Fory.builder().withXlang(true).build();
fory.register(Person.class, "example.Person");

Person person = new Person();
person.name = "Alice";
person.age = 30;
byte[] bytes = fory.serialize(person);
// Send bytes to Python, Go, Rust, etc.

Python（消费者）​

import pyfory
from dataclasses import dataclass

@dataclass
class Person:
    name: str
    age: pyfory.Int32

fory = pyfory.Fory(xlang=True)
fory.register_type(Person, typename="example.Person")

# Receive bytes from Java
person = fory.deserialize(bytes_from_java)
print(f"{person.name}, {person.age}")  # Alice, 30

Fory IDL​

对于 schema-first 项目，Fory 还提供 Fory IDL 和代码生成。

  • 编译器文档：Fory IDL Overview
  • 最适合大型多语言消息契约和长期维护的 schema

最小 IDL 示例​

创建 person.fdl：

package example;

message Person {
    string name = 1;
    int32 age = 2;
    optional string email = 3;
}

生成代码：

foryc person.fdl --lang java,python,cpp,go,rust,javascript,csharp,swift,dart,scala,kotlin --output ./generated

这会生成原生语言类型，并在所有目标语言之间保持一致的字段/类型映射。

何时使用 Fory IDL​

选项适用场景原因
原生 xlang 类型（无 IDL）只有少量消息类型，并且希望快速推进避免引入和运维编译器带来的集成/设置成本
Fory IDL（schema-first + codegen）有大量消息，跨多个语言/团队/服务使用提供单一契约、更强一致性，并让长期演进更容易
混合方式（先原生，后迁移到 IDL）项目初期较小，但消息数量和跨团队依赖在增长保持早期迭代速度，等 schema 复杂度上升后再标准化

文档​

主题描述
入门指南所有语言的安装和基本设置
类型映射Xlang 类型映射参考
序列化内置类型、自定义类型、引用处理
零拷贝大型数据的带外序列化
行格式支持随机访问的缓存友好二进制格式
故障排查常见问题和解决方案

特定语言指南​

有关特定语言的详细信息和 API 参考：

规范​