下面我将为您提供一份详细的指南，从环境搭建到核心 API,再到完整的代码示例和最佳实践。

环境准备 (Maven)

您需要将 dom4j 库添加到您的项目中，如果您使用 Maven，只需在 pom.xml 文件中添加以下依赖：

<dependencies>
    <!-- dom4j 核心库 -->
    <dependency>
        <groupId>org.dom4j</groupId>
        <artifactId>dom4j</artifactId>
        <version>2.1.4</version> <!-- 建议使用较新版本 -->
    </dependency>
    <!-- dom4j 通常需要配合一个 XPath 引擎，如 JAXEN -->
    <dependency>
        <groupId>jaxen</groupId>
        <artifactId>jaxen</artifactId>
        <version>1.2.0</version>
    </dependency>
</dependencies>

核心概念与 API

在开始编码之前，了解 dom4j 的几个核心类非常重要：

• Document: 代表整个 XML 文档，它是所有 XML 内容的根。
• Element: 代表 XML 中的一个元素（标签），<book>、<author>。Document 对象本身也是一个 Element（即根元素）。
• Attribute: 代表元素的属性，id="001"。
• CDATA: 用于包含可能包含特殊字符（如 <, >, &）的大块文本。
• DocumentHelper: 一个工厂类，用于方便地创建 Document、Element、Attribute 等对象，这是您生成 XML 的起点。
• XMLWriter: 用于将 Document 对象写入到输出流（如 FileOutputStream, StringWriter, System.out）。
• OutputFormat: 用于控制 XML 输出的格式，例如是否启用缩进（美化输出）、使用什么字符编码（如 UTF-8）等。

生成 XML 的基本步骤

使用 dom4j 生成 XML 的流程通常如下：

1. 创建 Document 对象：使用 DocumentHelper.createDocument() 创建一个新的、空的 XML 文档。
2. 添加根元素：使用 document.addElement("根元素名") 方法来添加根元素。
3. 添加子元素和属性：
   • 在父元素上调用 addElement("子元素名") 添加子元素。
   • 在元素上调用 addAttribute("属性名", "属性值") 添加属性。
   • 在元素上调用 addText("文本内容") 或 addElement(...).addText(...) 添加文本内容。
4. 格式化并输出：
   • 创建一个 OutputFormat 对象来配置输出格式（如缩进、编码）。
   • 创建一个 XMLWriter 对象，将 Document 和 OutputFormat 传递给它。
   • 调用 writer.write(document) 将 XML 写入目标位置（文件、控制台、字符串等）。

完整代码示例

下面我们通过一个具体的例子来生成一个图书列表的 XML 文件。

目标 XML 结构 (books.xml):

<?xml version="1.0" encoding="UTF-8"?>
<books>
    <book id="001">
        <title>Effective Java</title>
        <author>Joshua Bloch</author>
        <price currency="USD">59.99</price>
    </book>
    <book id="002">
        <title>Design Patterns</title>
        <author>Gang of Four</author>
        <price currency="CNY">89.00</price>
    </book>
</books>

Java 代码实现:

import org.dom4j.Document;
import org.dom4j.DocumentHelper;
import org.dom4j.Element;
import org.dom4j.io.OutputFormat;
import org.dom4j.io.XMLWriter;
import java.io.FileWriter;
import java.io.IOException;
import java.io.StringWriter;
public class Dom4jXmlGenerator {
    public static void main(String[] args) {
        // 1. 创建 Document 对象
        Document document = DocumentHelper.createDocument();
        // 2. 添加根元素 <books>
        Element rootElement = document.addElement("books");
        // --- 添加第一本书 <book id="001"> ---
        Element book1 = rootElement.addElement("book")
                                  .addAttribute("id", "001");
        book1.addElement("title").addText("Effective Java");
        book1.addElement("author").addText("Joshua Bloch");
        Element price1 = book1.addElement("price");
        price1.addText("59.99");
        price1.addAttribute("currency", "USD");
        // --- 添加第二本书 <book id="002"> ---
        Element book2 = rootElement.addElement("book")
                                  .addAttribute("id", "002");
        book2.addElement("title").addText("Design Patterns");
        book2.addElement("author").addText("Gang of Four");
        Element price2 = book2.addElement("price");
        price2.addText("89.00");
        price2.addAttribute("currency", "CNY");
        // 3. 格式化并输出 XML
        // 创建一个格式化对象，设置编码和缩进
        OutputFormat format = OutputFormat.createPrettyPrint();
        format.setEncoding("UTF-8"); // 设置编码
        try {
            // 示例1：输出到控制台
            System.out.println("--- 输出到控制台 ---");
            XMLWriter consoleWriter = new XMLWriter(System.out, format);
            consoleWriter.write(document);
            consoleWriter.close();
            // 示例2：输出到文件
            System.out.println("\n--- 输出到文件 books.xml ---");
            XMLWriter fileWriter = new XMLWriter(new FileWriter("books.xml"), format);
            fileWriter.write(document);
            fileWriter.close();
            System.out.println("文件生成成功！");
            // 示例3：输出为字符串
            System.out.println("\n--- 输出为字符串 ---");
            StringWriter stringWriter = new StringWriter();
            XMLWriter xmlWriter = new XMLWriter(stringWriter, format);
            xmlWriter.write(document);
            xmlWriter.close();
            String xmlString = stringWriter.toString();
            System.out.println(xmlString);
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}

运行结果:

控制台会打印出格式化后的 XML 内容，同时会在项目根目录下生成一个 books.xml 文件,内容与目标结构完全一致。

高级用法与最佳实践

1 使用 CDATA 处理特殊字符

中包含 <, >, & 等特殊字符，直接使用 addText 会导致 XML 格式错误，这时应该使用 CDATA。

Element contentElement = rootElement.addElement("content");
// 假设文本中包含 HTML 标签
String htmlText = "<p>This is a <b>test</b> string.</p>";
contentElement.addCDATA(htmlText);

生成的 XML 片段会是：

<content><![CDATA[<p>This is a <b>test</b> string.</p>]]></content>

2 处理命名空间 (Namespaces)

对于复杂的 XML（如 SOAP 消息、配置文件）,命名空间是必需的。

// 定义命名空间
Namespace ns = Namespace.get("ns", "http://www.example.com/books");
// 在创建 Document 时指定默认命名空间
Document document = DocumentHelper.createDocument(ns);
// 或者为特定元素添加命名空间
Element rootElement = document.addElement("books", ns); // 添加带命名空间的根元素
// 添加带命名空间的子元素
Element book = rootElement.addElement("book", ns);
book.addText("A book with namespace");

生成的 XML 片段会是：

<ns:books xmlns:ns="http://www.example.com/books">
    <ns:book>A book with namespace</ns:book>
</ns:books>

3 性能考虑

对于生成非常大的 XML 文件，一次性将整个文档加载到内存中 (Document) 可能会导致 OutOfMemoryError。dom4j 提供了 SAXWriter 来进行流式（StAX 风格）写入，它不会在内存中构建整个 Document 树,而是边生成边写入到输出流。

// 简化的流式写入示例
SAXWriter saxWriter = new SAXWriter(new FileWriter("large_books.xml"));
// 然后通过特定的 API (如 createXXX 方法) 来构建并写入事件
// 这比直接使用 Document 和 XMLWriter 更复杂，但内存效率更高

对于绝大多数应用场景，XMLWriter 和 Document 的组合已经足够高效且易于使用。

dom4j 是 Java 中处理 XML 的利器，其流畅的 API 设计使得生成复杂的 XML 文档变得简单直观,希望这份指南能帮助您快速上手！