跳到主要内容
版本：dev

配置

Fory JavaScript 是仅支持 xlang 的运行时。new Fory() 会写入 xlang 载荷，并默认使用兼容 Schema 演进。JavaScript API 中没有原生模式开关。

基本配置​

import Fory from "@apache-fory/core";

const fory = new Fory();

每个应用区域创建一个 Fory 实例并复用它。注册会为每个 schema 生成并缓存序列化器代码。

构造函数选项​

import Fory from "@apache-fory/core";
import hps from "@apache-fory/hps";

const fory = new Fory({
  ref: true,
  compatible: true,
  maxDepth: 100,
  maxBinarySize: 64 * 1024 * 1024,
  maxCollectionSize: 1_000_000,
  hps,
});
选项默认值说明
reffalse为共享或循环对象图启用引用跟踪
compatibletrue允许新增或删除字段而不破坏现有消息
maxDepth50最大嵌套深度。必须 >= 2。对于深度嵌套结构可以调大
maxBinarySize64 MiB任意单个二进制字段可接受的最大字节数
maxCollectionSize1_000_000任意 list、set 或 map 可接受的最大元素数
useSliceStringfalseNode.js 的可选字符串读取优化。除非已做基准测试，否则保持默认值
hps未设置来自 @apache-fory/hps 的可选快速字符串辅助库（Node.js 20+）
hooks.afterCodeGenerated未设置用于检查生成的序列化器代码的回调，便于调试

引用跟踪​

必须先启用全局引用跟踪，字段级引用元信息才会生效：

const fory = new Fory({ ref: true });

然后在 schema 中标记需要引用跟踪的字段，例如 Type.struct("example.node").setTrackingRef(true)。参见引用和 Schema 元信息。

兼容 Schema 演进​

兼容模式是默认设置：

const fory = new Fory();

对于滚动升级、独立部署的服务以及跨语言载荷，请使用该默认设置。你可以通过 evolving: false 为某个稳定 struct 关闭它；参见 Schema 演进。

可选 HPS 字符串路径​

@apache-fory/hps 提供可选的 Node.js 字符串快速路径：

import hps from "@apache-fory/hps";

const fory = new Fory({ hps });

除非你运行在 Node.js 20+ 且已经对工作负载做过基准测试，否则保持未设置。

安全​

安全相关配置：

  • 在反序列化不可信载荷前，只注册预期的 schema。
  • 根据服务可接受的最大载荷形状设置 maxDepth、maxBinarySize 和 maxCollectionSize。
  • 对不可信输入，优先使用显式的 Type.struct(...) schema，而不是 Type.any()。
  • 只传入与你部署的运行时版本配套的官方包中的 hps。

相关主题​