Java StringJoiner 怎样设置空集合的默认输出

Java 的 StringJoiner 在还没有添加任何元素时，可以用 setEmptyValue 指定默认输出。最关键的判断点是：这个默认值只针对“从未添加过元素”的状态；一旦调用过 add，即便加入的是空字符串，连接器也不再被视为真正空。

官方地址：https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/StringJoiner.html

如果空集合要显示为 []、无数据 或其他占位文本，就在创建 StringJoiner 后调用 setEmptyValue。不要用 add("") 代替它，因为两者的状态语义不同。

先看 StringJoiner 的真正空状态

StringJoiner 保存的是一组待拼接元素，并由分隔符、前缀和后缀共同生成字符串。构造完成但还没有调用 add 时，它处于真正的空状态：

import java.util.StringJoiner;

public class EmptyJoinerDemo {
    public static void main(String[] args) {
        // 分隔符只负责连接元素；前缀和后缀定义整体外壳。
        StringJoiner joiner = new StringJoiner(", ", "[", "]");

        // 未调用 add 时，默认表示是 prefix + suffix。
        System.out.println(joiner.toString());
    }
}

在这个例子里，默认表示是 []，因为前缀是 [、后缀是 ]。如果使用只有分隔符的构造器，则空状态默认会表现为空字符串；这仍然是“没有元素”，而不是已经添加了一个空元素。

用 setEmptyValue 设置空集合的默认文本

setEmptyValue 接收一个非空的 CharSequence，并返回当前对象，因此可以直接链式调用。它只会改变空状态下 toString 使用的文本，不会改变已经添加元素时的分隔规则。

import java.util.StringJoiner;

public class EmptyValueDemo {
    public static void main(String[] args) {
        // 为没有元素的结果设置业务占位文本。
        StringJoiner joiner = new StringJoiner(", ", "[", "]")
                .setEmptyValue("无数据");

        // 此时还没有 add，toString 返回 setEmptyValue 的内容。
        System.out.println(joiner); // 无数据

        // 添加正常元素后，恢复为前缀、元素和后缀的组合。
        joiner.add("Java").add("StringJoiner");
        System.out.println(joiner); // [Java, StringJoiner]
    }
}

这里的 无数据 是空集合的业务展示值；加入元素之后，setEmptyValue 不会继续覆盖正常拼接结果。传入 null 会触发 NullPointerException，所以默认值本身应当使用明确的非空文本。

空字符串不等于没有调用 add

最容易混淆的是 add("")。Java API 明确规定，调用过 add 后，即使元素本身是空字符串，StringJoiner 也不再处于空状态。它的显示结果可能看起来和前后缀组合相同，但内部语义已经不同。

import java.util.StringJoiner;

public class EmptyElementDemo {
    public static void main(String[] args) {
        // 先配置空集合的业务占位值。
        StringJoiner joiner = new StringJoiner(", ", "[", "]")
                .setEmptyValue("无数据");
        System.out.println(joiner); // 无数据

        // 空字符串仍然是一次 add；它不是“没有元素”。
        joiner.add("");
        System.out.println(joiner); // []

        // 后续元素仍按正常分隔规则追加。
        joiner.add("Java");
        System.out.println(joiner); // [, Java]
    }
}

因此，如果业务规则是“列表为空时显示无数据”，应该在集合遍历结束后根据是否添加过元素决定是否调用 setEmptyValue，而不是为了得到占位文本先添加一个空字符串。若业务上空字符串本身就是一项数据，就应该保留 add("") 的语义。

add(null) 会输出什么

StringJoiner.add 接收的是 CharSequence。当参数为 null 时，API 会把它作为文本 "null" 加入，而不是把连接器保持在空状态：

import java.util.StringJoiner;

public class NullElementDemo {
    public static void main(String[] args) {
        // null 元素会被转换成字面文本 null。
        StringJoiner joiner = new StringJoiner("|", "");
        joiner.add(null);

        // 这里已经有一个元素，输出包含字面量 null。
        System.out.println(joiner); // 
    }
}

所以“空集合默认输出”和“数据中存在 null”是两个问题：前者用 setEmptyValue 表达，后者要在调用 add 前由业务代码决定是否过滤、替换或保留。

写测试时检查这四个边界

可以把下面四种情况作为最小回归清单，避免只断言最终字符串而忽略状态差异：

如果测试只比较第一行和第三行的字符串，可能会误以为两者完全相同；更稳妥的做法是同时测试后续再添加一个正常元素的结果，确认空字符串是否被当作真实元素保留。

结论：默认值负责展示，add 负责改变状态

给空集合设置展示文本时，直接使用 setEmptyValue；需要表达真实元素时才调用 add。记住三个边界：未调用 add 才会使用 emptyValue，add("") 会结束空状态，add(null) 会加入文本 null。这样在格式化列表、生成查询条件或输出配置片段时，默认占位和实际数据就不会混在一起。

相关问题

• StringJoiner 的空值默认输出能设置为 null 吗？不能，setEmptyValue(null) 会抛出 NullPointerException；需要先决定一个具体文本。
• 调用 setEmptyValue 后还能继续 add 吗？可以。它只影响尚未添加元素时的表示，加入元素后仍按分隔符、前缀和后缀生成结果。
• 为什么 add 空字符串后不再使用无数据？因为空字符串也是一次成功的 add，连接器的状态已经从未添加元素变为已添加元素。