Краткий ответ

flatMap преобразует каждый элемент во вложенный Stream, а затем объединяет эти потоки в один. mapMulti передаёт функции общий downstream-приёмник, в который функция напрямую отправляет от нуля до нескольких результатов, поэтому промежуточный Stream для каждого входного элемента не создаётся.

Исторический контекст

Обычный flatMap хорошо выражает композицию потоков, но для простых случаев «один элемент порождает несколько значений» требует создавать вложенный поток на каждом вызове функции. В Java 16 появился mapMulti как более императивная альтернатива, уменьшающая такую инфраструктурную обвязку и позволяющая использовать обычный цикл внутри преобразования.

Это не отменяет flatMap: он остаётся более декларативным и удобным, когда результат естественно представляется отдельным потоком или когда нужно переиспользовать готовый потоковый конвейер.

Постановка проблемы

Предположим, каждый объект нужно условно развернуть в несколько записей. При использовании flatMap функция должна вернуть вложенный поток даже тогда, когда результат пуст или состоит всего из нескольких элементов.

Неверный выбор может привести либо к лишнему созданию объектов и усложнению горячего участка, либо к менее читаемому коду. При этом нельзя автоматически считать mapMulti более быстрым: итог зависит от источника, числа результатов, стоимости их создания и поведения последующих операций.

Подробное решение

flatMap работает как операция «элемент → поток элементов». Stream API затем последовательно проходит по каждому вложенному потоку и передаёт его элементы дальше по конвейеру. Пустой вложенный поток означает, что исходный элемент не даёт результата.

mapMulti работает как операция «элемент → вызовы потребителя». Функция получает исходный элемент и объект, принимающий результаты; каждый вызов этого объекта добавляет одно значение в результирующий поток. Если вызовов нет, для элемента получается ноль результатов.

Минимальный пример:

import java.util.stream.Stream;

Stream<Integer> result = Stream.of(1, 2, 3)
    .<Integer>mapMulti((value, out) -> {
        if (value % 2 == 1) {
            out.accept(value);
            out.accept(value * 10);
        }
    });

Для 1 и 3 функция отправит по два значения, а для 2 — ни одного. Явный тип <Integer> иногда нужен компилятору для разрешения перегруженного или недостаточно очевидного целевого типа.

mapMulti особенно уместен, когда преобразование содержит условие, небольшой цикл или несколько ветвей и не требует полноценного вложенного Stream API. flatMap предпочтительнее, когда вложенный поток уже существует, выражает самостоятельный конвейер или преобразование удобно описывается комбинацией потоковых операций.

Обе операции являются промежуточными и ленивыми. Они не определяют порядок сверх гарантий исходного упорядоченного стрима, а в параллельном режиме функция преобразования не должна зависеть от общего изменяемого состояния. Передача результата в downstream выполняется в рамках обработки соответствующего элемента; полагаться на конкретную межпоточную последовательность таких вызовов нельзя.

Ситуация из практики

Сервис разбирает записи документа и для каждой записи может сформировать от нуля до пяти поисковых токенов. Вариант с flatMap создаёт отдельный небольшой поток для каждой записи: он прозрачен, но добавляет вложенные объекты и требует размещать логику формирования результата внутри фабрики потока.

Вариант с mapMulti использует локальные проверки и цикл, отправляя найденные токены непосредственно downstream. Он проще для такого императивного преобразования и не создаёт вложенный Stream на каждую запись, поэтому выбран при профилировании горячего участка.

Полностью ручной for-цикл с изменяемым списком был бы потенциально ещё проще, но разрушил бы единый потоковый конвейер и потребовал бы отдельно контролировать промежуточное состояние. flatMap оставили бы предпочтительным вариантом, если бы разбор одной записи уже возвращал самостоятельный Stream или включал несколько стандартных потоковых операций. После замены на mapMulti сохранились ленивость и композиция конвейера, а лишнее создание вложенных потоков исчезло.

Что кандидаты часто упускают

Гарантирует ли mapMulti отсутствие всех промежуточных выделений памяти?

Нет. Он устраняет необходимость создавать вложенный Stream для каждого входного элемента, но сам конвейер может создавать другие объекты, а последующие операции, например сортировка или сбор в коллекцию, всё равно могут буферизовать данные. Поэтому утверждение о выигрыше нужно подтверждать измерениями, а не делать только по форме API.

Можно ли передать в downstream результат асинхронно после возврата функции mapMulti?

Нет. Приёмник предназначен для синхронной передачи результатов во время вызова функции преобразования. Сохранять его и вызывать позже из другого потока нельзя: это нарушает ожидаемый жизненный цикл операции и может привести к некорректному поведению. Асинхронную обработку нужно проектировать отдельными средствами, а не использовать downstream-приёмник как очередь.

Что произойдёт, если функция mapMulti отправит один и тот же изменяемый объект несколько раз, а затем изменит его?

В поток будут переданы ссылки на один объект, а не независимые копии. Если последующая обработка увидит объект после его изменения, все элементы могут фактически содержать одно последнее состояние. Для корректности нужно передавать неизменяемые значения либо создавать отдельный объект для каждого результата; mapMulti не копирует передаваемые значения автоматически.