67. Spring Boot Gradle 插件

Spring Boot Gradle 插件在 Gradle 中提供了 Spring Boot 支持，使您可以打包可执行 jar 或 warFiles，运行 Spring Boot 应用程序并使用spring-boot-dependencies提供的依赖项 Management。

67.1 引入插件

要使用 Spring Boot Gradle 插件，请使用plugins块对其进行配置：

plugins {
    id 'org.springframework.boot' version '1.5.9.RELEASE'
}

67.2 Gradle 依赖性 Management

spring-boot插件会自动应用依赖 Management 插件并将其配置为导入spring-boot-starter-parent bom。这提供了与 Maven 用户一样的依赖 Management 体验。例如，它允许您在声明 Bom 中 Management 的依赖项时省略版本号。要使用此功能，只需以通常的方式声明依赖项，但将版本号保留为空：

dependencies {
    compile("org.springframework.boot:spring-boot-starter-web")
    compile("org.thymeleaf:thymeleaf-spring4")
    compile("nz.net.ultraq.thymeleaf:thymeleaf-layout-dialect")
}

Note

您声明的spring-boot gradle 插件的版本确定了导入的spring-boot-starter-parent bom 的版本(这可确保构建始终可重复)。您应该始终将spring-boot gradle 插件的版本设置为希望使用的实际 Spring Boot 版本。所提供版本的详细信息可以在appendix中找到。

要了解有关 Dependency Management 插件功能的更多信息，请参考其documentation。

67.3 打包可执行 jar 和 war 文件

将spring-boot插件应用于您的项目后，它将自动尝试重写归档文件，以使它们可以使用bootRepackage task执行。您应将项目配置为以常规方式构建 jar 或 war(适当时)。

您可以使用配置选项或通过向清单添加Main-Class属性来指定要启动的主类。如果您未指定主类，则插件将使用public static void main(String[] args)方法搜索类。

Tip

检查第 67.6 节“重新打包配置”以获取配置选项的完整列表。

要构建和运行项目工件，可以键入以下内容：

$ gradle build
$ java -jar build/libs/mymodule-0.0.1-SNAPSHOT.jar

要构建可执行且可部署到外部容器的 war 文件，您需要将嵌入式容器依赖项标记为属于 war 插件的providedRuntime配置，例如：

...
apply plugin: 'war'

war {
    baseName = 'myapp'
    version =  '0.5.0'
}

repositories {
    jcenter()
    maven { url "http://repo.spring.io/libs-snapshot" }
}

dependencies {
    compile("org.springframework.boot:spring-boot-starter-web")
    providedRuntime("org.springframework.boot:spring-boot-starter-tomcat")
    ...
}

Tip

有关如何创建可部署的 war 文件的更多详细信息，请参见“ 第 85.1 节“创建可部署的 war 文件””部分。

67.4 就地运行项目

要在不构建 jar 的情况下就地运行项目，可以使用“ bootRun”任务：

$ gradle bootRun

如果已将devtools添加到您的项目中，它将自动监视您的应用程序的更改。另外，您也可以运行该应用程序，以便可以在实时应用程序中重新加载静态 Classpath 资源(即默认情况下为src/main/resources)，这在开发时可能会有所帮助。

bootRun {
    addResources = true
}

使静态 Classpath 资源可重载意味着bootRun不使用processResources任务的输出，即，当使用bootRun调用时，您的应用程序将以未经处理的形式使用这些资源。

67.5 Spring Boot 插件配置

gradle 插件会使用springBoot元素自动扩展构建脚本 DSL，以进行 Boot 插件的全局配置。设置适当的属性，就像使用其他任何 Gradle 扩展一样(请参阅下面的配置选项列表)：

springBoot {
    backupSource = false
}

67.6 重新打包配置

该插件添加了一个bootRepackage任务，您也可以直接对其进行配置，例如：

bootRepackage {
    mainClass = 'demo.Application'
}

提供以下配置选项：

