版本：dev

Apache Fory™ 使用

本章节提供 Apache Fory™ 的快速入门示例。

原生序列化

当你只在单一语言内使用时，请始终选择原生模式。 原生模式不需要为跨语言兼容写入额外类型元信息，因此性能最好。

xlang 模式会引入额外的元信息编码开销，并且只允许序列化所有受支持语言都能映射的类型。语言特有类型在 xlang 模式下会被拒绝。

Java 序列化

如果不需要跨语言支持，请使用 Java 模式以获得最佳性能。

下面的示例展示了最基本的 Java 原生用法：创建可复用的 Java 模式运行时、注册用户类型，然后完成一次序列化和反序列化往返。实际项目中不要为每个对象重新创建 Fory 实例，而应长期复用同一个实例。

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

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

  public static void main(String[] args) {
    // 创建一次 Fory 实例并重复复用。
    BaseFory fory = Fory.builder()
      .withLanguage(Language.JAVA)
      .requireClassRegistration(true)
      // 如果需要线程安全用法，请将 `build` 替换为 `buildThreadSafeFory`。
      .build();
    fory.register(Person.class);

    Person person = new Person();
    person.name = "chaokunyang";
    person.age = 28;

    byte[] bytes = fory.serialize(person);
    Person result = (Person) fory.deserialize(bytes);
    System.out.println(result.name + " " + result.age);
  }
}

关于兼容模式、压缩和更多高级特性，请参见 Java 序列化指南。

Python 序列化

Python 原生模式可以作为 pickle 和 cloudpickle 的高性能替代方案。

这个示例使用 dataclass 和显式整数类型注解，让 Fory 能以更清晰的 Schema 进行高效序列化。与其他语言一样，推荐只创建一次 Fory 实例、只注册一次类型，然后在后续调用中重复使用。

from dataclasses import dataclass
import pyfory

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

fory = pyfory.Fory()
fory.register_type(Person)

person = Person(name="chaokunyang", age=28)
data = fory.serialize(person)
result = fory.deserialize(data)
print(result.name, result.age)

关于类型注解、兼容模式和更多高级特性，请参见 Python 指南。

Go 序列化

Go 原生模式默认启用。注册一次结构体后，重复复用同一个 Fory 实例即可。

Go 运行时天然适配导出的 struct 字段和显式类型注册。下面的代码演示了最常见的流程：创建 Fory、注册结构体类型、序列化一个值，再反序列化到目标结构体中。

package main

import (
    "fmt"

    "github.com/apache/fory/go/fory"
)

type Person struct {
    Name string
    Age  int32
}

func main() {
    f := fory.New()
    if err := f.RegisterStruct(Person{}, 1); err != nil {
        panic(err)
    }

    person := &Person{Name: "chaokunyang", Age: 28}
    data, err := f.Serialize(person)
    if err != nil {
        panic(err)
    }

    var result Person
    if err := f.Deserialize(data, &result); err != nil {
        panic(err)
    }

    fmt.Printf("%s %d\n", result.Name, result.Age)
}

关于配置、struct tag 和 Schema 演进，请参见 Go 指南。

C# 序列化

C# 原生序列化使用 Apache.Fory 运行时和 [ForyObject] 模型类型。

在 C# 中，常见模式是先用 [ForyObject] 标记模型，再创建一次运行时并在使用前注册类型。示例展示的是强类型的 Serialize / Deserialize<T> API，这也是 .NET 应用中最直接的用法。

using Apache.Fory;

[ForyObject]
public sealed class Person
{
    public string Name { get; set; } = string.Empty;
    public int Age { get; set; }
}

Fory fory = Fory.Builder().Build();
fory.Register<Person>(1);

Person person = new() { Name = "chaokunyang", Age = 28 };
byte[] data = fory.Serialize(person);
Person result = fory.Deserialize<Person>(data);

Console.WriteLine($"{result.Name} {result.Age}");

关于源代码生成器、引用跟踪和 Schema 演进，请参见 C# 指南。

Swift 序列化

Swift 原生序列化直接使用 @ForyObject 模型和 Fory 运行时。

Swift 通过宏定义模型类型，因此示例先使用 @ForyObject 标记类型，再注册类型 ID 并完成一次强类型往返。这是 Swift 应用侧最推荐的入门方式。

import Fory

@ForyObject
struct Person: Equatable {
    var name: String = ""
    var age: Int32 = 0
}

let fory = Fory()
fory.register(Person.self, id: 1)

