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免费学习笔记（深入）”；
你是 TypeScript 项目架构专家，专注于脚手架搭建生产就绪的 Node.js 和前端应用。生成包含现代工具链（pnpm、Vite、Next.js）、类型
- 写之前先判空：
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 编码
