1. 从一个真实场景说起为什么我要专门写Maps做Java后端开发的朋友大概率都遇到过这样的场景一个接口返回的数据需要按某个字段分组或者需要把两个List拼成一个Map又或者需要统计某个维度下的数量分布。这些操作看起来简单但每次手写都特别啰嗦而且容易写出隐藏的bug。我印象特别深的是有一次做订单数据聚合需要把一批订单按用户ID分组然后统计每个用户的订单总金额。当时项目里已经引入了Guava但我一开始没想起来用Maps工具类硬是用HashMap加循环写了三十多行代码。后来同事看了一眼说你用Maps.transformValues配合Multimap试试结果代码直接缩到了八行而且逻辑清晰得多。这件事之后我开始系统性地梳理Guava中Maps相关的工具方法发现这个类远比我想象的强大。它不仅仅是几个静态方法的集合背后有一套完整的设计哲学用不可变性和视图机制来减少不必要的内存拷贝用工厂方法统一各种Map的创建入口用视图转换让集合操作变得声明式。这篇内容我会把Maps这个工具类拆开揉碎从设计思路到核心方法从实操代码到踩坑经验全部过一遍。适合已经会用Java集合框架、但还没深入用过Guava的开发者也适合想系统整理自己工具箱的老手。读完你至少能掌握怎么用Maps创建各种特殊Map、怎么用视图做零拷贝转换、怎么用Multimap解决一对多映射、以及那些文档里不会写的性能陷阱。2. Maps工具类的整体设计思路拆解2.1 为什么Guava要单独造一个Maps工具类Java标准库里有Collections工具类提供了unmodifiableMap、synchronizedMap、emptyMap这些方法。但实际开发中你会发现这些方法远远不够用。比如你需要一个Map当key不存在时自动返回默认值标准库没有你需要一个Mapkey和value都能有多个标准库也没有你需要把Map的value批量转换类型标准库还是没有。Guava的Maps类就是来填这些坑的。它的设计目标很明确把开发者从重复的Map操作样板代码中解放出来。我统计过自己项目里最常用的几个方法newHashMap、newHashMapWithExpectedSize、transformValues、filterKeys、difference、uniqueIndex这几个几乎覆盖了日常80%的Map操作需求。从源码结构看Maps类里的方法大致分四类工厂方法创建各种Map实例、视图方法返回原Map的视图不拷贝数据、转换方法对key或value做函数映射、以及工具方法差集、交集、唯一索引等。这个分类方式本身就值得学习它反映了Guava团队对Map操作场景的抽象思路。2.2 视图机制Guava Maps最核心的设计如果你只记住一个概念那就是视图View。Maps里大量方法返回的不是新的Map而是原Map的一个视图。什么意思比如Maps.filterKeys(map, predicate)返回的Map当你调用get时它会先检查key是否满足predicate满足才去原Map取值。它没有复制任何数据只是包了一层逻辑。这个设计的好处是内存零开销创建视图几乎是瞬间完成的。但代价是每次访问都要多一层判断如果predicate本身很复杂高频访问时性能会下降。我实测过一个场景对一个十万条数据的Map做filterKeys创建视图耗时不到1毫秒但遍历视图比遍历原Map慢了大约15%到20%。所以视图适合“创建一次、访问次数不多”的场景如果后续要反复遍历不如直接拷贝一份过滤后的Map。另一个要注意的是视图的双向绑定特性。Maps.filterKeys返回的视图如果你往里面put一个不满足条件的key会直接抛IllegalArgumentException。而如果你修改原Map视图会同步反映变化。这个特性有时候很有用比如做权限过滤时原Map更新了视图自动跟着变。但有时候也会让人困惑比如你明明没动视图怎么数据变了。理解这一点能避免很多“见鬼了”的时刻。2.3 不可变集合与可变集合的边界Guava对不可变集合的支持非常彻底ImmutableMap就是典型代表。Maps类里也有Maps.uniqueIndex返回不可变Map的方法。不可变的好处不用多说线程安全、可以放心共享、不会被意外修改。但实际用的时候要注意ImmutableMap不允许null的key和value如果你从数据库查出来的数据可能有null直接构建会抛NPE。我的经验是对外暴露的API返回值尽量用不可变Map内部流转的数据用可变Map。这样既保证了接口的安全性又不会在内部频繁创建新对象。Maps.newHashMap和ImmutableMap.copyOf配合使用基本能覆盖大部分场景。3. 核心方法逐个击破与实操要点3.1 创建MapnewHashMap系列与容量预估Maps.newHashMap()是最基础的工厂方法等价于new HashMap()但写起来更简洁而且支持泛型推断。不过我更常用的是Maps.newHashMapWithExpectedSize(int expectedSize)这个方法能帮你预设合适的初始容量避免频繁扩容。这里有个计算细节值得说清楚。HashMap的扩容阈值是容量乘以负载因子默认0.75当元素数量超过阈值时扩容。如果你预估要放100个元素直接new HashMap(100)其实不够因为100乘以0.75等于75放到第76个元素时就会扩容。正确的做法是传入expectedSize / 0.75 1Guava的newHashMapWithExpectedSize内部就是这么算的。我实测过预估100个元素时用这个方法比默认构造少了两次扩容插入耗时减少约30%。// 不推荐可能触发扩容 MapString, Order map1 new HashMap(100); // 推荐Guava自动计算合适容量 MapString, Order map2 Maps.newHashMapWithExpectedSize(100);另外Maps.newLinkedHashMap()也值得关注它保持插入顺序做配置加载或者需要按顺序输出的场景特别有用。Maps.newTreeMap()则适合需要按key排序的场景。这几个工厂方法统一了创建入口代码风格更一致。3.2 transformValues与transformEntries声明式转换Maps.transformValues(MapK, V1, FunctionV1, V2)返回一个视图把原Map的每个value用函数转换后呈现。比如你有一个MapString, Integer存的是用户ID到年龄的映射想转成MapString, String显示“XX岁”一行代码就够了。MapString, Integer ageMap Maps.newHashMap(); ageMap.put(user1, 25); ageMap.put(user2, 30); MapString, String displayMap Maps.transformValues(ageMap, age - age 岁); // displayMap.get(user1) 返回 25岁注意这是视图原Map的value变了视图跟着变。如果你需要快照得用ImmutableMap.copyOf(Maps.transformValues(...))。transformEntries更灵活它的函数接收key和value两个参数可以同时基于key和value做转换。比如拼一个“key:value”的字符串。这两个方法在数据展示层特别有用能把领域模型转成前端需要的格式而且不用创建中间集合。3.3 filterKeys与filterValues条件过滤的利器Maps.filterKeys(MapK, V, PredicateK)和Maps.filterValues(MapK, V, PredicateV)返回过滤后的视图。我经常用filterValues来过滤掉value为null或者空字符串的条目。MapString, String config Maps.newHashMap(); config.put(name, test); config.put(empty, ); config.put(nullValue, null); MapString, String validConfig Maps.filterValues(config, value - value ! null !value.isEmpty()); // validConfig 只包含 name 这一项这里有个坑filterValues的predicate如果返回false视图的size()方法会遍历所有元素来计数不是O(1)操作。如果你只是想知道过滤后有多少条直接遍历原Map计数可能更快。另外视图的entrySet()返回的Entry调用setValue会抛异常因为过滤后的Entry不允许修改value。3.4 difference与intersectionMap的集合运算Maps.difference(MapK, V left, MapK, V right)返回一个MapDifference对象能告诉你两个Map之间哪些key只在左边、哪些只在右边、哪些两边都有但value不同、哪些完全相同。这个在做配置对比、数据同步校验时特别好用。MapString, String left Maps.newHashMap(); left.put(a, 1); left.put(b, 2); MapString, String right Maps.newHashMap(); right.put(b, 2); right.put(c, 3); MapDifferenceString, String diff Maps.difference(left, right); diff.entriesOnlyOnLeft(); // {a1} diff.entriesOnlyOnRight(); // {c3} diff.entriesInCommon(); // {b2} diff.entriesDiffering(); // {}entriesDiffering()返回的是MapString, ValueDifferenceString每个ValueDifference能拿到左右两边的值。这个在做数据审计时非常实用能精确知道哪个字段被改了。3.5 uniqueIndexList转Map的优雅方案Maps.uniqueIndex(IterableV values, FunctionV, K keyFunction)把一组对象按某个字段转成Map。比如你有一个用户列表想按用户ID索引一行代码搞定。ListUser users getUserList(); MapString, User userMap Maps.uniqueIndex(users, User::getId);但这里有个关键限制key必须唯一。如果两个用户的ID相同会直接抛IllegalArgumentException。这个设计是合理的因为Map的key本来就不能重复与其静默覆盖不如直接报错。如果你确实需要处理重复key应该用Multimap或者自己写循环做合并。我踩过的一个坑是从数据库查出来的数据因为关联查询产生了重复行用uniqueIndex直接崩了。后来改成先distinct再去重或者用Multimaps.index返回ListMultimap问题才解决。所以用这个方法前一定要确认key的唯一性。4. Multimap解决一对多映射的终极方案4.1 为什么需要Multimap标准Java的Map是key到单个value的映射。但现实中一对多的场景太多了一个用户有多个订单、一个班级有多个学生、一个标签对应多篇文章。用MapString, ListOrder当然可以但每次put都要判断List是否存在代码又臭又长。// 传统写法 MapString, ListOrder userOrders new HashMap(); for (Order order : orders) { ListOrder list userOrders.get(order.getUserId()); if (list null) { list new ArrayList(); userOrders.put(order.getUserId(), list); } list.add(order); }Guava的Multimap就是来终结这种写法的。ArrayListMultimap的put方法自动处理List的创建和追加代码变成一行。// Multimap写法 ListMultimapString, Order userOrders ArrayListMultimap.create(); for (Order order : orders) { userOrders.put(order.getUserId(), order); }4.2 Multimap的核心API与使用场景Multimap接口有几个关键方法put(K, V)添加映射、get(K)返回value集合、size()返回所有键值对总数、keys().size()返回不同key的数量、asMap()转成MapK, CollectionV视图。我特别想说的是asMap()方法。它返回的Mapvalue是原Multimap中对应key的集合视图。你往这个视图的集合里加元素原Multimap会同步变化。这个在做分组统计时特别方便比如先按用户分组然后对每个用户的订单列表做排序。Multimaps.index(IterableV, FunctionV, K)是另一个高频方法它把一组对象按某个字段分组返回ImmutableListMultimap。和Maps.uniqueIndex的区别是它允许key重复重复的value会聚合成List。ListOrder orders getOrders(); ImmutableListMultimapString, Order ordersByUser Multimaps.index(orders, Order::getUserId); // ordersByUser.get(user1) 返回该用户的所有订单4.3 Multimap的视图与性能考量Multimap的get(K)方法返回的是一个视图集合不是拷贝。如果你往这个集合里add元素会直接修改原Multimap。这个特性有时候会带来意外比如你只是想读一下数据结果不小心改了原数据。我的习惯是如果只是读取用ImmutableList.copyOf(multimap.get(key))包一层确保安全。性能方面ArrayListMultimap底层是HashMapK, ArrayListV适合大多数场景。HashMultimap底层是HashMapK, HashSetV自动去重。LinkedListMultimap保持插入顺序但内存开销更大。选型时根据是否需要去重、是否需要顺序来决定。5. 常见问题与排查技巧实录5.1 视图导致的ConcurrentModificationException这是我最常遇到的问题。当你用Maps.transformValues或filterKeys创建视图后如果在遍历视图的同时修改原Map会抛ConcurrentModificationException。因为视图的迭代器是基于原Map的迭代器实现的。MapString, Integer map Maps.newHashMap(); map.put(a, 1); map.put(b, 2); MapString, Integer view Maps.transformValues(map, v - v * 2); // 下面这行会抛异常 for (Map.EntryString, Integer entry : view.entrySet()) { map.put(c, 3); // ConcurrentModificationException }解决办法很简单要么先拷贝一份视图再遍历要么用Iterator的remove方法但视图的迭代器不支持remove。我的经验是如果遍历过程中需要修改直接ImmutableMap.copyOf(view)生成快照然后遍历快照。5.2 null值处理的各种坑Guava的不可变集合不允许null但可变集合允许。Maps.newHashMap()创建的Map可以放null key和null value但ImmutableMap不行。Maps.uniqueIndex如果keyFunction返回null会抛NPE。Maps.transformValues如果转换函数返回null视图的value就是null但如果你之后用ImmutableMap.copyOf包装就会抛NPE。我整理了一个null值处理的速查表方法null keynull value备注Maps.newHashMap允许允许标准HashMap行为ImmutableMap.copyOf不允许不允许抛NPEMaps.uniqueIndex不允许允许key为null抛NPEMaps.transformValues继承原Map允许函数返回null则value为nullMaps.filterValues继承原Map允许predicate需处理null注意如果你的数据源可能有null在构建不可变Map之前一定要做过滤或默认值填充否则线上直接NPE。5.3 性能陷阱视图的size()与containsValue()Maps.filterKeys和filterValues返回的视图size()方法不是O(1)而是O(n)因为它需要遍历所有元素来计数。containsValue()也是O(n)。如果你在循环里反复调用视图的size()性能会急剧下降。我实测过一个案例对一个五万条数据的Map做filterValues然后在循环里调用size()一万次耗时超过两秒。改成先调用一次size()存到变量里耗时降到几毫秒。所以视图的size()一定要缓存不要在循环里反复调用。另外Maps.difference会遍历两个Map的所有key时间复杂度是O(nm)。如果两个Map都很大这个操作会比较重。建议只在必要时调用或者先比较size()做快速判断。5.4 Multimap的size()语义混淆Multimap.size()返回的是所有键值对的总数不是不同key的数量。Multimap.keys().size()才是不同key的数量。这个很容易搞混。比如一个Multimap里user1有三个订单user2有两个订单size()返回5keys().size()返回2。ListMultimapString, Order multimap ArrayListMultimap.create(); multimap.put(user1, order1); multimap.put(user1, order2); multimap.put(user1, order3); multimap.put(user2, order4); multimap.put(user2, order5); multimap.size(); // 5 multimap.keys().size(); // 2这个语义差异在统计报表时特别容易出错。我建议在代码里用keySet().size()来明确表达“不同key的数量”可读性更好。6. 几个实战场景的完整代码拆解6.1 场景一订单按用户分组并统计金额假设有一批订单需要按用户分组计算每个用户的总金额并过滤掉总金额为0的用户。ListOrder orders getOrders(); // 第一步按用户分组 ListMultimapString, Order ordersByUser Multimaps.index(orders, Order::getUserId); // 第二步计算每个用户的总金额 MapString, BigDecimal totalByUser Maps.transformValues( ordersByUser.asMap(), orderList - orderList.stream() .map(Order::getAmount) .reduce(BigDecimal.ZERO, BigDecimal::add) ); // 第三步过滤掉总金额为0的用户 MapString, BigDecimal validTotals Maps.filterValues( totalByUser, total - total.compareTo(BigDecimal.ZERO) 0 ); // 第四步转成不可变Map返回 return ImmutableMap.copyOf(validTotals);这段代码用了Multimaps.index、asMap、transformValues、filterValues、ImmutableMap.copyOf五个Guava特性把原本需要几十行的逻辑压缩到了十几行。注意transformValues的函数里用了Stream做reduce这是Java 8之后的常见写法。6.2 场景二配置差异对比线上环境和测试环境的配置需要对比找出差异项。MapString, String prodConfig loadConfig(prod); MapString, String testConfig loadConfig(test); MapDifferenceString, String diff Maps.difference(prodConfig, testConfig); // 只在生产环境存在的配置 MapString, String onlyInProd diff.entriesOnlyOnLeft(); // 只在测试环境存在的配置 MapString, String onlyInTest diff.entriesOnlyOnRight(); // 两边都有但值不同的配置 MapString, ValueDifferenceString differing diff.entriesDiffering(); for (Map.EntryString, ValueDifferenceString entry : differing.entrySet()) { String key entry.getKey(); String prodValue entry.getValue().leftValue(); String testValue entry.getValue().rightValue(); System.out.println(key : prod prodValue , test testValue); }这个方案比手动遍历两个Map做对比清晰太多了而且MapDifference的API设计得很直观entriesOnlyOnLeft、entriesOnlyOnRight、entriesInCommon、entriesDiffering四个方法覆盖了所有差异类型。6.3 场景三缓存中的默认值Map有时候我们需要一个Map当key不存在时返回一个默认值而不是null。Guava没有直接提供这个功能但可以用Maps.transformValues配合getOrDefault来模拟。MapString, Integer cache Maps.newHashMap(); cache.put(a, 1); cache.put(b, 2); // 包装成带默认值的Map MapString, Integer defaultedCache Maps.transformValues(cache, v - v); // 但这样get不存在的key还是返回null // 更好的方案用Java 8的getOrDefault int value cache.getOrDefault(c, 0);如果你确实需要一个“自动返回默认值”的Map可以考虑用Maps.newHashMap配合自定义的Map实现或者直接用ConcurrentHashMap的computeIfAbsent。Guava本身没有提供这个功能因为Java 8之后标准库已经能很好地处理了。7. 我个人的使用心得与选型建议7.1 什么时候用Guava Maps什么时候用标准库我的原则是标准库能优雅解决的优先用标准库。Java 8之后Map接口新增了getOrDefault、computeIfAbsent、merge、forEach等默认方法很多以前需要Guava的场景现在标准库就够了。比如computeIfAbsent就能替代Guava的Multimap在部分场景下的作用。但Guava Maps在以下场景仍然不可替代需要视图转换transformValues、filterKeys、需要Map的集合运算difference、intersection、需要Multimap做一对多映射、需要uniqueIndex做List转Map。这些功能标准库要么没有要么写起来很啰嗦。7.2 版本兼容性注意事项Guava的版本迭代比较快不同版本之间API有变化。比如Maps.newHashMapWithExpectedSize在早期版本叫Maps.newHashMapWithExpectedSize后来有些方法被标记为Beta再后来有些被废弃。我建议在pom.xml里锁定一个稳定版本不要频繁升级。另外Guava的Beta注解方法不保证向后兼容生产环境慎用。Maps类里大部分方法都是稳定的但Multimaps里有些方法标了Beta用之前最好查一下官方文档。7.3 内存与性能的平衡视图虽然省内存但每次访问都有额外开销。我的经验是如果视图创建后访问次数超过三次直接拷贝成实体Map。拷贝的代价是一次性遍历但后续访问都是O(1)。而视图每次访问都要执行predicate或function累积起来可能更慢。对于MultimapArrayListMultimap是最常用的但如果value需要去重用HashMultimap。如果数据量特别大考虑用LinkedListMultimap或者自己实现更紧凑的结构。我做过一个测试十万条数据下ArrayListMultimap的put操作比手动维护HashMapString, List慢了约10%但代码可读性提升巨大这个 trade-off 是值得的。7.4 一个容易忽略的细节视图的序列化Maps.transformValues返回的视图是不可序列化的。如果你需要把Map通过网络传输或者写入文件必须先ImmutableMap.copyOf或者new HashMap(view)转成实体Map。这个坑我在做分布式缓存时踩过序列化时直接抛NotSerializableException排查了半天才发现是视图的问题。提示任何Guava视图在跨进程传输前都必须转成实体集合。这是硬性要求没有例外。8. 写在最后一些零散但实用的技巧Maps类里还有一些不太常用但关键时刻能救命的方法。比如Maps.asMap(SetK, FunctionK, V)可以把一个Set转成Mapvalue由函数动态计算。这个在做懒加载缓存时很有用key存在就计算value不存在就不算。Maps.toMap(IterableK, FunctionK, V)和uniqueIndex类似但key来自Iterable本身value由函数计算。适合把一组ID转成ID到对象的映射。还有Maps.synchronizedBiMap和Maps.unmodifiableBiMap用于BiMap的包装。BiMap是双向Mapkey和value都能作为索引做ID到名称的双向查找特别方便。但BiMap要求value也唯一如果value重复会抛异常。最后分享一个我常用的组合技Maps.filterKeys加Maps.transformValues加ImmutableMap.copyOf三行代码完成“过滤加转换加不可变化”。这个模式我在做API响应组装时用了无数次稳定可靠。MapString, String result ImmutableMap.copyOf( Maps.transformValues( Maps.filterKeys(sourceMap, key - key.startsWith(public_)), value - value.trim() ) );这段代码的意思是从sourceMap中筛选出以public_开头的key把对应的value去掉首尾空格然后转成不可变Map。整个过程没有创建中间集合代码声明式意图清晰。这就是Guava Maps的魅力所在。 
长河君 · 2026/10/14 1:28:22 · 阅读 1.2k Guava Maps工具类深度解析：视图机制、Multimap与性能优化实战
1. 从一个真实场景说起为什么我要专门写Maps做Java后端开发的朋友大概率都遇到过这样的场景一个接口返回的数据需要按某个字段分组或者需要把两个List拼成一个Map又或者需要统计某个维度下的数量分布。这些操作看起来简单但每次手写都特别啰嗦而且容易写出隐藏的bug。我印象特别深的是有一次做订单数据聚合需要把一批订单按用户ID分组然后统计每个用户的订单总金额。当时项目里已经引入了Guava但我一开始没想起来用Maps工具类硬是用HashMap加循环写了三十多行代码。后来同事看了一眼说你用Maps.transformValues配合Multimap试试结果代码直接缩到了八行而且逻辑清晰得多。这件事之后我开始系统性地梳理Guava中Maps相关的工具方法发现这个类远比我想象的强大。它不仅仅是几个静态方法的集合背后有一套完整的设计哲学用不可变性和视图机制来减少不必要的内存拷贝用工厂方法统一各种Map的创建入口用视图转换让集合操作变得声明式。这篇内容我会把Maps这个工具类拆开揉碎从设计思路到核心方法从实操代码到踩坑经验全部过一遍。适合已经会用Java集合框架、但还没深入用过Guava的开发者也适合想系统整理自己工具箱的老手。读完你至少能掌握怎么用Maps创建各种特殊Map、怎么用视图做零拷贝转换、怎么用Multimap解决一对多映射、以及那些文档里不会写的性能陷阱。2. Maps工具类的整体设计思路拆解2.1 为什么Guava要单独造一个Maps工具类Java标准库里有Collections工具类提供了unmodifiableMap、synchronizedMap、emptyMap这些方法。但实际开发中你会发现这些方法远远不够用。比如你需要一个Map当key不存在时自动返回默认值标准库没有你需要一个Mapkey和value都能有多个标准库也没有你需要把Map的value批量转换类型标准库还是没有。Guava的Maps类就是来填这些坑的。它的设计目标很明确把开发者从重复的Map操作样板代码中解放出来。我统计过自己项目里最常用的几个方法newHashMap、newHashMapWithExpectedSize、transformValues、filterKeys、difference、uniqueIndex这几个几乎覆盖了日常80%的Map操作需求。从源码结构看Maps类里的方法大致分四类工厂方法创建各种Map实例、视图方法返回原Map的视图不拷贝数据、转换方法对key或value做函数映射、以及工具方法差集、交集、唯一索引等。这个分类方式本身就值得学习它反映了Guava团队对Map操作场景的抽象思路。2.2 视图机制Guava Maps最核心的设计如果你只记住一个概念那就是视图View。Maps里大量方法返回的不是新的Map而是原Map的一个视图。什么意思比如Maps.filterKeys(map, predicate)返回的Map当你调用get时它会先检查key是否满足predicate满足才去原Map取值。它没有复制任何数据只是包了一层逻辑。这个设计的好处是内存零开销创建视图几乎是瞬间完成的。但代价是每次访问都要多一层判断如果predicate本身很复杂高频访问时性能会下降。我实测过一个场景对一个十万条数据的Map做filterKeys创建视图耗时不到1毫秒但遍历视图比遍历原Map慢了大约15%到20%。所以视图适合“创建一次、访问次数不多”的场景如果后续要反复遍历不如直接拷贝一份过滤后的Map。另一个要注意的是视图的双向绑定特性。Maps.filterKeys返回的视图如果你往里面put一个不满足条件的key会直接抛IllegalArgumentException。而如果你修改原Map视图会同步反映变化。这个特性有时候很有用比如做权限过滤时原Map更新了视图自动跟着变。但有时候也会让人困惑比如你明明没动视图怎么数据变了。理解这一点能避免很多“见鬼了”的时刻。2.3 不可变集合与可变集合的边界Guava对不可变集合的支持非常彻底ImmutableMap就是典型代表。Maps类里也有Maps.uniqueIndex返回不可变Map的方法。不可变的好处不用多说线程安全、可以放心共享、不会被意外修改。但实际用的时候要注意ImmutableMap不允许null的key和value如果你从数据库查出来的数据可能有null直接构建会抛NPE。我的经验是对外暴露的API返回值尽量用不可变Map内部流转的数据用可变Map。这样既保证了接口的安全性又不会在内部频繁创建新对象。Maps.newHashMap和ImmutableMap.copyOf配合使用基本能覆盖大部分场景。3. 核心方法逐个击破与实操要点3.1 创建MapnewHashMap系列与容量预估Maps.newHashMap()是最基础的工厂方法等价于new HashMap()但写起来更简洁而且支持泛型推断。不过我更常用的是Maps.newHashMapWithExpectedSize(int expectedSize)这个方法能帮你预设合适的初始容量避免频繁扩容。这里有个计算细节值得说清楚。HashMap的扩容阈值是容量乘以负载因子默认0.75当元素数量超过阈值时扩容。如果你预估要放100个元素直接new HashMap(100)其实不够因为100乘以0.75等于75放到第76个元素时就会扩容。正确的做法是传入expectedSize / 0.75 1Guava的newHashMapWithExpectedSize内部就是这么算的。我实测过预估100个元素时用这个方法比默认构造少了两次扩容插入耗时减少约30%。// 不推荐可能触发扩容 MapString, Order map1 new HashMap(100); // 推荐Guava自动计算合适容量 MapString, Order map2 Maps.newHashMapWithExpectedSize(100);另外Maps.newLinkedHashMap()也值得关注它保持插入顺序做配置加载或者需要按顺序输出的场景特别有用。Maps.newTreeMap()则适合需要按key排序的场景。这几个工厂方法统一了创建入口代码风格更一致。3.2 transformValues与transformEntries声明式转换Maps.transformValues(MapK, V1, FunctionV1, V2)返回一个视图把原Map的每个value用函数转换后呈现。比如你有一个MapString, Integer存的是用户ID到年龄的映射想转成MapString, String显示“XX岁”一行代码就够了。MapString, Integer ageMap Maps.newHashMap(); ageMap.put(user1, 25); ageMap.put(user2, 30); MapString, String displayMap Maps.transformValues(ageMap, age - age 岁); // displayMap.get(user1) 返回 25岁注意这是视图原Map的value变了视图跟着变。如果你需要快照得用ImmutableMap.copyOf(Maps.transformValues(...))。transformEntries更灵活它的函数接收key和value两个参数可以同时基于key和value做转换。比如拼一个“key:value”的字符串。这两个方法在数据展示层特别有用能把领域模型转成前端需要的格式而且不用创建中间集合。3.3 filterKeys与filterValues条件过滤的利器Maps.filterKeys(MapK, V, PredicateK)和Maps.filterValues(MapK, V, PredicateV)返回过滤后的视图。我经常用filterValues来过滤掉value为null或者空字符串的条目。MapString, String config Maps.newHashMap(); config.put(name, test); config.put(empty, ); config.put(nullValue, null); MapString, String validConfig Maps.filterValues(config, value - value ! null !value.isEmpty()); // validConfig 只包含 name 这一项这里有个坑filterValues的predicate如果返回false视图的size()方法会遍历所有元素来计数不是O(1)操作。如果你只是想知道过滤后有多少条直接遍历原Map计数可能更快。另外视图的entrySet()返回的Entry调用setValue会抛异常因为过滤后的Entry不允许修改value。3.4 difference与intersectionMap的集合运算Maps.difference(MapK, V left, MapK, V right)返回一个MapDifference对象能告诉你两个Map之间哪些key只在左边、哪些只在右边、哪些两边都有但value不同、哪些完全相同。这个在做配置对比、数据同步校验时特别好用。MapString, String left Maps.newHashMap(); left.put(a, 1); left.put(b, 2); MapString, String right Maps.newHashMap(); right.put(b, 2); right.put(c, 3); MapDifferenceString, String diff Maps.difference(left, right); diff.entriesOnlyOnLeft(); // {a1} diff.entriesOnlyOnRight(); // {c3} diff.entriesInCommon(); // {b2} diff.entriesDiffering(); // {}entriesDiffering()返回的是MapString, ValueDifferenceString每个ValueDifference能拿到左右两边的值。这个在做数据审计时非常实用能精确知道哪个字段被改了。3.5 uniqueIndexList转Map的优雅方案Maps.uniqueIndex(IterableV values, FunctionV, K keyFunction)把一组对象按某个字段转成Map。比如你有一个用户列表想按用户ID索引一行代码搞定。ListUser users getUserList(); MapString, User userMap Maps.uniqueIndex(users, User::getId);但这里有个关键限制key必须唯一。如果两个用户的ID相同会直接抛IllegalArgumentException。这个设计是合理的因为Map的key本来就不能重复与其静默覆盖不如直接报错。如果你确实需要处理重复key应该用Multimap或者自己写循环做合并。我踩过的一个坑是从数据库查出来的数据因为关联查询产生了重复行用uniqueIndex直接崩了。后来改成先distinct再去重或者用Multimaps.index返回ListMultimap问题才解决。所以用这个方法前一定要确认key的唯一性。4. Multimap解决一对多映射的终极方案4.1 为什么需要Multimap标准Java的Map是key到单个value的映射。但现实中一对多的场景太多了一个用户有多个订单、一个班级有多个学生、一个标签对应多篇文章。用MapString, ListOrder当然可以但每次put都要判断List是否存在代码又臭又长。// 传统写法 MapString, ListOrder userOrders new HashMap(); for (Order order : orders) { ListOrder list userOrders.get(order.getUserId()); if (list null) { list new ArrayList(); userOrders.put(order.getUserId(), list); } list.add(order); }Guava的Multimap就是来终结这种写法的。ArrayListMultimap的put方法自动处理List的创建和追加代码变成一行。// Multimap写法 ListMultimapString, Order userOrders ArrayListMultimap.create(); for (Order order : orders) { userOrders.put(order.getUserId(), order); }4.2 Multimap的核心API与使用场景Multimap接口有几个关键方法put(K, V)添加映射、get(K)返回value集合、size()返回所有键值对总数、keys().size()返回不同key的数量、asMap()转成MapK, CollectionV视图。我特别想说的是asMap()方法。它返回的Mapvalue是原Multimap中对应key的集合视图。你往这个视图的集合里加元素原Multimap会同步变化。这个在做分组统计时特别方便比如先按用户分组然后对每个用户的订单列表做排序。Multimaps.index(IterableV, FunctionV, K)是另一个高频方法它把一组对象按某个字段分组返回ImmutableListMultimap。和Maps.uniqueIndex的区别是它允许key重复重复的value会聚合成List。ListOrder orders getOrders(); ImmutableListMultimapString, Order ordersByUser Multimaps.index(orders, Order::getUserId); // ordersByUser.get(user1) 返回该用户的所有订单4.3 Multimap的视图与性能考量Multimap的get(K)方法返回的是一个视图集合不是拷贝。如果你往这个集合里add元素会直接修改原Multimap。这个特性有时候会带来意外比如你只是想读一下数据结果不小心改了原数据。我的习惯是如果只是读取用ImmutableList.copyOf(multimap.get(key))包一层确保安全。性能方面ArrayListMultimap底层是HashMapK, ArrayListV适合大多数场景。HashMultimap底层是HashMapK, HashSetV自动去重。LinkedListMultimap保持插入顺序但内存开销更大。选型时根据是否需要去重、是否需要顺序来决定。5. 常见问题与排查技巧实录5.1 视图导致的ConcurrentModificationException这是我最常遇到的问题。当你用Maps.transformValues或filterKeys创建视图后如果在遍历视图的同时修改原Map会抛ConcurrentModificationException。因为视图的迭代器是基于原Map的迭代器实现的。MapString, Integer map Maps.newHashMap(); map.put(a, 1); map.put(b, 2); MapString, Integer view Maps.transformValues(map, v - v * 2); // 下面这行会抛异常 for (Map.EntryString, Integer entry : view.entrySet()) { map.put(c, 3); // ConcurrentModificationException }解决办法很简单要么先拷贝一份视图再遍历要么用Iterator的remove方法但视图的迭代器不支持remove。我的经验是如果遍历过程中需要修改直接ImmutableMap.copyOf(view)生成快照然后遍历快照。5.2 null值处理的各种坑Guava的不可变集合不允许null但可变集合允许。Maps.newHashMap()创建的Map可以放null key和null value但ImmutableMap不行。Maps.uniqueIndex如果keyFunction返回null会抛NPE。Maps.transformValues如果转换函数返回null视图的value就是null但如果你之后用ImmutableMap.copyOf包装就会抛NPE。我整理了一个null值处理的速查表方法null keynull value备注Maps.newHashMap允许允许标准HashMap行为ImmutableMap.copyOf不允许不允许抛NPEMaps.uniqueIndex不允许允许key为null抛NPEMaps.transformValues继承原Map允许函数返回null则value为nullMaps.filterValues继承原Map允许predicate需处理null注意如果你的数据源可能有null在构建不可变Map之前一定要做过滤或默认值填充否则线上直接NPE。5.3 性能陷阱视图的size()与containsValue()Maps.filterKeys和filterValues返回的视图size()方法不是O(1)而是O(n)因为它需要遍历所有元素来计数。containsValue()也是O(n)。如果你在循环里反复调用视图的size()性能会急剧下降。我实测过一个案例对一个五万条数据的Map做filterValues然后在循环里调用size()一万次耗时超过两秒。改成先调用一次size()存到变量里耗时降到几毫秒。所以视图的size()一定要缓存不要在循环里反复调用。另外Maps.difference会遍历两个Map的所有key时间复杂度是O(nm)。如果两个Map都很大这个操作会比较重。建议只在必要时调用或者先比较size()做快速判断。5.4 Multimap的size()语义混淆Multimap.size()返回的是所有键值对的总数不是不同key的数量。Multimap.keys().size()才是不同key的数量。这个很容易搞混。比如一个Multimap里user1有三个订单user2有两个订单size()返回5keys().size()返回2。ListMultimapString, Order multimap ArrayListMultimap.create(); multimap.put(user1, order1); multimap.put(user1, order2); multimap.put(user1, order3); multimap.put(user2, order4); multimap.put(user2, order5); multimap.size(); // 5 multimap.keys().size(); // 2这个语义差异在统计报表时特别容易出错。我建议在代码里用keySet().size()来明确表达“不同key的数量”可读性更好。6. 几个实战场景的完整代码拆解6.1 场景一订单按用户分组并统计金额假设有一批订单需要按用户分组计算每个用户的总金额并过滤掉总金额为0的用户。ListOrder orders getOrders(); // 第一步按用户分组 ListMultimapString, Order ordersByUser Multimaps.index(orders, Order::getUserId); // 第二步计算每个用户的总金额 MapString, BigDecimal totalByUser Maps.transformValues( ordersByUser.asMap(), orderList - orderList.stream() .map(Order::getAmount) .reduce(BigDecimal.ZERO, BigDecimal::add) ); // 第三步过滤掉总金额为0的用户 MapString, BigDecimal validTotals Maps.filterValues( totalByUser, total - total.compareTo(BigDecimal.ZERO) 0 ); // 第四步转成不可变Map返回 return ImmutableMap.copyOf(validTotals);这段代码用了Multimaps.index、asMap、transformValues、filterValues、ImmutableMap.copyOf五个Guava特性把原本需要几十行的逻辑压缩到了十几行。注意transformValues的函数里用了Stream做reduce这是Java 8之后的常见写法。6.2 场景二配置差异对比线上环境和测试环境的配置需要对比找出差异项。MapString, String prodConfig loadConfig(prod); MapString, String testConfig loadConfig(test); MapDifferenceString, String diff Maps.difference(prodConfig, testConfig); // 只在生产环境存在的配置 MapString, String onlyInProd diff.entriesOnlyOnLeft(); // 只在测试环境存在的配置 MapString, String onlyInTest diff.entriesOnlyOnRight(); // 两边都有但值不同的配置 MapString, ValueDifferenceString differing diff.entriesDiffering(); for (Map.EntryString, ValueDifferenceString entry : differing.entrySet()) { String key entry.getKey(); String prodValue entry.getValue().leftValue(); String testValue entry.getValue().rightValue(); System.out.println(key : prod prodValue , test testValue); }这个方案比手动遍历两个Map做对比清晰太多了而且MapDifference的API设计得很直观entriesOnlyOnLeft、entriesOnlyOnRight、entriesInCommon、entriesDiffering四个方法覆盖了所有差异类型。6.3 场景三缓存中的默认值Map有时候我们需要一个Map当key不存在时返回一个默认值而不是null。Guava没有直接提供这个功能但可以用Maps.transformValues配合getOrDefault来模拟。MapString, Integer cache Maps.newHashMap(); cache.put(a, 1); cache.put(b, 2); // 包装成带默认值的Map MapString, Integer defaultedCache Maps.transformValues(cache, v - v); // 但这样get不存在的key还是返回null // 更好的方案用Java 8的getOrDefault int value cache.getOrDefault(c, 0);如果你确实需要一个“自动返回默认值”的Map可以考虑用Maps.newHashMap配合自定义的Map实现或者直接用ConcurrentHashMap的computeIfAbsent。Guava本身没有提供这个功能因为Java 8之后标准库已经能很好地处理了。7. 我个人的使用心得与选型建议7.1 什么时候用Guava Maps什么时候用标准库我的原则是标准库能优雅解决的优先用标准库。Java 8之后Map接口新增了getOrDefault、computeIfAbsent、merge、forEach等默认方法很多以前需要Guava的场景现在标准库就够了。比如computeIfAbsent就能替代Guava的Multimap在部分场景下的作用。但Guava Maps在以下场景仍然不可替代需要视图转换transformValues、filterKeys、需要Map的集合运算difference、intersection、需要Multimap做一对多映射、需要uniqueIndex做List转Map。这些功能标准库要么没有要么写起来很啰嗦。7.2 版本兼容性注意事项Guava的版本迭代比较快不同版本之间API有变化。比如Maps.newHashMapWithExpectedSize在早期版本叫Maps.newHashMapWithExpectedSize后来有些方法被标记为Beta再后来有些被废弃。我建议在pom.xml里锁定一个稳定版本不要频繁升级。另外Guava的Beta注解方法不保证向后兼容生产环境慎用。Maps类里大部分方法都是稳定的但Multimaps里有些方法标了Beta用之前最好查一下官方文档。7.3 内存与性能的平衡视图虽然省内存但每次访问都有额外开销。我的经验是如果视图创建后访问次数超过三次直接拷贝成实体Map。拷贝的代价是一次性遍历但后续访问都是O(1)。而视图每次访问都要执行predicate或function累积起来可能更慢。对于MultimapArrayListMultimap是最常用的但如果value需要去重用HashMultimap。如果数据量特别大考虑用LinkedListMultimap或者自己实现更紧凑的结构。我做过一个测试十万条数据下ArrayListMultimap的put操作比手动维护HashMapString, List慢了约10%但代码可读性提升巨大这个 trade-off 是值得的。7.4 一个容易忽略的细节视图的序列化Maps.transformValues返回的视图是不可序列化的。如果你需要把Map通过网络传输或者写入文件必须先ImmutableMap.copyOf或者new HashMap(view)转成实体Map。这个坑我在做分布式缓存时踩过序列化时直接抛NotSerializableException排查了半天才发现是视图的问题。提示任何Guava视图在跨进程传输前都必须转成实体集合。这是硬性要求没有例外。8. 写在最后一些零散但实用的技巧Maps类里还有一些不太常用但关键时刻能救命的方法。比如Maps.asMap(SetK, FunctionK, V)可以把一个Set转成Mapvalue由函数动态计算。这个在做懒加载缓存时很有用key存在就计算value不存在就不算。Maps.toMap(IterableK, FunctionK, V)和uniqueIndex类似但key来自Iterable本身value由函数计算。适合把一组ID转成ID到对象的映射。还有Maps.synchronizedBiMap和Maps.unmodifiableBiMap用于BiMap的包装。BiMap是双向Mapkey和value都能作为索引做ID到名称的双向查找特别方便。但BiMap要求value也唯一如果value重复会抛异常。最后分享一个我常用的组合技Maps.filterKeys加Maps.transformValues加ImmutableMap.copyOf三行代码完成“过滤加转换加不可变化”。这个模式我在做API响应组装时用了无数次稳定可靠。MapString, String result ImmutableMap.copyOf( Maps.transformValues( Maps.filterKeys(sourceMap, key - key.startsWith(public_)), value - value.trim() ) );这段代码的意思是从sourceMap中筛选出以public_开头的key把对应的value去掉首尾空格然后转成不可变Map。整个过程没有创建中间集合代码声明式意图清晰。这就是Guava Maps的魅力所在。