在Java标准库中，javax.xml.transform.Transformer 是将内存中的DOM文档转换为XML文本的主流工具。很多系统在组装报文或调用第三方接口时，并不希望输出内容前面带着 XML 版本与编码声明，而是只需要从根节点开始的标签结构。要实现这一点，核心就在于正确使用 OutputKeys 中提供的 omit-xml-declaration 配置项。
一、Transformer 基础输出行为
当我们通过 TransformerFactory 得到一个 Transformer 实例，并将 Document 对象包装为 DOMSource，再指定 StreamResult 输出到字符串或文件时，如果不做任何额外设置，Transformer 会按照默认的序列化规则进行处理。其中最重要的一条默认规则就是：自动在输出内容的最前面写入 XML 声明，通常形式为 <?xml version="1.0" encoding="UTF-8"?>。
这种声明对于独立的 XML 文件来说是符合规范的，但在某些场景下它会带来麻烦。例如，我们需要将多个 XML 片段拼接成一个更大的报文，或者对方接口明确要求不能包含任何前置声明，此时默认行为就需要被关闭。理解这一默认机制，是后续进行精确控制的前提。
二、使用 OutputKeys 移除头部声明
OutputKeys 类中定义了一系列控制序列化输出的键值对常量，其中 OMIT_XML_DECLARATION 对应的实际属性名为 omit-xml-declaration。我们只需要调用 Transformer 的 setOutputProperty 方法，将该属性的值设为 yes，就可以告诉序列化器省略 XML 声明。
下面是一段完整的示例代码，演示如何创建 Transformer 并移除头部声明：
import javax.xml.parsers.DocumentBuilder;
import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.transform.OutputKeys;
import javax.xml.transform.Transformer;
import javax.xml.transform.TransformerFactory;
import javax.xml.transform.dom.DOMSource;
import javax.xml.transform.stream.StreamResult;
import org.w3c.dom.Document;
import org.w3c.dom.Element;
import java.io.StringWriter;
public class XmlDeclRemoveDemo {
public static void main(String[] args) throws Exception {
// 创建一个简单的DOM文档
DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
DocumentBuilder db = dbf.newDocumentBuilder();
Document doc = db.newDocument();
Element root = doc.createElement("user");
root.setAttribute("id", "1001");
Element name = doc.createElement("name");
name.setTextContent("张三");
root.appendChild(name);
doc.appendChild(root);
// 获取Transformer并设置移除XML声明
TransformerFactory tf = TransformerFactory.newInstance();
Transformer transformer = tf.newTransformer();
// 关键设置：省略XML头部声明
transformer.setOutputProperty(OutputKeys.OMIT_XML_DECLARATION, "yes");
transformer.setOutputProperty(OutputKeys.ENCODING, "UTF-8");
// 执行转换
DOMSource source = new DOMSource(doc);
StringWriter writer = new StringWriter();
StreamResult result = new StreamResult(writer);
transformer.transform(source, result);
// 输出结果，不包含<?xml ... ?>声明
System.out.println(writer.toString());
}
}
上述代码运行后，控制台打印的内容将以 <user> 标签起始，而不会看到 <?xml version="1.0" encoding="UTF-8"?>。如果注释掉 setOutputProperty(OutputKeys.OMIT_XML_DECLARATION, "yes") 这一行，声明就会重新出现，二者对比非常直观。
除了设置为 yes，该属性也可以设为 no，表示强制保留声明，而这正是未设置时的默认等效行为。因此显式声明 omit-xml-declaration 为 yes，是移除头部最标准、最可移植的做法，不依赖具体 JDK 实现。
三、常见误区与冲突点
开发者常遇到一种情况：明明已经设置了 OMIT_XML_DECLARATION 为 yes，但输出里依然有声明。这通常是因为在创建 Transformer 时使用了带样式表的 newTransformer(Templates templates) 或传入了包含 output 节点的 Source，而样式表中硬编码了 <xsl:output omit-xml-declaration="no"/>，此时代码层的设置可能被样式表覆盖。
另一个容易忽略的点是，某些旧版本 XML 解析器在与特定 StreamResult（例如直接绑定到 File 且文件已含 BOM）配合时，会出现声明写入异常。建议在做纯字符串拼接场景时统一使用 StringWriter 作为中间载体，再从 writer 中获取字符串进行后续处理，这样能最大程度保证 omit 设置生效。
四、保留与省略声明对比
为了更清晰地展示差异，我们可以通过一个小表格来归纳两种输出形态适用场景：
| 输出模式 | 开头内容 | 典型用途 |
|---|---|---|
| 保留声明 | <?xml version="1.0" encoding="UTF-8"?><root>...</root> | 独立XML文件、配置文件 |
| 省略声明 | <root>...</root> | 报文片段、数据库字段存储、接口内部拼装 |
从表中可以看出，省略声明并不是一种“不规范”的做法，而是针对特定集成需求的合理裁剪。只要上下游系统对编码和格式有共识，去掉声明反而能减少解析歧义。
最后需要提醒，若业务要求输出片段最终仍要被当作完整 XML 处理，省略声明后应当确保根元素唯一且结构良好。Transformer 本身不会因省略声明而校验文档合法性，责任在于调用方。
五、小结
通过 Transformer 的 OutputKeys.OMIT_XML_DECLARATION 属性，Java 开发者可以以极低代价控制 XML 序列化时是否携带头部声明。核心代码仅一行设置，但需注意样式表覆盖、JDK 实现差异以及结果载体选择等细节。
掌握这一技巧后，无论是对接严苛的第三方报文接口，还是做系统内部 XML 片段流转，都能更从容地输出符合要求的内容，避免无谓的格式联调成本。
JavaTransformerOutputKeys修改时间：2026-08-01 21:18:30