google/guava

Source: https://github.com/google/guava

Guava: Google 核心 Java 库

GitHub Release (https://github.com/google/guava/releases/latest) CI (https://github.com/google/guava/actions/workflows/ci.yml) OpenSSF Best Practices (https://www.bestpractices.dev/projects/7197)

Guava 是 Google 的一套核心 Java 库，包含新的集合类型（如 multimap 和 multiset）、不可变集合、图库，以及用于并发、I/O、哈希、原始类型、字符串等的工具！它被 Google 内部大多数 Java 项目广泛使用，也被许多其他公司广泛采用。

Guava 提供两种风格：

• JRE 风格要求 JDK 1.8 或更高版本。
• 如果你需要 Android 支持，请使用 Android 风格 (https://github.com/google/guava/wiki/Android)。

你可以在 [android directory] 中找到 Android Guava 的源代码。

将 Guava 添加到你的构建中

Guava 的 Maven group ID 是 com.google.guava，artifact ID 是 guava。

Guava 提供两种不同的“风格”：一种用于 (Java 8+) JRE，另一种用于 Android 或任何希望与 Android 兼容的库。这些风格通过 Maven 版本字段指定，分别为 33.6.0-jre 或 33.6.0-android。

关于依赖 Guava 的更多信息，请参阅在你的构建中使用 Guava。

要使用 Maven 添加对 Guava 的依赖，请使用以下配置：

<dependency>
  <groupId>com.google.guava</groupId>
  <artifactId>guava</artifactId>
  <version>33.6.0-jre</version>
  <!-- 或者，对于 Android： -->
  <version>33.6.0-android</version>
</dependency>

要使用 Gradle 添加依赖：

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 - 仅在实现中使用 Guava：
  implementation("com.google.guava:guava:33.6.0-android")

  // 4. Android - 在公共 API 中使用 Guava 类型：
  api("com.google.guava:guava:33.6.0-android")
}

有关何时使用 api 以及何时使用 implementation 的更多信息，请参阅 Gradle 文档中关于 API 和实现分离的部分 (https://docs.gradle.org/current/userguide/java_library_plugin.html#sec:java_library_separation)。

快照和文档

从 master 分支构建的 Guava 快照可通过 Maven 获取，使用版本 999.0.0-HEAD-jre-SNAPSHOT，Android 风格则使用 999.0.0-HEAD-android-SNAPSHOT。

同时提供快照 API Javadoc和快照 API 差异。

另一个获取 Javadoc 的简单方法是打开 guava.dev/api (https://guava.dev/api)。

你还可以通过在 guava.dev 后附加类名直接跳转到特定类。例如，guava.dev/ImmutableList (https://guava.dev/ImmutableList)！

了解 Guava

• 我们的用户指南，Guava Explained
• 一个包含其他有用链接的精彩合集 (https://www.tfnico.com/presentations/google-guava)

链接

• GitHub 项目 (https://github.com/google/guava)
• 问题跟踪器：报告缺陷或功能请求 (https://github.com/google/guava/issues/new)
• StackOverflow：提出“如何做”和“为什么不起作用”的问题 (https://stackoverflow.com/questions/ask?tags=guava+java)
• guava-announce：发布和即将到来的重大变更公告 (https://groups.google.com/group/guava-announce)
• guava-discuss：用于开放式问题和讨论 (https://groups.google.com/group/guava-discuss)

重要警告

1. 在类或方法级别标记了 @Beta 注解的 API 可能会发生变化。它们可以随时以任何方式修改，甚至被移除。如果你的代码本身是一个库（即它被你自己控制之外的用户放在 CLASSPATH 上使用），你不应该使用 beta API，除非你对其进行了重新打包。如果你的代码是一个库，我们强烈建议使用 Guava Beta Checker 来确保你没有使用任何 @Beta API！

2. 没有 @Beta 注解的 API 将在无限期未来保持二进制兼容。（以前，我们有时会在弃用期后移除此类 API。最后一个移除非 @Beta API 的版本是 Guava 21.0。）即使是 @Deprecated API 也会保留（同样，除非它们是 @Beta）。我们没有计划再次开始移除东西，但官方上，我们保留选择权，以防出现意外（比如严重的安全问题）。

3. Guava 有一个在运行时链接所需的依赖：com.google.guava:failureaccess:1.0.3。它还有一些仅包含注解的依赖，我们在该链接中详细讨论。

4. 除非另有说明，所有对象的序列化形式都可能发生变化。不要持久化这些数据，并假设它们能被未来版本的库读取。

5. 我们的类并非设计用于防御恶意调用者。你不应在可信与不可信代码之间的通信中使用它们。

6. 对于主线风格，我们在 Linux 和 Windows 上使用一系列 OpenJDK 版本测试库。某些功能，尤其是 com.google.common.io 中的功能，在非 Linux 环境下可能无法正常工作。对于 Android 风格，我们的单元测试也在 API 级别 24 (Nougat) 上运行。