Guava 深度解析：Google 的 Java 核心库为何仍是工程标配

<groupId>com.google.guava</groupId>
<artifactId>guava-parent</artifactId>
<version>999.0.0-HEAD-jre-SNAPSHOT</version>
<packaging>pom</packaging>
<inceptionYear>2010</inceptionYear>
<modules>
  <module>guava</module>
  <module>guava-bom</module>
  <module>guava-gwt</module>
  <module>guava-testlib</module>
  <module>guava-tests</module>
</modules>

<gummy-bears-api-24-version>0.15.0</gummy-bears-api-24-version>
<animal-sniffer-maven-plugin.version>1.27</animal-sniffer-maven-plugin.version>

// JDK 方式：只是一个"只读视图"，底层 list 变了它也跟着变
List<String> backing = new ArrayList<>(List.of("a", "b"));
List<String> view = Collections.unmodifiableList(backing);
backing.add("c");
System.out.println(view); // [a, b, c] —— 被"篡改"了！

// Guava 方式：真正的拷贝 + 结构不可变
ImmutableList<String> safe = ImmutableList.copyOf(backing);
backing.add("d");
System.out.println(safe); // [a, b, c] —— 纹丝不动

// 1. 字面量，元素数量已知且不多
ImmutableSet<String> STATUSES = ImmutableSet.of("INIT", "RUNNING", "DONE");

// 2. Builder，元素来自循环/条件分支
ImmutableMap.Builder<String, Integer> builder = ImmutableMap.builder();
for (Item item : items) {
    if (item.valid()) builder.put(item.key(), item.weight());
}
ImmutableMap<String, Integer> weights = builder.buildOrThrow();  // 重复 key 直接抛异常

// 3. Stream Collector
ImmutableList<String> names = users.stream()
    .map(User::name)
    .collect(ImmutableList.toImmutableList());

// 手写版：每次 put 都要判空初始化
Map<String, List<Order>> byUser = new HashMap<>();
byUser.computeIfAbsent(uid, k -> new ArrayList<>()).add(order);

// Guava 版
ListMultimap<String, Order> byUser = ArrayListMultimap.create();
byUser.put(uid, order);                    // 自动建 list
List<Order> orders = byUser.get(uid);      // 不存在返回空 list，而非 null
Map<String, Collection<Order>> asMap = byUser.asMap();  // 需要时再转回去

Multiset<String> wordCount = HashMultiset.create();
for (String w : words) {
    wordCount.add(w);                 // 无需 getOrDefault(w, 0) + 1
}
int n = wordCount.count("guava");     // 不存在返回 0
// 按频次降序
for (Multiset.Entry<String> e : Multisets.copyHighestCountFirst(wordCount).entrySet()) {
    System.out.println(e.getElement() + " -> " + e.getCount());
}

// 双向映射，强制 value 唯一
BiMap<String, Integer> codes = HashBiMap.create();
codes.put("CN", 86);
String country = codes.inverse().get(86);   // "CN"

// 二维表，替代 Map<R, Map<C, V>>
Table<String, String, Double> priceTable = HashBasedTable.create();
priceTable.put("SKU-1", "CN", 99.0);
priceTable.put("SKU-1", "US", 15.9);
Map<String, Double> skuRow = priceTable.row("SKU-1");     // 按行取
Map<String, Double> cnColumn = priceTable.column("CN");   // 按列取

LoadingCache<Long, UserProfile> cache = CacheBuilder.newBuilder()
    .maximumSize(10_000)                              // 容量维度：LRU 近似淘汰
    .expireAfterWrite(Duration.ofMinutes(10))         // 写后过期：保证数据新鲜度
    .refreshAfterWrite(Duration.ofMinutes(1))         // 写后刷新：异步续期，避免击穿
    .concurrencyLevel(8)                              // 并发维度：分段锁数量
    .recordStats()                                    // 可观测性
    .build(new CacheLoader<Long, UserProfile>() {
        @Override
        public UserProfile load(Long uid) {
            return userDao.findById(uid);
        }
        @Override
        public ListenableFuture<UserProfile> reload(Long uid, UserProfile old) {
            return executor.submit(() -> userDao.findById(uid));  // 异步 reload
        }
    });

