Java StAX XMLStreamWriter writeCharacters 写入文本内容

writecharacters 默认转义特殊字符以确保xml合法性，不适用于写入未转义的html等富文本，此时应使用writecdata；传NULL抛异常，空字符串合法；需手动trim空白；批量写入更高效；中文和emoji需确保utf-8编码。

writeCharacters 会自动转义特殊字符，不是“原样写入”

很多人以为 writeCharacters 就是把字符串直接塞进 XML 元素体里，结果发现 变成了 <code><、" 变成了 "——这没错，它本就该这样。StAX 的设计原则是「保证输出合法 XML」，所以所有字符级写入都默认转义。

如果你真需要不转义的原始文本（比如内嵌一段已校验过的 HTML 片段），writeCharacters 不适合，得换 writeCData 或手动拼接（不推荐）。

• 正常写纯文本内容（如用户昵称、日志消息）：放心用 writeCharacters
• 写入含标签的富文本（如 <b>加粗</b>）：改用 writeCData，否则会被当成普通文本显示
• 想绕过转义强行写 raw 字符？StAX 不提供接口，硬来会破坏 XML 结构

空字符串、null 和空白字符的处理差异

writeCharacters 对 null 和空字符串行为不同：传 null 会抛 NullPointerException；传 ""（空字符串）则合法，写入一个空文本节点——这对生成空元素体（如 <desc></desc> 或 <desc></desc>）有意义。

另外，纯空白（如 "n t"）也会被如实写入，不会自动 trim。XML 解析器通常保留这些空白，除非你启用了 xml:space="preserve" 控制策略。

立即学习“Java免费学习笔记（深入）”；

• 写之前先判空：if (str != null) writer.writeCharacters(str);
• 不想保留首尾空格？自己调 str.trim()，StAX 不做任何隐式清理
• 需要写入换行缩进？writeCharacters("n ") 是有效的，但注意这属于内容而非格式控制

性能敏感场景下，避免高频小段 writeCharacters 调用

每调一次 writeCharacters，底层至少触发一次缓冲区检查和字符编码转换。如果在循环里逐字或逐词写（比如解析日志行后拆成单词再写），性能会明显下降。

更优做法是批量拼接后再写入——尤其当数据源本身是 String 或可预估长度时。StAX 没有内置的“批量写字符”方法，但你可以用 StringBuilder 合并后再调一次 writeCharacters。

• 别这么写：for (char c : text.toCharArray()) writer.writeCharacters(String.valueOf(c));
• 应该合并：writer.writeCharacters(text);（直接传整个字符串）
• 若需动态拼接（如模板填充），先用 StringBuilder 构建，再一次性写入

中文、emoji 等 Unicode 字符写入失败？先查 encoding 配置

writeCharacters 本身不处理编码，它只把 java 字符序列交给底层 Outputstream 或 Writer。真正出问题的地方往往在 XMLOutputFactory 创建 XMLStreamWriter 时用的输出流没指定 UTF-8。

典型错误现象：中文变成 ??? 或直接抛 MalformedInputException。这不是 writeCharacters 的锅，而是流编码和 XML 声明不一致。

• 创建输出流时显式指定编码：new OutputStreamWriter(out, StandardCharsets.UTF_8)
• 确保 XML 声明匹配：<?xml version="1.0" encoding="UTF-8"?>（StAX 默认生成这个，但若你用自定义 Writer，得自己负责）
• emoji 属于增补平面字符（U+1F600 起），Java String 内部用代理对表示，writeCharacters 能正确处理，前提是底层流支持 UTF-8 编码

事情说清了就结束。最常被忽略的是：你以为在写内容，其实 StAX 在帮你守 XML 合法性边界——越想绕开它，越容易掉坑里。