什么是XML Catalog Resolver_技术教程

CatalogResolver 是 Java 中基于 OASIS XML Catalog 标准实现的资源映射策略接口，用于安全替换外部 XML 实体路径；需通过 CatalogManager 创建并按 API 类型（StAX/SAX/DOM/XSLT）注册，prefer="public" 可规避恶意 SYSTEM ID 重定向，配合禁用 DOCTYPE 更安全。

CatalogResolver 是 Java 中用于集中管理 XML 外部资源（如 DTD、XSD、XSLT、实体）加载路径的核心接口，它不是“解析器本身”，而是一个策略控制器：把 SYSTEM ID 或 PUBLIC ID 映射到本地文件或可信 URL，从而绕过网络请求、规避远程加载风险，并支持离线验证。

它本质是 OASIS XML Catalog 标准（v1.1）在 Java 的落地实现，同时兼容多个 XML API 层——既是 XMLResolver（StAX），也是 EntityResolver（SAX）、LSResourceResolver（DOM）、URIResolver（XSLT），一套配置，多处生效。

怎么创建并注册 CatalogResolver？

Java 14+（特别是 JDK 17/21）已内置 javax.xml.catalog 模块，无需额外依赖。关键不是“写一个 Resolver”，而是“用 CatalogManager 加载 catalog 文件生成它”：

CatalogResolver 实例必须通过 CatalogManager.catalogResolver(...) 创建，不能直接 new
catalog 文件（如 catalog.xml）需符合 OASIS 格式，含、、等条目
注册方式因解析器类型而异：StAX 用 XMLInputFactory.setXMLResolver()；SAX 用 XMLReader.setProperty("http://apache.org/xml/properties/internal/entity-resolver", resolver)；XSLT 用 TransformerFactory.setURIResolver()

// 示例：StAX 场景下启用 CatalogResolver
XMLInputFactory factory = XMLInputFactory.newInstance();
Catalog catalog = CatalogManager.catalog(CatalogFeatures.defaults(), 
    URI.create("file:///path/to/catalog.xml"));
CatalogResolver resolver = CatalogManager.catalogResolver(catalog);
factory.setXMLResolver(resolver); // ✅ 关键一步
XMLStreamReader reader = factory.createXMLStreamReader(new FileInputStream("doc.xml"));

为什么 prefer="public" 反而更安全？

OASIS 标准规定：解析器先查 system 条目，再查 public 条目；但 CatalogResolver 的 prefer 属性控制“当 SYSTEM ID 和 PUBLIC ID 同时存在时优先匹配谁”。默认 prefer="public" 并非鼓励用 PUBLIC ID，而是为了避免 SYSTEM ID 被恶意重定向——因为 SYSTEM ID 更容易被外部文档篡改（比如 DTD 声明里硬编码一个公网地址），而 PUBLIC ID 是标准化字符串（如 -//OASIS//DTD DocBook XML V4.5//EN），更可控、更易映射到本地 trusted catalog 条目。

若不设 prefer，且 catalog 中同时有和，解析器仍会优先走危险的 system 条目
显式设 prefer="public" 可强制 fallback 到更可信的 public 映射（前提是 catalog 里有对应条目）
真正安全的做法是：禁用外部 DTD（setFeature("http://apache.org/xml/features/disallow-doctype-decl", true)），再配合 catalog 控制白名单资源

常见报错和踩坑点

实际集成时，90% 的问题不是代码写错，而是路径、协议或类加载没对齐：

CatalogException: No matching entry found → catalog 文件未被正确加载（检查 URI 是否可访问、是否用了 file:// 协议、路径是否含空格或中文）
XMLStreamException: Cannot resolve entity → 注册了 CatalogResolver，但解析器没启用验证或没触发外部引用（比如 XML 没声明 DOCTYPE）
SAX 解析器报 java.lang.ClassCastException: CatalogResolver cannot be cast to EntityResolver → JDK 版本太低（javax.xml.catalog 冲突）
catalog 中不生效 → 因为解析器传入的是绝对 URL（如 https://example.com/schema.xsd），而 catalog 的 name 必须完全匹配该 URL 字符串，建议用 或做模糊匹配