Apache Fory 常用 CLI 命令与工具详解

目标：Apache Fory 是纯 Java 库，没有独立守护进程与专属命令行；日常「命令」实际由 Maven 构建命令、javac/java 运行命令以及 Fory 的 Java API 组成。本文汇总这些高频命令与 API，并给出真实回显。

一、工具组成

集成 Apache Fory 时用到的工具有三类：

类别	工具	用途
依赖与构建	Maven（`mvn`）	解析 `fory-core`、编译、打包、查看依赖树
编译与运行	`javac` / `java`	编译示例、以指定堆内存运行
编程接口	Fory Java API	`Fory`/`ThreadSafeFory` 的序列化、注册、配置

提示：Apache Fory 没有 fory 之类的独立可执行程序，所有操作都在 Java 应用内通过 API 完成。

二、Maven 常用命令

2.1 依赖解析与查看

mvn -q -B dependency:build-classpath -Dmdep.outputFile=cp.txt
cat cp.txt

真实回显：

/root/.m2/repository/org/apache/fory/fory-core/1.7.6/fory-core-1.7.6.jar:/root/.m2/repository/org/codehaus/janino/janino/3.1.12/janino-3.1.12.jar:/root/.m2/repository/org/codehaus/janino/commons-compiler/3.1.12/commons-compiler-3.1.12.jar

mvn -B dependency:tree

真实回显（节选）：

[INFO] com.example:fory-lab:jar:1.0
[INFO] \- org.apache.fory:fory-core:jar:1.7.6:compile
[INFO]    \- org.codehaus.janino:janino:jar:3.1.12:compile
[INFO]       \- org.codehaus.janino:commons-compiler:jar:3.1.12:compile
[INFO] BUILD SUCCESS

2.2 编译与打包

命令	作用
`mvn -B clean`	清理 `target/`
`mvn -B compile`	编译源码
`mvn -B package -DskipTests`	打包为 jar
`mvn -B clean package`	清理后完整构建

export MAVEN_OPTS="-Xmx384m"
mvn -B clean package -DskipTests

真实回显（节选）：

[INFO] Building jar: /root/fory-lab/target/fory-lab-1.0.jar
[INFO] BUILD SUCCESS
[INFO] Total time:  38.914 s

2.3 单依赖下载

不需要完整工程时，可直接把某个版本的 jar 拉到本地仓库：

mvn -q -B dependency:get -Dartifact=org.apache.fory:fory-core:1.7.6 -Dtransitive=false

三、javac 与 java 运行命令

3.1 编译

cd /root/fory-lab
CP=$(cat cp.txt)
javac -cp "$CP" -d target/classes src/main/java/com/example/HelloFory.java

3.2 运行

java -Xmx384m -cp "target/classes:$CP" com.example.HelloFory

真实回显：

original     : User{name=Alice, age=30}
deserialized : User{name=Alice, age=30}
content equal: true
Fory bytes   : 53
JDK  bytes   : 93

3.3 JDK 17+ 附加参数

在 JDK 17 及以上运行时可加入 --add-opens 避免模块反射访问告警：

java -Xmx384m \
  --add-opens java.base/java.lang=ALL-UNNAMED \
  --add-opens java.base/java.util=ALL-UNNAMED \
  --add-opens java.base/java.nio=ALL-UNNAMED \
  -cp "target/classes:$CP" com.example.HelloFory

四、版本查询命令

4.1 查询可用版本

curl -s https://repo1.maven.org/maven2/org/apache/fory/fory-core/maven-metadata.xml | head -40

真实回显（节选）：

    <artifactId>fory-core</artifactId>
      <latest>1.7.6</latest>
      <release>1.7.6</release>

4.2 运行时打印版本

System.out.println(Fory.class.getPackage().getImplementationVersion());

真实回显：

1.7.6

4.3 反编译查看 API（核查方法签名）

javap -cp ~/.m2/repository/org/apache/fory/fory-core/1.7.6/fory-core-1.7.6.jar org.apache.fory.Fory
javap -cp ~/.m2/repository/org/apache/fory/fory-core/1.7.6/fory-core-1.7.6.jar org.apache.fory.config.ForyBuilder

五、Fory API 速查

5.1 创建实例

语句	返回	说明
`Fory.builder().withLanguage(Language.JAVA).build()`	`Fory`	非线程安全，Java 模式
`Fory.builder().withLanguage(Language.XLANG).build()`	`Fory`	跨语言模式
`…buildThreadSafeFory()`	`ThreadSafeFory`	线程安全
`…buildThreadLocalFory()`	`ThreadLocalFory`	ThreadLocal 封装
`…buildThreadSafeForyPool(int)`	`ThreadSafeFory`	有界池

