Guava

Guava 概述

Guava 是 Google 提供的一套核心 Java 工具库，涵盖了新型集合类型（例如 multimap、multiset）、不可变集合、图数据结构库，以及并发、I/O、哈希、原生类型、字符串处理等方面的实用工具。该库在 Google 内部的绝大部分 Java 项目中被广泛使用，同时也是众多公司构建 Java 应用时的首选依赖。

运行时环境

Guava 提供两种发行版本：

• JRE 版本：要求 JDK 1.8 或更高。
• Android 版本：如果项目需要兼容 Android，请使用该版本。其源码托管在项目的 android 目录下。

添加依赖

Maven 的 group ID 为 com.google.guava，artifact ID 为 guava。版本号通过后缀区分运行环境：33.6.0-jre 对应 JRE 版本，33.6.0-android 对应 Android 版本。

Maven 配置

<dependency>
  <groupId>com.google.guava</groupId>
  <artifactId>guava</artifactId>
  <!-- 二选一 -->
  <version>33.6.0-jre</version>
  <!-- 或 <version>33.6.0-android</version> -->
</dependency>

Gradle 配置

dependencies {
  // 根据使用场景选取：

  // 1. 仅在自身实现中使用 Guava（JRE）
  implementation("com.google.guava:guava:33.6.0-jre")

  // 2. 在公开 API 中暴露 Guava 类型（JRE）
  api("com.google.guava:guava:33.6.0-jre")

  // 3. 仅在自身实现中使用 Guava（Android）
  implementation("com.google.guava:guava:33.6.0-android")

  // 4. 在公开 API 中暴露 Guava 类型（Android）
  api("com.google.guava:guava:33.6.0-android")
}

如果项目同时作为库被其他模块引用，那么对于在公开 API 中暴露的类型应使用 api 配置；否则使用 implementation 即可。

快照版本与文档

基于 master 分支构建的快照可通过 Maven 获取，版本号为：

• 999.0.0-HEAD-jre-SNAPSHOT（JRE 版本）
• 999.0.0-HEAD-android-SNAPSHOT（Android 版本）

快照 API 的 Javadoc 与差异对比同样可在线查阅。访问 https://guava.dev/api 可直达最新文档，附加具体类名（如 guava.dev/ImmutableList）则可直接跳转到对应类的页面。

学习资源

• 用户指南：GitHub Wiki 中的《Guava Explained》
• 第三方维护的链接汇总，包含演示文稿与教程

重要提示

1. @Beta 注解的 API：以 @Beta 标记的类或方法随时可能变更甚至删除。若本项目是供他人引用的库，不应直接暴露 beta API，应通过重新打包（shading/repackaging）来隔离，或使用 Guava Beta Checker 工具进行静态检查，避免误用。

2. 非 beta API 的兼容性：未标注 @Beta 的 API 在可预见的未来保持二进制兼容。即使被标记为 @Deprecated 的方法也会继续保留（除非其本身为 @Beta）。最后一批删除非 beta API 的版本是 Guava 21.0。

3. 运行时依赖：Guava 唯一的运行时刻依赖是 com.google.guava:failureaccess:1.0.3；此外还存在若干仅在编译期使用的注解依赖。

4. 序列化兼容性：除非明确声明，所有对象的序列化格式都不保证稳定，不应假设未来版本能够读取既有持久化数据。

5. 安全模型：Guava 的类并未针对恶意调用方做防御设计，不应在受信与不可信代码之间承担安全边界。

6. 测试环境：主版本在 Linux 与 Windows 上的多个 OpenJDK 版本中进行测试；com.google.common.io 中的部分功能在非 Linux 环境下可能表现异常。Android 版本的单元测试在 API level 24（Nougat）上运行。