Apache XMLSchema 介绍与选型指南

目标：讲清 Apache XMLSchema（构件名 xmlschema-core）是什么、能做什么、不能做什么，并与同类 XML Schema 对象模型方案做横向对比，给出可落地的选型结论。本文所有版本号、坐标、体积、依赖树均在 Ubuntu 22.04 + OpenJDK 17 + Maven 3.6.3 环境实测通过。

一、环境信息

本章先交代实测环境的软硬件版本，后续所有结论都基于该环境。先查看操作系统与基础工具链版本：

grep PRETTY_NAME /etc/os-release

实测输出：

PRETTY_NAME="Ubuntu 22.04.5 LTS"

java -version

实测输出：

openjdk version "17.0.20.1" 2026-08-18
OpenJDK Runtime Environment (build 17.0.20.1+1-1-22.04-Ubuntu)
OpenJDK 64-Bit Server VM (build 17.0.20.1+1-1-22.04-Ubuntu, mixed mode, sharing)

mvn -version | head -3

实测输出：

Apache Maven 3.6.3
Maven home: /usr/share/maven
Java version: 17.0.20.1, vendor: Ubuntu, runtime: /usr/lib/jvm/java-17-openjdk-amd64

验证 Maven 能正常拉取本文主角的构件（这也是最常用的单依赖获取方式）：

mvn dependency:get -Dartifact=org.apache.ws.xmlschema:xmlschema-core:2.3.3 2>&1 | grep -E 'BUILD|Downloaded.*xmlschema'

实测输出：

[INFO] BUILD SUCCESS

💡 说明：dependency:get 是 Maven 自带的按坐标精确拉取构件的命令，不需要工程 POM，常用于提前把依赖预热的本地仓库。BUILD SUCCESS 表示 2.3.3 构件已真实下载到本地。

二、软件概述

Apache XMLSchema 是 Apache Web Services 旗下处理 W3C XML Schema（XSD）的纯 Java 库，官方描述为 "Apache Web Services - XmlSchema"。它把 XSD 文档解析成一个内存中的 XML Schema 信息集（Infoset）对象模型：读入 XSD，得到 XmlSchemaCollection/XmlSchema/XmlSchemaElement 等对象树，程序再对这些对象做遍历、查找、修改与重新序列化。它不是校验器，也不生成代码，而是给上层框架（Axis2、CXF 等）提供「理解 XSD」的统一底座。

Maven 坐标与最新稳定版（以 Maven Central 的 maven-metadata.xml 实测为准）：

curl -s "https://repo1.maven.org/maven2/org/apache/ws/xmlschema/xmlschema-core/maven-metadata.xml" | tail -8

实测输出：

      <version>2.3.0</version>
      <version>2.3.1</version>
      <version>2.3.2</version>
      <version>2.3.3</version>
    </versions>
    <lastUpdated>20260929083836</lastUpdated>
  </versioning>
</metadata>

curl -s "https://repo1.maven.org/maven2/org/apache/ws/xmlschema/xmlschema-core/maven-metadata.xml" | grep -E 'latest|release'

实测输出：

    <latest>2.3.3</latest>
    <release>2.3.3</release>

⚠️ 注意：search.maven.org 的搜索 API 当时返回的 latestVersion 仍是 2.3.2（缓存滞后），而 maven-metadata.xml 已是 2.3.3（2026-09-29 上架）。查最新版本时以 maven-metadata.xml 为准，不要只看搜索页缓存。

版本线如实披露：Maven Central 上该构件共 15 个版本，从 2.0 线（2.0/2.0.1/2.0.2/2.0.3）到 2.1、2.2 线（2.2.0~2.2.5），再到 2.3 线（2.3.0/2.3.1/2.3.2/2.3.3）。仓库 maven-metadata.xml 的 lastUpdated 为 2026-09-29，说明 2.3 线仍在上架新版本。

活跃度（GitHub 官方镜像 apache/ws-xmlschema 实测）：

curl -s "https://api.github.com/repos/apache/ws-xmlschema" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d['full_name'], '|', d.get('description'), '| pushed_at:', d['pushed_at'], '| stars:', d['stargazers_count'], '| open_issues:', d['open_issues_count'])"

