Apache Commons RDF 0.5.0 RDF 解析与序列化示例详解

目标：用 Apache Commons RDF 0.5.0 完成一次完整的「文件 → 内存图 → 文件」往返——真实解析 Turtle 与 RDF/XML 两种格式并逐条列出三元组，再真实序列化回 N-Triples 与 Turtle 并解读输出差异，同时辨析 simple 实现与 Jena/RDF4J 绑定的角色分工；本文全部命令与回显均已在 Ubuntu 22.04 实测通过。

解析与序列化是 Commons RDF 的能力分水岭：commons-rdf-api + commons-rdf-simple 只有内存建图能力，读写 RDF 文件必须借助绑定实现——0.5.0 提供 jena 绑定（底层 Apache Jena 3.5.0）与 rdf4j 绑定（底层 RDF4J 2.2.2），两者都通过 asGraph/asJenaGraph 系桥接方法与原生 API 互转。本文全部实验基于 jena 绑定，因为它实测提供了 0.5.0 experimental RDFParser 规范的完整实现（JenaRDFParser），且依赖树在 Maven 中央仓库可解析。

一、环境信息

本节固定可复现基线。解析/序列化能力来自 jena 绑定及其全套传递依赖（第三节列出实测依赖树）。

操作系统：Ubuntu 22.04.5 LTS
架构：x86_64
JDK：OpenJDK 17.0.20.1（apt 包 openjdk-17-jdk）
构建工具：Apache Maven 3.6.3
组件版本：commons-rdf-api 0.5.0、commons-rdf-simple 0.5.0、commons-rdf-jena 0.5.0（绑定 Jena 3.5.0 / jsonld-java 0.11.1 / httpclient-osgi 4.5.3 等，见第三节）
Maven 坐标：org.apache.commons:commons-rdf-jena:0.5.0（含 api 与 simple）
工作目录：/root/rdf-demo（工程）、/root/rdf-data（RDF 数据文件）

二、解析与序列化选型

本节先定格式与入口两个选型，再进实验。Commons RDF 的解析入口有两种，覆盖不同场景：

维度	experimental RDFParser（JenaRDFParser）	Jena 桥接（RDFDataMgr + asGraph）
API 包	`org.apache.commons.rdf.jena.experimental`	直接使用 `org.apache.jena.riot`
类型抽象	全程 Commons RDF 类型，业务零 Jena 依赖	中间经过 Jena `Model`
协议支持	`source(Path/InputStream/IRI)` + `contentType` + `base` + `target(Graph/Dataset)`	Jena riot 全能力（含远程 URL、压缩流）
定位	0.5.0 experimental 模块（可能调整）	成熟稳定，功能最全
本文用法	第四节 Turtle、第五节 RDF/XML	第四节 4.3 对比、第六节序列化输出

💡 技术拓展：RDF 常见序列化格式对比如下——

格式语法风格命名图可读性典型用途
Turtle 前缀缩写、分号/逗号列表否（TriG 才有）最好人工维护的数据文件
N-Triples 一行一条、全量 IRI 展开否差机器交换、diff 比对、流式处理
RDF/XML XML 是中老 Java 生态、W3C 标准
JSON-LD JSON 是好 Web API、前端集成
TriG / N-Quads Turtle/N-Triples 扩展是好/差命名图数据集交换

本文选 Turtle 作输入（人工可读、能覆盖前缀/语言标签/类型化字面量/空白节点/相对 IRI 五种特性）、RDF/XML 作第二输入（XML 生态兼容）、N-Triples 与 Turtle 作输出（最简形式 + 最可读形式）。

格式	语法风格	命名图	可读性	典型用途
Turtle	前缀缩写、分号/逗号列表	否（TriG 才有）	最好	人工维护的数据文件
N-Triples	一行一条、全量 IRI 展开	否	差	机器交换、diff 比对、流式处理
RDF/XML	XML	是	中	老 Java 生态、W3C 标准
JSON-LD	JSON	是	好	Web API、前端集成
TriG / N-Quads	Turtle/N-Triples 扩展	是	好/差	命名图数据集交换

三、前置条件：依赖与数据文件

