DocumentHelper.createDocument() 创建的不是真正“空文档”，而是有XML声明但无根元素的文档，直接写入会因缺失根节点抛出“no root element”异常。
DocumentHelper.createDocument() 创建的真是“空文档”吗？
不是。它创建的是一个有声明但无根元素的文档，直接写入文件会报 org.dom4j.DocumentException: no root element。DOM 标准要求 XML 文档必须有且仅有一个根节点，createDocument() 只建了壳，没给骨头。
- 常见错误现象：调用
write()或asXML()时抛出异常，提示 “no root element” - 正确做法是紧接着调用
addElement()创建根节点，例如：doc.addElement("root") - 不建议先
createDocument()再反复addElement()拼接——容易漏掉层级或属性，更适合用DocumentHelper.parseText()解析字符串或从模板加载
为什么不用 new DocumentImpl() 而用 DocumentHelper.createDocument()？
DocumentHelper.createDocument() 是 Dom4j 提供的工厂方法，能确保返回实例兼容当前版本的内部机制；而 DocumentImpl 是具体实现类，直接 new 容易在升级 Dom4j 后因构造签名变化或初始化缺失导致 NullPointerException 或节点行为异常。
- 使用场景：所有需要从零构建文档的逻辑，比如生成配置快照、组装 API 响应体
- 性能影响几乎为零，两者底层都是轻量对象，差异在于封装安全性和可维护性
- 注意：Dom4j 2.x 中
DocumentHelper已被标记为@Deprecated，但替代方案DocumentFactory.getInstance().createDocument()行为一致，仍推荐走工厂路径
中文字符写入乱码或报错怎么办？
Dom4j 默认按 UTF-8 处理，但输出时若未显式指定编码，部分老版本 JDK 或特定 OutputStreamWriter 配置会导致 BOM 缺失或平台默认编码干扰，表现为乱码或 Invalid byte 1 of 1-byte UTF-8 sequence。
- 关键动作：写入前设置输出编码，例如用
OutputFormat.createPrettyPrint().setEncoding("UTF-8") - 避免直接用
FileWriter（它用系统默认编码），改用OutputStreamWriter(new FileOutputStream(...), "UTF-8") - 如果用
XMLWriter，务必传入带编码的OutputFormat，否则asXML()返回的字符串虽是 UTF-8，但写文件时可能二次编码
和 JAXP DocumentBuilder 的空文档创建方式有什么区别？
Dom4j 的 DocumentHelper.createDocument() 和 JAXP 的 DocumentBuilder.newDocument() 看似等价，实则语义不同：前者返回的是 Dom4j 自己的 Document 接口实现，后者返回 W3C org.w3c.dom.Document；混用会触发 ClassCastException，尤其在封装通用 XML 工具类时容易踩坑。
立即学习“Java免费学习笔记（深入）”；
- 不要把
DocumentHelper.createDocument()的结果强转成org.w3c.dom.Document - 如果项目同时依赖两种 API，建议用适配层隔离，比如封装一个
XmlDocumentFactory统一出口 - Dom4j 更适合流式构建和 XPath 查询，JAXP 更适合与 Java EE 标准组件（如 Transformer）集成——选哪个取决于你接下来要调谁的 API