实测输出：

apache/ws-xmlschema | Apache Web Services - XmlSchema | pushed_at: 2026-10-14T04:59:21Z | stars: 18 | open_issues: 0

💡 说明：这是一个典型的「基础设施库」活跃度画像——Star 数低（18）、无挂起 issue，但仓库在 2026 年 10 月仍在持续推送。它服务的不是终端开发者社区，而是 Axis2/CXF 等下游运行时的版本需求，判断其活跃度应看下游生态与推送时间，而不是 Star 数。

三、核心架构

本节拆解 xmlschema-core 的对象模型与工作流程，并实测验证「单 jar、零传递依赖、OSGi bundle」这些架构卖点。

3.1 对象模型层次

核心对象层次是三层：

XmlSchemaCollection：模式集合，负责读取 XSD、解析 xsd:include/xsd:import、按命名空间或 systemId 查找、持有解析器（URIResolver）等全局配置；
XmlSchema：单个 XSD 文档对应的模型，持有 targetNamespace、全局元素、全局类型、命名空间上下文等；
各构件对象：XmlSchemaElement、XmlSchemaComplexType、XmlSchemaSimpleType、XmlSchemaAttribute、XmlSchemaSequence 等，与 XSD 规范中的构件一一对应。

工作流程是「read → 对象树 →（查找/遍历/修改）→ write」：read() 把 XSD 解析为对象树，write() 把对象树重新序列化为 XSD，中间的查找与遍历全部是对内存对象的操作。

用 javap 直接观察 2.3.3 的公开 API 面（这是「轻量」的第一手证据）：

javap -cp lib/xmlschema-core-2.3.3.jar org.apache.ws.commons.schema.XmlSchemaCollection 2>&1 | sed -n 1,16p

实测输出：

