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 格式，含<system>、<uri>、<rewriteSystem>等条目 - 注册方式因解析器类型而异：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 systemId="x.dtd" uri="http://evil.com/x.dtd"/>和<public publicId="-//FOO//DTD BAR//EN" uri="local-bar.dtd"/>，解析器仍会优先走危险的 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 中
<uri name="schema.xsd" uri="schemas/local.xsd"/>不生效 → 因为解析器传入的是绝对 URL（如https://example.com/schema.xsd），而 catalog 的name必须完全匹配该 URL 字符串，建议用<rewriteURI或<uriSuffix做模糊匹配
CatalogResolver 的复杂性不在 API，而在 catalog 文件的编写逻辑和各 XML API 层之间隐式的契约——它要求你同时懂 XML 规范、解析器生命周期、以及 Java 模块系统的边界。一旦配通，它就是最安静、最可靠、最符合企业级部署需求的资源治理方案。
