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

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

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

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

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

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

Функция, переданная в flatMap, может не иметь данных для дальнейшей обработки и вернуть null. Если ожидать обычное поведение, можно ошибочно предположить, что возникнет NullPointerException или что null попадёт в результирующий поток как отдельный элемент.

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

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

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

import java.util.stream.Stream;

var result = Stream.of(1, 2, 3)
    .flatMap(value -> value == 2 ? null : Stream.of(value, value * 10))
    .toList();

System.out.println(result); // [1, 10, 3, 30]

Здесь элемент 2 не даёт результатов, поэтому в списке отсутствуют и 2, и 20. При этом null, возвращённый из самой функции, не становится элементом результата.

Гарантия не распространяется на ошибки внутри функции. Если функция сама выбросит исключение, поток завершится с этим исключением. Также отдельный вопрос — входное значение null: функция может обработать его, выбросить исключение или вернуть пустой поток в зависимости от своей логики.

В параллельном стриме правило остаётся тем же: null означает отсутствие результатов для соответствующего элемента. Параллельность может изменить порядок обработки, но не превращает null в элемент потока.

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

Сервис преобразует записи заказа в поток связанных сущностей. Для некоторых записей связанные сущности отсутствуют, и функция преобразования возвращает null вместо пустого стрима.

Вариант с предварительной проверкой null вокруг каждого вызова делает цепочку многословной и увеличивает вероятность пропуска проверки. Вариант с возвратом Stream.empty() явно показывает отсутствие результатов, но требует дисциплины от каждой функции.

Выбранное решение — использовать контракт flatMap, допускающий null, если это согласовано в команде и подтверждено тестами. Однако для читаемости и единообразия обычно предпочтительнее явно возвращать Stream.empty(): такой код понятнее без знания специального поведения flatMap. Результат в обоих случаях одинаков — записи без связанных сущностей не попадают в итоговую последовательность.

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

Попадёт ли null в результат как элемент при использовании flatMap?

Нет. flatMap получает от функции поток, а не отдельное значение. Возвращённый null интерпретируется как отсутствие потока, поэтому соответствующий входной элемент порождает ноль выходных элементов. Чтобы добавить именно null как элемент, нужна другая логика преобразования, а не возврат null вместо потока.

Что произойдёт, если исключение возникло внутри функции до её возврата?

Исключение не считается пустым результатом. Оно распространяется по цепочке и обычно прерывает выполнение терминальной операции. Поведение null является специальной частью обработки результата функции, но не механизмом подавления исключений.

Чем в этой ситуации отличается map от flatMap?

map воспринимает результат функции как значение элемента. Поэтому функция map, возвращающая null, создаёт в результирующем потоке элемент со значением null. flatMap ожидает поток: при null такой поток считается пустым, и элемент результата не создаётся.