Name	Description
`enabled`	布尔标志，用于关闭重新打包程序(如果您需要其他引导功能，但不希望使用此功能，则有时很有用)
`mainClass`	应该运行的主要类。如果未指定，并且您已经应用了应用程序插件，那么将使用`mainClassName`项目属性。如果尚未应用插件或未指定`mainClassName`，则将在存档中搜索合适的类。 “合适的”表示具有格式正确的`main()`方法的唯一类(如果发现多个，则构建将失败)。如果您已经应用了应用程序插件，那么也可以通过其“运行”任务(`main`属性)和/或其“ startScripts”任务(`mainClassName`属性)来指定主类，以替代使用“ springBoot”配置。
`classifier`	一个文件名段(在 extensions 之前)要添加到存档中，以便将原始文件保留在其原始位置。默认值为`null`，在这种情况下，将存档重新打包到位。缺省值在很多情况下都很方便，但是如果要将原始 jar 用作另一个项目中的依赖项，则必须使用分类器来定义可执行 Files。
`withJarTask`	`Jar`任务的名称或值(默认为`Jar`类型的所有任务)，用于查找要重新打包的 Files。
`customConfiguration`	自定义配置的名称，该自定义配置用于填充嵌套的 lib 目录(如果不指定此名称，则将获得所有编译和运行时依赖项)。
`executable`	布尔值标志，用于指示 jar 文件是否可以在 Unix 之类的 os 上完全执行。默认为`false`。
`embeddedLaunchScript`	如果完全可执行，嵌入式启动脚本将位于 jar 的前面。如果未指定，将使用“ Spring Boot”默认脚本。
`embeddedLaunchScriptProperties`	将在启动脚本中扩展的其他属性。默认脚本支持`mode`属性，该属性可以包含值`auto`，`service`或`run`。
`excludeDevtools`	布尔值标志，指示是否应从重新打包的 Files 中排除 devtools jar。默认为`true`。

67.7 使用自定义 Gradle 配置重新打包

有时，不打包从compile，runtime和provided范围解析的默认依赖关系可能更合适。如果要按原样运行创建的可执行 jar 文件，则需要将所有依赖项嵌套在其中；但是，如果计划爆炸 jar 文件并手动运行主类，则可能已经可以通过CLASSPATH使用某些库。在这种情况下，您可以使用一组不同的依赖项重新打包 jar。

使用自定义配置将自动禁用compile，runtime和provided范围的依赖关系解析。自定义配置可以全局定义(在springBoot部分中)，也可以按任务定义。

task clientJar(type: Jar) {
    appendix = 'client'
    from sourceSets.main.output
    exclude('**/*Something*')
}

task clientBoot(type: BootRepackage, dependsOn: clientJar) {
    withJarTask = clientJar
    customConfiguration = "mycustomconfiguration"
}

在上面的示例中，我们创建了一个新的clientJar Jar 任务，以打包来自已编译源的自定义文件集。然后，我们创建了一个新的clientBoot BootRepackage 任务，并指示它只能与clientJar task 和mycustomconfiguration一起使用。

configurations {
    mycustomconfiguration.exclude group: 'log4j'
}

dependencies {
    mycustomconfiguration configurations.runtime
}

我们在BootRepackage中引用的配置是普通的Gradle configuration。在上面的示例中，我们创建了一个名为mycustomconfiguration的新配置，指示它从runtime派生并排除log4j组。如果执行clientBoot任务，则重新包装的启动 jar 将具有runtime的所有依赖关系，但没有log4j jar。

67.7.1 配置选项

提供以下配置选项：

