Apache Commons Collections 4.6.0 介绍与选型指南

目标：面向希望扩展 JDK 集合框架能力（Bag、双向 Map、有序 Map、布隆过滤器等）的 Java 开发者与架构师，梳理 Apache Commons Collections 的定位、核心概念、官方用法示例与同类选型对比。本文为认知篇（A1），仅基于官方来源联网查证，不包含本地安装与实测内容。

一、信息基准

本章说明本文所有结论的数据来源与版本依据，便于读者复核时效性。

1.1 查询日期与版本依据

1.2 官方来源清单

• 官方主站：https://commons.apache.org/collections/
• 用户指南：https://commons.apache.org/proper/commons-collections/userguide.html
• 布隆过滤器文档：https://commons.apache.org/proper/commons-collections/bloomFilters.html
• 发布历史：https://commons.apache.org/proper/commons-collections/changes-report.html
• Maven Central 元数据：https://repo1.maven.org/maven2/org/apache/commons/commons-collections4/maven-metadata.xml
• GitHub 同步副本：https://github.com/apache/commons-collections
• JIRA 问题跟踪：https://issues.apache.org/jira/projects/COLLECTIONS

二、软件概述

Apache Commons Collections 在 JDK 集合框架（Java 1.2 引入、后成为 Java 集合处理事实标准）之上提供新接口、新实现与新工具类（官方首页自述，查询日期 2026-10-18）。最新稳定版 4.6.0（2026-08），Apache-2.0 许可，是 JVM 生态使用最广泛的集合扩展库之一。

2.1 项目背景与 3.x/4.x 分野

Collections 自 2001 年前后进入 Commons Proper，历史上存在 2.x、3.x、4.x 三条主线。官方首页明确：4.x 为现代主线（Maven 坐标 commons-collections4），3.x 的最后一个版本为 3.2.2，仅作历史归档提供 Javadoc（来源：官方首页 Documentation 章节，查询日期 2026-10-18）。新项目不应再引入 3.x。

2.2 版本与许可

• 当前版本 4.6.0（官方站点 Last Published 2026-08-06；Maven Central lastUpdated 2026-08-10）。
• 近期节奏：4.4（2019-07-05）之后经历 4.5.0-M1（2024-03-31）、4.5.0-M2（2024-06-15）、4.5.0-M3（2024-12-15）三个里程碑，随后发布 4.5.0 正式版并演进到 4.6.0（标签日期均见官方 Release Notes/GitHub，查询日期 2026-10-18）。里程碑周期较长，主线维护属于低频稳定型。

2.3 生态位

JDK 标准集合覆盖通用场景，Commons Collections 专注三类增量：JDK 没有的数据结构抽象（Bag、BidiMap、OrderedMap）、JDK 有但不便用的能力（MapIterator、集合运算、装饰器）、以及统计型数据结构（布隆过滤器）。它以纯 Java 库形态内嵌于应用进程，无外部服务依赖。

三、核心概念

以下概念与示例均出自官方用户指南（https://commons.apache.org/proper/commons-collections/userguide.html，查询日期 2026-10-18）。

3.1 Bag：计数集合

Bag 记录每个对象的出现份数，适合词频统计、库存计数等"集合 + 计数"复合场景，省去手工维护 Map<T, Integer> 的样板代码。JDK 至今没有对应接口。

3.2 BidiMap：双向映射

BidiMap 支持键查值与值查键的双向等价操作，并提供 inverseBidiMap() 视图交换键值，适合编码↔名称、ID↔枚举这类对称关系建模。

3.3 MapIterator 与 OrderedMap

MapIterator 简化 Map 遍历（避免 EntrySet/KeySet 二选一的繁琐）；OrderedMap 表达"有插入顺序但非按值排序"的语义，支持 firstKey()/nextKey() 双向游走，实现类有 LinkedMap 与装饰器 ListOrderedMap。

3.4 布隆过滤器（4.5.0 起）

4.5.0 系列新增 org.apache.commons.collections4.bloomfilter 包，提供布隆过滤器类与接口（官方首页特性列表与 4.5.0-M2/M3 发布说明均确认），用于低内存的成员存在性近似判断。

3.5 线程安全模型

官方用户指南"Note On Synchronization"明确：多数实现默认非线程安全，多线程使用需调用方自行同步（可用 JDK Collections 的 synchronized 包装方法，如 synchronizedMap）；类级 Javadoc 未显式声明线程安全时应按需同步对待（查询日期 2026-10-18）。

💡 技术拓展（集合扩展库的流派差异）：Commons Collections 选择"补齐 JDK 缺失的接口与实现"；Guava 选择"不可变集合 + 多值映射（Multimap/Multiset）+ 函数式工具"；Eclipse Collections 选择"每种原始类型专用的富接口集合（如 IntList）以消除装箱"。三者接口互不兼容，混用同一集合概念时需在边界处转换，选型时应以团队既有依赖为准。

四、功能特性

官方首页列出的特性包括（来源：https://commons.apache.org/collections/，查询日期 2026-10-18）：

