Stream.peek()是Java 8中延迟执行、无副作用的中间操作，用于日志、监控等可观测性场景，但不可修改元素或依赖外部状态。
Stream.peek() 是 Java 8 Stream API 中一个常被误解但非常实用的中间操作：它允许你在不改变流元素的前提下，对每个元素执行一个 无副作用 的消费动作（如打印、埋点、统计），且只在流真正被终端操作触发时才执行。关键在于——它不是“立即执行”，而是“延迟执行 + 副作用可控”。
peek() 的本质与使用前提
peek() 接收一个 Consumer<t></t>，返回原流（即不修改元素、不中断流）。但它仅在流管道被终端操作（如 forEach、collect、count）驱动时才触发。如果流没被消费（比如只定义了 stream 变量但没调用终端方法），peek 里的代码根本不会运行。
⚠️ 注意：官方文档明确要求 peek 的行为必须是“无副作用”（side-effect-free）——意思是不能依赖它来修改外部状态（如递增全局计数器、写文件、发 HTTP 请求），否则会导致不可预测行为（尤其在并行流中）。但实践中，日志、监控、调试类轻量级可观测性操作，只要不破坏流逻辑一致性，是合理且广泛接受的用法。
安全埋点：记录处理数量与典型样本
适合在开发/测试阶段快速验证流逻辑是否按预期走通，又不想侵入业务代码：
- 用原子计数器统计进入某环节的元素个数（确保线程安全）
- 对前 N 个元素做详细日志（避免刷屏），例如打印 ID 和关键字段
- 配合条件判断，只对异常值或特定类型打点（如
e.getStatus() == ERROR）
示例：
AtomicInteger processed = new AtomicInteger(0);
List<User> activeUsers = users.stream()
.filter(User::isActive)
.peek(u -> {
int count = processed.incrementAndGet();
if (count <= 3) {
System.out.println("DEBUG: peeked user " + u.getId() + ", name=" + u.getName());
}
})
.map(User::toDto)
.collect(Collectors.toList());
监控指标采集：结合 Micrometer 或自定义指标器
在生产环境，可将 peek 作为轻量级指标注入点，对接 Prometheus 等系统：
- 每次 peek 调用对应一次“处理事件”，可用于计算吞吐率（需注意采样率控制）
- 提取元素特征（如响应时间、错误码）并更新 Gauge / Timer / Counter
- 避免在 peek 中做耗时操作（如远程调用、磁盘 I/O），否则拖慢整个流
示例（伪代码，基于 Micrometer）：
Counter successCounter = Counter.builder("stream.process.success").register(registry);
Timer processTimer = Timer.builder("stream.process.latency").register(registry);
users.stream()
.peek(u -> {
// 计数
successCounter.increment();
// 记录耗时（需提前记录开始时间，此处略）
// processTimer.record(Duration.between(start, Instant.now()));
})
.map(this::enrichUserData)
.collect(Collectors.toList());
调试陷阱：什么时候不该用 peek？
peek 不是万能调试钩子，以下情况应避免或改用更明确的方式：
- 需要修改元素本身（如 set 字段）→ 改用
map()并返回新对象 - 需要条件跳过或终止流 → 用
filter()或takeWhile() - 需要聚合状态（如 sum、max） → 用
reduce()或终端操作后的变量收集 - 并行流中执行非线程安全操作（如往普通 ArrayList add）→ 必须加锁或换用线程安全容器
简单说：peek 只看不碰，只记不改，只观不控。
