שימוש ב-Bill of Materials (BOM) עם ספריות לקוח של Java ב-Cloud

כדי לוודא שבפרויקטים שלכם יש גרסאות תואמות של ספריות לקוח ב-Cloud, צריך להשתמש בגרסאות שמצוינות ב Google Cloudרשימת החומרים (BOM) של הספריות. בספריות ב-BOM אין התנגשויות תלות שיופיעו כ-NoSuchMethodError או כ-NoClassDefFoundError.

ה-BOM נחוץ כי Google מפרסמת יותר ממאתיים ספריות Java בקוד פתוח שמקלות על השימוש בשירותים ב- Google Cloud. הספריותGoogle Cloud תלויות בכמה ספריות בסיסיות שאפשר להשתמש בהן למטרות כלליות.

ההמלצות האלה רלוונטיות לרכיבים של הספריות הבאות:

עדכון הפרויקט לשימוש ב-BOM

כדי לוודא שהפרויקטים משתמשים בגרסאות תואמות של הספריות ושל רכיבי הארטיפקט שלהן, מייבאים את com.google.cloud:libraries-bom ומשתמשים ב-BOM כדי לציין גרסאות של יחסי תלות. חשוב להסיר את כל הגרסאות שהגדרתם בעבר.

אם נתקלתם בבעיות תאימות ל-protobuf-java 4.x, עליכם לעדכן את בסיס הקוד ואת התלות כדי להבטיח תאימות. למידע על בעיות תאימות אפשריות, אפשר לעיין בהערות הגרסה של libraries-bom v26.50.0 ושל libraries-bom v26.75.0.

Maven

מייבאים את ה-BOM בקטע dependencyManagement של קובץ pom.xml. בקטע dependencies צריך לכלול את הארטיפקטים הספציפיים שאתם מסתמכים עליהם, אבל לא לציין את הגרסאות של הארטיפקטים בקטע dependencies. בדוגמה הבאה אפשר לראות איך מייבאים את ה-BOM וכוללים את ארטיפקט google-cloud-storage.

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>libraries-bom</artifactId>
      <version>26.78.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-storage</artifactId>
  </dependency>
  <dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-storage-control</artifactId>
  </dependency>
</dependencies>

בדוגמה הזו, מכיוון ש-BOM מנהל את גרסאות הספרייה, הגרסה של google-cloud-storage מושמטת.

Gradle

רשימות BOM נתמכות כברירת מחדל ב-Gradle 5.x ומעלה. מוסיפים תלות ב-com.google.cloud:libraries-bom ומסירים את הגרסה מהצהרות התלות בקובץ build.gradle של הארטיפקט.platform

implementation platform('com.google.cloud:libraries-bom:26.83.0')

implementation 'com.google.cloud:google-cloud-storage'

מילות המפתח platform ו-enforcedPlatform מספקות גרסאות של תלות שהוגדרו ב-BOM. מילת המפתח enforcedPlatform מחילה את גרסאות התלות שהוגדרו ב-BOM, ולכן מבטלת את מה שציינתם. לפרטים נוספים על מילות המפתח platform ו-enforcedPlatform ב-Gradle 5.x ואילך, אפשר לעיין במאמר Gradle: Importing Maven BOMs.

אם אתם משתמשים ב-Gradle 4.6 ואילך, מוסיפים את enableFeaturePreview('IMPROVED_POM_SUPPORT') לקובץ settings.gradle. פרטים נוספים זמינים במאמר בנושא הערות על הגרסה Gradle 4.6: ייבוא BOM. גרסאות של Gradle שקודמות לגרסה 4.6 לא תומכות ב-BOM.

SBT

‫SBT לא תומך ב-BOM. אפשר למצוא גרסאות מומלצות של ספריות מגרסת BOM מסוימת בלוח הבקרה ולהגדיר את הגרסאות באופן ידני.

Bazel

‫Bazel לא תומך ב-BOM. אפשר למצוא גרסאות מומלצות של ספריות מגרסת BOM מסוימת בלוח הבקרה ולהגדיר את הגרסאות באופן ידני.

גרסאות Guava‏ -jre או -android

מאז ההשקה של גרסה 21.0.0, ה-BOM של Libraries כולל את גרסת -jre של Guava (שכוללת תמיכה ב-Java 8 ואילך). הקטע הבא לא רלוונטי למשתמשי Java 8.

הגרסה של Guava מבית Google מכילה שתי גרסאות של ארטיפקטים: גרסאות ‎-jre ו-‎-android. הגרסה עם ‎-jre (למשל com.google.guava:guava:31.1-jre) היא ל-Java 8 ותומכת בפונקציות lambda ובזרמים. הגרסה השנייה עם הסיומת ‎-android (למשל com.google.guava:guava:31.1-android) מיועדת ל-Java 7 ולפיתוח ל-Android.

‫ Google Cloud Libraries BOM מכיל את Guava בגרסה ‎-android כדי לוודא ש-BOM פועל ב-Java 7. עם זאת, המשמעות היא שבגרסת Guava ב-BOM אין שיטות מסוימות שמיועדות לפונקציות lambda של Java 8, כמו ImmutableList.toImmutableList().

אם הפרויקט שלכם דורש Java 8 ומעלה ומשתמש במחלקות Guava כמו com.google.common.collect.Streams, אתם צריכים להוסיף תלות בגרסת JRE של Guava.

ב-Maven:

  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>com.google.guava</groupId>
        <artifactId>guava</artifactId>
        <version>31.1-jre</version>  <!-- "-jre" for Java 8 or higher -->
      </dependency>
    </dependencies>
    <dependencies>
      <dependency>
        <groupId>com.google.cloud</groupId>
        <artifactId>libraries-bom</artifactId>
        ...
  </dependencyManagement>

ב-Gradle:

dependencies {
  constraints {
    implementation 'com.google.guava:guava:31.1-jre' // "-jre" for Java 8 or higher
  }
  implementation platform('com.google.cloud:libraries-bom:26.12.0')
  ...
}

הדוגמה הקודמת לא תפעל אם תשתמשו ב-enforcedPlatform כי enforcedPlatform קודם ל-constraints. אם רוצים להשתמש ב-enforcedPlatform עם גרסת Guava, אפשר להגדיר את ResolutionStrategy.