Spring Boot Gradle Plugin_2.1.0参考指南

作者简介

陈喆，现就职于中科院某研究所担任副研究员，专注于工业云平台、MES系统的设计与研发。

内容来源：https://docs.spring.io/spring-boot/docs/2.1.0.BUILD-SNAPSHOT/gradle-plugin/reference/html/

1.简介

Spring Boot Gradle 插件对Gradle项目提供了Spring Boot支持，实现了将项目打包成可执行jar或war文件，运行Spring Boot应用程序和使用spring-boot-dependencies提供的依赖管理功能。该插件要求使用Gradle 4.0或以上版本。

2. 开始使用

使用该插件需要在项目中添加如下引用：

buildscript {
	repositories {
		maven { url 'https://repo.spring.io/libs-snapshot' }
	}

	dependencies {
		classpath 'org.springframework.boot:spring-boot-gradle-plugin:2.1.0.BUILD-SNAPSHOT'
	}
}

apply plugin: 'org.springframework.boot'

单独使用该插件不会对项目产生太大影响，但当与其它插件共同使用的时候会相应的修改配置。例如，当使用java插件时会自动配置一个用于构建可执行jar包的任务。

典型的Spring Boot项目会应用groovy, java, 或 org.jetbrains.kotlin.jvm 插件，最少要应用 io.spring.dependency-management 插件。例如：

apply plugin: 'java'
apply plugin: 'io.spring.dependency-management'

3. 管理依赖

当应用io.spring.dependency-management插件的时候，Spring Boot插件将自动从使用的Spring Boot版本导入spring-boot-dependencies，你可以省略bom中声明依赖的版本号。

dependencies {
	compile 'org.springframework.boot:spring-boot-starter-web'
	compile 'org.springframework.boot:spring-boot-starter-data-jpa'
}

3.1 定制管理版本

可以通过设置相关属性来定制管理版本。例如，通过slf4j.version属性定制SLF4J 的版本：

ext['slf4j.version'] = '1.7.20'

注：每个版本的Spring Boot都是与特定版本的第三方依赖适配的。重置版本可能会导致兼容性问题。

4. 打包成可执行文件

该插件可以创建包含应用全部依赖的可执行文件（jar文件或war文件），然后通过java -jar命令执行。

4.1 打包成可执行jar包

通过bootjar任务构建可执行jar包。该任务在应用 java 插件的时候自动创建，是一个BootJar实例。assemble任务依赖于bootJar任务，所以当执行assemble（或build）任务时自动执行bootJar任务。

4.2 打包成可执行war包

通过bootwar任务构建可执行jar包。该任务在应用 war 插件的时候自动创建，是一个BootWar实例。assemble任务依赖于bootWar任务，所以当执行assemble（或build）任务时自动执行bootWar任务。

4.2.1 打包可执行并且可部署的war包

如果要创建一个war文件，既可以通过 java -jar 命令运行，也可以部署到一个外部容器中，那就需要将一个内嵌servlet容器依赖添加大providedRuntime配置中，例如：

dependencies {
	compile 'org.springframework.boot:spring-boot-starter-web'
	providedRuntime 'org.springframework.boot:spring-boot-starter-tomcat'
}

这样可以保证它们被打包到WEB-INF/lib-provided文件夹中，从而避免与外部容器冲突。

注：推荐使用providedRuntime替代compileOnly，因为依赖未存在test classpath于，所以所有的web集成测试都会失败。

4.3 打包可执行的普通归档文件

默认情况下，配置了bootJar或者bootWar任务，jar或者war任务就失效。工程可以通过启用jar或者war任务实现同时支持可执行归档文件和普通归档文件：

jar {
	enabled = true
}

为了避免可执行归档文件和普通归档文件写入到相同地址，其中一个要配置成使用其它地址。可以通过配置classifier实现：

bootJar {
	classifier = 'boot'
}

4.4 配置可执行归档文件打包

BootJar和BootWar任务分别是Gradle的Jar和War任务的子类。所以，所有打包jar或者war包的标准配置选项对于可执行jar或者war包同样可用。同时，还提供了一些可执行jar或者war包特有的配置选项。

4.4.1 配置主类

可以通过mainClassName属性显示配置主类：

bootJar {
	mainClassName = 'com.example.ExampleApplication'
}

也可以在Sprong Boot DSL中配置mainClassName属性：

springBoot {
	mainClassName = 'com.example.ExampleApplication'
}

如果应用了application插件，也可以通过设置项目属性mainClassName来设置：

mainClassName = 'com.example.ExampleApplication'

最后，也可以设置任务清单中的Start-Class属性：

bootJar {
	manifest {
		attributes 'Start-Class': 'com.example.ExampleApplication'
	}
}

4.4.2 排除Devtools

默认情况下，Spring Boot的Devtools模块，org.springframework.boot:spring-boot-devtools会排除在可执行jar或war包之外。如果想在文件中包含Devtools需要设置excludeDevtools属性为false：

bootWar {
	excludeDevtools = false
}

4.4.3 配置需要拆包的库

大部分的库被配置成内嵌到可执行归档文件中被直接引用，但这样也可能会产生一些问题。比如，JRuby包含一个内嵌的jar文件，它假设在文件系统中一直有一个可用的jruby-complete.jar文件。

为了处理有问题的库，可以配置实现当可执行归档文件运行的时候将指定的内嵌jar文件拆包到一个临时文件夹下。可以通过Ant类型的模式匹配源jar文件的绝对路径来指定要拆包的库：