Compiled from "XmlSchemaCollection.java"
public final class org.apache.ws.commons.schema.XmlSchemaCollection {
  java.lang.String baseUri;
  java.util.Deque<org.apache.ws.commons.schema.XmlSchemaCollection$SchemaKey> stack;
  java.util.Map<javax.xml.namespace.QName, java.util.List<org.apache.ws.commons.schema.TypeReceiver>> unresolvedTypes;
  org.apache.ws.commons.schema.XmlSchema xsd;
  int builderNestingDepth;
  static final long MAX_ENTITY_EXPANSIONS;
  public org.apache.ws.commons.schema.XmlSchemaCollection();
  public boolean check(org.apache.ws.commons.schema.XmlSchemaCollection$SchemaKey);
  public org.apache.ws.commons.schema.extensions.ExtensionRegistry getExtReg();
  public java.util.Map<java.lang.String, org.apache.ws.commons.schema.XmlSchema> getKnownNamespaceMap();
  public org.apache.ws.commons.schema.utils.NamespacePrefixList getNamespaceContext();
  public org.apache.ws.commons.schema.resolver.URIResolver getSchemaResolver();
  public org.apache.ws.commons.schema.XmlSchemaType getTypeByQName(javax.xml.namespace.QName);
  public org.apache.ws.commons.schema.XmlSchema[] getXmlSchema(java.lang.String);

💡 技术拓展：把 XSD 变成内存对象树，业界不止 xmlschema-core 一种实现。常见选择对比——

方案原理/特点适用场景
Apache XMLSchema（xmlschema-core）轻量建模，只做信息集对象树，jar 约 190KB、零传递依赖 WS 运行时建模、元数据分析、代码生成前置
Xerces XML Schema API（XSModel）解析器内置的 PSVI 级模型，信息最全但重需要完整校验后信息的深度工具
手工 DOM/SAX 解析用 JAXP 直接遍历 XSD 文档树只取一两个字段、不想引依赖
JAXB xjc / wsdl2java 直接生成代码，跳过显式建模目标是数据绑定而非模型分析

本文主角选第一种，理由是它把「建模」这一件事做小做纯，下游框架（CXF/Axis2）也是这么选的。

方案	原理/特点	适用场景
Apache XMLSchema（xmlschema-core）	轻量建模，只做信息集对象树，jar 约 190KB、零传递依赖	WS 运行时建模、元数据分析、代码生成前置
Xerces XML Schema API（XSModel）	解析器内置的 PSVI 级模型，信息最全但重	需要完整校验后信息的深度工具
手工 DOM/SAX 解析	用 JAXP 直接遍历 XSD 文档树	只取一两个字段、不想引依赖
JAXB xjc / wsdl2java	直接生成代码，跳过显式建模	目标是数据绑定而非模型分析

3.2 单 jar、零传递依赖实测

先看构件体积与 jar 内容：

ls -l lib/xmlschema-core-2.3.3.jar

实测输出：

-rw-r--r-- 1 root root 193402 Oct 16 02:34 lib/xmlschema-core-2.3.3.jar

unzip -l lib/xmlschema-core-2.3.3.jar | tail -2 && unzip -l lib/xmlschema-core-2.3.3.jar | grep -c '\.class'

实测输出：

---------                     -------
   389703                     155 files
135

再在一个最小 Maven 工程里验证传递依赖（完整工程搭建过程见《Apache XMLSchema 在 Ubuntu 22.04 集成使用指南》）：

mvn dependency:tree 2>&1 | sed -n '/maven-dependency-plugin/,/BUILD/p' | head -6

实测输出：

[INFO] --- maven-dependency-plugin:2.8:tree (default-cli) @ xmlschema-demo ---
[INFO] com.example:xmlschema-demo:jar:1.0.0
[INFO] \- org.apache.ws.xmlschema:xmlschema-core:jar:2.3.3:compile
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS

依赖树里只有它自己——一个 193,402 字节、155 个文件（135 个 .class）的 jar，没有任何传递依赖。2.3.3 jar 的 SHA-256 实测为 9d9b17f0d383e38c2ce041675211572992d6a1012926cc77f72d89be201614e3，可校验后入库内网仓库。其 POM 打包类型为 bundle（OSGi），可直接放入 OSGi 容器环境。

四、功能特性

本节把 xmlschema-core 的能力面列全，每项都注明验证方式，避免「说明书式罗列」。

能力	说明	验证方式
XSD 建模读取	`XmlSchemaCollection.read(Source)` 读入 XSD 为对象树，自动解析 xsd:include/xsd:import	《集成使用指南》示例 1 实测
全局查找	集合级 `getElementByQName`/`getTypeByQName` 跨 schema 深查找	《集成使用指南》实测回显
深度遍历	序列子元素、属性、简单类型约束面（facet）逐层可取	《集成使用指南》实测回显
对象级建模	`new XmlSchema(...)` 从零构造 XSD 并序列化	《集成使用指南》BuildSchema 实测
序列化	`write(OutputStream)` 输出规范化 XSD，默认无 XML 声明、四空格缩进	《配置参数详解》diff 对照实测
解析器定制	`setSchemaResolver(URIResolver)` 重定向 import/include 的 schemaLocation	《配置参数详解》实测回显
网络防护	2.3.x 内置 remote.allowNetwork/maxBytes/maxImportDepth 等 SSRF/资源耗尽防护	《配置参数详解》实测回显
只读集合保护	系统属性开启后 getElements() 等返回运行时校验的只读集合	《配置参数详解》实测回显

💡 说明：表里「建模」「查找」「遍历」是它的主业；「校验实例文档」「生成代码」不是它的职责，见下一章限制说明。

五、适用场景与限制

5.1 适用场景

Web 服务运行时的 schema 底座：CXF 与 Axis2 都依赖 xmlschema-core 做 WSDL/XSD 建模。实际锁定版本实测（取自各自父 POM）：

curl -s "https://repo1.maven.org/maven2/org/apache/cxf/cxf-parent/4.1.4/cxf-parent-4.1.4.pom" | grep '<cxf.xmlschema.version>'

实测输出：

        <cxf.xmlschema.version>2.3.2</cxf.xmlschema.version>

curl -s "https://repo1.maven.org/maven2/org/apache/axis2/axis2/1.8.2/axis2-1.8.2.pom" | grep '<xmlschema.version>'

实测输出：