5.2 序列化与反序列化

方法	说明
`byte[] serialize(Object obj)`	序列化为字节数组
`void serialize(OutputStream out, Object obj)`	写入输出流
`MemoryBuffer serialize(MemoryBuffer buf, Object obj)`	写入零拷贝缓冲
`Object deserialize(byte[] bytes)`	从字节数组反序列化
`<T> T deserialize(byte[] bytes, Class<T> cls)`	指定目标类型反序列化
`Object deserialize(MemoryBuffer buf)`	从缓冲反序列化

实测两种用法：

Fory fory = Fory.builder().withLanguage(Language.JAVA).requireClassRegistration(false).build();
byte[] bytes = fory.serialize(new User("Alice", 30));      // 序列化
User u1 = (User) fory.deserialize(bytes);                  // 无类型
User u2 = fory.deserialize(bytes, User.class);             // 指定类型

5.3 关于 serializeJavaObject / deserializeJavaObject

这两个方法名属于 Fury 时代（org.apache.fury:fury-core:0.10.0，实测存在），用于只写对象体、不带类头。迁移到 Apache Fory（org.apache.fory）后：

serializeJavaObject(Object) → 使用 serialize(Object)；
deserializeJavaObject(byte[], Class<T>) → 使用 deserialize(byte[], Class<T>)。

即在新版本中统一由 serialize/deserialize 及其重载承担，旧方法名已不存在。

5.4 类注册

方法	说明
`register(Class<?> cls)`	按类名注册
`register(Class<?> cls, int id)`	按数字 id 注册，体积最小
`register(Class<?> cls, String typeName)`	按字符串类型名注册（跨语言）
`register(String className)`	按类名字符串注册

实测注册效果：

[no-register] THROW org.apache.fory.exception.InsecureException: class ... is not registered ...
[register] OK bytes=67 -> User{name=Alice, age=30, email=alice@example.com, vip=true}
[xlang] OK bytes=68 -> User{name=Alice, age=30, email=alice@example.com, vip=true}

六、ForyBuilder 常用方法速查表

方法	取值	说明
`withLanguage(Language)`	`JAVA` / `XLANG`	语言模式
`withXlang(boolean)`	true/false	跨语言开关
`withRefTracking(boolean)`	true/false	引用跟踪（循环引用必需）
`withRefCopy(boolean)`	true/false	拷贝时保留引用结构
`withCompatibleMode(CompatibleMode)`	`COMPATIBLE` / `SCHEMA_CONSISTENT`	兼容模式
`withCompatible(boolean)`	true/false	兼容模式布尔开关
`withMetaShare(boolean)`	true/false	共享元信息
`withScopedMetaShare(boolean)`	true/false	作用域元信息共享
`withIntCompressed(boolean)`	true/false	int 压缩
`withLongCompressed(boolean)`	true/false	long 压缩
`withStringCompressed(boolean)`	true/false	字符串压缩
`withNumberCompressed(boolean)`	true/false	数值压缩总开关
`withCodegen(boolean)`	true/false	JIT 代码生成
`withAsyncCompilation(boolean)`	true/false	异步编译
`requireClassRegistration(boolean)`	true/false	是否强制类注册
`withClassLoader(ClassLoader)`	ClassLoader	指定类加载器
`withBufferSizeLimitBytes(int)`	正整数	缓冲上限
`withMaxDepth(int)`	正整数	最大对象深度
`withName(String)`	字符串	实例命名

七、JVM 参数建议

参数	说明
`-Xmx384m`	示例统一使用的堆上限，建议保持在 256–512 MB
`-XX:+UseG1GC`	大对象吞吐场景可选 G1
`--add-opens java.base/...=ALL-UNNAMED`	JDK 17+ 反射访问所需

八、常见问题

Q1：为什么没有 fory 命令？

Apache Fory 是库而非服务，无独立可执行文件。构建用 mvn，运行用 java -cp，能力通过 Java API 调用。

Q2：mvn dependency:build-classpath 生成的 cp.txt 怎么用？

它是一行长 classpath，作为 javac -cp "$(cat cp.txt)" 与 java -cp "target/classes:$(cat cp.txt)" 的输入。

Q3：模块化运行报找不到 resources 文件（如 fory-core 的 services）？

不要把 fory-core 当作命名模块直接 --module-path 载入，使用 classpath 方式（-cp）即可。

Q4：javap 看不到某个方法？

说明该版本未提供该方法。例如 serializeJavaObject 在 org.apache.fory 系列中已移除，请改用 serialize。

Q5：如何快速确认依赖版本？

使用 mvn dependency:tree 查看解析到的实际版本，或用 mvn dependency:get -Dartifact=org.apache.fory:fory-core:<version> 拉取指定版本。