UserProfile p = cache.getUnchecked(uid);
System.out.println(cache.stats().hitRate());

ListeningExecutorService pool =
    MoreExecutors.listeningDecorator(Executors.newFixedThreadPool(8));

ListenableFuture<byte[]> raw = pool.submit(() -> fetchRemote(url));

// transform：同步映射
ListenableFuture<Doc> doc = Futures.transform(raw, Doc::parse, pool);

// transformAsync：返回 Future 的链式调用，避免 Future<Future<T>>
ListenableFuture<Result> result =
    Futures.transformAsync(doc, d -> pool.submit(() -> index(d)), pool);

// 聚合多个
ListenableFuture<List<Result>> all = Futures.allAsList(f1, f2, f3);

Futures.addCallback(result, new FutureCallback<Result>() {
    @Override public void onSuccess(Result r) { log.info("ok {}", r); }
    @Override public void onFailure(Throwable t) { log.error("fail", t); }
}, pool);

MutableGraph<String> deps = GraphBuilder.directed()
    .allowsSelfLoops(false)
    .expectedNodeCount(100)
    .build();

deps.putEdge("service-api", "service-core");
deps.putEdge("service-web", "service-api");

Set<String> downstream = deps.successors("service-api");   // 我依赖谁
Set<String> upstream   = deps.predecessors("service-api"); // 谁依赖我
boolean reachable = Graphs.reachableNodes(deps, "service-web").contains("service-core");
boolean hasCycle  = Graphs.hasCycle(deps);

HashFunction hf = Hashing.murmur3_128();
HashCode code = hf.newHasher()
    .putLong(userId)
    .putString(email, StandardCharsets.UTF_8)
    .putBoolean(isVip)
    .hash();

// 一致性哈希：节点数变化时最小化重映射
int bucket = Hashing.consistentHash(code, shardCount);

// 布隆过滤器：亿级去重，内存换准确率
BloomFilter<CharSequence> filter =
    BloomFilter.create(Funnels.stringFunnel(UTF_8), 10_000_000, 0.001);
filter.put(url);
if (filter.mightContain(candidate)) { /* 可能存在，需回源确认 */ }

// Splitter：行为完全可控，不像 String.split 有正则和尾部空串的怪癖
List<String> parts = Splitter.on(',')
    .trimResults()
    .omitEmptyStrings()
    .limit(3)
    .splitToList("a, b, , c, d");   // [a, b, c, d] 前三段

// Joiner
String s = Joiner.on(" | ").skipNulls().join(list);
String kv = Joiner.on('&').withKeyValueSeparator('=').join(paramMap);

// CharMatcher：字符集合的函数式操作
String digits = CharMatcher.inRange('0', '9').retainFrom(input);
String clean  = CharMatcher.whitespace().collapseFrom(raw, ' ');

// 原语工具：避免 int[] ↔ Integer[] 装箱
int max = Ints.max(array);
List<Integer> view = Ints.asList(array);   // 视图，零拷贝

<dependency>
  <groupId>com.google.guava</groupId>
  <artifactId>guava</artifactId>
  <version>33.6.0-jre</version>
  <!-- Android 项目改为: <version>33.6.0-android</version> -->
</dependency>

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.guava</groupId>
      <artifactId>guava-bom</artifactId>
      <version>33.6.0-jre</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

dependencies {
  // 1. 仅在实现中使用 Guava
  implementation("com.google.guava:guava:33.6.0-jre")

  // 2. 公开 API 中出现 Guava 类型
  api("com.google.guava:guava:33.6.0-jre")

  // 3. Android - 仅实现中使用
  implementation("com.google.guava:guava:33.6.0-android")

  // 4. Android - 公开 API 中使用
  api("com.google.guava:guava:33.6.0-android")
}

<version>999.0.0-HEAD-jre-SNAPSHOT</version>
<!-- Android: 999.0.0-HEAD-android-SNAPSHOT -->

import com.google.common.base.Joiner;
import com.google.common.base.Splitter;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.HashMultiset;
import com.google.common.collect.Multiset;

