Spring Boot - Gradle Plugin

简介

Spring Boot Gradle Plugin为Spring Boot提供了对Gradle的支持，允许你将打包可执行的jar或者war archives,运行Spring Boot程序，然后使用spring-boot-dependencies提供的依赖管理。Spring Boot’s Gradle插件需要Gradle 3.4及以上。原文地址:http://docs.spring.io/spring-boot/docs/2.0.0.M2/gradle-plugin//reference/html/

除了这个用户指南，API 文档也已经有了。

开始

需要在项目里加上下面的配置来使用插件。

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

    dependencies {
        classpath 'org.springframework.boot:spring-boot-gradle-plugin:2.0.0.M2'
    }
}

apply plugin: 'org.springframework.boot'

使用这个插件可以让减少项目的改动。而且，会检测其他插件的使用或者更新。比如，当应用了java插件，会自动在构建时打包成可执行的jar。
一个经典的Spring Boot项目至少会使用groovy
, java
, or org.jetbrains.kotlin.jvm
插件 and the io.spring.dependency-management
插件. 比如:

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

依赖管理

当使用了io.spring.dependency-management
插件, Spring Boot的插件会自动地从你使用的Spring Boot版本里导入spring-boot-dependencies bom。
Maven用户使用起来感觉区别不大。比如，允许你在声明依赖的时候忽略掉版本号，使用这项功能，只需要正常的声明依赖，不用写版本号就可以了。

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

自定义管理版本号

当应用了依赖管理插件，spring-boot-dependencies bom会被自动导入，使用属性控制它管理的依赖的版本号。点击 bom 查看完整的属性列表。

如果要自定义管理版本，设置它的扩展属性。比如，自定义被管理的SLF4J的版本号，设置属性：

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

每个Spring Boot版本都与制定的第三方依赖设计和测试好了。覆盖版本可能会造成兼容问题，所以自定义的时候小心一点

打包可执行文件

插件可以创建可执行文件(jar文件或者war文件)，里面包含所有应用的依赖并且可以使用java -jar执行。

打包可执行jars

可以使用bootJar任务构建可执行的jars。如果应用了java插件，这个任务会自动的创建，并且是 BootJar
的实例.
assemble任务会自动配置依赖于bootJar任务，所以运行assemble也会运行bootJar任务。

打包可执行和普通文件

默认的，当bootJar或者bootWar任务配置了，jar或者war任务会被禁用掉。但是可以同时构建一个可执行和普通的文件通过设置jar或者war任务可用：

jar {
    enabled = true
}

为了避免可执行文件和普通文件生成在同一个目录，其中一个应该使用不同的位置。一种方法就是配置一个classifier:

bootJar {
    classifier = 'boot'
}

配置可执行文件打包

BootJar
和 BootWar
任务分别是Gradle的jar或者war任务的子类。所以，所有的在打包jar或者war时用的标准配置都对可执行的jar或者war可用。当然也有对可执行jars或者wars的特殊配置。

配置主类

默认的，可执行文件的主类会自动的在任务的类路径目录里查找一个带有public static void main(String[])的方法。主类也可以显示的使用mainCalss设置：

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

另外，如果应用了 application plugin 可以这么设置mainClassName属性：

mainClassName = 'com.example.ExampleApplication'

最后，Start-Class属性可以在任务的manifest里配置:

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

Excluding Devtools

默认SpringBoot的Devtools模块org.springframework.boot:spring-boot-devtools不会被打包进可执行的jar或者war。如果打包Devtools到文件里，设置excludeDevtools属性为false:

bootWar {
    excludeDevtools = false
}

配置需要移除的库

大多数库可以直接嵌套进可执行的文件里，但是某些库可能有问题。比如,JRuby引入了它自己的内嵌jar支持，比如jruby-complete.jar总是直接在文件系统上可用。
处理这个问题库，可执行文件可以配置在运行(run)的时候移除指定的嵌套jars到临时目录。库可以使用Ant-style模式匹配源jar文件的绝对路径移除需要的包：

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

让文件完全可执行

Spring Boot对完全可执行文件提供支持。通过已知的如何启动应用的预shell脚步来制造完全可执行。在类Unix平台上，这个启动脚本运行文件可以像任何可执行文件直接运行或者作为服务安装。
启用这个特性，launchScript必须启用：

bootJar {
    launchScript {
        included = true
    }
}

这将添加Spring Boot的默认脚本到文件里。默认的启动脚本包含若干个属性并且设置了合适的默认值，当然也可以通过properties属性自定义默认值：

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

