Java XMLStreamWriter 怎样写入带命名空间的元素

用 Java XMLStreamWriter 写带命名空间的元素，核心不是把 xmlns 当普通属性拼出来，而是同时管理三件事：元素使用的 prefix、它对应的 namespaceURI，以及当前作用域里是否已经写出命名空间声明。最稳妥的写法是先绑定前缀，再用三参数 writeStartElement 写元素，必要时显式调用 writeNamespace。

官方地址：https://docs.oracle.com/en/java/javase/25/docs/api/java.xml/javax/xml/stream/XMLStreamWriter.html

可以先记住这条判断：setPrefix解决“这个 URI 用什么前缀”，writeNamespace解决“把绑定声明写进当前元素”，writeStartElement解决“写出哪个元素名”。三者混在一起时，最容易出现前缀看似正确、文档却没有对应 xmlns 的情况。

先把元素名和命名空间关系分开

XML 名称的本地部分是 localName，例如 order；命名空间 URI 是真正的身份，例如 urn:demo:order；o 只是便于书写的前缀。前缀本身没有固定含义，能否被 XML 解析器理解取决于同一作用域中是否存在对应的 xmlns:o="urn:demo:order" 声明。

因此不要把 writeStartElement("o:order") 当成完整的命名空间写法。更清晰的做法是分别传入前缀、本地名和 URI，让写入器维护元素作用域；命名空间声明则用命名空间方法单独表达。

用显式前缀写出稳定的元素边界

当一份 XML 同时包含订单、扩展字段等多个命名空间时，显式前缀更容易读和维护。下面的代码先建立 o 与订单 URI 的关系，再在根元素作用域内写出声明，最后用同一组前缀和 URI 写元素及属性。

String orderUri = "urn:demo:order"; // URI 是命名空间身份，不要用短前缀代替
String extUri = "urn:demo:extension"; // 扩展字段使用独立的命名空间
XMLStreamWriter writer = null; // writer 由输出工厂创建，这里只声明资源引用
try {
    XMLOutputFactory factory = XMLOutputFactory.newFactory(); // 创建 StAX 输出工厂
    writer = factory.createXMLStreamWriter(outputStream, "UTF-8"); // 输出流的编码由创建时决定
    writer.writeStartDocument("UTF-8", "1.0"); // 写 XML 声明

    writer.setPrefix("o", orderUri); // 绑定订单 URI 的前缀
    writer.setPrefix("x", extUri); // 绑定扩展 URI 的前缀
    writer.writeStartElement("o", "order", orderUri); // 元素名、前缀和 URI 三者保持一致
    writer.writeNamespace("o", orderUri); // 在当前元素作用域写出 xmlns:o
    writer.writeNamespace("x", extUri); // 同时声明扩展命名空间

    writer.writeStartElement("o", "id", orderUri); // 子元素继续使用订单命名空间
    writer.writeCharacters("A-1001"); // 文本由 writer 负责转义特殊字符
    writer.writeEndElement(); // 关闭 id 元素

    writer.writeStartElement("x", "source", extUri); // 扩展元素使用 x 前缀和 extUri
    writer.writeAttribute("code", "import"); // 无命名空间的普通属性直接写本地名
    writer.writeCharacters("batch"); // 写入扩展元素内容
    writer.writeEndElement(); // 关闭 source 元素
    writer.writeEndElement(); // 关闭 order 元素
    writer.writeEndDocument(); // 补齐尚未关闭的文档结构
    writer.flush(); // 将 writer 的缓存写入底层输出流
} catch (XMLStreamException ex) {
    // XML 写入失败时保留原始异常，便于调用方区分 IO 和 XML 边界
    throw new IllegalStateException("写入带命名空间的 XML 失败", ex);
} finally {
    if (writer != null) {
        writer.close(); // 释放 writer；底层 outputStream 仍由创建者负责关闭
    }
}