public class GuavaHello {
    public static void main(String[] args) {
        ImmutableList<String> langs = ImmutableList.of("Java", "Go", "Rust", "Java");

        Multiset<String> counter = HashMultiset.create(langs);
        System.out.println("Java 出现次数: " + counter.count("Java"));   // 2

        System.out.println(Joiner.on(" / ").join(langs));                // Java / Go / Rust / Java

        System.out.println(Splitter.on('/')
            .trimResults()
            .omitEmptyStrings()
            .splitToList("a / b // c"));                                  // [a, b, c]
    }
}

import static com.google.common.base.Preconditions.*;

public Order createOrder(String userId, int quantity, BigDecimal price) {
    checkNotNull(userId, "userId 不能为空");
    checkArgument(quantity > 0, "quantity 必须为正数，实际为 %s", quantity);
    checkArgument(price.signum() > 0, "price 必须为正数");
    checkState(inventory.isReady(), "库存服务尚未初始化");
    // ...
}

public class SalesAggregator {

    private final Table<String, String, BigDecimal> gmv = HashBasedTable.create();
    private final ListMultimap<String, Order> byCity = ArrayListMultimap.create();

    public void accept(Order o) {
        byCity.put(o.city(), o);
        BigDecimal cur = gmv.get(o.city(), o.category());
        gmv.put(o.city(), o.category(), cur == null ? o.amount() : cur.add(o.amount()));
    }

    /** 某城市各品类 GMV */
    public Map<String, BigDecimal> cityBreakdown(String city) {
        return ImmutableMap.copyOf(gmv.row(city));
    }

    /** 某品类在全国各城市的分布（Table 的列视图，嵌套 Map 做不到的能力） */
    public Map<String, BigDecimal> categoryAcrossCities(String category) {
        return ImmutableMap.copyOf(gmv.column(category));
    }

    /** Top N 城市 */
    public List<String> topCities(int n) {
        return byCity.keySet().stream()
            .sorted(Comparator.comparing(
                (String c) -> gmv.row(c).values().stream()
                    .reduce(BigDecimal.ZERO, BigDecimal::add)).reversed())
            .limit(n)
            .collect(ImmutableList.toImmutableList());
    }
}

public class RemoteProfileService {

    private final RateLimiter limiter = RateLimiter.create(200.0);  // QPS 上限 200
    private final ListeningExecutorService pool =
        MoreExecutors.listeningDecorator(Executors.newFixedThreadPool(16));

    private final LoadingCache<Long, Profile> cache = CacheBuilder.newBuilder()
        .maximumSize(50_000)
        .expireAfterWrite(Duration.ofMinutes(30))
        .refreshAfterWrite(Duration.ofMinutes(5))
        .recordStats()
        .build(new CacheLoader<Long, Profile>() {
            @Override public Profile load(Long id) {
                limiter.acquire();               // 回源前限流，保护下游
                return httpClient.getProfile(id);
            }
            @Override public ListenableFuture<Profile> reload(Long id, Profile old) {
                return pool.submit(() -> {
                    limiter.acquire();
                    return httpClient.getProfile(id);
                });
            }
        });

    public Profile get(long id) {
        return cache.getUnchecked(id);
    }

    public ListenableFuture<List<Profile>> batchAsync(Collection<Long> ids) {
        List<ListenableFuture<Profile>> futures = ids.stream()
            .map(id -> pool.<Profile>submit(() -> get(id)))
            .collect(ImmutableList.toImmutableList());
        return Futures.successfulAsList(futures);   // 部分失败不整体失败，失败项为 null
    }

    public CacheStats stats() {
        return cache.stats();
    }
}

public class DependencyChecker {

    public static Optional<String> check(Map<String, List<String>> declared) {
        MutableGraph<String> graph = GraphBuilder.directed()
            .allowsSelfLoops(true)
            .build();

        declared.forEach((svc, deps) -> {
            graph.addNode(svc);
            deps.forEach(d -> graph.putEdge(svc, d));
        });

        if (Graphs.hasCycle(graph)) {
            return Optional.of("检测到循环依赖，涉及节点: " + findCycleNodes(graph));
        }
        return Optional.empty();
    }

