Java 平台插件 - Gradle8.1.1中文文档 - API参考文档

Java 平台插件带来了为 Java 生态系统声明平台的能力。一个平台可以用于不同的目的：

一起发布的模块的描述（例如，共享相同的版本）
一组推荐的异构库版本。一个典型的例子包括 Spring Boot BOM
共享一组依赖版本子项目之间

平台是一种特殊的软件组件，不包含任何来源：它仅用于引用其他库，以便它们在依赖项解析期间能够很好地协同工作。

平台可以发布为 Gradle 模块元数据和 Maven 物料清单。

java-platform 插件不能与给定项目中的 java 或 java-library 插件结合使用。从概念上讲，一个项目要么是一个平台，没有二进制文件，or 生成二进制文件。

用法

要使用 Java 平台插件，请在构建脚本中包含以下内容：

示例 1.使用 Java 平台插件

KotlinGroovy

build.gradle.kts

plugins {
    `java-platform`
}

build.gradle

plugins {
    id 'java-platform'
}

API和运行时分离

Maven BOM 和 Java 平台之间的主要区别在于，在 Gradle 中，依赖项和约束被声明并限定为配置和扩展它的配置。虽然许多用户只关心声明 compile time 依赖项的约束，因此由运行时和测试的依赖项继承，但它允许声明仅适用于运行时或测试的依赖项或约束。

为此，该插件公开了两个可用于声明依赖项的 configurations：api 和 runtime。 api 配置应用于声明针对平台编译时应使用的约束和依赖项，而 runtime 配置应用于声明在运行时可见的约束或依赖项。

示例 2.声明 API 和运行时约束

KotlinGroovy

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'
    }
}

请注意，此示例使用 constraints 而不是依赖项。通常，这就是您想要做的：只有当这样的组件被直接或传递地添加到依赖关系图中时，约束才会应用。这意味着平台中列出的所有约束都不会添加依赖项，除非另一个组件将其引入：它们可以被视为 recommendations 。

例如，如果一个平台声明了对 org:foo:1.1 的约束，并且没有其他任何东西对 foo 产生依赖性，则 foo 将 not 出现在图中。然而，如果 foo 出现，那么通常的冲突解决将开始。如果依赖项引入 org:foo:1.0 ，那么我们将选择 org:foo:1.1 来满足平台约束。

默认情况下，为了避免在平台中添加依赖而不是约束的常见错误，如果您尝试这样做，Gradle 将失败。如果出于某种原因，除了约束之外还想添加 dependencies，则需要显式启用它：

示例 3.允许依赖声明

KotlinGroovy

build.gradle.kts

javaPlatform {
    allowDependencies()
}

build.gradle

javaPlatform {
    allowDependencies()
}

本地项目限制

如果你有一个多项目构建并且想要发布一个链接到子项目的平台，你可以通过在属于该平台的子项目上声明约束来实现，如下例所示：

示例 4.声明对子项目的约束

KotlinGroovy

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 dependency 导入：

示例 5.导入平台

KotlinGroovy

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 发布

KotlinGroovy

build.gradle.kts

publishing {
    publications {
        create<MavenPublication>("myPlatform") {
            from(components["javaPlatform"])
        }
    }
}

build.gradle

publishing {
    publications {
        myPlatform(MavenPublication) {
            from components.javaPlatform
        }
    }
}

这将为平台生成一个 BOM 文件，其中有一个 <dependencyManagement> 块，其中它的 <dependencies> 对应于平台模块中定义的约束。

消费平台

因为 Java 平台是一种特殊的组件，所以必须使用 platform 或 enforcedPlatform 关键字声明对 Java 平台的依赖性，如管理传递依赖部分所述。例如，如果你想在子项目之间共享依赖版本，你可以定义一个平台模块来声明所有版本：

示例 7.在平台模块中推荐版本

KotlinGroovy

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.从平台获取推荐

KotlinGroovy

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'
}