【Gradle jvm插件系列2】 Java platform平台插件权威详解

Java平台插件

使用

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

plugins {
    id 'java-platform'
}

API和运行时分离

Maven BOM和Java平台之间的一个重要区别是，在Gradle中，依赖项和约束是声明和作用于配置及其扩展的。虽然许多用户只关心对编译时依赖项的约束，因此这些约束将继承到运行时和测试时依赖项上，但它还允许声明仅适用于运行时或测试的依赖项或约束。

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

dependencies {
    constraints {
        api 'commons-httpclient:commons-httpclient:3.1'
        runtime 'org.postgresql:postgresql:42.2.5'
    }
}

注意，此示例使用的是constraints而不是dependencies。一般来说，这就是您想要做的：只有当这样的组件被添加到依赖图中（直接或传递地）时，约束才会生效。这意味着在平台中列出的所有约束都不会添加依赖项，除非另一个组件将其引入：它们可以看作是建议。

例如，如果平台对org:foo:1.1有约束，并且没有其他内容引入了对foo的依赖关系，那么foo将不会出现在图中。但是，如果foo出现了，那么通常的冲突解决将会生效。如果一个依赖项引入了org:foo:1.0，那么我们将选择org:foo:1.1来满足平台约束。

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

javaPlatform {
    allowDependencies()
}

本地项目约束

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

dependencies {
    constraints {
        api project(":core")
        api project(":lib")
    }
}

项目符号将在发布的元数据中变为传统的group:name:version符号。

从其他平台获取约束

有时，您定义的平台是另一个现有平台的扩展。

为了使您的平台包含第三方平台的约束，它需要作为平台依赖项导入：

javaPlatform {
    allowDependencies()
}

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

发布平台

使用maven-publish插件发布Java平台，配置一个使用javaPlatform组件的Maven出版物：

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

这将生成一个平台的BOM文件，其中的块中的对应于平台模块中定义的约束。

消费平台

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

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

dependencies {
    constraints {
        // 平台声明了一些子项目中使用的库的版本
        api 'commons-httpclient:commons-httpclient:3.1'
        api 'org.apache.commons:commons-lang3:3.8.1'
    }
}

然后让子项目依赖于平台以获取推荐版本。

示例8. 从平台获取推荐版本

dependencies {
    // 从平台项目中获取推荐版本
    api platform(project(':platform'))
    // 不需要指定版本
    api 'commons-httpclient:commons-httpclient'
}

参考资料

小军李：【Gradle jvm插件系列1】 Java Application插件权威详解

小军李：【Gradle jvm插件系列2】 Java Library插件用法示例权威详解

小军李：【Gradle jvm插件系列3】 Java platform平台插件权威详解

小军李：【Gradle jvm插件系列4】 scala插件权威详解

小军李：【gradle多模块系列1】多项目构建和子项目的添加管理

小军李：【Gradle多模块系列2】在子项目之间声明依赖关系和共享构建逻辑示例详解

小军李：【Gradle 多模块系列3】如何开发自定义Gradle插件

小军李：【Gradle多模块系列4】JVM项目的依赖管理