1.5.2.RELEASE

Part I. Spring Boot 文档

本节简要介绍了Spring Boot文档，是整个文档的参考指南。 您可以完整阅读本参考指南，或者如果您不感兴趣的话可以跳过该部分。

1. 关于文档

Spring Boot参考指南可以以 html，pdf 和 epub 文档的形式获取。 最新版本的文档可在http://docs.spring.io/spring-boot/docs/current/reference 中找到。

本文档您可以自己使用，或发布给别人，印刷版还是以电子形式都可以，但必须包含本版权声明，不可进行盈利。

2. 获得帮助

如果使用 Spring Boot 时遇到问题，可以在下面获取帮助：

• 尝试 How-to’s - 这里为最常见的问题提供解决方案。
• 了解Spring的基础知识 - Spring Boot建立在许多其他Spring项目上，请查看 spring.io 网站以获取其他项目的参考文档。 如果您刚刚开始使用Spring，请阅读这个指南。
• 在stackoverflow上提问题 - 我们会一起关注 stackoverflow.com 上有spring-boot标签的问题。
• 在Github上报告bug。

Spring Boot 所有的东西都是开源的，包括文档！ 如果您发现文档有问题; 或者如果你想改进他们，欢迎参与。

3. 第一步

如果你刚刚开始使用 Spring Boot，或刚刚开始使用“Spring”，请从这里开始！

• 从头开始：概述 | 要求 | 安装
• 教程：Part 1 | Part 2
• 运行你的例子：Part 1 | Part 2

4. 使用 Spring Boot

• 构建系统: Maven | Gradle | Ant | Starters
• 最佳做法：代码结构 | @Configuration | @EnableAutoConfiguration | Beans 和依赖注入
• 运行代码：IDE | Packaged | Maven | Gradle
• 打包应用程序： Production jars
• Spring Boot CLI：使用CLI

5. 了解Spring Boot功能

需要有关Spring Boots核心功能的更多细节？请看这里

• 核心功能: SpringApplication | External Configuration | Profiles | Logging
• Web 应用: MVC | Embedded Containers
• 数据处理: SQL | NO-SQL
• 消息处理: Overview | JMS
• 测试: Overview | Boot Applications | Utils
• 扩展: Auto-configuration | @Conditions

6. 转移到生产环境

当您准备好将Spring Boot 应用程序放到生产环境时，我们有一些您可能会喜欢的技巧！

• 部署 Spring Boot 应用程序: Cloud Deployment | OS Service
  构建工具插件：Maven | Gradle
  附录: Application Properties | 自动配置类 | 可执行 Jars

Part II. 入门指南

如果你刚刚开始使用Spring Boot，这是你的一部分内容！ 在这里我们将会回答一些基本的what?”, “how?” 和 “why?”的问题。 在这里你会找到一个详细的介绍Spring Boot和安装说明。 然后，我们将构建我们的第一个Spring Boot应用程序，并讨论一些核心原则。

8. Spring Boot 介绍

Spring Boot可以基于Spring轻松创建可以“运行”的、独立的、生产级的应用程序。 对Spring平台和第三方类库我们有一个自己看法，所以你最开始的时候不要感到奇怪。 大多数Spring Boot应用程序需要很少的Spring配置。

您可以使用Spring Boot创建可以使用java -jar或传统 war 包部署启动的Java应用程序。 我们还提供一个运行“spring脚本”的命令行工具。

我们的主要目标是：

• 为所有的Spring开发者提供一个更快，更广泛接受的入门体验。
• Be opinionated out of the box, but get out of the way quickly as requirements start to diverge from the defaults.
• 提供大量项目中常见的一系列非功能特征（例如嵌入式服务器，安全性，指标，运行状况检查，外部化配置）。
• 绝对没有代码生成，也不需要XML配置。

9. 系统要求

默认情况下，Spring Boot 1.5.2.RELEASE需要Java 7和Spring Framework 4.3.7.RELEASE或更高版本。 您可以进行一些其他配置在Java 6上使用Spring Boot。 有关详细信息，请参见第84.11节“如何使用Java 6”。 为Maven（3.2+）和Gradle 2（2.9或更高版本）和3提供了显式构建支持。

