280. Java Stream API - Debugging Streams：如何调试 Java 流处理过程？

280. Java Stream API - Debugging Streams：如何调试 Java 流处理过程？

---

🎯 本节目标

• 理解 peek() 的作用与用途
• 正确使用 peek() 观察流中数据的"旅程"
• 明确 peek() 的使用边界：仅限调试，禁止用于业务逻辑

---

🚧 为什么调试 Stream 这么难？

在传统的 for 循环中，我们可以很容易地使用 System.out.println() 或断点查看变量状态。但一旦使用了 Stream：

• 流操作是惰性执行的（lazy）
• 很难在合适的位置打断点
• IDE 跳转调试时常常进入 Stream 的底层实现，而不是我们的 lambda 表达式

📌 所以我们需要一个"观察窗口" ------ peek()。

---

🔍 peek() 是什么？

peek() 是 Stream API 中的一个中间操作，可以让我们"偷看"流中元素在每个阶段的状态。

📘 方法签名：

Stream<T> peek(Consumer<? super T> action)

• 它接收一个 Consumer（比如 System.out::println）
• 会在每个元素被处理时调用该 consumer
• 不会改变元素本身！

---

⚠️ 使用建议

☢️ peek() 仅适用于调试！不要用它去修改元素或执行副作用操作。

---

🔨 示例代码

List<String> strings = List.of("one", "two", "three", "four");

List<String> result = strings.stream()
    .peek(s -> System.out.println("Starting with = " + s))        // 阶段 1：输入流
    .filter(s -> s.startsWith("t"))                                // 阶段 2：过滤首字母是 "t"
    .peek(s -> System.out.println("Filtered = " + s))              // 阶段 3：通过过滤后的
    .map(String::toUpperCase)                                      // 阶段 4：转大写
    .peek(s -> System.out.println("Mapped = " + s))                // 阶段 5：映射结果
    .toList();

System.out.println("result = " + result);

---

🖨️ 控制台输出：

Starting with = one
Starting with = two
Filtered = two
Mapped = TWO
Starting with = three
Filtered = three
Mapped = THREE
Starting with = four
result = [TWO, THREE]

---

🧠 分析输出过程

让我们一条一条分析上面是如何打印出来的：

元素	输出过程
one	打印 Starting with = one → 被 filter() 排除，没再处理
two	打印 Starting with = two → 通过过滤 → 打印 Filtered = two → 转大写 → 打印 Mapped = TWO
three	类似 two 流程
four	打印 Starting with = four → 被过滤掉，流程终止

---

🧭 peek() 和 Stream 执行顺序的启示

通过 peek()，你可以非常直观地看到流是如何"懒加载、单元素逐个处理"的：

• 每个元素是一步步完整走完流水线 （filter → map → collect）
• 然后再处理下一个元素
• 不是先全部过滤、再全部映射、再全部收集！❌

这就是流式处理的本质。

---

❌ 错误用法举例

stream.peek(s -> database.save(s)) // ❌ 千万不要用 peek 执行业务操作

原因：

• peek 是调试工具，不保证一定会被调用（比如流终止前短路操作）
• peek 不是副作用执行的安全位置
• 用 forEach() 或其他显式终端操作替代更合适

---

🎯 实战建议

场景	是否使用 peek()
想调试每一步中间处理结果	✅
想打印过滤、映射的过程	✅
想执行日志记录或测试调试打印	✅（调试环境）
想保存到数据库或写文件等副作用操作	❌
用 peek 代替 map、filter 逻辑	❌

---

🧪 拓展练习：数值流调试

List<Integer> numbers = List.of(1, 2, 3, 4, 5, 6);

List<Integer> evens = numbers.stream()
    .peek(n -> System.out.println("Original = " + n))
    .filter(n -> n % 2 == 0)
    .peek(n -> System.out.println("Even = " + n))
    .map(n -> n * n)
    .peek(n -> System.out.println("Squared = " + n))
    .toList();

System.out.println("evens squared = " + evens);

---

🧩 小结

• peek() 是 Stream 的调试"望远镜"，用来查看元素在流中的变化路径
• 不要在生产代码中做副作用操作
• 它可以帮你理解 Stream 的执行顺序与"懒加载"的执行模型