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

peek не гарантирует, что его действие будет выполнено для каждого элемента потока. Это промежуточная операция, предназначенная прежде всего для наблюдения за прохождением элементов, а не для обязательной бизнес-логики или побочных эффектов.

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

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

Stream API отделяет описание обработки данных от её фактического выполнения. Такой подход позволяет строить ленивые конвейеры, применять оптимизации и, при необходимости, выполнять обработку параллельно.

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

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

Разработчик может поместить в peek запись в журнал, изменение внешнего счётчика, отправку события или обновление другой коллекции, ожидая, что действие произойдёт для каждого элемента.

Это опасно по двум причинам. Во-первых, некоторые элементы могут не пройти фактическую обработку из-за оптимизаций конвейера. Во-вторых, при параллельном стриме побочные эффекты могут выполняться одновременно и в порядке, который не совпадает с порядком элементов.

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

peek является промежуточной и ленивой операцией. Она не запускает обработку сама по себе, а добавляет действие в конвейер; выполнение начинается только после терминальной операции.

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

import java.util.stream.Stream;

long count = Stream.of("a", "b", "c")
    .peek(System.out::println)
    .count();

System.out.println(count);

Здесь значение count равно трём, но печать элементов не является гарантированной частью контракта. Нельзя использовать peek как замену map, filter, forEach или отдельной операции записи результата.

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

Побочные эффекты внутри peek также усложняют тестирование и нарушают функциональный стиль Stream API. В параллельном режиме общий изменяемый объект потребует корректной синхронизации, но синхронизация может снизить масштабируемость; обычно лучше собирать результат через подходящий Collector.

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

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

Рассматривались три варианта. Сохранить peek было проще всего, но это не даёт требуемой гарантии. Перейти на параллельный forEach могло ускорить обработку, однако потребовало бы потокобезопасного аудитора и не сохранило бы порядок событий. Выполнить явную терминальную обработку с передачей каждого заказа в аудитор и отдельно подсчитать результат было менее компактно, зато контракт стал очевидным.

Выбран последний вариант. Аудит стал обязательным этапом бизнес-операции, а подсчёт выполнялся независимо; в результате ни оптимизация Stream API, ни режим параллельности не могли незаметно убрать требуемую запись.

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

Вопрос: Может ли наличие терминальной операции гарантировать выполнение peek для всех элементов?

Ответ: Нет. Терминальная операция запускает конвейер, но не обязана физически посещать каждый элемент, если результат можно получить иначе. Особенно это заметно у операций, которым достаточно метаданных источника или ограниченного числа элементов. Кроме того, короткозамыкающие операции могут завершить обработку раньше полного обхода.
Вопрос: Безопасно ли использовать peek для изменения общего счётчика в параллельном стриме?

Ответ: Нет, обычный изменяемый счётчик может потерять обновления из-за гонки данных. Использование атомарного счётчика устранит часть проблемы с корректностью, но не сделает саму обработку гарантированной: peek всё равно может быть пропущен, а порядок обновлений не определён. Для вычисления агрегата предпочтительнее count, sum, reduce или специализированный коллектор.
Вопрос: Чем peek концептуально отличается от map, если обе операции могут содержать лямбду?

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