本节给出完整依赖与两份输入数据。工程 pom 在《Apache Commons RDF 0.5.0 常用 API 与图操作详解》第三节已全文给出（api + simple + jena 三个依赖），此处补充 jena 绑定引入的完整依赖树（实测回显）：

cd /root/rdf-demo && mvn -B dependency:tree 2>&1 | grep -E "rdf-demo:jar|[+\\\\|].*jar"

[INFO] demo:rdf-demo:jar:1.0.0
[INFO] +- org.apache.commons:commons-rdf-api:jar:0.5.0:compile
[INFO] +- org.apache.commons:commons-rdf-simple:jar:0.5.0:compile
[INFO] \- org.apache.commons:commons-rdf-jena:jar:0.5.0:compile
[INFO]    +- org.apache.jena:jena-osgi:jar:3.5.0:compile
[INFO]    |  +- org.apache.httpcomponents:httpclient-osgi:jar:4.5.3:compile
[INFO]    |  +- org.apache.httpcomponents:httpcore-osgi:jar:4.4.6:compile
[INFO]    |  +- com.github.jsonld-java:jsonld-java:jar:0.11.1:compile
[INFO]    |  |  +- com.fasterxml.jackson.core:jackson-core:jar:2.9.0:compile
[INFO]    |  |  +- com.fasterxml.jackson.core:jackson-databind:jar:2.9.0:compile
[INFO]    |  |  |  \- com.fasterxml.jackson.core:jackson-annotations:jar:2.9.0:compile
[INFO]    |  |  \- commons-io:commons-io:jar:2.5:compile
[INFO]    |  +- org.apache.commons:commons-csv:jar:1.4:compile
[INFO]    |  +- org.apache.thrift:libthrift:jar:0.9.3:compile
[INFO]    |  +- org.slf4j:jcl-over-slf4j:jar:1.7.25:compile
[INFO]    |  +- org.slf4j:slf4j-api:jar:1.7.25:compile
[INFO]    |  +- org.apache.commons:commons-lang3:jar:3.4:compile
[INFO]    |  \- org.osgi:org.osgi.core:jar:5.0.0:compile
[INFO]    +- org.apache.servicemix.bundles:org.apache.servicemix.bundles.xerces:jar:2.11.0_1:compile
[INFO]    |  \- xml-apis:xml-apis:jar:1.4.01:compile
[INFO]    \- com.github.andrewoma.dexx:collection:jar:0.7:compile

解读：jena 绑定共拖入 18 个 jar。设计上有两个细节值得注意——其一，Jena 以 OSGi bundle 形态（jena-osgi）打包，连带 httpclient-osgi/httpcore-osgi；其二，XML 解析用 ServiceMix 重打包的 xerces（2.11.0_1）替代 JDK 内置实现，规避 JDK 内部 API 依赖，这也是它能在 JDK 17 上稳定运行的原因之一。

运行期 classpath 生成（与 API 详解篇相同，实测回显）：

cd /root/rdf-demo && mvn -B -q compile; echo COMPILE_EXIT=$?

COMPILE_EXIT=0

cd /root/rdf-demo && mvn -q -B dependency:build-classpath -Dmdep.outputFile=cp.txt

3.1 Turtle 数据文件

people.ttl（完整内容，文件路径 /root/rdf-data/people.ttl）刻意覆盖五种特性：前缀、多谓语缩写、语言标签字面量、类型化整数字面量、空白节点、相对 IRI：

@prefix foaf: <http://xmlns.com/foaf/0.1/> .
@prefix ex:  <http://example.org/people/> .

ex:alice foaf:name "Alice" ;
         foaf:age 30 ;
         foaf:knows ex:bob .

ex:bob  foaf:name "Bob" , "Bobby"@en ;
        foaf:knows _:charlie .

_:charlie foaf:name "Charlie" ;
          foaf:knows <#wanda> .

3.2 RDF/XML 数据文件

people.rdf（完整内容，文件路径 /root/rdf-data/people.rdf），注意其中嵌套元素会展开为 rdf:type 三元组：

