StringJoiner适用于需固定前缀、后缀和分隔符的结构化字符串拼接场景，如JSON数组片段、SQL IN子句；不适合简单拼接或单次连接，使用时须注意参数顺序为delimiter、prefix、suffix，并主动处理空集合逻辑。
StringJoiner 适合什么场景
当你需要拼接字符串，且必须带固定前缀、后缀、分隔符时，StringJoiner 比 StringBuilder + 手动加头尾更安全，比 String.join() 更灵活。它不是为“简单拼接”设计的，而是为“结构化拼接”服务的——比如生成 JSON 数组片段、SQL IN 子句、带括号的列表打印。
常见错误现象：用 StringBuilder 拼 "[" + String.join(", ", list) + "]"，结果空集合时变成 "[]"（看似没问题），但若要求空时返回 null 或跳过整个字段，就容易漏判；又或者分隔符和前后缀逻辑散落在多处，后续改需求时容易漏同步。
实操建议：
- 空集合时
StringJoiner默认输出前缀+后缀（如"[]"），不自动跳过——这点必须主动检查是否符合业务预期 - 如果要支持“空时不输出任何内容”，得额外判断
joiner.toString().equals(prefix + suffix)或维护计数器 - 不要用它替代
String.concat()或单次拼接，构造开销比直接+高
构造参数顺序和含义容易搞反
StringJoiner 的三个参数是：delimiter、prefix、suffix——注意，分隔符在前，前后缀在后。这不是直觉顺序，IDE 自动补全也常让人误以为是 prefix, delimiter, suffix。
典型错误：写成 new StringJoiner("[", ",", "]")，结果得到 "[a,b,c]"？不对，实际是 "[a]b]c]"，因为 "[" 被当成了分隔符，"," 变成 prefix，"]" 是 suffix，逻辑全乱。
实操建议：
- 永远按文档顺序记：
new StringJoiner(delimiter, prefix, suffix) - 初始化时把参数名显式写出来（靠 IDE 提示或注释）：
new StringJoiner(",", "[", "]") - 如果 prefix/suffix 为空字符串，传
""，别传null，否则抛NullPointerException
add() 和 merge() 的行为差异很关键
add() 往当前实例追加元素；merge() 把另一个 StringJoiner 的所有已添加内容（不含自身 prefix/suffix）合并进来，再拼到当前的中间位置。它不递归嵌套，也不重置状态。
分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
使用场景：批量构建多个子片段，最后统一组装。比如日志中拼接多个「键值对块」，每个块自己有前缀后缀，最终再套一层外层结构。
容易踩的坑：
-
merge()不会校验被合并对象的prefix和suffix，只取它的拼接结果（即toString()值），所以如果那个StringJoiner还没 add 任何东西，merge()就等于插入一串空 prefix+suffix - 合并后，原
StringJoiner实例状态不变，但目标实例的分隔符会作用于合并内容之间——例如两个都用","，合并后不会多出逗号，但若目标分隔符是";"，就会在块之间插分号 - 不能 merge null，会 NPE；也不能 merge 自己（会导致无限循环或异常）
和 String.join()、Collectors.joining() 怎么选
三者都能拼字符串，但抽象层级不同：String.join() 是静态工具方法，最轻量；Collectors.joining() 是流式聚合，适合配合 stream().collect()；StringJoiner 是可变对象，支持中途修改、条件拼接、多次 add、跨方法传递。
性能影响：三者底层都基于 StringBuilder，差异微乎其微；但 StringJoiner 多一层对象封装，如果只是单次、无条件拼接，没必要引入。
实操建议：
- 纯列表拼接 → 优先用
String.join(delimiter, list) - 在 stream 流水线里 → 用
Collectors.joining(delimiter, prefix, suffix) - 需要分阶段拼、可能跳过某些元素、或需复用拼接器（比如循环内反复 reset/reuse）→ 才上
StringJoiner - 别为了“看起来高级”而用
StringJoiner替代一行String.join()，代码反而难读
空集合处理逻辑不统一，是这三个 API 最容易忽略的细节：String.join 返回空字符串；Collectors.joining 返回 prefix+suffix；StringJoiner 同样返回 prefix+suffix。但如果你期望空时返回 null 或抛异常，所有方式都得额外判空——这点没人替你做。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
