Java Platform 外掛提供宣告 Java 生態系統平台的能力。平台可用於不同的目的

平台是一種特殊軟體元件，不包含任何來源：它僅用於參考其他函式庫，以便它們在相依性解析期間順利運作。

平台可以發布為 Gradle 模組元資料 和 Maven BOM。

java-platform 外掛無法與特定專案中的 java 或 java-library 外掛結合使用。概念上，專案不是平台（沒有二進位檔），或 產生二進位檔。

用法

若要使用 Java Platform 外掛，請在您的建置指令碼中包含以下內容

範例 1. 使用 Java Platform 外掛
build.gradle.kts
plugins {
    `java-platform`
}
build.gradle
plugins {
    id 'java-platform'
}

API 和執行時間分離

Maven BOM 和 Java 平台之間的主要差異在於，在 Gradle 中，相依性和 約束 會宣告並限定在組態中，以及延伸組態的組態中。雖然許多使用者只會在意宣告編譯時間相依性的約束，因此會繼承執行時間和測試的相依性，但它允許宣告僅適用於執行時間或測試的相依性或約束。

為了這個目的，外掛公開兩個 組態，可用於宣告相依性：api 和 runtime。api 組態應用于宣告約束和相依性，這些約束和相依性應在針對平台編譯時使用，而 runtime 組態應用于宣告在執行時間可見的約束或相依性。

範例 2. 宣告 API 和執行時間約束
build.gradle.kts
dependencies {
    constraints {
        api("commons-httpclient:commons-httpclient:3.1")
        runtime("org.postgresql:postgresql:42.2.5")
    }
}
build.gradle
dependencies {
    constraints {
        api 'commons-httpclient:commons-httpclient:3.1'
        runtime 'org.postgresql:postgresql:42.2.5'
    }
}

請注意，此範例使用約束，而不是相依性。一般來說，這是您想要執行的動作：只有在相依性圖中加入此類元件（直接或遞迴）時，約束才會套用。這表示平台中列出的所有約束不會加入相依性，除非另一個元件引入它：它們可以視為建議。

例如，如果平台宣告對 org:foo:1.1 的約束，且沒有其他任何內容引入對 foo 的相依性，則 foo 不會 出現在圖表中。但是，如果 foo 出現，則會啟動一般的衝突解決。如果相依性引入 org:foo:1.0，則我們會選取 org:foo:1.1 來滿足平台約束。

預設情況下，為了避免在平台中加入相依性而非約束的常見錯誤，如果您嘗試執行此動作，Gradle 會失敗。如果您因為某些原因想要在約束之外加入相依性，則需要明確啟用它

範例 3. 允許宣告相依性
build.gradle.kts
javaPlatform {
    allowDependencies()
}
build.gradle
javaPlatform {
    allowDependencies()
}

本機專案約束

如果您有多專案建置，且想要發布連結到子專案的平台，您可以宣告屬於平台的子專案的約束，如下面的範例所示

範例 4. 宣告子專案的約束
build.gradle.kts
dependencies {
    constraints {
        api(project(":core"))
        api(project(":lib"))
    }
}
build.gradle
dependencies {
    constraints {
        api project(":core")
        api project(":lib")
    }
}

專案表示法會在已發布的元資料中變成傳統的 group:name:version 表示法。

從另一個平台取得約束

有時您定義的平台是另一個現有平台的延伸。

為了讓您的平台包含來自第三方平台的約束，它需要作為 platform 相依性 匯入

範例 5. 匯入平台
build.gradle.kts
javaPlatform {
    allowDependencies()
}

dependencies {
    api(platform("com.fasterxml.jackson:jackson-bom:2.9.8"))
}
build.gradle
javaPlatform {
    allowDependencies()
}

dependencies {
    api platform('com.fasterxml.jackson:jackson-bom:2.9.8')
}

發布平台

發布 Java 平台是透過套用 maven-publish 外掛，並設定使用 javaPlatform 元件的 Maven 發布

範例 6. 發布為 BOM
build.gradle.kts
publishing {
    publications {
        create<MavenPublication>("myPlatform") {
            from(components["javaPlatform"])
        }
    }
}
build.gradle
publishing {
    publications {
        myPlatform(MavenPublication) {
            from components.javaPlatform
        }
    }
}

這會為平台產生一個 BOM 檔案，其中包含一個 <dependencyManagement> 區塊，其 <dependencies> 對應到平台模組中定義的約束

使用平台

因為 Java 平台是一種特殊類型的元件，所以對 Java 平台的相依性必須使用 platform 或 enforcedPlatform 關鍵字宣告，如 管理傳遞相依性 區段中所說明。例如，如果您想要在子專案之間共用相依性版本，您可以定義一個平台模組，其中會宣告所有版本

範例 7. 在平台模組中建議版本
build.gradle.kts
dependencies {
    constraints {
        // Platform declares some versions of libraries used in subprojects
        api("commons-httpclient:commons-httpclient:3.1")
        api("org.apache.commons:commons-lang3:3.8.1")
    }
}
build.gradle
dependencies {
    constraints {
        // Platform declares some versions of libraries used in subprojects
        api 'commons-httpclient:commons-httpclient:3.1'
        api 'org.apache.commons:commons-lang3:3.8.1'
    }
}

然後讓子專案相依於平台以取得建議

範例 8. 從平台取得建議
build.gradle.kts
dependencies {
    // get recommended versions from the platform project
    api(platform(project(":platform")))
    // no version required
    api("commons-httpclient:commons-httpclient")
}
build.gradle
dependencies {
    // get recommended versions from the platform project
    api platform(project(':platform'))
    // no version required
    api 'commons-httpclient:commons-httpclient'
}