<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
         xmlns:foaf="http://xmlns.com/foaf/0.1/">

  <foaf:Person rdf:about="http://example.org/people/dave">
    <foaf:name>Dave</foaf:name>
    <foaf:mbox rdf:resource="mailto:dave@example.org"/>
  </foaf:Person>

  <foaf:Person rdf:about="http://example.org/people/erin">
    <foaf:name>Erin</foaf:name>
    <foaf:knows rdf:resource="http://example.org/people/dave"/>
  </foaf:Person>

</rdf:RDF>

四、Turtle 解析详解

本节用两种入口解析同一个 people.ttl，实测三元组清单、空白节点标签重映射与相对 IRI 解析。

4.1 experimental RDFParser 入口实测

解析代码（RdfDemo.parseTurtle，主类全文见 API 详解篇第三节）：

JenaRDF rdf = new JenaRDF();
Graph graph = rdf.createGraph();
new JenaRDFParser()
        .source(Paths.get(DATA, "people.ttl"))
        .contentType(RDFSyntax.TURTLE)
        .base("http://example.org/people")
        .target(graph)
        .parse()
        .get();
System.out.println("解析得到三元组数=" + graph.size());
for (Triple t : graph.iterate()) {
    System.out.println("  " + t.getSubject().ntriplesString()
            + " " + t.getPredicate().ntriplesString()
            + " " + t.getObject().ntriplesString());
}
IRI wanda = rdf.createIRI("http://example.org/people#wanda");
System.out.println("相对 IRI <#wanda> 已按 base 解析: contains=" + graph.contains(null, null, wanda));

运行（实测回显）：

cd /root/rdf-demo && java -Dfile.encoding=UTF-8 -Ddata.dir=/root/rdf-data -cp target/classes:$(cat cp.txt) demo.RdfDemo parse-ttl

== 解析 Turtle（experimental RDFParser 统一入口） ==
解析得到三元组数=8
  <http://example.org/people/bob> <http://xmlns.com/foaf/0.1/knows> _:Be8852f12c60104893d67852b596c6054
  <http://example.org/people/bob> <http://xmlns.com/foaf/0.1/name> "Bobby"@en
  <http://example.org/people/bob> <http://xmlns.com/foaf/0.1/name> "Bob"
  _:Be8852f12c60104893d67852b596c6054 <http://xmlns.com/foaf/0.1/knows> <http://example.org/people#wanda>
  _:Be8852f12c60104893d67852b596c6054 <http://xmlns.com/foaf/0.1/name> "Charlie"
  <http://example.org/people/alice> <http://xmlns.com/foaf/0.1/knows> <http://example.org/people/bob>
  <http://example.org/people/alice> <http://xmlns.com/foaf/0.1/age> "30"^^<http://www.w3.org/2001/XMLSchema#integer>
  <http://example.org/people/alice> <http://xmlns.com/foaf/0.1/name> "Alice"
相对 IRI <#wanda> 已按 base 解析: contains=true

结果解读：

8 条三元组全部落地，与源文件的语义一一对应：ex:alice 3 条、ex:bob 3 条、_:charlie 2 条。
空白节点标签被重映射：源文件写的是 _:charlie，解析后变成随机标签 _:Be8852f12c60104893d67852b596c6054。这是 RDFParser 规范行为（每次解析会话内重映射标签，避免不同会话标签冲突）；同一会话内引用同一空白节点的 3 条三元组标签一致，图结构语义不变。
相对 IRI 按 base 解析：<#wanda> 依据 .base("http://example.org/people") 变成 http://example.org/people#wanda，末行 contains=true 给出程序级验证。
字面量形态忠实还原：语言标签 "Bobby"@en、类型化整数 "30"^^xsd:integer 均保持 RDF 1.1 规范形态。

4.2 Jena 桥接入口实测

同一份数据走 Jena 原生 riot 读入 Model，再用 asGraph 包成 Commons RDF 视图（RdfDemo.parseTurtleJenaBridge）：

JenaRDF rdf = new JenaRDF();
Model model = ModelFactory.createDefaultModel();
try (InputStream in = Files.newInputStream(Paths.get(DATA, "people.ttl"))) {
    RDFDataMgr.read(model, in, Lang.TURTLE);
}
Graph graph = rdf.asGraph(model);
IRI alice = rdf.createIRI("http://example.org/people/alice");
try (Stream<? extends Triple> s = graph.stream(alice,
        rdf.createIRI("http://xmlns.com/foaf/0.1/name"), null)) {
    s.forEach(t -> System.out.println("  桥接图查询: " + t.getObject().ntriplesString()));
}