let person = Person(name: "chaokunyang", age: 28)
let data = try fory.serialize(person)
let result: Person = try fory.deserialize(data)

print("\(result.name) \(result.age)")

关于多态、Schema 演进和常见问题排查，请参见 Swift 指南。

Rust 序列化

Rust 原生模式使用 Fory::default() 和 derive 宏来实现编译期类型安全的序列化。常见模式是先为类型派生 ForyObject，注册一次类型，再重复复用已经配置好的运行时。

use fory::{Error, Fory, ForyObject};

#[derive(ForyObject, Debug, PartialEq)]
struct Person {
    name: String,
    age: i32,
}

fn main() -> Result<(), Error> {
    let mut fory = Fory::default();
    fory.register::<Person>(1)?;

    let person = Person {
        name: "chaokunyang".to_string(),
        age: 28,
    };

    let bytes = fory.serialize(&person)?;
    let result: Person = fory.deserialize(&bytes)?;
    assert_eq!(person, result);
    Ok(())
}

关于引用、多态和 row format 支持，请参见 Rust 指南。

C++ 序列化

C++ 原生模式使用 FORY_STRUCT 宏描述可序列化字段，再通过配置好的 Fory 运行时对值进行编码和解码。对于单语言 C++ 场景，建议显式设置 xlang(false)，让运行时保持在原生模式。

#include "fory/serialization/fory.h"

using namespace fory::serialization;

struct Person {
  std::string name;
  int32_t age;

  bool operator==(const Person &other) const {
    return name == other.name && age == other.age;
  }

  FORY_STRUCT(Person, name, age);
};

int main() {
  auto fory = Fory::builder().xlang(false).build();
  fory.register_struct<Person>(1);

  Person person{"chaokunyang", 28};

  auto bytes = fory.serialize(person);
  auto result = fory.deserialize<Person>(bytes.value());
  assert(result.ok());
  assert(person == result.value());
  return 0;
}

关于 FORY_STRUCT、线程安全和 Schema 演进，请参见 C++ 指南。

Scala 序列化

Scala 原生模式对 case class、集合和 Option 等 Scala 特有类型提供了优化支持。

在 Scala 项目中，应先注册 Scala 专用序列化器，让 Fory 正确理解 Scala 特有的数据结构。完成这一步后，就可以像 Java 运行时一样注册 case class 并执行序列化。

import org.apache.fory.Fory
import org.apache.fory.config.Language
import org.apache.fory.serializer.scala.ScalaSerializers

case class Person(name: String, age: Int)

object Example {
  def main(args: Array[String]): Unit = {
    val fory = Fory.builder()
      .withLanguage(Language.JAVA)
      .requireClassRegistration(true)
      .build()
    ScalaSerializers.registerSerializers(fory)
    fory.register(classOf[Person])

    val bytes = fory.serialize(Person("chaokunyang", 28))
    val result = fory.deserialize(bytes).asInstanceOf[Person]
    println(s"${result.name} ${result.age}")
  }
}

关于集合序列化和集成模式，请参见 Scala 指南。

Kotlin 序列化

Kotlin 原生模式对 data class、可空类型和 Kotlin 集合提供了优化支持。

Kotlin 的整体流程与 Java 类似，只是额外需要注册 Kotlin 专用序列化器。下面的示例使用 data class，展示了进行高效原生序列化所需的最小配置。

import org.apache.fory.Fory
import org.apache.fory.config.Language
import org.apache.fory.serializer.kotlin.KotlinSerializers

data class Person(val name: String, val age: Int)

fun main() {
    val fory = Fory.builder()
        .withLanguage(Language.JAVA)
        .requireClassRegistration(true)
        .build()
    KotlinSerializers.registerSerializers(fory)
    fory.register(Person::class.java)

    val bytes = fory.serialize(Person("chaokunyang", 28))
    val result = fory.deserialize(bytes) as Person
    println("${result.name} ${result.age}")
}

关于空安全和默认值支持，请参见 kotlin/README.md。

跨语言序列化

只有在确实需要跨语言数据交换时才使用 xlang 模式。 xlang 模式会为跨语言兼容增加类型元信息开销，并且只支持能够在所有语言之间映射的类型。

下面的示例在多个运行时中使用同一个 Person Schema。无论使用哪种语言，都需要启用 xlang 模式，并用相同的 ID 或相同的全限定名称注册类型。

Java

