global-coding-governance/java-coding-style/references/03-集合并发与时间.md

集合、并发与时间

集合

• 必须：选择与语义相符的集合；需要唯一性用 Set，需要键查找用 Map，不要靠线性扫描模拟索引。
• 推荐：规模可预估时设置合理初始容量，但不得按不可信输入直接分配超大容器。
• 必须：Arrays.asList 不是可增删列表；数组元素变化会反映到视图。需要独立可变列表时显式复制。
• 必须：集合转数组使用类型安全的 toArray 形式，并遵循项目 JDK 的惯用写法。
• 必须：遍历时删除元素应使用迭代器、removeIf 或收集后处理，不在增强 for 中直接结构性修改。
• 必须：不要修改 Map.keySet()、values() 等视图后假设原映射不变。
• 必须：自定义对象作为 Map 键或 Set 元素时保证 equals/hashCode 稳定；插入后不得改变参与哈希的字段。
• 推荐：返回只读视图或副本时明确其快照/联动语义；unmodifiable 不等于深度不可变。
• 推荐：Stream 用于清晰的数据变换；有副作用、异常流程或复杂分支时使用普通循环。

并发

• 必须：先识别共享可变状态，再选择不可变、线程封闭、并发容器、原子类或锁；volatile 不能保证复合操作原子性。
• 必须：线程池必须有清晰的线程数、队列、线程命名、拒绝策略和关闭策略。传统平台线程池不得直接使用默认无界的便捷工厂掩盖这些参数。
• 参考：Java 21+ 虚拟线程需确认项目支持、阻塞模型、限流方式与 ThreadLocal 成本；不要把虚拟线程当作无限资源。
• 必须：ThreadLocal 使用后在 finally 中清理，尤其在线程池和请求复用场景。
• 必须：锁范围尽可能小，不在持锁期间执行未知回调、远程调用或慢 I/O；多个锁必须有固定顺序。
• 必须：捕获 InterruptedException 后恢复中断标记或明确终止流程，不得吞掉中断。
• 推荐：高并发随机数使用 ThreadLocalRandom；共享计数根据竞争程度选择原子类或累加器。
• 推荐：并行 Stream 仅在数据量、无副作用、线程池影响和基准数据明确时使用。
• 必须：并发正确性不能只靠一次测试；检查竞态、可见性、重复执行、超时、取消与关闭路径。

日期与时间

• 必须：优先使用 java.time；旧 Date/Calendar 仅用于兼容边界并尽快转换。
• 必须：业务时间明确时区。存储时间点优先用 Instant，面向地区规则时显式使用 ZoneId。
• 必须：不得共享非线程安全的旧式日期格式化器；优先使用不可变的 DateTimeFormatter。
• 必须：持续时间测量使用单调时钟语义，如 System.nanoTime()；不要用墙上时钟计算短耗时。
• 必须：时间测试固定 Clock 或等价抽象，避免依赖当前时间造成不稳定测试。
• 推荐：日期边界、夏令时、闰年和跨时区转换要有针对性用例。