运行（实测回显）：

cd /root/rdf-demo && java -Dfile.encoding=UTF-8 -Ddata.dir=/root/rdf-data -cp target/classes:$(cat cp.txt) demo.RdfDemo parse-ttl-jena

== 解析 Turtle（Jena RDFDataMgr + asGraph 桥接） ==
桥接视图三元组数=8
  桥接图查询: "Alice"

结果解读：asGraph(model) 是视图而非拷贝——桥接图的三元组数 8 与 Model 完全一致，且对桥接图的过滤查询（按主语 alice + 谓语 name）直接命中。这种入口适合「已有 Jena 代码」的项目：数据留在 Jena 体系内，Commons RDF API 作为统一查询门面叠加其上。

五、RDF/XML 解析详解

RDF/XML 换用 RDFSyntax.RDFXML 常量即可，解析代码（RdfDemo.parseRdfXml）：

new JenaRDFParser()
        .source(Paths.get(DATA, "people.rdf"))
        .contentType(RDFSyntax.RDFXML)
        .target(graph)
        .parse()
        .get();

运行（实测回显）：

cd /root/rdf-demo && java -Dfile.encoding=UTF-8 -Ddata.dir=/root/rdf-data -cp target/classes:$(cat cp.txt) demo.RdfDemo parse-rdfxml

== 解析 RDF/XML（experimental RDFParser 统一入口） ==
解析得到三元组数=6
  <http://example.org/people/erin> <http://xmlns.com/foaf/0.1/knows> <http://example.org/people/dave>
  <http://example.org/people/erin> <http://xmlns.com/foaf/0.1/name> "Erin"
  <http://example.org/people/erin> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://xmlns.com/foaf/0.1/Person>
  <http://example.org/people/dave> <http://xmlns.com/foaf/0.1/mbox> <mailto:dave@example.org>
  <http://example.org/people/dave> <http://xmlns.com/foaf/0.1/name> "Dave"
  <http://example.org/people/dave> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://xmlns.com/foaf/0.1/Person>

结果解读：

6 条三元组：源文件两个 <foaf:Person> 节点各展开 3 条。
rdf:type 三元组自动生成：RDF/XML 的类型化节点语法 <foaf:Person rdf:about="http://example.org/people/dave"> 隐含「该主体是 foaf:Person」的陈述，解析器补出两条 rdf:type 三元组（实测可见 rdf-syntax-ns#type）。这是 RDF/XML 特有的语义糖，Turtle 需要显式写 a foaf:Person。
资源属性展开：<foaf:mbox rdf:resource="mailto:dave@example.org"/> 展开为宾语为 IRI 的三元组，mailto: 是合法 IRI scheme。

六、序列化输出详解

本节把解析出的图分别序列化为 N-Triples 与 Turtle。代码（RdfDemo.serialize）：Commons RDF 图经 asJenaGraph 桥接回 Jena，用 RDFDataMgr.write 输出：

JenaRDF rdf = new JenaRDF();
Graph graph = rdf.createGraph();
new JenaRDFParser()
        .source(Paths.get(DATA, "people.ttl"))
        .contentType(RDFSyntax.TURTLE)
        .base("http://example.org/people")
        .target(graph)
        .parse()
        .get();

ByteArrayOutputStream nt = new ByteArrayOutputStream();
RDFDataMgr.write(nt, rdf.asJenaGraph(graph), Lang.NTRIPLES);
System.out.print(new String(nt.toByteArray(), StandardCharsets.UTF_8));

ByteArrayOutputStream ttl = new ByteArrayOutputStream();
RDFDataMgr.write(ttl, rdf.asJenaGraph(graph), Lang.TURTLE);
System.out.print(new String(ttl.toByteArray(), StandardCharsets.UTF_8));

运行（实测回显）：

cd /root/rdf-demo && java -Dfile.encoding=UTF-8 -Ddata.dir=/root/rdf-data -cp target/classes:$(cat cp.txt) demo.RdfDemo serialize

