Java Stream mapMulti 怎么替代 flatMap：条件展开、空结果与分配边界

订单服务返回的标签字段并不总是规整：有的订单带一个标签，有的带多个别名，还有的只保留了空值。要把每个订单转换成零个或少量标签，直接套 flatMap 往往要先创建一条临时 Stream，分支一多，代码也会变得绕。Java 16 起可以用 mapMulti 把“要不要输出、输出几个”的逻辑写在同一个回调里，写起来更顺手。

mapMulti 解决的不是“把 Stream 写短”

mapMulti 的核心语义是：一个输入元素可以替换为零个或多个输出元素。它和 flatMap 都是一对多转换，但写法差异很大：flatMap 要显式返回一个 Stream，mapMulti 直接向回调提供的 Consumer 推送结果就行。

举个常见场景，订单对象里有一个用逗号分隔的标签字段，空字段直接不输出，标签长度超过8个字符时还要额外拆出一个短码：

record Order(long id, String labels) {}

List tags = orders.stream()
    .mapMulti((order, out) -> {
        if (order.labels() == null || order.labels().isBlank()) {
            return;
        }
        for (String raw : order.labels().split(",")) {
            String tag = raw.trim();
            if (!tag.isEmpty()) {
                out.accept(tag);
                if (tag.length() > 8) {
                    out.accept(tag.substring(0, 8));
                }
            }
        }
    })
    .distinct()
    .toList();

这里一个订单可能没有任何输出，也可能输出多个标签。所有分支逻辑直接落在循环里，读者不用在 flatMap 的多个 Stream.of、Stream.empty() 和临时集合之间来回跳转梳理逻辑。

最小配方：只在回调里短暂使用 Consumer

最容易踩的坑不是语法写错，而是没注意 out 的生命周期限制。官方API明确说明，这个Consumer不能在回调结束后继续使用；把它存到字段里、交给另一个线程运行，最终得到的结果都是未定义的，随时可能出问题。

static Stream aliases(Order order) {
    return Stream.of(order.labels().split(","))
        .map(String::trim)
        .filter(tag -> !tag.isEmpty());
}

List safe = orders.stream()
    .mapMulti((order, out) -> {
        if (order.labels() != null) {
            aliases(order).forEach(out);
        }
    })
    .toList();

这个例子里，forEach(out) 在回调尚未返回时就完成了所有操作，属于安全用法。不要先提前保存 out、等回调结束后再调用，也不要把输出动作直接丢进异步线程里。

mapMulti 与 flatMap 怎么选

官方说明把「每组结果数量较少」和「命令式生成更容易」列为 mapMulti 的适用条件。它不是对所有 flatMap 的性能承诺；正式改造前仍应使用业务实测数据评估分配开销和吞吐情况。

泛型推断和基础类型的兼容边界

当回调里没有足够的目标类型信息时，编译器可能无法判断输出类型。最稳妥的写法是在方法调用处明确指定类型：

List numbers = values.stream()
    .mapMulti((value, out) -> {
        if (value instanceof Number number) {
            out.accept(number.intValue());
        }
    })
    .toList();

数组、对象或少量数字结果可以使用对应的 mapMulti 变体。若目标是大量原始数值，还要比较 mapMultiToInt、mapMultiToLong 或 mapMultiToDouble，避免为了追求流式写法又不断产生装箱操作，拖慢性能。

项目运行在 Java 11 或更早版本时，mapMulti 根本不存在。兼容旧版本只能继续使用 flatMap、临时集合或普通循环，只改import是解决不了问题的。

一段可验收的完整片段

static List visibleTags(List orders) {
    return orders.stream()
        .mapMulti((order, out) -> {
            String source = order.labels();
            if (source == null) return;
            for (String item : source.split(",")) {
                String tag = item.strip();
                if (!tag.isEmpty() && !tag.startsWith("_")) {
                    out.accept(tag);
                }
            }
        })
        .distinct()
        .sorted()
        .toList();
}

// 输入："go, _internal, java, go"
// 输出：[go, java]

验收至少要覆盖四种输入场景：空字段不产生结果、下划线标签被过滤、重复标签只保留一个、一个订单输出多个标签。再用一组真实订单比对 mapMulti 和原实现的结果集合完全一致，最后再评估耗时和分配数据。

常见问题

mapMulti 是不是一定比 flatMap 快？

不是。它减少的是每个输入元素创建结果 Stream 的表达成本，实际收益取决于展开数量、后续操作、数据分布和运行时版本。

Consumer 可以保存到 List 里稍后使用吗？

不可以。Consumer 只应在当前回调中同步调用；需要延后处理时，先构造明确的数据结构再返回。

Java 8 项目能直接使用 mapMulti 吗？

不能。mapMulti 从 Java 16 开始提供，Java 8 项目应保留 flatMap 或普通循环实现。

什么时候继续用 flatMap 更好？

当已有方法自然返回 Stream，或展开逻辑本身就是多个 Stream 的组合时，flatMap 更容易读、测和复用。

把选择写进代码评审标准

如果展开逻辑是“每个输入输出零到几个值”，并且分支放在 Consumer 里更清楚，可以选择 mapMulti；如果结果天然来自一个 Stream，继续用 flatMap。无论选哪一个，都要保留空结果、重复值、旧 JDK 编译和真实数据规模的测试。