跳到主要内容
版本：dev

配置

本页介绍 Fory 配置参数和语言模式。

Fory 类​

主要序列化接口：

class Fory:
    def __init__(
        self,
        xlang: bool = False,
        ref: bool = False,
        strict: bool = True,
        compatible: bool = False,
        max_depth: int = 50
    )

ThreadSafeFory 类​

使用线程本地存储的线程安全序列化接口：

class ThreadSafeFory:
    def __init__(
        self,
        xlang: bool = False,
        ref: bool = False,
        strict: bool = True,
        compatible: bool = False,
        max_depth: int = 50
    )

参数​

参数类型默认值描述
xlangboolFalse启用跨语言序列化。当为 False 时，启用 Python 原生模式，支持所有 Python 对象。当为 True 时，启用跨语言模式，兼容 Java、Go、Rust 等。
refboolFalse启用引用跟踪以支持共享/循环引用。如果数据没有共享引用，禁用此选项可获得更好性能。
strictboolTrue出于安全考虑需要类型注册。生产环境强烈推荐。仅在受信任的环境中禁用。
compatibleboolFalse在跨语言模式中启用 schema 演化，允许在保持兼容性的同时添加/删除字段。
max_depthint50反序列化的最大深度，用于安全防护，防止栈溢出攻击。

核心方法​

# 序列化（serialize/deserialize 与 dumps/loads 完全相同）
data: bytes = fory.serialize(obj)
obj = fory.deserialize(data)

# 替代 API（别名）
data: bytes = fory.dumps(obj)
obj = fory.loads(data)

# 按 ID 注册类型（用于 Python 模式）
fory.register(MyClass, type_id=123)
fory.register(MyClass, type_id=123, serializer=custom_serializer)

# 按名称注册类型（用于跨语言模式）
fory.register(MyClass, typename="my.package.MyClass")
fory.register(MyClass, typename="my.package.MyClass", serializer=custom_serializer)

语言模式比较​

特性Python 模式 (xlang=False)跨语言模式 (xlang=True)
使用场景纯 Python 应用多语言系统
兼容性仅限 PythonJava、Go、Rust、C++、JavaScript 等
支持的类型所有 Python 类型仅限跨语言兼容类型
函数/Lambda✓ 支持✗ 不允许
本地类✓ 支持✗ 不允许
动态类✓ 支持✗ 不允许
Schema 演化✓ 支持（需要 compatible=True）✓ 支持（需要 compatible=True）
性能极快非常快
数据大小紧凑紧凑（带类型元数据）

Python 模式 (xlang=False)​

Python 模式支持所有 Python 类型，包括函数、类和闭包：

import pyfory

# 完全 Python 兼容模式
fory = pyfory.Fory(xlang=False, ref=True, strict=False)

# 支持所有 Python 对象：
data = fory.dumps({
    'function': lambda x: x * 2,        # 函数和 lambda
    'class': type('Dynamic', (), {}),    # 动态类
    'method': str.upper,                # 方法
    'nested': {'circular_ref': None}    # 循环引用（当 ref=True 时）
})

# 可直接替代 pickle/cloudpickle
import pickle
obj = [1, 2, {"nested": [3, 4]}]
assert fory.loads(fory.dumps(obj)) == pickle.loads(pickle.dumps(obj))

跨语言模式 (xlang=True)​

跨语言模式将类型限制为所有 Fory 实现间兼容的类型：

import pyfory

# 跨语言兼容模式
f = pyfory.Fory(xlang=True, ref=True)

# 仅支持跨语言兼容类型
f.register(MyDataClass, typename="com.example.MyDataClass")

# 数据可以被 Java、Go、Rust 等读取
data = f.serialize(MyDataClass(field1="value", field2=42))

示例配置​

生产环境配置​

import pyfory

# 生产环境推荐设置
fory = pyfory.Fory(
    xlang=False,        # 如果需要跨语言支持则使用 True
    ref=False,          # 如果有共享/循环引用则启用
    strict=True,        # 关键：生产环境始终为 True
    compatible=False,   # 仅在需要 schema 演化时启用
    max_depth=20        # 根据数据结构深度调整
)

# 预先注册所有类型
fory.register(UserModel, type_id=100)
fory.register(OrderModel, type_id=101)
fory.register(ProductModel, type_id=102)

开发环境配置​

import pyfory

# 开发设置（更宽松）
fory = pyfory.Fory(
    xlang=False,
    ref=True,
    strict=False,    # 开发时允许任何类型
    max_depth=1000   # 开发时更高的限制
)

相关主题​