这里的重点是声明和使用保持同一组 URI。setPrefix建立的是写入器内部的绑定上下文，writeNamespace才把声明输出到 XML。为了让输出协议更稳定，生产代码通常显式写声明，而不是依赖实现自动生成难以预测的前缀。

整棵树只有一个 URI 时可以用默认命名空间

如果根元素和主要子元素都属于同一个 URI，可以省略短前缀，使用默认命名空间。默认命名空间只影响元素，不会自动给普通属性加上命名空间；这是排查“元素能解析、属性却不在目标命名空间”时最值得先看的边界。

String catalogUri = "urn:demo:catalog"; // 整棵目录树共享的命名空间 URI
XMLStreamWriter writer = null; // 记录 writer，确保 finally 可以安全关闭
try {
    XMLOutputFactory factory = XMLOutputFactory.newFactory(); // 创建输出工厂
    writer = factory.createXMLStreamWriter(outputStream, "UTF-8"); // 创建 UTF-8 XML writer
    writer.writeStartDocument("UTF-8", "1.0"); // 输出 XML 声明
    writer.setDefaultNamespace(catalogUri); // 把 URI 绑定到默认命名空间
    writer.writeStartElement(catalogUri, "catalog"); // 通过 URI 写根元素
    writer.writeDefaultNamespace(catalogUri); // 输出 xmlns="urn:demo:catalog"
    writer.writeStartElement(catalogUri, "item"); // 子元素沿用默认命名空间
    writer.writeAttribute("id", "7"); // 普通属性仍然没有命名空间
    writer.writeCharacters("book"); // 写入元素文本
    writer.writeEndElement(); // 关闭 item
    writer.writeEndElement(); // 关闭 catalog
    writer.writeEndDocument(); // 完成文档
} catch (XMLStreamException ex) {
    // 将 StAX 的受检异常转换为业务层可处理的异常
    throw new IllegalStateException("写目录 XML 失败", ex);
} finally {
    if (writer != null) {
        writer.close(); // 关闭 writer，不替代 outputStream 的生命周期管理
    }
}

默认命名空间适合单一协议树；一旦出现多个 URI，显式前缀通常更直观。不要仅凭输出文本里有没有前缀判断是否正确，真正要看的是元素的命名空间 URI 是否符合接收方协议。

未绑定前缀时，先决定是否让实现自动修复

writeStartElement(namespaceURI, localName)要求 URI 已经绑定到可用前缀；Oracle API 说明，如果 URI 没有绑定且没有启用 javax.xml.stream.isRepairingNamespaces，写入可能抛出 XMLStreamException。修复模式可以让实现生成声明和前缀，但生成结果不一定适合需要固定前缀的签名、对比或下游协议。

工程上可以按这张清单判断：

• 接收方只关心 URI：可以考虑 repairing namespaces，减少手工绑定。
• 接收方要求固定前缀或 XML 要参与签名：显式 setPrefix 与 writeNamespace 更可控。
• 默认命名空间只覆盖元素：带命名空间的属性要使用带前缀的 writeAttribute 重载。
• 关闭 writer 不等于关闭底层输出流：谁创建输出流，谁负责它的关闭策略。

常见问题

只调用 setPrefix，为什么看不到 xmlns？

setPrefix只建立写入器的绑定上下文，不保证立刻把声明写到当前元素。需要在合适的元素作用域调用 writeNamespace，或者明确使用支持命名空间修复的配置。

writeNamespace 应该放在 writeStartElement 前还是后？

它描述当前元素作用域中的命名空间声明，通常在对应的开始元素已经写出、但还没有写属性或子内容时调用。这样声明和元素边界最清楚，也避免在错误的写入状态调用。

默认命名空间会给 id 属性加上命名空间吗？

不会。默认命名空间针对元素；如果属性也属于某个 URI，应使用带 prefix、namespaceURI、localName 的 writeAttribute 重载，并确保前缀已声明。