在使用Dom4j解析XML文件时，几乎所有操作都始于Document对象。Document代表整棵XML文档树，而它的入口就是根元素。通过getRootElement()方法拿到Element实例后，才能继续访问子节点、属性和文本。这个方法本身只有一行代码，但围绕它的读取流程、返回值特性和常见异常，还是有不少细节值得梳理清楚。
一、获取根元素的基本用法
Dom4j中读取XML通常借助SAXReader。SAXReader解析输入流或文件后返回一个Document对象，调用getRootElement()即可得到根元素。下面是一段完整的示例代码，读取classpath下的XML文件并输出根元素名称：
import org.dom4j.Document;
import org.dom4j.DocumentException;
import org.dom4j.Element;
import org.dom4j.io.SAXReader;
import java.io.InputStream;
public class RootElementDemo {
public static void main(String[] args) {
SAXReader reader = new SAXReader();
try (InputStream in = RootElementDemo.class
.getClassLoader().getResourceAsStream("users.xml")) {
Document document = reader.read(in);
// 获取根元素
Element root = document.getRootElement();
System.out.println("根元素名称：" + root.getName());
} catch (Exception e) {
e.printStackTrace();
}
}
}假设users.xml的内容如下，那么输出结果就是users：
<?xml version="1.0" encoding="UTF-8"?>
<users>
<user id="1">
<name>张三</name>
<age>25</age>
</user>
</users>需要注意几点。第一，getRootElement()的返回值是Element类型，一个格式合法的XML文档有且仅有一个根元素，所以这个方法只会返回一个节点。第二，如果直接用new Document()创建了一个空Document而没有添加根元素，此时调用该方法会返回null，后续操作就容易抛出空指针异常，务必先做判空处理。第三，XML声明之前不允许有任何其他内容，哪怕是空行或BOM头，都可能导致解析失败，这一点在Windows下手动编辑过的文件中尤其常见。
二、从根元素出发遍历整棵树
拿到根元素之后，常用的下一步是遍历子元素。Element提供了elements()、element(String name)、attributeValue(String name)、getTextTrim()等方法，配合递归可以实现整棵树的遍历。看下面的例子：
public static void listNodes(Element node) {
// 输出当前节点名称
System.out.println("当前节点：" + node.getName());
// 输出属性
node.attributes().forEach(attr ->
System.out.println("属性：" + attr.getName() + " = " + attr.getValue()));
// 输出非空文本内容
if (!node.getTextTrim().isEmpty()) {
System.out.println("文本：" + node.getTextTrim());
}
// 递归遍历子元素
for (Object obj : node.elements()) {
listNodes((Element) obj);
}
}递归遍历的优点是写法直观，对任意深度的嵌套结构都适用；缺点是层级太深时调用栈会随之增长，不过在常规业务配置文件这个量级下完全不必担心。如果只是想取某个固定层级的数据，用root.element("user")、root.elements("user")这类带名称的过滤方法更直接，代码也更短。
另一个实用的思路是使用XPath。Dom4j内置了XPath支持，root.selectNodes("//user/name")可以直接定位所有user节点下的name元素，对于结构复杂但路径明确的文档，比逐层递归省事得多。需要注意不同版本的Dom4j对XPath语法的支持有差异，1.6.x默认支持XPath 1.0，而2.x版本部分XPath能力被拆到了jaxen依赖中，使用时要确认依赖完整。
三、常见问题与排查办法
第一个常见问题是空指针异常。典型场景是Document尚未成功解析就调用了getRootElement()，或者XML本身缺少根元素。排查时先确认reader.read()没有抛出DocumentException，再看返回的Document是否为null。从classpath读取资源时，如果路径写错，getResourceAsStream会返回null，SAXReader读取null流会直接报错，这类问题在打包成jar后更容易出现，因为文件系统的相对路径在jar内部不可用。
第二个问题是中文乱码。乱码的根源大多不在Dom4j，而在流的编码与XML声明不一致。解决办法是不要用FileInputStream直接读文件再交给SAXReader猜测编码，而是明确指定编码，或者用InputSource包装并设置characterStream与encoding。示例：
SAXReader reader = new SAXReader();
reader.setEncoding("UTF-8");
Document document = reader.read(new File("D:\\data\\users.xml"));第三个问题是安全问题。如果解析的XML来自不可信来源，XML内部可能引用外部实体，造成XXE注入风险。建议在创建SAXReader后显式关闭外部实体与DOCTYPE声明：
SAXReader reader = new SAXReader();
reader.setFeature("http://apache.org/xml/features/disallow-doctype-decl", true);
reader.setFeature("http://xml.org/sax/features/external-general-entities", false);
reader.setFeature("http://xml.org/sax/features/external-parameter-entities", false);最后，如果需要把解析或修改后的Document写回文件，可以用OutputFormat.createPrettyPrint()配合XMLWriter做格式化输出，写完后记得调用writer的close方法，避免流未关闭造成内容截断。掌握这些细节后，getRootElement()这个看似简单的方法就能在整个XML处理链路中稳定发挥作用。
Dom4jDocument.getRootElementXML解析修改时间：2026-09-16 05:12:28