Apache Gora 0.9 常用命令与工具详解
详解 Apache Gora 0.9 命令行工具链：gora-compiler-cli 编译器实测详解（用法、静默 exit(1) 失败链与源码定位、classpath 准备、生成代码核验）、mvn 命令速查、gora-maven-plugin 与周边模块参考，含实测 FAQ
Apache Gora 0.9 常用命令与工具详解
Gora 的核心 CLI 是 GoraCompilerCLI（Avro schema → 持久化类编译器），也是 0.9 唯一随发行包提供的命令行工具。本文全部输出在 Ubuntu 22.04 容器（Temurin 17 + Maven 3.9.16，gora-compiler-cli/gora-core 0.9）真实采集；标注"参考"的内容来自官方文档/源码。
一、工具清单（0.9 实际可用）
| 工具 | 坐标 | 形态 | 状态 |
|---|---|---|---|
| GoraCompilerCLI | org.apache.gora:gora-compiler-cli:0.9 | java -cp ... org.apache.gora.compiler.cli.GoraCompilerCLI | 实测 |
| gora-compiler | org.apache.gora:gora-compiler:0.9 | 编译内核（API/库） | 传递引入 |
| gora-maven-plugin | org.apache.gora:gora-maven-plugin | Maven 插件 | 未随 0.9 核验，参考 |
| gora-goraci | org.apache.gora:gora-goraci | 分布式排序示例/基准工具 | 参考 |
| gora-tutorial | org.apache.gora:gora-tutorial | 官方教程工程（conf 模板来源） | 参考 |
二、GoraCompilerCLI 用法（源码 printHelp 实拍）
Usage: GoraCompiler <schema file> <output dir> [-license <id>]
| 参数 | 说明 |
|---|---|
<schema file> | Avro JSON schema 文件；也可以是目录（编译目录下全部 schema） |
<output dir> | 生成代码输出目录，必须预先存在（否则静默退出 1，见第三章） |
-license <id> | 可选，生成文件头许可标识（如 ASLv2） |
主类实测核实：jar tf gora-compiler-cli-0.9.jar 中确认 org/apache/gora/compiler/cli/GoraCompilerCLI.class。
三、首次失败实录：静默 exit(1)（最重要的排障章）
未预建输出目录、classpath 无 SLF4J 绑定时直接编译，实测无任何日志、直接退出：
=== 正式编译 person.json -> src-generated/java ===
exit=1
定位过程（实测下载 gora-compiler-cli-0.9-sources.jar 阅读源码），两个因素叠加：
- 输出目录必须预先存在——CLI 源码逻辑：
File outputDir = new File(args[args.length-1]);
if(!outputDir.isDirectory()){ ... System.exit(1); }
- SLF4J 无可用绑定时错误日志被吞——传递依赖 slf4j-log4j12 1.6.6 无 log4j 配置不出声，错误"发生了但看不见"。
解法（实测有效）：先 mkdir -p 输出目录，并把 slf4j-simple-1.7.36.jar 加进 -cp。
四、classpath 准备与成功运行实测
mvn dependency:build-classpath -Dmdep.outputFile=/tmp/gora-cp.txt
mkdir -p src-generated/java
java -cp "/tmp/slf4j-simple-1.7.36.jar:$CP" org.apache.gora.compiler.cli.GoraCompilerCLI \
src/main/resources/person.json src-generated/java
真实输出（逐行照抄，实测）：
SLF4J: Class path contains multiple SLF4J bindings.
SLF4J: Found binding in [jar:file:/tmp/slf4j-simple-1.7.36.jar!/org/slf4j/impl/StaticLoggerBinder.class]
SLF4J: Found binding in [jar:file:/root/.m2/repository/org/slf4j/slf4j-log4j12/1.6.6/slf4j-log4j12-1.6.6.jar!/org/slf4j/impl/StaticLoggerBinder.class]
SLF4J: See http://www.slf4j.org/codes.html#multiple_bindings for an explanation.
SLF4J: Actual binding is of type [org.slf4j.impl.SimpleLoggerFactory]
[main] INFO org.apache.gora.compiler.GoraCompiler - Compiling: /work/gora-demo/src/main/resources/person.json
[main] INFO org.apache.gora.compiler.GoraCompiler - Compiled into: /work/gora-demo/src-generated/java
[main] INFO org.apache.gora.compiler.cli.GoraCompilerCLI - Compiler executed SUCCESSFULL.
exit=0
=== 生成文件清单 ===
src-generated/java/demo/gora/Person.java
- 前 5 行 SLF4J 提示是预期现象（手动 slf4j-simple 与传递 slf4j-log4j12 并存），实际绑定 SimpleLoggerFactory，不影响结果；
- 三行 INFO 给出输入路径、输出目录与成功结论，配合
exit=0双重确认。
五、schema 与生成代码核验
schema person.json（fields: id/long 主键、name/string、age/int，namespace demo.gora），生成类关键签名（对生成文件 grep 实拍）：
21:public class Person extends org.apache.gora.persistency.impl.PersistentBase implements org.apache.avro.specific.SpecificRecord, org.apache.gora.persistency.Persistent {
97: public void put(int field$, java.lang.Object value) {
117: public void setId(java.lang.Long value) {
141: public void setName(java.lang.CharSequence value) {
165: public void setAge(java.lang.Integer value) {
类型映射实测结论：schema long → java.lang.Long、string → java.lang.CharSequence、int → java.lang.Integer。类同时实现 Avro SpecificRecord 与 Gora Persistent 契约（PersistentBase 基类 + 内嵌 SCHEMA$）。
后续工序：把 src-generated/java 加入 Maven 的 build-helper-maven-plugin additional-source（参考用法）或直接拷入 src/main/java，随工程一起编译。
六、Maven 命令速查
| 命令 | 作用 |
|---|---|
mvn dependency:build-classpath -Dmdep.outputFile=/tmp/gora-cp.txt | 导出编译器 classpath（实测命令） |
mvn clean package | 编译工程（含生成的持久化类） |
mvn dependency:tree -Dincludes=org.apache.gora | 查看 Gora 模块依赖树 |
jar tf ~/.m2/repository/org/apache/gora/gora-compiler-cli/0.9/gora-compiler-cli-0.9.jar | grep GoraCompilerCLI | 核实主类（实测命令） |
七、gora-maven-plugin 与周边（参考）
- gora-maven-plugin：把 schema 编译接入 Maven 生命周期的插件模块（模块清单见介绍篇第四章），goal 详情以官方插件站点为准（0.9 周边发行质量参差，本次未实测）；
- gora-goraci：官方"分布式有序表"示例工程，可作为接入 HBaseStore 的参考实现；
- gora-tutorial：官方教程工程，其
conf/gora.properties是配置模板的权威来源（配置篇第二章）。
八、FAQ（实测排障）
Q1：编译器 exit=1 且无任何输出？
两大原因叠加：输出目录不存在 + SLF4J 无绑定（第三章）。mkdir -p + classpath 加 slf4j-simple 即可。
Q2：schema 文件传目录行不行？
行，<schema file> 可以是目录（编译目录下全部 schema）。
Q3：生成类字段类型和预期不同？ 以实测映射为准：long→Long、string→CharSequence、int→Integer（第五章）；业务代码按 CharSequence 处理 name 类字段。
Q4：-license 必须传吗？
可选；不传则生成文件无许可头，公司合规要求时加 -license ASLv2。
Q5：多个 schema 怎么一次编译？ 指向目录，或多次调用逐个文件；输出目录共用。
Q6：生成的类能直接用 Jackson 序列化吗？ 可以但无意义——Gora 实体走 Avro 序列化链路（SCHEMA$ 内嵌），持久化交给 DataStore。
Q7：Java 17 编译生成的类有问题吗？ 实测生成源码可在 17 下编译；Gora 0.9 运行时对 JDK 17 无官方认证，生产建议 JDK 8/11。
Q8：能跳过 schema 直接写 @PersistenceCapable 式注解吗？ 不能，Gora 0.9 实体必须由 Avro schema 编译生成（区别于 JDO 注解模式）。
Q9：编译器输出目录里会生成什么？
每个 schema 一个 .java（namespace/类名.java，实测 demo/gora/Person.java），无其他文件。
Q10：项目已退役（Attic）还能用这些工具吗？ 能，0.9 为终版且构件长期留存 Maven Central；新项目选型需评估维护风险（介绍篇第八章迁移视角）。
参考链接
- Gora Compiler 文档：https://gora.apache.org/current/compiler.html
- Gora 主类源码（tag apache-gora-0.9）：https://github.com/apache/gora/tree/apache-gora-0.9/gora-compiler-cli
- 介绍篇实测：《Apache Gora 介绍与入门详解》