stream.peek是专为调试设计的中间操作，不改变元素也不终止流，仅在终端操作执行时观察数据；其效果取决于在流链中的位置，需搭配日志、避免副作用并必须接终端操作才能生效。
Stream.peek 是专为调试设计的中间操作，它不改变元素、不终止流，只在终端操作执行时“顺路看一眼”。用对位置、避开副作用、配好日志和终端操作，才是稳定观察流状态的关键。
找准插入位置，看清你想观察的数据
peek 的输出完全取决于它在流链中的位置：
- 放在 filter 前：能看到全部原始输入元素，适合确认数据源是否符合预期
- 放在 filter 后：只看到通过过滤的子集，便于验证过滤逻辑是否生效
- 放在 map 后：看到的是转换后的新值（如已转大写、已计算结果），不是原始值
- 可叠加多个 peek：比如 filter 前一个、filter 后一个、map 后一个，分步比对更清晰
用日志代替 System.out.println，兼顾安全与可控
打印只是起点，生产环境需升级为结构化日志：
- 优先使用 SLF4J 或 Log4j 的 debug 级日志，通过日志级别开关控制是否启用
- 避免直接打印整个对象（如
log.debug("item: {}", item)），改用关键字段快照：log.debug("id={}, status={}", item.getId(), item.getStatus()) - 字段可能为 null？用
Optional.ofNullable()包裹或提前判空，防止 peek 内部抛 NPE 中断整条流 - 高吞吐场景下加采样，例如每 100 条记录打印 1 条：
if (counter.incrementAndGet() % 100 == 0) log.debug(...)
严守无副作用边界，不碰状态、不调阻塞操作
peek 不是业务入口，它的稳定性依赖克制：
-
禁止修改对象字段（如
item.setProcessed(true)），破坏不可变性，且并行流中线程不安全 - 禁止同步 I/O：不发 HTTP 请求、不写文件、不查数据库——这些会拖慢甚至卡死流
- 禁止抛出未捕获异常：Consumer 不支持受检异常；一旦发生 NPE 或空指针，整条流立即终止
- 并行流中不依赖执行顺序：日志可能乱序，也不要用 ThreadLocal 存上下文
必须接终端操作，否则 peek 什么都不会做
这是最常被忽略的前提：
-
stream.peek(...).filter(...)单独写完就结束？不会触发任何行为，因为 Stream 是惰性求值 - 必须接上
.collect()、.forEach()、.count()、.findFirst()等终端操作，整条流水线才真正启动 - 短路操作（如
findFirst）可能只处理前几个元素，peek 也只触发对应次数，属正常行为
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