• Bag 接口：按份数持有对象的集合；
• BidiMap 接口：键值双向查找；
• 布隆过滤器类与接口（4.5.0 起）；
• MapIterator 接口：简单快速地迭代 Map；
• 转换装饰器（Transforming decorators）：对象加入集合时自动变形；
• 组合集合（Composite collections）：把多个集合视为一个；
• 有序 Map/Set：保留加入顺序，含基于 LRU 的 Map；
• 引用 Map（Reference map）：可按受控策略让键/值被垃圾回收；
• 大量比较器（Comparator）与迭代器（Iterator）实现；
• 数组、枚举与集合之间的适配类；
• 集合论运算工具：并集、交集、闭包等测试与构造。

上述能力以 CollectionUtils/MapUtils/SetUtils 等工具类 + 接口实现族 + 装饰器三种形态提供，官方用户指南按 Utilities/Maps/Bags/Bloom filters 组织。

五、快速上手

本章示例引自官方用户指南（https://commons.apache.org/proper/commons-collections/userguide.html，查询日期 2026-10-18），除为独立可读补齐的变量取值外保持官方原文结构，未做本地运行验证。

5.1 Maven 依赖

<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-collections4</artifactId>
    <version>4.6.0</version>
</dependency>

坐标来源：Maven Central org.apache.commons:commons-collections4 元数据（https://repo1.maven.org/maven2/org/apache/commons/commons-collections4/maven-metadata.xml，查询日期 2026-10-18）。

5.2 MapIterator 遍历

官方示例（setValue 的取值按官方示意补全为具体值）：

IterableMap<String, String> map = new HashedMap<>();
map.put("A", "1");
MapIterator<String, String> it = map.mapIterator();
while (it.hasNext()) {
    String key = it.next();
    String value = it.getValue();
    it.setValue(value + "-updated");
}

5.3 OrderedMap 双向游走

官方示例（原文注释即返回值说明）：

OrderedMap<String, String> map = new LinkedMap<>();
map.put("FIVE", "5");
map.put("SIX", "6");
map.put("SEVEN", "7");
map.firstKey();      // returns "FIVE"
map.nextKey("FIVE"); // returns "SIX"
map.nextKey("SIX");  // returns "SEVEN"

5.4 BidiMap 双向查找

官方示例：

BidiMap<String, String> bidi = new TreeBidiMap<>();
bidi.put("SIX", "6");
bidi.get("SIX");        // returns "6"
bidi.getKey("6");       // returns "SIX"
bidi.removeValue("6");  // removes the mapping
BidiMap<String, String> inverse = bidi.inverseBidiMap(); // keys and values swapped

5.5 Bag 计数

官方示例：

Bag<String> bag = new HashBag<>();
bag.add("ONE", 6);        // add 6 copies of "ONE"
bag.remove("ONE", 2);     // removes 2 copies of "ONE"
bag.getCount("ONE");      // returns 4, the number of copies in the bag (6 - 2)

六、适用场景与限制

6.1 适用场景

• 需要计数集合（Bag）、双向映射（BidiMap）、插入序游走（OrderedMap）等 JDK 缺失抽象的通用 Java 服务；
• 低内存近似判重的布隆过滤器需求（4.5.0+），希望避免额外引入 Guava 或自研；
• 需要集合论工具（交集、并集、闭包）与组合/装饰器的数据处理代码；
• 既有代码库已广泛使用 commons-collections4，保持技术栈一致性。

6.2 限制与注意事项

• 线程安全需自管：多数实现非线程安全（官方同步说明，见 3.5），并发场景必须显式同步或改用并发集合；
• 只做数据结构，不做流式 API：Java 8 Stream 生态的惰性求值/并行流不在其职责内，函数式改造需求应配合 JDK Stream 或 StreamEx 等；
• 版本节奏偏慢：4.4 到 4.5 之间相隔近五年（2019-07 至 2024-03 起的里程碑序列），依赖其快速跟进新需求的团队需有心理预期；
• 禁止引入 3.x：3.x 已停更，官方仅作历史归档（见 2.1）。

6.3 不适合的场景

• 以原始类型性能为核心诉求的数值密集场景（Eclipse Collections 的专用原始类型集合更合适，见第七章）；
• 需要不可变集合与丰富多值映射语义、且项目已用 Guava 的场景（Guava Multimap/Multiset 与 Immutable 系列更成熟）。

七、同类选型对比

注：Stars 采信 shields.io / ungh.cc 当日返回值；EDL-1.0 为 Eclipse Foundation Distribution License，对商业集成友好。

选型建议：需要 Bag/BidiMap/布隆过滤器这类"JDK 缺口"抽象选 Commons Collections；项目已引入 Guava 则多值映射与不可变集合直接用 Guava，避免两套集合语义并存；追求原始类型性能与流式风格选 Eclipse Collections（注意 Java 17 基线）；只求让 Stream 更顺手则 StreamEx 最小侵入。

八、参考链接

1. 官方主站：https://commons.apache.org/collections/
2. 用户指南：https://commons.apache.org/proper/commons-collections/userguide.html
3. 布隆过滤器文档：https://commons.apache.org/proper/commons-collections/bloomFilters.html
4. Release Notes：https://commons.apache.org/proper/commons-collections/changes-report.html
5. Maven Central 元数据：https://repo1.maven.org/maven2/org/apache/commons/commons-collections4/maven-metadata.xml
6. GitHub 同步副本：https://github.com/apache/commons-collections
7. Guava 仓库：https://github.com/google/guava
8. Eclipse Collections 发布页：https://github.com/eclipse-collections/eclipse-collections/releases
9. StreamEx 仓库：https://github.com/amaembo/streamex