Collectors.toList() 在 Java 16+ 明确返回不可变列表，调用 add() 或 clear() 抛 UnsupportedOperationException；此前版本虽常返回 ArrayList，但属规范行为而非保证，不可依赖可变性。
Collectors.toList() 为什么有时返回不可变列表？
Java 16 之前 Collectors.toList() 返回的是 ArrayList，但它是“规范行为”，不是“保证实现”——JVM 厂商可以换，你不能依赖它的可变性。Java 16+ 的 toList() 明确返回不可变列表，调用 add() 或 clear() 会直接抛 UnsupportedOperationException。
- 如果需要后续修改，显式用
Collectors.toCollection(ArrayList::new) - 如果只是临时收集、马上遍历或传参，用
toList()更安全，避免意外修改 - 注意 IDE 可能不报错，但运行时崩——尤其在测试里改了列表再断言，容易漏掉
分组后想保留插入顺序，该选 toMap 还是 groupingBy？
Collectors.groupingBy() 默认用 HashMap，不保证顺序；toMap() 也不保序，除非你传 LinkedHashMap::new 作为 mapSupplier。
- 按自然顺序分组（如按字符串首字母）：用
groupingBy(Function.identity(), LinkedHashMap::new, Collectors.toList()) - 需要自定义 key-value 映射逻辑（比如 key 是 id，value 是 name + age 拼接）：用
toMap(Person::getId, p -> p.getName() + "-" + p.getAge(), (a,b) -> a, LinkedHashMap::new) - 别漏第四个参数
LinkedHashMap::new，否则默认是HashMap，顺序随机
Collectors.averagingDouble 算出来是 NaN？
只要流里有一个 null 元素，或者被映射的字段是 null，averagingDouble 就会返回 NaN，而不是跳过或报错。
java-api-doc-generator
下载
分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
- 先过滤 null：
stream.filter(Objects::nonNull).collect(Collectors.averagingDouble(Person::getSalary)) - 或用
mapToDouble+OptionalDouble手动控制：stream.mapToDouble(p -> p.getSalary() != null ? p.getSalary() : 0.0).average() - 注意
averagingDouble底层调用的是DoubleStream.average()，而空流也会返回OptionalDouble.empty()，但 collector 把它转成NaN了——这点和直觉相反
多个 Collector 组合时，joining 和 mapping 容易套错层级
比如想把每个 Person 的名字转大写，再用逗号拼接，写成 Collectors.joining(", ", "", "") 是没用的，它只对字符串流有效；必须先 mapping 再 joining。
立即学习“Java免费学习笔记（深入）”；
- 正确写法：
Collectors.mapping(Person::getName, Collectors.collectingAndThen(Collectors.toList(), list -> list.stream().map(String::toUpperCase).collect(Collectors.joining(", ")))) - 更简洁写法：
Collectors.mapping(p -> p.getName().toUpperCase(), Collectors.joining(", ")) - 常见错误：把
joining放外层、mapping放内层，结果编译不过——因为mapping要求下游 collector 接收转换后的类型，类型不匹配就炸
最常被忽略的是 collector 的“下游约束”：每个组合操作都隐含类型流转，一旦中间映射出错或 null 处理遗漏，不会报编译错误，但运行时结果诡异或空指针。写完最好拿两个边界值（空集合、单元素、含 null）快速过一遍。