Name	Description
`mainClass`	应由可执行 Files 运行的主要类。
`providedConfiguration`	提供的配置的名称(默认为`providedRuntime`)。
`backupSource`	是否应在重新打包之前备份原始源归档文件(默认为`true`)。
`customConfiguration`	定制配置的名称。
`layout`	存档的类型，与内部依赖项的布局相对应(默认为基于存档类型的猜测)。参见可用的布局以获取更多详细信息。
`layoutFactory`	如果需要自定义布局，可以使用布局工厂。第三方可以提供其他布局。仅当未指定`layout`时才使用布局工厂。
`requiresUnpack`	必须运行的依赖项列表(格式为“ groupId：artifactId”，必须从 Fat JAR Jar中解包才能运行。项目仍被打包到 Fat JAR Jar中，但运行时会自动解包。

67.7.2 可用的布局

layout属性用于配置存档的格式以及是否应包含引导加载程序。提供以下布局：

Name	Description	Executable
`JAR`	常规可执行文件JAR layout。	Yes
`WAR`	可执行文件WAR layout。将`provided`依赖项放在`WEB-INF/lib-provided`中，以避免在将`war`部署到 servlet 容器中时发生任何冲突。	Yes
`ZIP`(别名为`DIR`)	与`JAR`布局类似，使用PropertiesLauncher。	Yes
`MODULE`	Binding 依赖关系(不包括具有`provided`范围的依赖关系)和项目资源。	No
`NONE`	Binding 所有依赖项和项目资源。	No

67.7.3 使用自定义布局

如果您对如何在重新包装的 jar 中安排依赖项和加载程序类有自定义要求，则可以使用自定义布局。任何定义一个或多个LayoutFactory实现的库都可以添加到构建脚本依赖项中，然后布局工厂就可以在springBoot配置中使用。例如：

buildscript {
	repositories {
		mavenCentral()
	}
	dependencies {
		classpath("org.springframework.boot:spring-boot-gradle-plugin:1.5.9.RELEASE")
		classpath("com.example:custom-layout:1.0.0")
	}
}

springBoot {
	layoutFactory = new com.example.CustomLayoutFactory()
}

Note

如果构建 Classpath 上只有一个自定义LayoutFactory，并且在META-INF/spring.factories中列出了该自定义LayoutFactory，则无需在springBoot配置中显式设置它。仅当未指定显式layout时才使用布局工厂。

67.8 了解 Gradle 插件的工作方式

将spring-boot应用于您的 Gradle 项目时，会自动创建一个名为bootRepackage的默认任务。 bootRepackage任务依赖于 Gradle assemble任务，并且在执行时，它会尝试查找所有限定符为空的 jar 工件(即自动跳过测试和源 jar)。

由于bootRepackage会找到“所有”创建的 jar 工件，因此 Gradle 任务执行的 Sequences 很重要。大多数项目仅创建一个 jar 文件，因此通常这不是问题。但是，如果您打算使用自定义的Jar和BootRepackage任务创建更复杂的项目设置，则无需考虑一些调整。

如果您只是从项目中创建自定义 jar 文件，则只需禁用默认的jar和bootRepackage任务即可：

jar.enabled = false
bootRepackage.enabled = false

另一种选择是指示默认的bootRepackage任务仅与默认的jar任务一起使用。

bootRepackage.withJarTask = jar

如果您具有用于创建和重新打包主 jar 文件的默认项目设置，并且您仍然希望创建其他自定义 jar，则可以将自定义重新打包任务组合在一起并使用dependsOn，以便bootJars任务将在默认设置后运行bootRepackage任务已执行：

task bootJars
bootJars.dependsOn = [clientBoot1,clientBoot2,clientBoot3]
build.dependsOn(bootJars)

上述所有调整通常用于避免重新包装已经创建的启动 jar 的情况。重新包装现有的启动 jar 不会破坏任何内容，但是您可能会发现它包含不必要的依赖项。

67.9 使用 Gradle 将工件发布到 Maven 存储库

如果您是声明没有版本的依赖，并且想要将工件发布到 Maven 存储库，则需要使用 Spring Boot 依赖 Management 的详细信息配置 Maven 发布。这可以通过将其配置为发布从spring-boot-starter-parent继承的 pom 或从spring-boot-dependencies导入依赖项 Management 来实现。此配置的确切细节取决于您使用 Gradle 的方式以及尝试发布工件的方式。

67.9.1 配置 Gradle 以生成继承依赖 Management 的 pom

以下是将 Gradle 配置为生成从spring-boot-starter-parent继承的 pom 的示例。有关更多信息，请参考Gradle 用户指南。

uploadArchives {
    repositories {
        mavenDeployer {
            pom {
                project {
                    parent {
                        groupId "org.springframework.boot"
                        artifactId "spring-boot-starter-parent"
                        version "1.5.9.RELEASE"
                    }
                }
            }
        }
    }
}

67.9.2 配置 Gradle 以生成导入依赖项 Management 的 pom

以下是将 Gradle 配置为生成 pom 的示例，该 pom 导入spring-boot-dependencies提供的依赖项 Management。有关更多信息，请参考Gradle 用户指南。

uploadArchives {
    repositories {
        mavenDeployer {
            pom {
                project {
                    dependencyManagement {
                        dependencies {
                            dependency {
                                groupId "org.springframework.boot"
                                artifactId "spring-boot-dependencies"
                                version "1.5.9.RELEASE"
                                type "pom"
                                scope "import"
                            }
                        }
                    }
                }
            }
        }
    }
}

Spring Boot 中文文档

67. Spring Boot Gradle 插件

67.1 引入插件

67.2 Gradle 依赖性 Management

67.3 打包可执行 jar 和 war 文件

67.4 就地运行项目

67.5 Spring Boot 插件配置

67.6 重新打包配置

67.7 使用自定义 Gradle 配置重新打包

67.7.1 配置选项

67.7.2 可用的布局

67.7.3 使用自定义布局

67.8 了解 Gradle 插件的工作方式

67.9 使用 Gradle 将工件发布到 Maven 存储库

67.9.1 配置 Gradle 以生成继承依赖 Management 的 pom

67.9.2 配置 Gradle 以生成导入依赖项 Management 的 pom