bootJar {
	requiresUnpack '**/jruby-complete-*.jar'
}

4.4.4 使归档文件完全可执行

Spring Boot支持完全可执行归档文件。可以通过准备一个指定应用如何启动的shell脚本将一个归档文件设置成完全可执行。在Unix-like平台上，启动脚本允许归档文件直接启动运行或安装成服务。

为了启用该特性，需要启用启动脚本：

bootJar {
	launchScript()
}

这将Spring Boot的默认启动脚本添加到归档文件中。默认启动脚本包含一些带有默认值的属性，这些属性可以通过properties属性自定义：

bootJar {
	launchScript {
		properties 'logFilename': 'example-app.log'
	}
}

如果默认的启动脚本无法满足需求，可以使用script属性创建自定义启动脚本：

bootJar {
	launchScript {
		script = file('src/custom.script')
	}
}

4.4.5 使用PropertiesLauncher

通过设置任务清单中的Main-Class属性来设置使用PropertiesLauncher启动可执行jar或war包：

bootWar {
	manifest {
		attributes 'Main-Class': 'org.springframework.boot.loader.PropertiesLauncher'
	}
}

注：PropertiesLauncher可以实现通过属性文件读取定义用户配置classpath和主类。

5 发布你的应用

5.1 使用maven插件发布

当使用maven插件时，会为bootArchives配置自动创建一个名为uploadBootArchive的Upload任务。默认情况下，bootArchives配置包含bootJar或bootWar任务创建的归档文件。uploadBootArchive任务可以将归档文件发布到Maven仓库中：

uploadBootArchives {
	repositories {
		mavenDeployer {
			repository url: 'https://repo.example.com'
		}
	}
}

5.2 使用maven-publish插件发布

通过MavenPublication的artifact方法发布文件。将生成归档文件的任务传递给artifact方法。例如，发布bootJar任务生成的文件：

publishing {
	publications {
		bootJava(MavenPublication) {
			artifact bootJar
		}
	}
	repositories {
		maven {
			url 'https://repo.example.com'
		}
	}
}

5.3 通过application插件分发

当应用applicaton插件时一个名为boot的发行版已经创建出来。该发行版包含bootJar或bootWar任务生成的归档文件和启动脚本。可以通过bootDistZip或bootDistTar任务分别创建zip或tar发行版。

6 使用Gradle启动应用

在第一构建项目时可以使用bootRun任务启动应用：

$ ./gradlew bootRun

bootRun任务时JavaExec子类BootRun的一个实例。照此，所有使用Gradle执行一个Java进程的常规配置选项都可用。

默认情况下，主类被为任务路径下带有public static void main(String[])的类。

也可以通过main属性显性的设置主类：

bootRun {
	main = 'com.example.ExampleApplication'
}

也可以在Sprong Boot DSL中配置mainClassName属性：

springBoot {
	mainClassName = 'com.example.ExampleApplication'
}

如果应用了application插件，也可以通过设置项目属性mainClassName来设置：

mainClassName = 'com.example.ExampleApplication'

6.1 重载资源

如果devtools被添加到项目中，它可以自动监控你应用的变化。另外，你还可以配置bootRun实现从其它地址加载应用静态资源：

bootRun {
	sourceResources sourceSets.main
}

7 集成执行器

7.1 生成构建信息

Spring Boot Actuator的info端点自动发布META-INF/build-info.properties文件中的应用构建信息。BuildInfo任务用户生成此文件。可以通过插件DSL使用该任务：

springBoot {
	buildInfo()
}

这样会配置一个名为bootBuldInfo的BuildInfo任务，当该任务存在时，Java插件的classes任务会依赖于它。该任务的目标目录是主资源输出目录的META-INF文件夹。

默认情况下，生成的构建信息派生自项目：

Property	Default value
build.artifact	The base name of the bootJar or bootWar task, or unspecified if no such task exists
build.group	The group of the project
build.name	The name of the project
build.version	The version of the project
build.time	The time at which the project is being built

可以使用DSL自定义以上属性：

springBoot {
	buildInfo {
		properties {
			artifact = 'example-app'
			version = '1.2.3'
			group = 'com.example'
			name = 'Example application'
		}
	}
}

build.time的默认值是项目构建的时刻。这样做的一个副作用是任务永远不是最新的。结果导致当包含多个任务时构建时间会更长，包括测试也会被执行一遍。另一个副作用是任务的输出永远会改变，因此，构建永远不是真正重复的。如果相比于build.time属性的准确性，你更看重构建的性能或者重复性，可以将time设置为null或者一个固定值。

还可以给构建信息添加额外属性：

springBoot {
	buildInfo {
		properties {
			additional = [
				'a': 'alpha',
				'b': 'bravo'
			]
		}
	}
}

8 反作用于其它插件

当应用其它插件时Spring Boot插件会通过修改项目配置来反作用于其它插件。

8.1 反作用于Java plugin

当项目应用java plugin时，Spring Boot plugin会：

1. 创建一个名为bootJar的BootJar任务，用于创建项目的可执行jar包。该jar包会包含运行时类路径中的所有内容；类被打包到BOOT-INF/classes文件夹，jar文件被打包到BOOT-INF/lib文件夹。
2. 配置assemble任务依赖于bootJar任务
3. 停用jar任务
4. 创建名为bootRun的BootRun任务，用于运行应用程序。
5. 创建一个名为bootArchives的配置，包含bootJar任务生成的输出。
6. 配置所有未配置的JavaCompile任务使用UTF-8编码。
7. 配置所有JavaCompile任务使用-parameters编译器参数。