    /** 反复剥离出度为 0 的节点（Kahn 算法逆向），剩下的即环上节点 */
    private static Set<String> findCycleNodes(Graph<String> g) {
        MutableGraph<String> copy = Graphs.copyOf(g);
        boolean changed = true;
        while (changed) {
            changed = false;
            for (String n : ImmutableList.copyOf(copy.nodes())) {
                if (copy.successors(n).isEmpty()) {
                    copy.removeNode(n);
                    changed = true;
                }
            }
        }
        return ImmutableSet.copyOf(copy.nodes());
    }
}

public class UrlDeduper {

    // 1 亿 URL，1‰ 误判率，约占 170MB 内存（对比 HashSet 存原串需数 GB）
    private final BloomFilter<CharSequence> seen =
        BloomFilter.create(Funnels.stringFunnel(StandardCharsets.UTF_8),
                           100_000_000L, 0.001);

    private final Set<String> confirmSet = ConcurrentHashMap.newKeySet();

    public boolean shouldCrawl(String url) {
        String norm = normalize(url);
        if (!seen.mightContain(norm)) {
            seen.put(norm);        // 一定没见过，直接放行
            return true;
        }
        // 可能见过：走精确集合二次确认，消除误判
        return confirmSet.add(norm);
    }

    private String normalize(String url) {
        return CharMatcher.whitespace().trimFrom(url).toLowerCase(Locale.ROOT);
    }
}

# Maven：查看依赖树
mvn dependency:tree -Dincludes=com.google.guava:guava

# Gradle
./gradlew :app:dependencyInsight --dependency guava

<!-- 1. 用 BOM 或 dependencyManagement 强制统一版本（首选） -->
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.guava</groupId>
      <artifactId>guava</artifactId>
      <version>33.6.0-jre</version>
    </dependency>
  </dependencies>
</dependencyManagement>

<!-- 2. 排除传递依赖 -->
<dependency>
  <groupId>org.apache.hadoop</groupId>
  <artifactId>hadoop-common</artifactId>
  <exclusions>
    <exclusion>
      <groupId>com.google.guava</groupId>
      <artifactId>guava</artifactId>
    </exclusion>
  </exclusions>
</dependency>

<dependency>
  <groupId>com.google.guava</groupId>
  <artifactId>failureaccess</artifactId>
  <version>1.0.3</version>
</dependency>

<plugin>
  <artifactId>maven-compiler-plugin</artifactId>
  <configuration>
    <compilerArgs>
      <arg>-Xplugin:ErrorProne -Xep:BetaApi:ERROR</arg>
    </compilerArgs>
  </configuration>
</plugin>

implementation("com.google.guava:guava:33.6.0-android")

android {
    buildTypes {
        release {
            minifyEnabled true
            shrinkResources true
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
        }
    }
}

// 方案 1：定时主动清理
scheduler.scheduleAtFixedRate(cache::cleanUp, 1, 1, TimeUnit.MINUTES);

// 方案 2：加容量上限兜底（强烈建议永远配置）
CacheBuilder.newBuilder()
    .maximumSize(10_000)
    // 或按权重计算，适合 value 大小差异大的场景
    .maximumWeight(100_000_000)
    .weigher((String k, byte[] v) -> v.length)
    .build(loader);

// 方案 3：软引用（不推荐，GC 行为不可预测，可能引发长 STW）
CacheBuilder.newBuilder().softValues().build(loader);

// 1. load 内部设置严格超时
@Override public Profile load(Long id) {
    return httpClient.getProfile(id, Duration.ofMillis(300));
}

// 2. 用 refreshAfterWrite 让续期走异步，读请求永不阻塞
.refreshAfterWrite(Duration.ofMinutes(1))
.expireAfterWrite(Duration.ofMinutes(10))

// 3. 预热关键 key，避免冷启动雪崩
hotIds.forEach(id -> cache.refresh(id));

// ❌ 危险
redis.set(key, SerializationUtils.serialize(immutableMap));

// ✅ 安全
redis.set(key, gson.toJson(new LinkedHashMap<>(immutableMap)));