Part I. Spring Boot参考文档
本小节是对Spring Boot参考文档的概述. 是文档其余部分的映射.
1. 关于本参考文档
本参考文档支持的文件格式有：
HTML
PDF
EPUB
最新版本路径：docs.spring.io/spring-boot/docs/current/reference.
本文档免费，并且没有任何使用限制。
2. 获取帮助
如果你在使用spring boot时遇到困难，可以通过以下方式获取帮助：
参考How-to文档。它提供了大多数常见问题的解决方案。
学习Spring基础文档。spring boot建立在其他spring项目之上。访问spring.io网站可以获取到大量参考文档。如果你是初学者，可以选择其中一个作为入门引导。
问问题。有什么问题可以在stackoverflow.com上提出，但是要加上spring-boot标签。
可以在github.com/spring-projects/spring-boot/issues上报告spring boot的bug。
[注意]
spring boot及其文档都是开源的，如果你在文档中发现问题或你想要改进他们，请参与进来。
3. 第一步
如果你以正常的方式来开启学习spring boot或spring，请从以下步骤开始：
从头开始: 概述 | 要求 | 安装
辅导教程: Part 1 | Part 2
运行你的示例: Part 1 | Part 2
4. 使用Spring Boot
准备好开始使用Spring Boot了吗? 我们已经为你安排好了:
创建系统: Maven | Gradle | Ant | Starters
最佳实践: Code Structure | @Configuration | @EnableAutoConfiguration | Beans and Dependency Injection
运行你的代码: IDE | Packaged | Maven | Gradle
打包你的应用: 生产jars
Spring Boot命令行界面: 使用命令行界面
5. 学习Spring Boot的特性
需要了解更多Spring Boot核心特性的细节? 请参考以下内容:
核心特性: SpringApplication | External Configuration | Profiles | Logging
Web应用: MVC | Embedded Containers
数据操作: SQL | NO-SQL
消息机制: Overview | JMS
测试: Overview | Boot Applications | Utils
扩展: Auto-configuration | @Conditions
6. 生产
当你要将你的spring boot应用放到生产中，这里有一些诀窍你或许喜欢：
管理终端: Overview | Customization
连接选项: HTTP | JMX
监控: Metrics | Auditing | Tracing | Process
7. 高级主题
最后，我们有一些话题是为高级用户准备的:
Spring Boot应用部署: Cloud Deployment | OS Service
构建工具插件: Maven | Gradle
附录: Application Properties | Auto-configuration classes | Executable Jars
----------------------------------------------------------------------------------------------------------
Part II. 启动
如果你打算用正常的方式开始spring boot或spring，从本节开始。本节解答 “什么？”， “怎么？” 和 “为什么？” 这三个问题。包括对spring boot
的介绍，和安装过程的描述。然后你就可以创建自己的第一个spring boot应用并和我们一起讨论一些spring boot的核心原理了。
8. 介绍Spring Boot
spring boot使得你可以很容易的创建一个可运行的独立的生产级的基于spring的应用。我们对于spring平台和第三方库有自己的规划，这样可以
使你轻松的启动。大多数的spring boot应用只需要很少的spring配置。
你可以使用spring boot创建使用java -jar或更传统的war部署启动的java应用。我们也提供了命令行工具运行“spring 脚本”。
我们的主要目标是：
我们为所有spring 开发提供了一个极端快速和易理解的开发体验。开箱即用，但是当需求开始偏离预设时要及时退出。我们提供了一些大类型项目通用
的非功能特性（例如嵌入式服务器，安全，metric监控，健康检测，和外部化配置）。完全不需要生成代码也不需要任何XML配置。
9. 系统要求
要求Spring Boot 2.0.3.RELEASE，Java 8或9，以及Spring Framework 5.0.7.RELEASE或以上。Maven 3.2+和Gradle 4
9.1 Servlet容器
Spring Boot支持一下嵌入式servlet容器:
名称 Servlet版本
Tomcat 8.5
Jetty 9.4
Undertow 1.4
你也可以将spring boot部署到任何兼容Servlet 3.1+的容器中。
10. 安装Spring Boot
spring boot可以使用经典的java工具安装也可以通过命令行工具来安装。无论哪种方式，都需要java SDK v1.8及以上。开始之前你需要使用以下
命令检查java版本：
$ java -version
如果你是一个java开发的新手或者你想用spring boot做实验，你可以首先尝试一下spring boot命令行。不然，也可以继续阅读经典安装方式
的介绍。
10.1 安装指南
你可以像使用其他java标准库一样使用spring boot。这样做，你的类路径的会包含适当的spring-boot-*.jar文件。spring boot不需要任何
特殊的集成工具，你可以使用任何的IDE或文本编辑器。同样，spring boot应用也没有任何特殊的地方，你可以像其他java程序一样运行和
调试spring boot应用。
相对于拷贝spring boot的jar包，我们强烈建议您使用支持依赖管理的构建工具来导包（例如maven或gradle）；
10.1.1 Maven安装
spring boot需要Apache Maven 3.2或以上。如果你还没有安装maven，你可以参考maven.apache.org上的说明。
[小窍门]
在许多的操作系统中，maven可以通过包管理器来安装。如果你使用OSX Homebrew，可以尝试使用brew安装maven。ubuntu用户可以
运行sudo apt-get install maven。使用Chocolatey的windows用户可以运行choco install maven。
spring boot依赖使用org.springframework.boot groupId。典型的，你的Maven POM文件继承spring-boot-starter-parent项目，
并且声明一个或更多“Starters”。spring boot也提供可选的Maven插件来创建可执行jar。
以下内容展示了一个典型的pom.xml文件配置：
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>myproject</artifactId>
<version>0.0.1-SNAPSHOT</version>
<!-- Inherit defaults from Spring Boot -->
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.0.3.RELEASE</version>
</parent>
<!-- Add typical dependencies for a web application -->
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
</dependencies>
<!-- Package as an executable jar -->
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>
[小窍门]
spring-boot-starter-parent是使用spring boot的很好的方式，但是它并不是所有的时候都适用。有时你需要继承其他的
父POM，或你不喜欢默认的配置。遇到这种情况，查看13.2.2节，13.2.2，“使用没有父POM的Spring Boot”。通过导入域来替代。
10.1.2 Gradle安装
spring boot兼容Gradle 4。如果你还没有安装Gradle，你可以在gradle.org查看安装说明。
可以使用org.springframework.boot group声明spring boot依赖。你的项目可以声明一个或多个“Starters”。spring boot提供了
一个有用的Gradle插件可以去进行简单的依赖声明和创建可执行jar。
Gradle Wrapper
Gradle Wrapper在你需要创建项目时提供了一种很好的获取Gradle的方式。你只需要在你的代码旁边提交很小的脚本和库来辅助创建
过程。参考docs.gradle.org/4.2.1/userguide/gradle_wrapper.html查看详细内容。
以下展示了一个典型的build.gradle文件的内容：
plugins {
id 'org.springframework.boot' version '2.0.3.RELEASE'
id 'java'
}
jar {
baseName = 'myproject'
version = '0.0.1-SNAPSHOT'
}
repositories {
jcenter()
}
dependencies {
compile("org.springframework.boot:spring-boot-starter-web")
testCompile("org.springframework.boot:spring-boot-starter-test")
}
10.2 安装Spring Boot命令行界面
spring boot命令行界面是一个可以使你快速使用spring 原型的命令行工具。它可以使你运行groovy脚本，意味着你可以使用一个没有太多
样本代码的熟悉的类java语法。
你不需要使用命令行界面操作spring boot，但是它确实是使spring应用运行的最快方式。
10.2.1 自定义安装
你可以从spring软件仓库下载spring命令行界面。
spring-boot-cli-2.0.3.RELEASE-bin.zip
spring-boot-cli-2.0.3.RELEASE-bin.tar.gz
简化版同样可以.
下载下来以后，参考解压包中文件INSTALL.txt中的说明进行安装。总之，在解压包的bin/目录下有一个spring脚本。你可以对.jar文件使用
java -jar命令（这个脚本帮助你确保类路径设置正确）。
10.2.2 使用SDKMAN安装!
SDKMAN！（软件开发工具管理器）可以用来管理多个版本的各种二进制SDKs，包括Groovy和spring boot命令行界面。获取SDKMAN!
从sdkman.io下载并且使用以下命令安装spring boot：
$ sdk install springboot
$ spring --versions
如果你要发挥命令行的特性并且想要很容易的获得你所创建的版本，使用以下命令：
$ sdk install springboot dev
/path/to/spring-boot/spring-boot-cli/target/spring-boot-cli-2.0.3.RELEASE-bin/spring-2.0.3.RELEASE/
$ sdk default springboot dev
$ springboot --version
Spring CLI v2.0.3.RELEASE
以上调用dev实例安装了一个本地的spring实例。它指出了你的目标路径，所以每次重新创建spring boot，spring都是最新的。
你可以通过以下命令来查看：
$ sdk ls springboot
================================================================================
Available Springboot Versions
================================================================================
> + dev
* 2.0.3.RELEASE
================================================================================
+ - local version
* - installed
> - currently in use
================================================================================
10.2.3 OSX Homebrew安装
如果你在Mac环境并且使用Homebrew，你可以使用以下命令安装spring boot命令行界面：
$ brew tap pivotal/tap
$ brew install springboot
Homebrew installs spring to /usr/local/bin.
[注意]
如果你没有看到以上结果，你安装的brew可能已经过时了。如果那样，运行brew update并且重试。
10.2.4 MacPorts安装
如果你在Mac环境中使用MacPorts，你可以通过以下命令安装spring boot命令行界面：
$ sudo port install spring-boot-cli
10.2.5 命令行实现
spring boot命令行界面提供BASH和zsh shells命令实现脚本。你可以从任何shell中提取脚本并放在你个人或是系统的bash初始化中。
在一个Debian系统中，系统脚本在/shell-completion/bash文件夹下，并且所有这个文件夹下的脚本在新shell启动时都会执行。例如，
如果使用SDKMAN!安装了命令行界面，可以手动的运行以下命令：
$ . ~/.sdkman/candidates/springboot/current/shell-completion/bash/spring
$ spring <HIT TAB HERE>
grab help jar run test version
[注意]
如果你使用Homebrew或MacPorts安装了spring boot命令行界面，命令行实现脚本会自动注册到你的shell中。
10.2.6 Windows Scoop安装
如果你在windows环境使用Scoop，你可以使用以下命令安装spring boot命令行界面：
> scoop bucket add extras
> scoop install springboot
Scoop installs spring to ~/scoop/apps/springboot/current/bin.
[注意]
如果没有看到以上结果，你安装的scoop可能已经过时。如果那样，运行scoop update并且重试。
10.2.7 快速启动spring命令行界面实例
你可以使用以下web应用测试你的安装。首先，创建一个app.groovy文件，如下：
@RestController
class ThisWillActuallyRun {
@RequestMapping("/")
String home() {
"Hello World!"
}
}
然后在shell中运行文件，如下：
$ spring run app.groovy
[注意]
由于要下载依赖，第一次运行应用会很慢。以后运行会快很多。
在你的浏览器中访问localhost:8080. 你会看到以下输出：
Hello World!
10.3 从早期版本更新Spring Boot
如果你要更新早期的spring boot，参考项目wiki中的“migration guide”，里面提供了详细的更新说明。参考“release notes”中的
“new and noteworthy”，了解每个版本中的新特性。
更新一个已存在的命令行界面版本，使用适当的包管理器命令，如果你是手动安装的命令行界面，参考标准说明书，记得更新环境变量
的路径并移除旧的引用。
11. 开发你的第一个spring boot应用
本节描述了如何开发一个具有spring boot特性的简单的“Hello World”Web应用。考虑到多数IDE的支持，我们使用maven构建这个项目。
[小窍门]
spring.io网站包含了许多使用spring boot的启动引导，如果你有特殊的需求，可以参考那里。你可以跳过以下步骤去start.spring.io在搜
索器中选择Web依赖直接创建项目。这样创建一个新项目后你就可以开始编代码了。可以参考spring初始化文档了解更多细节。
开始之前，打开终端运行以下命令以保证你安装的的java和maven的版本满足要求：
$ java -version
java version "1.8.0_102"
Java(TM) SE Runtime Environment (build 1.8.0_102-b14)
Java HotSpot(TM) 64-Bit Server VM (build 25.102-b14, mixed mode)
$ mvn -v
Apache Maven 3.3.9 (bb52d8502b132ec0a5a3f4c09453c07478323dc5; 2015-11-10T16:41:47+00:00)
Maven home: /usr/local/Cellar/maven/3.3.9/libexec
Java version: 1.8.0_102, vendor: Oracle Corporation
[注意]
本样例需要创建文件夹。随后的介绍假设你在自己的目录中已经创建好了合适的文件夹。
11.1 创建POM
开始时我们需要创建一个maven的pom.xml文件，用来创建你的项目。打开你的文本编辑器添加以下内容：
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>myproject</artifactId>
<version>0.0.1-SNAPSHOT</version>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.0.3.RELEASE</version>
</parent>
<!-- Additional lines to be added here... -->
</project>
[注意]
在这一点上，你可以使用IDE（支持maven）导入项目。为了简单，本例我们继续使用文本编辑器。
11.2 添加依赖
spring boot提供了一系列“Starters”来使你在类路径中添加jar包。我们的应用样例已经在pom的父本标签部分使用了
spring-boot-starter-parent。spring-boot-starter-parent提供了非常有用的对maven的默认支持。它同样提供了依赖管理功能使你在
添加“blessed”（spring boot的依赖）依赖时不需要再加版本标签。
“Starters”也会提供你开发应用时所需要的其他依赖。由于我们是开发web应用，我们会添加一个spring-boot-starter-web依赖。在此之前
我们可以通过运行以下命令查看现有依赖：
$ mvn dependency:tree
[INFO] com.example:myproject:jar:0.0.1-SNAPSHOT
mvn dependency:tree命令打印出你项目的依赖树。你可以看到spring-boot-starter-parent本身没有提供任何的依赖。可以在父本标签
下面添加spring-boot-starter-web依赖，如下：
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
</dependencies>
如果你再次运行mvn dependency:tree，你会看到包括Tomcat服务器和spring boot在内的一系列依赖。
11.3 编写代码
为了完成我们的应用，我们需要创建一个java文件。包括以下内容：
import org.springframework.boot.*;
import org.springframework.boot.autoconfigure.*;
import org.springframework.web.bind.annotation.*;
@RestController
@EnableAutoConfiguration
public class Example {
@RequestMapping("/")
String home() {
return "Hello World!";
}
public static void main(String[] args) throws Exception {
SpringApplication.run(Example.class, args);
}
}
虽然代码不多，但是发生了好多事情。接下来我们逐步介绍。
11.3.1 @RestController和@RequestMapping注解
实例文件中第一个注解是@RestController。这是一个很老的注解。他告诉spring本类的角色是一个web@Controller（控制器），因此
处理web请求时spring就会考虑调用这个类。
@RequestMapping注解提供路径信息。它告诉spring任何满足“/”路径的HTTP请求都会映射到home方法。@RestController注解告诉spring
将结果字符串返回给请求者。
[小窍门]
@RestController和@RequestMapping注解是spring MVC注解. (并不是Spring Boot特有.) 在spring 参考文档中查看MVC部分可以
了解更多细节。
11.3.2 @EnableAutoConfiguration注解
第二个类级注解是@EnableAutoConfiguration。这个注解告诉Spring Boot根据已添加的依赖猜测你将如何配置spring。由于
spring-boot-starter-web添加了Tomcat和Spring MVC，自动配置认为你在开发Web应用，所以对spring进行了相应的设置。
启动器和自动配置：
自动配置被设计为可以很好的支持“Starters”，但是两者并不是直接捆绑在一起的。你也可以选择外部的依赖，spring boot
依然尽可能的将其自动配置到你的应用中。
11.3.3 “main”方法
应用的最后部分是main方法。它只是一个标准的遵循java约定的应用入口方法。我们的main方法通过调用run方法将入口委托给
spring boot的SpringApplication类。SpringApplication引导我们的应用开启spring，反过来，通过spring开启自动配置
Tomcat服务器。我们需要将Example.class作为run方法的参数来告诉SpringApplication哪个是主要的spring组件。参数列表也会
用来显示一些命令行参数。
11.4 运行实例
在本节，你的应用将会运行起来。由于你使用了spring-boot-starter-parent POM，你有一个的很好运行目标。在项目的根目录运行
mvn spring-boot:run来开启应用。你会看到类似以下内容的输出：
$ mvn spring-boot:run
. ____ _ __ _ _
/\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
\\/ ___)| |_)| | | | | || (_| | ) ) ) )
' |____| .__|_| |_|_| |_\__, | / / / /
=========|_|==============|___/=/_/_/_/
:: Spring Boot :: (v2.0.3.RELEASE)
....... . . .
....... . . . (log output here)
....... . . .
........ Started Example in 2.222 seconds (JVM running for 6.514)
If you open a web browser to localhost:8080, you should see the following output:
Hello World!
To gracefully exit the application, press ctrl-c.
11.5 创建一个可运行jar
我们通过创建一个可以运行在生产中的完全独立的可执行jar文件作为本实例的结束。可执行jars（有时也叫“fat jars”）中包含了你的编译类
以及所有代码运行需要的依赖。
可运行jars和Java：
java不支持jar文件间的嵌入。这样出现的问题是你很难部署一个自己的独立应用。
为了解决这个问题，许多开发者生使用“uber” jars. 一个uber jar将所有应用所需依赖的类文件打包在了一起。这样就很难看出
你的应用中都有哪些库。并且有同样文件名的属于不同jar的不同文件也不能一起放在uber jar中。
spring boot使用了一种不同的方式使得可以直接内嵌jar。
创建一个可执行jar，我们需要在pom.xml中添加spring-boot-maven-plugin。具体操作是在依赖标签下面插入以下内容：
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
[注意]
spring-boot-starter-parent POM包含<executions>配置来绑定重新打包。如果你不是用父本（parent）POM，你需要自己声明这个配置。
查看插件文档了解更多细节。
保存你的pom.xml并且在命令行运行以下内容：
$ mvn package
[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Building myproject 0.0.1-SNAPSHOT
[INFO] ------------------------------------------------------------------------
[INFO] .... ..
[INFO] --- maven-jar-plugin:2.4:jar (default-jar) @ myproject ---
[INFO] Building jar: /Users/developer/example/spring-boot-example/target/myproject-0.0.1-SNAPSHOT.jar
[INFO]
[INFO] --- spring-boot-maven-plugin:2.0.3.RELEASE:repackage (default) @ myproject ---
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
如果你查看目标目录，你应该会看到myproject-0.0.1-SNAPSHOT.jar。这个文件大约10M大小。如果你想要查看文件里面的内容，你可以使用
jar tvf，如下：
$ jar tvf target/myproject-0.0.1-SNAPSHOT.jar
你会在目标文件夹中看到一个更小的名为myproject-0.0.1-SNAPSHOT.jar.original的文件。这是maven创建的spring boot重新打包之前的
原始jar文件。
运行应用，使用java -jar命令, 如下:
$ java -jar target/myproject-0.0.1-SNAPSHOT.jar
. ____ _ __ _ _
/\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
\\/ ___)| |_)| | | | | || (_| | ) ) ) )
' |____| .__|_| |_|_| |_\__, | / / / /
=========|_|==============|___/=/_/_/_/
:: Spring Boot :: (v2.0.3.RELEASE)
....... . . .
....... . . . (log output here)
....... . . .
........ Started Example in 2.536 seconds (JVM running for 2.864)
ctrl-c退出应用。
12. 导读
本节提供了一些spring boot的基本内容，并且指导你写了自己的应用。如果你是一个以工作为导向的开发者，你可能想要跳到spring.io的启动
指南来定制自己的spring启动方式。我们同样有spring boot的“How-to”参考文档。
spring boot仓库也有很多你可以运行的样例。这些样例是独立的。
另外，下一步是阅读Part III, “Using Spring Boot”。如果你实在缺乏耐心，你可以直接跳到spring boot特性部分。