虽然您可以在Java 6或7上使用 Spring Boot，但我们通常推荐Java 8。

9.1 Servlet容器

以下嵌入式servlet容器可以直接使用：

您还可以将Spring Boot应用程序部署到任何兼容Servlet 3.0+ 的容器中。

10. 安装 Spring Boot

Spring Boot可以与“经典(classic)”Java开发工具一起使用或作为命令行工具安装。 无论如何，您将需要Java SDK v1.6或更高版本。 在开始之前检查当前的Java安装：

1

$ java -version

如果您是Java开发的新手，或者您只想尝试一下 Spring Boot，您可能需要首先尝试使用 Spring Boot CLI，如果想正式使用Spring Boot，请阅读“经典(classic)”安装说明。

虽然Spring Boot 与Java 1.6兼容，但我们建议使用最新版本的Java。

10.1 Java开发程序员安装说明

Spring Boot的使用方式与标准Java库的使用相同，只需在类路径中包含适当的spring-boot-*.jar文件。Spring Boot不需要任何特殊的集成工具，所以可以使用任何IDE或文本编辑器进行开发；并且Spring Boot 应用程序没有什么特殊的地方，因此您可以像其他Java程序一样运行和调试。虽然您可以直接复制Spring Boot 的jar包，但我们通常建议您使用依赖关系管理的构建工具（如Maven或Gradle）。

10.1.1 Maven安装

Spring Boot 兼容 Apache Maven 3.2。 如果您还没有安装Maven，可以按照 https://maven.apache.org/ 上的说明进行安装。

在许多操作系统上，Maven可以通过软件包管理器进行安装。 如果您是OSX Homebrew用户，请尝试使用命令：brew install maven。 Ubuntu用户可以运行命令：sudo apt-get install maven。

Spring Boot 依赖 org.springframework.boot groupId。通常，您的Maven POM文件将从 spring-boot-starter-parent 项目继承，并声明一个或多个“启动器(启动器)”的依赖关系。Spring Boot还提供了一个可选的Maven插件来创建可执行的jar包。

典型的pom.xml文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

<?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>1.5.2.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节“使用不带父POM的Spring Boot”作为使用导入作用域(import scope)的替代解决方案。

10.1.2 Gradle 安装

Spring Boot 兼容 Gradle 2（2.9或更高版本）和Gradle 3。如果您尚未安装Gradle，您可以按照http://www.gradle.org/ 上的说明进行操作。

可以使用org.springframework.boot 组(group)声明Spring Boot 的依赖项。 通常，您的项目将声明一个或多个“启动器(Starters)”的依赖。Spring Boot提供了一个有用的Gradle插件，可用于简化依赖关系声明和创建可执行 jar包。

Gradle Wrapper

当您需要构建项目时，Gradle Wrapper提供了一种“获取(obtaining)”Gradle的更好的方式。 它是一个小脚本和库，它与代码一起引导构建过程。 有关详细信息，请参阅https://docs.gradle.org/2.14.1/userguide/gradle_wrapper.html 。

典型的 build.gradle 文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

