跳到主要内容
版本：1.3.0

配置

本页介绍 Fory 配置选项和序列化模式。

序列化模式​

Apache Fory™ 支持两种序列化模式：

SchemaConsistent 模式（默认）​

类型声明必须在通信双方完全匹配：

auto fory = Fory::builder().build(); // 默认为 SchemaConsistent

Compatible 模式​

允许独立的 schema 演化：

auto fory = Fory::builder().compatible(true).build();

构建器模式​

使用 ForyBuilder 构造具有自定义配置的 Fory 实例：

#include "fory/serialization/fory.h"

using namespace fory::serialization;

// 默认配置
auto fory = Fory::builder().build();

// 用于 schema 演化的兼容模式
auto fory = Fory::builder()
    .compatible(true)
    .build();

// 跨语言模式
auto fory = Fory::builder()
    .xlang(true)
    .build();

// 完整配置
auto fory = Fory::builder()
    .compatible(true)
    .xlang(true)
    .track_ref(true)
    .max_dyn_depth(10)
    .max_type_fields(512)
    .max_type_meta_bytes(4096)
    .max_schema_versions_per_type(10)
    .max_average_schema_versions_per_type(3)
    .check_struct_version(true)
    .build();

配置选项​

xlang(bool)​

启用/禁用跨语言（xlang）序列化模式。

auto fory = Fory::builder()
    .xlang(true)  // 启用跨语言兼容性
    .build();

启用后，包含用于与 Java、Python、Go、Rust 和 JavaScript 跨语言兼容的元数据。

默认值： true

compatible(bool)​

启用/禁用用于 schema 演化的兼容模式。

auto fory = Fory::builder()
    .compatible(true)  // 启用 schema 演化
    .build();

启用后，支持读取使用不同 schema 版本序列化的数据。

默认值： false

track_ref(bool)​

启用/禁用共享引用和循环引用的引用跟踪。

auto fory = Fory::builder()
    .track_ref(true)  // 启用引用跟踪
    .build();

启用后，避免重复序列化共享对象并处理循环引用。

默认值： true

max_dyn_depth(uint32_t)​

设置动态类型对象的最大允许嵌套深度。

auto fory = Fory::builder()
    .max_dyn_depth(10)  // 允许最多 10 层
    .build();

这限制了嵌套多态对象序列化的最大深度（例如 shared_ptr<Base>、unique_ptr<Base>）。防止深度嵌套结构在动态序列化场景中导致栈溢出。

默认值： 5

何时调整：

  • 增加：对于合法的深度嵌套数据结构
  • 减少：对于更严格的安全要求或浅层数据结构

max_schema_versions_per_type(uint32_t)​

设置一个逻辑类型可接受的最大远端 metadata 版本数。

auto fory = Fory::builder()
    .max_schema_versions_per_type(10)
    .build();

默认值： 10

max_type_fields(uint32_t)​

设置一个收到的远端 struct metadata body 中可接受的最大字段数。

auto fory = Fory::builder()
    .max_type_fields(512)
    .build();

默认值： 512

max_type_meta_bytes(uint32_t)​

设置一个收到的 TypeDef body 可接受的最大编码 body 字节数，不包含 8 字节 header 和扩展 size varint。

auto fory = Fory::builder()
    .max_type_meta_bytes(4096)
    .build();

默认值： 4096

max_average_schema_versions_per_type(uint32_t)​

设置所有已接受远端类型的平均 metadata 版本数限制。有效全局下限为 8192 个 schema。

auto fory = Fory::builder()
    .max_average_schema_versions_per_type(3)
    .build();

默认值： 3

check_struct_version(bool)​

启用/禁用结构体版本检查。

auto fory = Fory::builder()
    .check_struct_version(true)  // 启用版本检查
    .build();

启用后，验证类型哈希以检测 schema 不匹配。

默认值： false

线程安全 vs 单线程​

单线程（最快）​

auto fory = Fory::builder()
    .xlang(true)
    .build();  // 返回 Fory

单线程 Fory 是最快的选项，但非线程安全。每个线程使用一个实例。

线程安全​

auto fory = Fory::builder()
    .xlang(true)
    .build_thread_safe();  // 返回 ThreadSafeFory

ThreadSafeFory 使用 Fory 实例池提供线程安全的序列化。由于池开销略慢，但可以从多个线程并发安全使用。

配置摘要​

选项说明默认值
xlang(bool)启用跨语言模式true
compatible(bool)启用 schema 演化false
track_ref(bool)启用引用跟踪true
max_dyn_depth(uint32_t)动态类型的最大嵌套深度5
max_type_fields(uint32_t)一个收到的 struct metadata body 最大字段数512
max_type_meta_bytes(uint32_t)一个收到的 metadata body 最大编码字节数4096
max_schema_versions_per_type(uint32_t)一个逻辑类型最大远端 metadata 版本数10
max_average_schema_versions_per_type(uint32_t)所有远端类型的平均 metadata 版本数3
check_struct_version(bool)启用结构体版本检查false

安全​

安全相关配置：

  • 在反序列化不可信 payload 前，只注册预期的类型。
  • 对 intentional same-schema payload，将 check_struct_version(true) 与 compatible(false) 配合使用。
  • 尽可能降低 max_dyn_depth(...)，以拒绝异常深的多态对象图。
  • 除非数据不是恶意输入，且可信 peer 会发送更大的 metadata 或大量 schema 版本，否则保持远端 schema metadata 限制的默认值。
  • 对不可信输入，优先使用具体字段，避免宽泛的多态字段。

相关主题​