如果启动脚本没有你想要的，script属性可以提供一个自定义的启动脚本：

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

使用PropertiesLauncher

要想使用PropertiesLauncher启动可执行jar或者war，配置任务的manifest来设置Main-Class属性：

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

发布应用

使用maven插件发布应用

应用了 maven plugin ,uploadBootArchives的BootArchives上传任务会被自动创建。默认的，bootArchives配置包含了bootJar或者bootWar任务产生文件。uploadBootArchives任务可以这么配置来发布到Maven repository里:

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

使用maven-publish插件发布

使用MavenPublication的artifact方法发布你的Spring Boot jar或者war。将任务传给到你想要发布的artifact方法上。比如，通过默认的bootJar任务发布artifact:

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

使用application插件分发

当使用了application plugin ，boot分发器会被创建。这个分发器包含了通过bootJar或者bootWar任务和脚本在类Unix和Windows上启动。可以通过bootDistZip和bootDistTar任务压缩或者解压构建分发器。

使用Gradle运行程序

使用bootRun任务来运行程序，不需要产生文件：

$ ./gradlew bootRun

bootRun任务是JavaExec子类的 BootRun
的实例. 所以, 所有的 usual configuration options在Gradle里执行Java处理都可用。任务会使用主源文件的运行期类路径自动配置。
默认的，通过查找任务的类路径下的public static void main(String[])会自动配置。
主类也可以显示的配置:

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

另外，如果使用了application pluginmainClassName项目属性可以被使用:

mainClassName = 'com.example.ExampleApplication'

重加载资源

如果项目里加入了devtools，它会自动的监控你的程序变化。另外，如果你配置了bootRun比如静态资源，应用程序的静态资源会从源位置被加载：

bootRun {
    sourceResources sourceSets.main
}

这在开发时很有用。

整合Actuator

生成构建信息

Spring Boot Actuator的信息endpoint自动发布META-INF/build-info.properties文件里的信息。BuildInfo
任务可以用来生成这个文件。最简单的方式是通过插件的DSL使用任务：

springBoot {
    buildInfo()
}

这会配置一个bootBuildInfo的任务BuildInfo
，并且如果他存在，会让Java插件的类任务基于它。任务的目标目录将会是META-INF在主源设置的资源的输出目录(通常是build/resources/main)。
默认的，生成的信息是从项目里派生出来的:

属性可以使用DSL自定义：

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

可以添加额外的构建信息：

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

为其他插件动态化

当使用了其他插件，Spring Boot插件会相应的为项目配置做出一些改变。本章节描述这些改变。

动态化Java插件

当项目里使用了java plugin,Spring Boot插件会:

1. 创建一个名为bootJar的BootJar
   任务，它会为项目创建一个可执行的fat jar。jar会包含所有main source set下运行时的类路径；类会被打包进BOOT-INF/classes里，jars会被打包进BOOT-INF/lib里。
2. 配置一个依赖于bootJar任务的assemble任务。
3. 禁止jar任务
4. 创建一个名为bootRun的BootRun
   任务， 用来运行你的程序。
5. 创建一个名为bootArchives的配置包含通过bootJar产生的artifact。
6. 无需配置，所有的Java编译任务都使用UTF-8。

动态化War插件

当项目用用了Gradle的war plugin，Spring Boot插件会:

1. 创建一个名为bootWar的BootWar
   任务，用来为项目创建可执行的，far war。另外对于标准的打包，所以是providedRuntime的配置都会打包进WEB-INF/lib-provided里；
2. 配置一个依赖于bootWar任务的assemble任务；
3. 禁止war任务；
4. 配置bootArchives任务包含通过bootWar任务产生的artifact。

动态化application插件

当项目使用了Gradle的application plugin插件，Spring Boot插件会：

1. 创建一个名为bootStartScripts的CreateStartScripts的任务，它会创建一个脚本用来使用java -jar命令启动在bootArchives配置里的artifact。
2. 创建一个名为boot的新分发并且将它配置到lib目录下的包含artifact的bootArchives配置里，然后start scripts在bin目录里。
3. 使用mainClassName作为main属性配置bootRuntask。
4. 使用applicationDefaultJvmArgs参数作为jvmArgs属性配置bootRun任务。
5. 使用mainClassName属性在mainifest作为Start-Class入口配置bootJar任务。
6. 使用mainClassName作为mainifest的Start-Class入口配置bootWar任务。

动态化Maven插件

当使用了Gradle的 maven
plugin 插件, Spring Boot插件会配置一个uploadBootArchives上传任务保证在它产生的pom里没有依赖被声明。