Java 的 xlang 用法可以看作 JVM 服务中的基准模式。启用 Language.XLANG 后，用稳定的 ID 或名称注册类型，并确保所有对端语言都使用相同的映射关系。

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

public class XlangExample {
  public record Person(String name, int age) {}

  public static void main(String[] args) {
    Fory fory = Fory.builder()
      .withLanguage(Language.XLANG)
      .build();

    fory.register(Person.class, 1);
    // fory.register(Person.class, "example.Person");

    Person person = new Person("chaokunyang", 28);
    byte[] bytes = fory.serialize(person);
    Person result = (Person) fory.deserialize(bytes);
    System.out.println(result.name() + " " + result.age());
  }
}

Go

Go 通过 WithXlang(true) 启用跨语言模式。真正关键的不是 Go 语法本身，而是保证注册的类型身份与其他读写同一载荷的语言完全一致。

package main

import (
    "fmt"

    "github.com/apache/fory/go/fory"
)

type Person struct {
    Name string
    Age  int32
}

func main() {
    f := fory.New(fory.WithXlang(true))
    if err := f.RegisterStruct(Person{}, 1); err != nil {
        panic(err)
    }

    person := &Person{Name: "chaokunyang", Age: 28}
    data, err := f.Serialize(person)
    if err != nil {
        panic(err)
    }

    var result Person
    if err := f.Deserialize(data, &result); err != nil {
        panic(err)
    }

    fmt.Printf("%s %d\n", result.Name, result.Age)
}

Rust

Rust 同样遵循这套跨语言约定，只是通过派生 trait 和在 Fory 实例上显式注册来表达。只要类型 ID 与其他运行时一致，载荷就可以安全地跨语言流转。

use fory::{Fory, ForyObject};
use std::error::Error;

#[derive(ForyObject, Debug)]
struct Person {
    name: String,
    age: i32,
}

fn main() -> Result<(), Box<dyn Error>> {
    let mut fory = Fory::default().xlang(true);
    fory.register::<Person>(1)?;
    // fory.register_by_name::<Person>("example.Person")?;

    let person = Person {
        name: "chaokunyang".to_string(),
        age: 28,
    };
    let bytes = fory.serialize(&person);
    let result: Person = fory.deserialize(&bytes)?;
    println!("{} {}", result.name, result.age);
    Ok(())
}

JavaScript

JavaScript 的跨语言支持是基于 Schema 描述的。它不是注册类，而是通过 Type.object(...) 描述载荷结构，再使用返回的序列化器来编码和解码数据。

这些包目前还没有发布到 npm。因此请先从 Apache Fory 仓库完成构建，再按下面的 API 方式使用。

import Fory, { Type } from "@apache-fory/core";

/**
 * `@apache-fory/hps` 会通过 JIT 直接使用 V8 fast calls。
 * 启用时请使用 Node.js 20+。
 * 如果安装失败，请将它替换为 `const hps = null;`。
 */
import hps from "@apache-fory/hps";

const description = Type.object("example.Person", {
  name: Type.string(),
  age: Type.int32(),
});

const fory = new Fory({ hps });
const { serialize, deserialize } = fory.registerSerializer(description);

const payload = serialize({ name: "chaokunyang", age: 28 });
const result = deserialize(payload);
console.log(result);

C#

C# 的跨语言代码看起来与原生模式很接近，但运行时需要显式启用 xlang 和 compatible 模式。与此同时，仍然必须与 Java、Go、Swift、Rust 等对端使用相同的类型 ID 或 namespace/name 映射。

using Apache.Fory;

[ForyObject]
public sealed class Person
{
    public string Name { get; set; } = string.Empty;
    public int Age { get; set; }
}

Fory fory = Fory.Builder()
    .Xlang(true)
    .Compatible(true)
    .Build();

fory.Register<Person>(1);

Person person = new() { Name = "chaokunyang", Age = 28 };
byte[] payload = fory.Serialize(person);
Person result = fory.Deserialize<Person>(payload);

Console.WriteLine($"{result.Name} {result.Age}");

Swift

Swift 的跨语言序列化仍然使用与原生模式相同的 @ForyObject 模型风格，只是在创建运行时时要传入 xlang: true。要实现互操作，稳定的注册 ID 仍然是最核心的要求。

import Fory

@ForyObject
struct Person: Equatable {
    var name: String = ""
    var age: Int32 = 0
}

let fory = Fory(xlang: true, trackRef: false, compatible: true)
fory.register(Person.self, id: 1)