== 序列化（Commons RDF Graph 经 asJenaGraph 回 Jena 输出） ==
-- N-Triples 输出 --
<http://example.org/people/bob> <http://xmlns.com/foaf/0.1/knows> _:B9b715883d6328e442dc3d2e848f93267 .
<http://example.org/people/bob> <http://xmlns.com/foaf/0.1/name> "Bobby"@en .
<http://example.org/people/bob> <http://xmlns.com/foaf/0.1/name> "Bob" .
<http://example.org/people/alice> <http://xmlns.com/foaf/0.1/knows> <http://example.org/people/bob> .
<http://example.org/people/alice> <http://xmlns.com/foaf/0.1/age> "30"^^<http://www.w3.org/2001/XMLSchema#integer> .
<http://example.org/people/alice> <http://xmlns.com/foaf/0.1/name> "Alice" .
_:B9b715883d6328e442dc3d2e848f93267 <http://xmlns.com/foaf/0.1/knows> <http://example.org/people#wanda> .
_:B9b715883d6328e442dc3d2e848f93267 <http://xmlns.com/foaf/0.1/name> "Charlie" .
-- Turtle 输出 --
@prefix ex:    <http://example.org/people/> .
@prefix foaf:  <http://xmlns.com/foaf/0.1/> .

ex:bob  foaf:knows  [ foaf:knows  <http://example.org/people#wanda> ;
                      foaf:name   "Charlie"
                    ] ;
        foaf:name   "Bobby"@en , "Bob" .

ex:alice  foaf:age  30 ;
        foaf:knows  ex:bob ;
        foaf:name   "Alice" .

结果解读（对照 4.1 节解析回显）：

