שימוש ב-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.83.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 של הספריות כולל את גרסת -jreGuava (שתומכת ב-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.