        <xmlschema.version>2.3.0</xmlschema.version>

即 CXF 4.1.4 锁定 2.3.2，Axis2 1.8.2 锁定 2.3.0。给这两个框架做 schema 相关扩展（自定义拦截器分析消息结构、动态组装 schema 等）时，xmlschema-core 是唯一官方入口。

XSD 元数据分析与治理：扫描一批 XSD，统计全局元素、类型、引用关系、命名空间清单，做企业 schema 治理或文档化。
离线/内网 schema 集合管理：配合自定义 URIResolver 把远程 import 重定向到本地镜像，把一组互相引用的 XSD 统一装载进一个集合。
代码生成器的前置解析：自己写生成器时，用它的对象树拿到精确的类型/出现次数/约束信息，不必手写 XSD 解析。

5.2 限制（如实披露）

不做实例文档校验。它只建模 XSD 本身；校验 XML 实例必须走 JAXP Validator（与 xmlschema-core 联动的完整示例见《Apache XMLSchema 在 Ubuntu 22.04 集成使用指南》）。
读取容错宽松。重复的全局元素声明在 read() 时不报错（后一个覆盖前一个），同样的 XSD 交给 JAXP 编译会报 sch-props-correct.2 错误。这一行为差异在《Apache XMLSchema 2.3.3 配置参数详解》有对照实测。
API 冷门、资料少。公开文档以 javadoc 为主，很多行为要靠读源码确认（例如 getItems() 返回的是 XmlSchemaSequenceMember 接口而非 XmlSchemaObject，直接按后者强转会编译失败——这是实测踩过的坑）。
集合对象非线程安全。源码注释明确说明其内部 map 是普通可变对象，跨线程共享 XmlSchemaCollection 需自行同步或只读共享。

六、同类选型对比

本节回答「什么时候选它，什么时候不选」。先把候选方案的体积与依赖放在一起实测对比（Xerces 两个 jar 体积取自 Maven Central 的 HTTP 响应头）：

curl -sI "https://repo1.maven.org/maven2/xerces/xercesImpl/2.12.2/xercesImpl-2.12.2.jar" | grep -i content-length

实测输出：

content-length: 1446149

curl -sI "https://repo1.maven.org/maven2/xml-apis/xml-apis/1.4.01/xml-apis-1.4.01.jar" | grep -i content-length

实测输出：

content-length: 220536

选型对照表：

维度	xmlschema-core 2.3.3	Xerces XSModel（xercesImpl 2.12.2 + xml-apis 1.4.01）	手工 DOM 解析
依赖体积	193,402 字节，0 传递依赖	约 1,666,685 字节，且与 JDK 内置 Xerces 版本易冲突	0（复用 JDK）
模型完整度	信息集级：元素/类型/属性/约束面	PSVI 级：信息最全	自定义，要多少写多少
xsd:import/include 处理	自动解析进集合，可定制解析器	自动，但解析行为随解析器配置	全部自己实现
修改后重新序列化	write() 一行完成	不支持直接回写	自己拼 DOM
实例文档校验	不支持（配 JAXP）	支持	不支持
上游用户	CXF、Axis2	各类校验工具	一次性脚本

关键差异与选型建议：需要「理解并操作 XSD」选 xmlschema-core；需要「校验 XML 实例」选 JAXP/Xerces 校验器；两者在工程里经常同时存在——用前者建模分析，用后者校验实例。只取一两个字段的一次性脚本不必引库，DOM 就够。若项目已被 CXF/Axis2 传递引入 xmlschema-core，直接复用该版本即可，注意 CXF 4.1.4 传的是 2.3.2、Axis2 1.8.2 传的是 2.3.0，同工程共存时用依赖管理统一到 2.3.3。

七、参考链接

Maven Central 构件页：https://repo1.maven.org/maven2/org/apache/ws/xmlschema/xmlschema-core/
官方源码镜像（GitHub）：https://github.com/apache/ws-xmlschema
Apache 官方项目页：https://ws.apache.org/commons/xmlschema20/（2.x 线文档）
javadoc（2.3.3）：https://ws.apache.org/commons/xmlschema20/apidocs/
相关落地文档：《Apache XMLSchema 在 Ubuntu 22.04 集成使用指南》《Apache XMLSchema 2.3.3 配置参数详解》