N-Triples 是解析结果的规范化镜像：8 条三元组、每行一条、行尾句点；IRI 全量展开、主语按字典序排列。空白节点标签输出为 _:B9b715883d6328e442dc3d2e848f93267（本次运行会话的重映射标签，与 4.1 节的 _:Be8852f12c60104893d67852b596c6054 不同属正常——标签会话内一致、会话间随机）。
Turtle 输出发生三重优化：前缀声明（@prefix ex:/foaf:）、同主语谓语合并（foaf:name "Bobby"@en , "Bob"）、空白节点内联为匿名节点（Turtle 空白节点属性列表语法）（ex:bob foaf:knows [ foaf:knows <http://example.org/people#wanda> ; foaf:name "Charlie" ]）。数据模型完全等价，文件体积与可读性大幅提升。
类型化字面量输出简写：Turtle 输出 foaf:age 30，N-Triples 输出 "30"^^<http://www.w3.org/2001/XMLSchema#integer>——Turtle 中整数简写即 xsd:integer 的语法糖，两种输出语义相同。
序列化排序不构成 API 承诺：N-Triples 行序、Turtle 节点序均为 Jena 内部排序行为， diff 比对时建议先归一化。

七、simple 与 Jena/RDF4J 绑定的角色差异

本节把全系列实验背后「谁负责什么」讲透。Commons RDF 0.5.0 的模块生态实测分工如下：

模块	角色	内存图	解析/序列化	存储后端	依赖量
commons-rdf-api	接口定义（编译期唯一必选）	—	—	—	0
commons-rdf-simple	参考实现	内置内存图	无	无	1（仅 api）
commons-rdf-jena	Jena 3.5.0 绑定	视图桥接	全格式（riot）	可接 TDB 等	18 个 jar
commons-rdf-rdf4j	RDF4J 2.2.2 绑定	视图桥接	全格式	可接 Repository/Sail	RDF4J 全家桶
commons-rdf-jsonld-java	JSON-LD 解析适配	无	仅 JSON-LD	无	轻量

角色差异的三层含义（全部有本文实测支撑）：

simple 是「教科书实现」：接口语义的内存参考，纯建图/遍历场景两 jar 即用（依赖树实测只有 api+simple 两节点），但没有文件 IO 能力——给它一个 Turtle 文件它无法解析。
绑定实现是「能力供应商」：解析、序列化、存储都来自底层库。Commons RDF 的价值在于把这些能力收敛到统一 API 后面——JenaRDFParser 的产出是标准 Triple，业务代码不知道 riot 的存在（4.1 节实测）。
桥接是双向的：Jena → Commons RDF 用 asGraph(model)（4.2 节视图实测），Commons RDF → Jena 用 asJenaGraph(graph)（第六节序列化实测）。视图是零拷贝的：桥接图上的 stream/contains 直接穿透到 Jena Model。

💡 技术拓展：选型上一句话总结——用 simple 写业务与单测（快、零依赖），用 jena/rdf4j 绑定做 IO（全格式），接口层永远依赖 api。若项目已深度绑定某一底层库（如已有 Jena TDB 存储），优先选对应绑定以获得零拷贝视图；若从零开始且只需要文件读写，两者皆可，jena 绑定在 0.5.0 上实验覆盖更完整（experimental RDFParser 仅 jena 提供实现）。

八、常见问题（FAQ）

Q1：不设置 base 解析含相对 IRI 的文件会怎样？ 实测不会报错，但结果更危险：解析器按来源路径猜测 base，/root/rdf-data/people.ttl 的相对 IRI <#wanda> 被静默解析为 file:///root/rdf-data/people.ttl#wanda（独立小工具 NoBaseParse 实测回显）：

解析得到三元组数=8
file 路径猜 base 命中: contains=true
期望 http base 命中: contains=false

8 条三元组全部「成功」落地，但相对 IRI 落在错误的 file 命名空间。解决：解析含相对 IRI 的文件时显式传 .base("http://example.org/people")（见 4.1 节）。

Q2：两次解析同一文件，空白节点标签为什么不一样？ RDFParser 按解析会话重映射空白节点标签（4.1 节 _:charlie → _:Be8852f12c60104893d67852b596c6054，第六节另一次运行 → _:B9b715883d6328e442dc3d2e848f93267）。会话内一致即可保证图结构等价；需要跨会话稳定标识请改用 IRI 或在业务层维护映射。

Q3：RDF/XML 解析比源文件多了 rdf:type 三元组，是 bug 吗？ 不是。<foaf:Person rdf:about="http://example.org/people/dave"> 类型化节点语法在 RDF/XML 规范中隐含类型陈述（第五节实测 6 条中的 2 条 rdf:type）。这是格式语义，Turtle 无此糖。

Q4：为什么不用 simple 实现直接序列化？ simple 没有实现序列化。0.5.0 的 experimental RDFParser 规范只有 jena 绑定提供实现（rdf4j 绑定同样走自身桥接），文件 IO 必须由绑定承担，输出经 asJenaGraph 借 Jena riot 完成（第六节实测）。

Q5：运行时三行 SLF4J 提示如何消除？ jena-osgi 带 slf4j-api 1.7.25 但无实现，SLF4J 回退 NOP 并打印提示（不影响功能）。在 pom 加 org.slf4j:slf4j-simple:1.7.25 依赖即可；本文回显均以 grep -v SLF4J 过滤提示行后展示。

Q6：commons-rdf-jena 0.5.0 绑定的 Jena 3.5.0 很老，能在 JDK 17 上跑吗？ 实测可以（本文全部解析/序列化实验均在 OpenJDK 17.0.20.1 上完成）。依赖树中 Jena 全部以 OSGi bundle 形态打包、XML 解析用重打包的 xerces 规避 JDK 内部 API（第三节），这是它在高版本 JDK 上稳定的关键。

九、参考链接

Commons RDF 用户指南（解析与序列化章节）：https://commons.apache.org/proper/commons-rdf/userguide.html
Commons RDF 0.5.0 API Javadoc（experimental.RDFParser）：https://commons.apache.org/proper/commons-rdf/javadocs/api-0.5.0/
Maven 坐标页（jena 绑定）：https://repo1.maven.org/maven2/org/apache/commons/commons-rdf-jena/
Apache Jena riot 文档（底层解析/序列化引擎）：https://jena.apache.org/documentation/notes/riot.html
Turtle 1.1 规范：https://www.w3.org/TR/turtle/
RDF/XML 1.1 规范：https://www.w3.org/TR/rdf-syntax-grammar/
N-Triples 1.1 规范：https://www.w3.org/TR/n-triples/