plugins {
    id 'org.springframework.boot' version '1.5.2.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 CLI

Spring Boot CLI是一个命令行工具，如果要使用Spring快速原型(quickly prototype)，可以使用它。 它允许您运行Groovy脚本，这意味着会有您熟悉的类似Java的语法，没有太多的样板代码(boilerplate code)。

您也不必要通过CLI来使用Spring Boot，但它绝对是开始Spring应用程序最快方法。

10.2.1 手动安装

您可以从Spring软件版本库下载Spring CLI发行版：

• spring-boot-cli-1.5.2.RELEASE-bin.zip
• spring-boot-cli-1.5.2.RELEASE-bin.tar.gz

各发布版本的快照。

下载完成后，请按照解压缩后文件中的INSTALL.txt的说明进行操作。 总而言之：在.zip文件的bin/目录中有一个spring脚本（Windows的spring.bat），或者你可以使用java -jar（脚本可以帮助您确保类路径设置正确）。

10.2.2 使用SDKMAN!安装

SDKMAN!（软件开发套件管理器）可用于管理各种二进制SDK的多个版本，包括Groovy和Spring Boot CLI。从http://sdkman.io/ 获取SDKMAN！并安装Spring Boot。

1
2
3

$ sdk install springboot
$ spring --version
Spring Boot v1.5.2.RELEASE

如果您正在开发CLI的功能，并希望轻松访问刚创建的版本，请遵循以下额外说明。

1
2
3
4

$ sdk install springboot dev /path/to/spring-boot/spring-boot-cli/target/spring-boot-cli-1.5.2.RELEASE-bin/spring-1.5.2.RELEASE/
$ sdk default springboot dev
$ spring --version
Spring CLI v1.5.2.RELEASE

这将安装一个称为dev的spring的本地实例(instance)。 它指向您构建位置的target，所以每次重建(rebuild)Spring Boot时，Spring 将是最新的。

你可以看到：

1
2
3
4
5
6
7
8
9
10
11
12
13

$ sdk ls springboot
================================================================================
Available Springboot Versions
================================================================================
> + dev
* 1.5.2.RELEASE
================================================================================
+ - local version
* - installed
> - currently in use
================================================================================

10.2.3 OSX Homebrew 安装

如果您在Mac上使用 Homebrew，安装Spring Boot CLI 只需要下面命令：

1
2

$ brew tap pivotal/tap
$ brew install springboot

Homebrew会将Spring 安装到 /usr/local/bin。

如果您没有看到公式(formula)，您的安装可能会过期。 只需执行brew更新，然后重试。

10.2.4 MacPorts安装

如果您在Mac上使用 MacPorts，安装Spring Boot CLI 只需要下面命令：

1

$ sudo port install spring-boot-cli

10.2.5 命令行补全

Spring Boot CLI为BASH和zsh shell提供命令补全的功能。 您可以在任何shell中引用脚本（也称为spring），或将其放在您的个人或系统范围的bash完成初始化中。 在Debian系统上，系统范围的脚本位于 /shell-completion/bash 中，当新的shell启动时，该目录中的所有脚本将被执行。 手动运行脚本，例如 如果您使用SDKMAN安装了！

1
2
3

$ . ~/.sdkman/candidates/springboot/current/shell-completion/bash/spring
$ spring <HIT TAB HERE>
  grab  help  jar  run  test  version

如果使用Homebrew或MacPorts安装Spring Boot CLI，则命令行补全脚本将自动注册到您的shell。

10.2.6 快速启动Spring CLI示例

这是一个非常简单的Web应用程序，可用于测试您的安装是否正确。 创建一个名为app.groovy的文件：

1
2
3
4
5
6
7
8
9

@RestController
class ThisWillActuallyRun {
    @RequestMapping("/")
    String home() {
        "Hello World!"
    }
}

然后从shell运行它：

1

$ spring run app.groovy

因为下载依赖的库，首次运行应用程序需要一些时间，。 后续运行将会更快。

在浏览器中打开 http://localhost:8080 ，您应该会看到以下输出：

1

Hello World!

10.3 从早期版本的Spring Boot升级

如果您从早期版本的 Spring Boot 升级，请检查项目wiki上托管的“发行说明”。 您将找到升级说明以及每个版本的“新的和值得注意的”功能的列表。

要升级现有的CLI安装，请使用包管理工具相应的package manager命令（例如brew upgrade），如果您手动安装了CLI，请按照标准说明记住更新PATH环境变量以删除任何旧的引用。

11. 开发您的第一个Spring Boot应用程序

让我们在Java中开发一个简单的“Hello World！”Web应用程序，突显Spring Boot一些主要的功能。 我们将使用Maven构建该项目，因为大多数IDE支持它。

https://spring.io/ 包含许多使用Spring Boot的“入门指南”。 如果您正在寻求解决一些具体问题; 可以先看一下那里。

您可以在 https://start.spring.io/ 的依赖关系搜索器中选择Web启动器来快速完成以下步骤。
这会自动生成一个新的项目结构，方便您立即开始编码。 查看文档了解更多详细信息。

在开始之前，打开终端来检查您是否安装了有效的Java和Maven版本。

1
2
3
4
5
6
7
8
9
10

$ java -version
java version "1.7.0_51"
Java(TM) SE Runtime Environment (build 1.7.0_51-b13)
Java HotSpot(TM) 64-Bit Server VM (build 24.51-b03, mixed mode)
$ mvn -v
Apache Maven 3.2.3 (33f8c3e1027c3ddde99d3cdebad2656a31e8fdf4; 2014-08-11T13:58:10-07:00)
Maven home: /Users/user/tools/apache-maven-3.1.1
Java version: 1.7.0_51, vendor: Oracle Corporation

这个示例需要在其自己的文件夹中创建。 后面我们假设您在当前目录已经创建了一个正确的文件夹。

11.1 创建POM

我们需要先创建一个Maven pom.xml文件。 pom.xml是用于构建项目的配置文件。打开编辑器并添加以下内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

<?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>1.5.2.RELEASE</version>
    </parent>
    <!-- Additional lines to be added here... -->
</project>

这应该给你一个工作构建(working build)，你可以通过运行 mvn package 进行测试（你可以暂时忽略警告：“jar will be empty - no content was marked for inclusion!”）。

现在，您可以将项目导入到IDE中（最新的Java IDE内置对Maven的支持）。 为了简单起见，这个示例我们继续使用纯文本编辑器。

11.2 添加类路径依赖关系

Spring Boot提供了一些“启动器(Starters)”，可以方便地将jar添加到类路径中。我们的示例应用程序已经在POM的父部分使用了spring-boot-starter-parent。spring-boot-starter-parent是一个特殊启动器，提供一些Maven的默认值。它还提供依赖管理 dependency-management 标签，以便您可以省略子模块依赖关系的版本标签。

其他“启动器(Starters)”只是提供您在开发特定类型的应用程序时可能需要的依赖关系。 由于我们正在开发Web应用程序，所以我们将添加一个spring-boot-starter-web依赖关系，但在此之前，我们来看看我们目前的依赖。

1
2
3

$ mvn dependency:tree
[INFO] com.example:myproject:jar:0.0.1-SNAPSHOT

mvn dependency:tree：打印项目依赖关系的树形表示。 您可以看到spring-boot-starter-parent本身不在依赖关系中。 编辑pom.xml并在 parent 下添加spring-boot-starter-web依赖关系：

1
2
3
4
5
6

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
</dependencies>

如果您再次运行 mvn dependency:tree ，您将看到现在有许多附加依赖关系，包括Tomcat Web服务器和Spring Boot本身。

11.3 编写代码

要完成我们的应用程序，我们需要创建一个的Java文件。 默认情况下，Maven将从src/main/java编译源代码，因此您需要创建该文件夹结构，然后添加一个名为src/main/java/Example.java的文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

import org.springframework.boot.*;
import org.springframework.boot.autoconfigure.*;
import org.springframework.stereotype.*;
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 注解

我们的Example类的第一个注解是@RestController。 这被称为 stereotype annotation。它为人们阅读代码提供了一些提示，对于Spring来说，这个类具有特定的作用。在这里，我们的类是一个web @Controller，所以Spring在处理传入的Web请求时会考虑这个类。

@RequestMapping注解提供“路由”信息。 告诉Spring，任何具有路径“/”的HTTP请求都应映射到home方法。 @RestController注解告诉Spring将生成的字符串直接返回给调用者。

@RestController和@RequestMapping注解是Spring MVC 的注解（它们不是Spring Boot特有的）。 有关更多详细信息，请参阅Spring参考文档中的MVC部分。

11.3.2 @EnableAutoConfiguration注解

第二个类级别的注释是@EnableAutoConfiguration。 这个注解告诉 Spring Boot 根据您添加的jar依赖关系来“猜(guess)”你将如何配置Spring。由于spring-boot-starter-web添加了Tomcat和Spring MVC，自动配置将假定您正在开发Web应用程序并相应地配置Spring。

启动器和自动配置

自动配置旨在与“起动器”配合使用，但两个概念并不直接相关。 您可以自由选择启动器之外的jar依赖项，Spring Boot仍然会自动配置您的应用程序。

11.3.3 “main”方法

我们的应用程序的最后一部分是main()方法。 这只是一个遵循Java惯例的应用程序入口点的标准方法。 我们的main()方法通过调用run()委托(delegates)给Spring Boot的SpringApplication类。 SpringApplication将引导我们的应用程序，启动Spring，然后启动自动配置的Tomcat Web服务器。 我们需要将Example.class作为一个参数传递给run方法来告诉SpringApplication，它是主要的Spring组件。 还传递了args数组以传递命令行参数。

11.4 运行示例

由于我们使用了spring-boot-starter-parent POM，所以我们有一个可用的运行目标，我们可以使用它来启动应用程序。 键入mvn spring-boot：从根目录运行以启动应用程序：

1
2
3
4
5
6
7
8
9
10
11
12
13

$ mvn spring-boot:run
  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::  (v1.5.2.RELEASE)
....... . . .
....... . . . (log output here)
....... . . .
........ Started Example in 2.222 seconds (JVM running for 6.514)

如果你用浏览器打开 http://localhost:8080 你应该看到以下输出：

1

Hello World!

ctrl-c 正常(gracefully)退出应用程序。

11.5 创建可执行的jar

让我们完成我们的例子，创建一个完全自包含的可执行jar文件，我们可以在生产环境中运行。 可执行的jar（有时称为“fat jars”）是包含编译的类以及代码运行所需要的所有jar包依赖的归档(archives)。

可执行jar和Java

Java不提供任何标准的方法来加载嵌套的jar文件（即本身包含在jar中的jar文件）。 如果您正在寻找可以发布自包含的应用程序，这可能是有问题的。
为了解决这个问题，许多开发人员使用“uber” jars。 一个uber jar简单地将所有类、jar包进行档案。 这种方法的问题是，很难看到您在应用程序中实际使用哪些库。 如果在多个jar中使用相同的文件名（但具有不同的内容），也可能会出现问题。
Spring Boot采用一个不同的方法这样可以直接对jar进行嵌套。

要创建可执行的jar，我们需要将spring-boot-maven-plugin添加到我们的pom.xml中。 在下方插入以下行：

1
2
3
4
5
6
7
8

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
    </plugins>
</build>

spring-boot-starter-parent POM 包括绑定重新包装目标的 配置。 如果您不使用该父POM，您将需要自己声明此配置。 有关详细信息，请参阅插件文档。

保存您的pom.xml并从命令行运行 mvn package：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

$ 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:1.5.2.RELEASE:repackage (default) @ myproject ---
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------

如果你看看target目录，你应该看到myproject-0.0.1-SNAPSHOT.jar。 该文件的大小约为10 MB。 如果你想查看里面，可以使用jar tvf：

1

$ jar tvf target/myproject-0.0.1-SNAPSHOT.jar

您还应该在target目录中看到一个名为myproject-0.0.1-SNAPSHOT.jar.original的较小文件。 这是Maven在Spring Boot重新打包之前创建的原始jar文件。

使用java -jar命令运行该应用程序：

1
2
3
4
5
6
7
8
9
10
11
12
13

$ java -jar target/myproject-0.0.1-SNAPSHOT.jar
  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::  (v1.5.2.RELEASE)
....... . . .
....... . . . (log output here)
....... . . .
........ Started Example in 2.536 seconds (JVM running for 2.864)

像之前一样，ctrl+c正常退出应用程序。

12. 接下来读什么

希望本节能为您提供一些Spring Boot基础知识，并让您准备编写自己的应用程序。 如果你是一个面向具体任务的开发人员，你可能想跳过 https://spring.io/ ，看看一些解决具体的“如何用Spring”问题的入门指南; 我们还有Spring Boot-specific How-to参考文档。

Spring Boot库还有一大堆可以运行的示例。 示例与代码的其余部分是独立的（这样您不需要构建多余的代码来运行或使用示例）。

下一个是第三部分“使用 Spring Boot”。 如果你真的没有这个耐心，也可以跳过去阅读Spring Boot功能。

Part III. 使用 Spring Boot

本部分将详细介绍如何使用Spring Boot。 这部分涵盖诸如构建系统，自动配置以及如何运行应用程序等主题。 我们还介绍了一些Spring Boot的最佳实践(best practices)。 虽然Spring Boot没有什么特殊之处（它只是一个可以使用的库），但是有一些建议可以让您的开发过程更容易一些。

如果您刚刚开始使用Spring Boot，那么在深入本部分之前，您应该阅读入门指南。

13. 构建系统

强烈建议您选择一个支持依赖管理并可以使用“Maven Central”存储库的构建系统。 我们建议您选择Maven或Gradle。 Spring Boot 可以与其他构建系统（例如 Ant ）配合使用，但是它们不会得到很好的支持。

13.1 依赖管理

每个版本的Spring Boot提供了一个它所支持的依赖关系列表。 实际上，您不需要为构建配置文件中的这些依赖关系提供版本，因为Spring Boot会为您进行管理这些依赖的版本。 当您升级Spring Boot本身时，这些依赖关系也将以一致的进行升级。

如果您觉得有必要，您仍然可以指定一个版本并覆盖Spring Boot建议的版本。

管理的列表中包含可以使用Spring Boot的所有Spring模块以及第三方库的精简列表。 该列表可作为标准的物料(Materials)清单（spring-boot-dependencies）使用，并且还提供了对 Maven 和 Gradle 的额外支持。

Spring Boot的每个版本与Spring Framework的基本版本相关联，因此我们强烈建议您不要自己指定其版本。

13.2 Maven

Maven用户可以从 spring-boot-starter-parent-parent 项目中继承，以获得合理的默认值。 父项目提供以下功能：

• Java 1.6作为默认编译器级别。
• 源代码UTF-8编码。
• 依赖关系管理，允许您省略常见依赖的标签，其默认版本继承自spring-boot-dependencies POM。
• 更合理的资源过滤。
• 更合理的插件配置（exec plugin，surefire，Git commit ID，shade）。
• 针对application.properties和application.yml的更合理的资源过滤，包括特定的文件（例如application-foo.properties和application-foo.yml）
• 最后一点：由于默认的配置文件接受Spring样式占位符（${…}），Maven过滤更改为使用 @..@ 占位符（您可以使用Maven属性resource.delimiter覆盖它）。

13.2.1 继承启动器parent

要将项目配置为继承spring-boot-starter-parent，只需设置标签如下：

1
2
3
4
5
6

<!-- Inherit defaults from Spring Boot -->
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>1.5.2.RELEASE</version>
</parent>

您只需要在此依赖项上指定Spring Boot版本号。 如果您导入其他起始器，则可以放心地省略他们的版本号。

通过该设置，您还可以通过覆盖自己的项目中的属性来覆盖单个依赖。 例如，要升级到另一个 Spring Data 版本序列，您需要将以下内容添加到您的pom.xml中。

1
2
3

<properties>
    <spring-data-releasetrain.version>Fowler-SR2</spring-data-releasetrain.version>
</properties>

检查 spring-boot-dependencies pom 以获取支持的属性列表。

13.2.2 使用没有父POM的 Spring Boot

不是每个人都喜欢从spring-boot-starter-parent POM继承。 您公司可能有自己标准的父母，或者您可能只希望明确声明所有的Maven配置。

如果您不想使用spring-boot-starter-parent，则仍然可以通过使用scope=import依赖来保持依赖管理（但不是插件管理）的好处：

1
2
3
4
5
6
7
8
9
10
11
12

<dependencyManagement>
     <dependencies>
        <dependency>
            <!-- Import dependency management from Spring Boot -->
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-dependencies</artifactId>
            <version>1.5.2.RELEASE</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

该设置不允许您使用如上所述的属性来覆盖单个依赖关系。 要实现相同的结果，您需要在spring-boot-dependencies条目之前在项目的dependencyManagement中添加一个条目。 例如，要升级到另一个Spring Data发行序列，您需要将以下内容添加到您的pom.xml中。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

<dependencyManagement>
    <dependencies>
        <!-- Override Spring Data release train provided by Spring Boot -->
        <dependency>
            <groupId>org.springframework.data</groupId>
            <artifactId>spring-data-releasetrain</artifactId>
            <version>Fowler-SR2</version>
            <scope>import</scope>
            <type>pom</type>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-dependencies</artifactId>
            <version>1.5.2.RELEASE</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

在上面的例子中，我们指定了一个BOM，但是任何依赖关系类型都可以被这样覆盖。

13.2.3 更改Java版本

spring-boot-starter-parent选择相当保守的Java兼容性版本。 如果要遵循我们的建议并使用更高版本的Java版本，可以添加java.version属性：

1
2
3

<properties>
    <java.version>1.8</java.version>
</properties>

13.2.4 使用Spring Boot Maven插件

Spring Boot包括一个Maven插件，可以将项目打包成可执行jar。 如果要使用它，请将插件添加到部分：

1
2
3
4
5
6
7
8

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
    </plugins>
</build>

如果您使用Spring Boot启动器 parent pom，则只需要添加这个插件，除非您要更改parent中定义的设置，否则不需要进行配置。

13.3 Gradle

Gradle用户可以直接在其依赖关系部分导入“启动器”。 不像Maven，没有“超级父”导入来共享一些配置。

1
2
3
4
5
6
7

repositories {
    jcenter()
}
dependencies {
    compile("org.springframework.boot:spring-boot-starter-web:1.5.2.RELEASE")
}

spring-boot-gradle-plugin也是可用的，它提供了从源代码创建可执行jar并运行项目的任务。 它还提供依赖关系管理，除其他功能外，还允许您省略由Spring Boot管理的任何依赖关系的版本号：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

plugins {
    id 'org.springframework.boot' version '1.5.2.RELEASE'
    id 'java'
}
repositories {
    jcenter()
}
dependencies {
    compile("org.springframework.boot:spring-boot-starter-web")
    testCompile("org.springframework.boot:spring-boot-starter-test")
}

13.4 Ant

可以使用Apache Ant + Ivy构建Spring Boot项目。 spring-boot-antlib“AntLib”模块也可用于帮助Ant创建可执行文件。

要声明依赖关系，典型的ivy.xml文件将如下所示：

1
2
3
4
5
6
7
8
9
10
11

<ivy-module version="2.0">
    <info organisation="org.springframework.boot" module="spring-boot-sample-ant" />
    <configurations>
        <conf name="compile" description="everything needed to compile this module" />
        <conf name="runtime" extends="compile" description="everything needed to run this module" />
    </configurations>
    <dependencies>
        <dependency org="org.springframework.boot" name="spring-boot-starter"
            rev="${spring-boot.version}" conf="compile" />
    </dependencies>
</ivy-module>

典型的build.xml将如下所示：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

<project
    xmlns:ivy="antlib:org.apache.ivy.ant"
    xmlns:spring-boot="antlib:org.springframework.boot.ant"
    name="myapp" default="build">
    <property name="spring-boot.version" value="1.3.0.BUILD-SNAPSHOT" />
    <target name="resolve" description="--> retrieve dependencies with ivy">
        <ivy:retrieve pattern="lib/[conf]/[artifact]-[type]-[revision].[ext]" />
    </target>
    <target name="classpaths" depends="resolve">
        <path id="compile.classpath">
            <fileset dir="lib/compile" includes="*.jar" />
        </path>
    </target>
    <target name="init" depends="classpaths">
        <mkdir dir="build/classes" />
    </target>
    <target name="compile" depends="init" description="compile">
        <javac srcdir="src/main/java" destdir="build/classes" classpathref="compile.classpath" />
    </target>
    <target name="build" depends="compile">
        <spring-boot:exejar destfile="build/myapp.jar" classes="build/classes">
            <spring-boot:lib>
                <fileset dir="lib/runtime" />
            </spring-boot:lib>
        </spring-boot:exejar>
    </target>
</project>

请参见第84.10节“从Ant构建可执行存档，而不使用spring-boot-antlib”如果不想使用spring-boot-antlib模块，请参阅“操作方法”。

13.5 启动器

启动器是一组方便的依赖关系描述符，可以包含在应用程序中。 您可以获得所需的所有Spring和相关技术的一站式服务，无需通过示例代码搜索和复制粘贴依赖配置。 例如，如果要开始使用Spring和JPA进行数据库访问，那么只需在项目中包含spring-boot-starter-data-jpa依赖关系即可。

启动器包含许多依赖关系，包括您需要使项目快速启动并运行，并具有一致的受支持的依赖传递关系。

What’s in a name

所有正式起动器都遵循类似的命名模式： spring-boot-starter- ，其中是特定类型的应用程序。 这个命名结构旨在帮助你快速找到一个启动器。 许多IDE中的Maven插件允许您按名称搜索依赖项。 例如，安装Eclipse或STS的Maven插件后，您可以简单地在POM编辑器中点击 Dependency Hierarchy，并在filter输入“spring-boot-starter”来获取完整的列表。
如创建自己的启动器部分所述，第三方启动程序不应该从Spring-boot开始，因为它是为正式的Spring Boot artifacts 保留的。 acme 的 第三方启动器通常被命名为acme-spring-boot-starter。

Spring Boot在org.springframework.boot组下提供了以下应用程序启动器：

表13.1. Spring Boot应用程序启动器

除了应用程序启动器，以下启动器可用于添加生产准备(production ready)功能：

表13.2 Spring Boot生产环境启动器

最后，Spring Boot还包括一些启动器，如果要排除或替换特定的技术，可以使用它们：

有关社区贡献的更多启动器的列表，请参阅GitHub上的spring-boot-startters模块中的README文件。

14. 构建代码

Spring Boot不需要任何特定的代码结构设计，但是有一些最佳实践可以帮助您。

14.1 使用“default”包

当类不包括包声明时，它被认为是在“默认包”中。 通常不鼓励使用“默认包”，并应该避免使用。 对于使用@ComponentScan，@EntityScan或@SpringBootApplication注解的Spring Boot应用程序，可能会有一些特殊的问题，因为每个jar的每个类都将被读取。

我们建议您遵循Java推荐的软件包命名约定，并使用反向域名（例如，com.example.project）。

14.2 查找主应用程序类

我们通常建议您将应用程序主类放到其他类之上的根包(root package)中。 @EnableAutoConfiguration注解通常放置在您的主类上，它隐式定义了某些项目的基本“搜索包”。 例如，如果您正在编写JPA应用程序，则@EnableAutoConfiguration注解类的包将用于搜索@Entity项。

使用根包(root package)还可以使用@ComponentScan注释，而不需要指定basePackage属性。 如果您的主类在根包中，也可以使用@SpringBootApplication注释。

这是一个典型的布局：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

com
 +- example
     +- myproject
         +- Application.java
         |
         +- domain
         |   +- Customer.java
         |   +- CustomerRepository.java
         |
         +- service
         |   +- CustomerService.java
         |
         +- web
             +- CustomerController.java

Application.java文件将声明main方法以及基本的@Configuration。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

package com.example.myproject;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
@Configuration
@EnableAutoConfiguration
@ComponentScan
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

15. 配置类

Spring Boot支持基于Java的配置。虽然可以使用XML配置用SpringApplication.run()，但我们通常建议您的主source是@Configuration类。 通常，定义main方法的类也是作为主要的@Configuration一个很好的选择。

许多使用XML配置的Spring示例已经在网上发布。 如果可能的话我们建议始终尝试使用等效的基于Java的配置。 搜索 enable* 注解可以是一个很好的起点。

15.1 导入其他配置类

转载：Spring Boot中文文档