Java Stream.peek 为什么不能用来保证业务副作用执行

如果你把写入数据库、发送通知或更新订单状态放进 Stream.peek()，偶尔发现动作没有发生，这通常不是日志系统丢了，而是把“观察流水线”误当成了“业务执行点”。peek 是惰性中间操作，只有终止操作真正消费元素时才可能被调用；遇到短路、可优化的终止操作或并行流时，它也不适合承担必须发生的副作用。

先把 peek 放回 Stream 流水线里的位置

一条 Stream 通常由数据源、若干中间操作和一个终止操作组成。filter、map、peek 都只是描述处理方式，真正遍历数据要等终止操作出现。下面这段代码不会打印任何订单：

List orders = loadOrders();
orders.stream()
      // 这里只登记观察动作，不会主动消费订单
      .peek(order -> auditLog(order.getId()))
      .filter(Order::isPaid);

因为最后的表达式仍是一条未消费的 Stream。加上 toList() 后，数据才会沿着流水线流动，peek 才有机会被调用。但“有机会”不等于业务契约：它的职责是观察，不是承诺每个元素都完成一次动作。

为什么加了终止操作，peek 仍可能少执行

终止操作只保证它自己的结果或动作，不保证每个中间阶段都必须逐元素执行。比如源是一个有已知大小的集合时，count() 可能直接得到数量，不需要运行不会影响计数结果的中间阶段：

long total = orders.stream()
    .peek(order -> auditLog(order.getId()))
    // count 只关心数量，不能把 peek 当成逐条审计保证
    .count();

而 findFirst()、anyMatch()、limit() 等会提前结束消费；过滤条件一旦满足，后面的元素就不会继续经过 peek。并行流还会带来线程与顺序问题：即使最终结果保持遇到顺序，回调执行的线程和副作用可见性也不能拿来当业务协议。

所以排查时要问三个问题：终止操作是否真的需要每个元素？流水线是否会短路？peek 里的动作是否允许少一次、乱序或换线程？只要最后一个答案是否定的，就应该重构。

把观察动作和业务副作用分开

调试打印、临时计数这类低风险观察可以使用 peek，但也应控制生命周期。订单落库、库存扣减、发送支付通知则必须有明确的调用点、异常处理和重试边界。不要把它们藏在一段看似纯查询的链式表达式里：

List receipts = orders.stream()
    .filter(Order::isPaid)
    .map(this::buildReceipt)
    // map 负责生成值，不在中间阶段写库
    .toList();

// 终止动作集中在业务层，失败和重试边界更清楚
receipts.forEach(receiptRepository::save);

这里的 map 只做订单到回执的转换，toList 明确结束计算；保存动作由单独的循环承接。若保存顺序重要，就不要直接改成 parallel()；若必须并发，应让仓储层具备线程安全、幂等和可观测的失败处理，而不是依赖 peek 的执行顺序。

几种常见写法该怎么选

一句实用判断是：如果删掉 peek 后，流水线的返回值应该完全不变，那么它最多是观察点；如果删掉后会导致订单状态不一致，就说明副作用放错了位置。

常见问题

加了 collect 后，peek 会对每条数据执行吗？

在没有短路和优化省略的普通流水线中通常会经过，但 API 不把它定义成业务副作用保证。不要用这个“通常”替代明确的终止动作。

peek 适合打印调试日志吗？

可以用于短期观察，但日志不应改变结果，也不要在并行流中假设日志顺序。稳定诊断最好使用专门的计数、追踪或测试断言。

forEach 就一定比 peek 安全吗？

它的位置更明确，但安全性仍取决于共享状态、线程模型、异常处理和幂等设计。并行流里的 forEach 不提供遇到顺序；需要顺序时再评估 forEachOrdered 的成本。

peek 最适合“看一眼流水线发生了什么”，不适合“保证业务一定发生什么”。把数据转换留在 Stream 中，把保存、通知和状态变更放到可命名、可测试、可重试的业务动作里，问题会比继续调整链式调用更容易收敛。