Java Stream mapMulti 怎样展开少量结果

当一个输入只产生零个、一个或少量结果，而且用 if 与循环生成结果更自然时，可以用 mapMulti：在映射回调中调用 out.accept(value) 发出结果，不必让回调返回一个子 Stream。若手里本来就有子流，flatMap 通常更直观。选择依据是结果生成方式，而不是把 mapMulti 当成无条件更快的替代品。

官方 API 地址：https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/stream/Stream.html。mapMulti 从 Java 16 提供，下面用 JDK 17 或以上完成一个无依赖的小例子。

把订单条件展开为零到两个标签

项目只做一个任务：为每个订单输出需要关注的标签。urgent 为真时输出“优先处理”，需要人工复核时输出“人工复核”，两个条件都不满足就不输出。标签带订单编号，避免合并后失去归属。

输入 A 同时满足两个条件，B 都不满足，C 只需要复核。目标输出三项：A 的两个标签和 C 的一个标签。这里不是一对一映射，所以仅用 map 返回字符串会很别扭；也不需要先把所有标签放进共享可变列表。

准备一个不依赖框架的单文件

把代码保存为 TagExpansion.java。示例只处理内存 List，不接数据库、文件流或网络。Order 记录描述输入，labels 方法提供结果列表，main 只负责演示固定样本。

在回调作用域中发出结果

import java.util.List;

public class TagExpansion {
    record Order(String id, boolean urgent, boolean reviewRequired) {}

    static List labels(List orders) {
        // 显式给出输出类型，避免复杂回调的泛型推断不清楚
        return orders.stream().mapMulti((order, out) -> {
            if (order.urgent()) {
                out.accept(order.id() + ":优先处理");
            }
            if (order.reviewRequired()) {
                out.accept(order.id() + ":人工复核");
            }
            // 都不满足时不发出结果，不用制造空标签
        }).toList();
    }

    public static void main(String[] args) {
        var orders = List.of(
            new Order("A", true, true),
            new Order("B", false, false),
            new Order("C", false, true)
        );
        // 终端操作已封装在 labels 中；此处只展示返回列表
        System.out.println(labels(orders));
    }
}

两个独立 if 是业务语义：同时满足时都要输出。若误写为 if/else if，A 就少一个标签。回调没有 return 标签列表，而是由提供的 Consumer 接收结果；不调用 accept 就代表这个订单没有输出项。

运行时应看到什么

读者可在自己的示例目录运行下面命令。本文未运行这些命令，展示的是可复现方式和预期结果，不是实际控制台证据。

# 使用支持 mapMulti 与示例语法的 JDK 编译
javac -encoding UTF-8 TagExpansion.java
# 运行固定样本，不访问任何外部服务
java TagExpansion

对于示例中的有序顺序流，预期打印：

[A:优先处理, A:人工复核, C:人工复核]

检查点不只是数量为三，还包括 B 没有空字符串占位，A 的两类标签均保留。这个例子的 toList 结果不用于后续原地添加；业务需要可变容器时，应另行选择合适的收集方式。

已有子流时，flatMap 可以更直接

同一标签规则也能写成返回子流的函数。把下面方法加入同一个类即可；它通过全限定名使用 Stream，不需要改动原来的 import。

static java.util.stream.Stream labelsFor(Order order) {
    // 每个候选只对应一个条件；移除未启用的占位值
    return java.util.stream.Stream.of(
        order.urgent() ? order.id() + ":优先处理" : null,
        order.reviewRequired() ? order.id() + ":人工复核" : null
    ).filter(java.util.Objects::nonNull);
}

static List labelsWithFlatMap(List orders) {
    // 映射函数已经返回 Stream 时，直接扁平化
    return orders.stream()
        .flatMap(TagExpansion::labelsFor)
        .toList();
}

这里两种实现服务同一个契约。mapMulti 把“按条件发出几项”集中在一个命令式回调里；flatMap 让“一个订单对应一个子流”成为独立函数。若项目原本就有可复用的 labelsFor 一类方法，没有必要只为了换 API 而重写。

接入业务时保留这些边界

labels 可作为服务层的纯计算方法接收订单快照，调用方再决定怎样显示或保存标签。不要把数据库写入、消息发送等有副作用的工作塞进展开回调，也不要修改正在遍历的源集合。

Consumer 只能在当前映射调用的作用域内使用，不能保存到字段里，不能交给异步任务稍后调用。mapMulti 也不是适合无限输出循环的承诺；少量、有限的派生结果最容易理解和控制。

是否一定比 flatMap 快？官方 API 说明了少量结果场景的动机，但它不是针对你的负载给出的速度保证，接口默认实现还描述了内部缓冲与 flatMap 的实现方式。本文没有压测，不能据此声称零分配或固定提速。是否能用同一个 Stream 比较两种方法？应从相同 List 分别创建新流，不复用已消费流。

建议为这个小项目保留三类用例：全部不满足应返回空列表；单个条件应得到一项；两个条件同时满足应得到两项。再加一个空输入列表，确保没有额外占位。选择清楚的契约，比机械替换所有 flatMap 更有价值。