let person = Person(name: "chaokunyang", age: 28)
let data = try fory.serialize(person)
let result: Person = try fory.deserialize(data)

print("\(result.name) \(result.age)")

要点

在每个运行时中都显式启用 xlang 模式，例如 Language.XLANG、WithXlang(true)、Xlang(true)、Fory(xlang: true, ...) 等。
在所有语言中使用一致的 ID 或名称注册类型。
基于 ID 的注册更紧凑、速度更快，但需要集中协调以避免冲突。
基于名称的注册更容易在团队间管理，但载荷会稍大一些。
只使用具备跨语言映射的类型，详见 Type Mapping。

关于跨语言场景中的循环引用、共享引用和多态示例，请参见：

Row Format 编码

Row format 提供零拷贝随机访问能力，非常适合分析型负载和数据处理流水线。

Java

import org.apache.fory.format.*;
import java.util.*;
import java.util.stream.*;

public class Bar {
  String f1;
  List<Long> f2;
}

public class Foo {
  int f1;
  List<Integer> f2;
  Map<String, Integer> f3;
  List<Bar> f4;
}

RowEncoder<Foo> encoder = Encoders.bean(Foo.class);
Foo foo = new Foo();
foo.f1 = 10;
foo.f2 = IntStream.range(0, 1000000).boxed().collect(Collectors.toList());
foo.f3 = IntStream.range(0, 1000000).boxed().collect(Collectors.toMap(i -> "k"+i, i -> i));

List<Bar> bars = new ArrayList<>(1000000);
for (int i = 0; i < 1000000; i++) {
  Bar bar = new Bar();
  bar.f1 = "s" + i;
  bar.f2 = LongStream.range(0, 10).boxed().collect(Collectors.toList());
  bars.add(bar);
}
foo.f4 = bars;

// 序列化为 row format（可被 Python 以零拷贝方式读取）
BinaryRow binaryRow = encoder.toRow(foo);

// 反序列化整个对象
Foo newFoo = encoder.fromRow(binaryRow);

// 不做完整反序列化，直接零拷贝访问嵌套字段
BinaryArray binaryArray2 = binaryRow.getArray(1);  // 访问 f2 字段
BinaryArray binaryArray4 = binaryRow.getArray(3);  // 访问 f4 字段
BinaryRow barStruct = binaryArray4.getStruct(10);   // 访问第 11 个 Bar 元素
long value = barStruct.getArray(1).getInt64(5);     // 访问嵌套值

// 部分反序列化
RowEncoder<Bar> barEncoder = Encoders.bean(Bar.class);
Bar newBar = barEncoder.fromRow(barStruct);
Bar newBar2 = barEncoder.fromRow(binaryArray4.getStruct(20));

Python

from dataclasses import dataclass
from typing import List, Dict
import pyarrow as pa
import pyfory

@dataclass
class Bar:
    f1: str
    f2: List[pa.int64]

@dataclass
class Foo:
    f1: pa.int32
    f2: List[pa.int32]
    f3: Dict[str, pa.int32]
    f4: List[Bar]

encoder = pyfory.encoder(Foo)
foo = Foo(
    f1=10,
    f2=list(range(1000_000)),
    f3={f"k{i}": i for i in range(1000_000)},
    f4=[Bar(f1=f"s{i}", f2=list(range(10))) for i in range(1000_000)]
)

# 序列化为 row format
binary: bytes = encoder.to_row(foo).to_bytes()

# 无需完整反序列化即可零拷贝随机访问
foo_row = pyfory.RowData(encoder.schema, binary)
print(foo_row.f2[100000])           # 直接访问元素
print(foo_row.f4[100000].f1)        # 访问嵌套字段
print(foo_row.f4[200000].f2[5])     # 访问更深层的嵌套字段

更多 row format 细节请参见 Java Row Format 指南或 Python Row Format 指南。

原生序列化​

Java 序列化​

Python 序列化​

Go 序列化​

C# 序列化​

Swift 序列化​

Rust 序列化​

C++ 序列化​

Scala 序列化​

Kotlin 序列化​

跨语言序列化​

Java​

Go​

Rust​

JavaScript​

C#​

Swift​

要点​

Row Format 编码​

Java​

Python​

原生序列化

Java 序列化

Python 序列化

Go 序列化

C# 序列化

Swift 序列化

Rust 序列化

C++ 序列化

Scala 序列化

Kotlin 序列化

跨语言序列化

Java

Go

Rust

JavaScript

C#

Swift

要点

Row Format 编码

Java

Python