Route-nice
0%

SpringBoot官方文档翻译-Getting Started

发表于 更新于 分类于 Disqus：

介绍SpringBoot

Spring Boot 使创建可运行的独立，基于生产级的基于 Spring 的应用程序变得容易。我们对 Spring 平台和第三方库持固执己见的观点，这样您就可以以最小的麻烦开始使用。大多数 Spring Boot 应用程序只需要很少的 Spring 配置。

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

我们的主要目标是：

  • 为所有 Spring 开发提供根本上更快且可广泛访问的 Starter 经验。
  • 开箱即用，但由于需求开始与默认值有所出入，因此很快就会摆脱困境。
  • 提供一系列大型项目通用的非功能性功能(例如嵌入式服务器，安全性，Metrics，运行状况检查和外部化配置)。
  • 完全没有代码生成，也不需要 XML 配置。

系统要求

Spring Boot 2.1.1.RELEASE 需要Java 8，并且与 Java 11(包括)兼容。也必须Spring Framework 5.1.3. 发布或更高。

为以下构建工具提供了明确的构建支持：

Build Tool Version
Maven 3.3+
Gradle 4.4+

Servlet容器

Spring Boot 支持以下嵌入式 servlet 容器：

Name Servlet Version
Tomcat 9.0 4.0
Jetty 9.4 3.1
Undertow 2.0 4.0

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

安装SpringBoot

Spring Boot 可以与“经典” Java 开发工具一起使用，也可以作为命令行工具安装。无论哪种方式，您都需要Java SDK v1.8或更高。在开始之前，您应该使用以下命令检查当前的 Java 安装：

1
$ java -version

如果您不熟悉 Java 开发，或者想尝试使用 Spring Boot，则可能要先尝试Spring Boot CLI(命令行界面)。否则，请 continue 阅读“经典”安装说明。

Java开发人员的安装说明

您可以像使用任何标准 Java 库一样使用 Spring Boot。为此，请在 Classpath 中包含适当的spring-boot-*.jar文件。 Spring Boot 不需要任何特殊的工具集成，因此您可以使用任何 IDE 或文本编辑器。另外，Spring Boot 应用程序没有什么特别的，因此您可以像运行其他 Java 程序一样运行和调试 Spring Boot 应用程序。

尽管您可以复制 Spring Boot jar，但是我们通常建议您使用支持依赖项 Management 的构建工具(例如 Maven 或 Gradle)。

Maven安装

Spring Boot 与 Apache Maven 3.3 或更高版本兼容。如果尚未安装 Maven，则可以按照maven.apache.org上的说明进行操作。

Tip

在许多 os 上，Maven 可以与程序包 Management 器一起安装。如果您使用 OSX Homebrew，请尝试brew install maven。 Ubuntu 用户可以运行sudo apt-get install maven。具有Chocolatey的 Windows 用户可以从提升的(Management 员)提示符下运行choco install maven。

Spring Boot 依赖项使用org.springframework.boot groupId。通常，您的 Maven POM 文件从spring-boot-starter-parent项目继承，并声明对一个或多个“Starters”的依赖关系。 Spring Boot 还提供了一个可选的Maven plugin来创建可执行 jar。

以下 Lists 显示了一个典型的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>2.1.1.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>

Tip

spring-boot-starter-parent是使用 Spring Boot 的好方法，但可能并不总是适合。有时您可能需要从其他父 POM 继承，或者您可能不喜欢我们的默认设置。在这些情况下，请参阅第 13.2.2 节“在没有父 POM 的情况下使用 Spring Boot”以获取使用import范围的替代解决方案。

Gradle安装

Spring Boot 与 Gradle 4.4 及更高版本兼容。如果尚未安装 Gradle，则可以按照gradle.org上的说明进行操作。

可以使用org.springframework.boot group声明 Spring Boot 依赖项。通常，您的项目声明对一个或多个“Starters”的依赖关系。 Spring Boot 提供了一个有用的Gradle plugin，可用于简化依赖项声明并创建可执行 jar。

Gradle Wrapper

当您需要构建项目时，Gradle 包装器提供了一种“获取” Gradle 的好方法。这是一个小的脚本和库，您随代码一起提交以引导构建过程。有关详情，请参见。

有关 Spring Boot 和 Gradle Starter 的更多详细信息，可以在 Gradle 插件参考指南的Starter 部分中找到。

安装SpringBootCLI

Spring Boot CLI(命令行界面)是一个命令行工具，可用于快速使用 Spring 进行原型设计。它使您可以运行Groovy脚本，这意味着您具有类似 Java 的熟悉语法，而没有太多样板代码。

您无需使用 CLI 即可与 Spring Boot 配合使用，但这绝对是使 Spring 应用程序启动的最快方法。

手动安装

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

最先进的snapshot distributions也可用。

下载完成后，请按照解压后的存档中的INSTALL.txt说明进行操作。总之，在.zip文件的bin/目录中有一个spring脚本(对于 Windows 是spring.bat)。或者，您可以将java -jar与.jar文件一起使用(脚本可帮助您确保正确设置了 Classpath)。

使用SDKMAN安装！

SDKMAN！ (软件开发工具包 Management 器)可用于 Management 各种二进制 SDK 的多个版本，包括 Groovy 和 Spring Boot CLI。获取 SDKMAN！从sdkman.io开始，并使用以下命令安装 Spring Boot：

1
2
3
$ sdk install springboot
$ spring --version
Spring Boot v2.1.1.RELEASE

如果您为 CLI 开发功能并希望轻松访问所构建的版本，请使用以下命令：

1
2
3
4
$ sdk install springboot dev /path/to/spring-boot/spring-boot-cli/target/spring-boot-cli-2.1.1.RELEASE-bin/spring-2.1.1.RELEASE/
$ sdk default springboot dev
$ spring --version
Spring CLI v2.1.1.RELEASE

前面的说明将安装称为dev实例的spring本地实例。它指向您的目标构建位置，因此，每次重建 Spring Boot 时，spring都是最新的。

您可以通过运行以下命令来查看它：

1
2
3
4
5
6
7
8
9
10
11
12
13
$ sdk ls springboot

================================================================================
Available Springboot Versions
================================================================================
> + dev
* 2.1.1.RELEASE

================================================================================
+ - local version
* - installed
> - currently in use
================================================================================

OSXHomebrew安装

如果您使用的是 Mac 并使用Homebrew，则可以使用以下命令安装 Spring Boot CLI：

1
2
$ brew tap pivotal/tap
$ brew install springboot

自制软件将spring安装到/usr/local/bin。

Note

如果看不到该公式，则说明 brew 的安装可能已过期。在这种情况下，请运行brew update，然后重试。

MacPorts安装

如果您使用的是 Mac 并使用MacPorts，则可以使用以下命令安装 Spring Boot CLI：

1
$ sudo port install spring-boot-cli

命令行完成

Spring Boot CLI 包括为BASH)和zsh Shell 提供命令完成的脚本。您可以在任何 shell 中source脚本(也称为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

Note

如果您使用 Homebrew 或 MacPorts 安装 Spring Boot CLI，则命令行完成脚本会自动注册到您的 Shell 中。

WindowsScoop安装

如果您使用的是 Windows 并使用Scoop，则可以使用以下命令安装 Spring Boot CLI：

1
2
> scoop bucket add extras
> scoop install springboot

Scoop 将spring安装到~/scoop/apps/springboot/current/bin。

Note

如果您没有看到应用 Lists，则可能是因为瓢的安装已过期。在这种情况下，请运行scoop update，然后重试。

快速StarterSpringCLI示例

您可以使用以下 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

Note

由于依赖项已下载，因此您的应用程序的第一次运行很慢。随后的运行要快得多。

在您喜欢的网络浏览器中打开localhost:8080。您应该看到以下输出：

1
Hello World!

从早期版本的SpringBoot升级

如果您要从较早版本的 Spring Boot 升级，请检查项目 Wiki 上的“迁移指南”，其中提供了详细的升级说明。还要在“release notes”上查看每个版本的“新功能和值得注意的”功能列表。

升级到新功能版本时，某些属性可能已被重命名或删除。 Spring Boot 提供了一种在启动时分析应用程序环境并打印诊断的方法，而且还可以在运行时为您临时迁移属性。要启用该功能，请将以下依赖项添加到您的项目中：

1
2
3
4
5
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-properties-migrator</artifactId>
    <scope>runtime</scope>
</dependency>

Warning

较晚添加到环境的属性(例如使用@PropertySource时)将不被考虑。

Note

迁移完成后，请确保从项目的依赖项中删除此模块。

要升级现有的 CLI 安装，请使用适当的程序包 Management 器命令(例如brew upgrade)，或者，如果手动安装了 CLI，请遵循standard instructions，记住要更新PATH环境变量以删除任何较旧的引用。

开发您的第一个SpringBoot应用程序

本节介绍如何开发一个简单的“ Hello World！”。 Web 应用程序，重点介绍了 Spring Boot 的一些关键功能。我们使用 Maven 来构建此项目，因为大多数 IDE 都支持它。

Tip

spring.io网站包含许多使用 Spring Boot 的“Starter” guides。如果您需要解决特定问题，请首先检查。

您可以通过转到start.spring.io并从依赖项搜索器中选择“ Web”启动器来简化以下步骤。这样做会生成一个新的项目结构，以便您可以立即开始编码。检查Spring Initializr 文档以获得更多详细信息。

在开始之前，请打开终端并运行以下命令，以确保安装了有效的 Java 和 Maven 版本：

1
2
3
4
5
6
7
8
$ 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.5.4 (1edded0938998edf8bf061f1ceb3cfdeccf443fe; 2018-06-17T14:33:14-04:00)
Maven home: /usr/local/Cellar/maven/3.3.9/libexec
Java version: 1.8.0_102, vendor: Oracle Corporation

Note

该示例需要在其自己的文件夹中创建。随后的说明假定您已经创建了一个合适的文件夹，并且它是当前目录。

创建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>2.1.1.RELEASE</version>
    </parent>

    <!-- Additional lines to be added here... -->

</project>

上面的 Lists 应为您提供有效的构建。您可以通过运行mvn package进行测试(目前，您可以忽略“ jar 将为空-没有内容被标记为包含！”警告)。

Note

此时，您可以将项目导入到 IDE 中(大多数现代 Java IDE 都包含对 Maven 的内置支持)。为了简单起见，我们在此示例中 continue 使用纯文本编辑器。

添加Classpath依赖项

Spring Boot 提供了许多“启动器”，使您可以将 jar 添加到 Classpath 中。我们的示例应用程序已经在 POM 的parent部分中使用了spring-boot-starter-parent。 spring-boot-starter-parent是一个特殊的启动器，提供有用的 Maven 默认值。它还提供了一个dependency-management部分，以便您可以省略version标签来表示“受祝福的”依赖关系。

其他“Starter”提供了开发特定类型的应用程序时可能需要的依赖项。由于我们正在开发 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并将spring-boot-starter-web依赖性添加在parent部分的正下方：

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 本身。

编写代码

要完成我们的应用程序，我们需要创建一个 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
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);
    }

}

尽管这里没有太多代码，但正在进行很多工作。我们将在接下来的几节中逐步介绍重要部分。

RestController注解和RequestMapping注解

我们的Example类的第一个注解是@RestController。这称为“定型”注解。它为阅读代码的人和 Spring 提供了提示，提示该类起特定作用。在这种情况下，我们的类是一个 Web @Controller，因此 Spring 在处理传入的 Web 请求时会考虑使用它。

@RequestMapping注解提供“路由”信息。它告诉 Spring，任何带有/路径的 HTTP 请求都应 Map 到home方法。 `@RestController注解 告诉 Spring 将结果字符串直接渲染回调用方。

Tip

@RestController和`@RequestMapping注解是 Spring MVC 注解。 (它们并非特定于 Spring Boot.)有关更多详细信息，请参见 Spring 参考文档中的MVC section。

EnableAutoConfiguration注解

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

Starters and Auto-configuration

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

Main方法

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

运行示例

此时，您的应用程序应该可以运行了。由于您使用了spring-boot-starter-parent POM，因此您有一个有用的run目标，可用于启动应用程序。在根项目目录中键入mvn spring-boot:run以启动应用程序。您应该看到类似于以下内容的输出：

1
2
3
4
5
6
7
8
9
10
11
12
13
$ mvn spring-boot:run

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::  (v2.1.1.RELEASE)
....... . . .
....... . . . (log output here)
....... . . .
........ Started Example in 2.222 seconds (JVM running for 6.514)

如果您打开 Web 浏览器到localhost:8080，则应该看到以下输出：

1
Hello World!

要正常退出该应用程序，请按ctrl-c。

创建一个可执行的Jar

通过创建一个可以在生产环境中运行的完全独立的可执行 jar 文件来结束示例。可执行 jar(有时称为“胖 jar”)是包含您的已编译类以及代码需要运行的所有 jar 依赖项的归档文件。

Executable jars and Java

Java 没有提供加载嵌套 jar 文件(jar 中本身包含的 jar 文件)的标准方法。如果您要分发独立的应用程序，则可能会出现问题。

为了解决此问题，许多开发人员使用“uber”Jar。 uber jar 将来自应用程序所有依赖项的所有类打包到单个存档中。这种方法的问题在于，很难查看应用程序中包含哪些库。如果在多个 jar 中使用了相同的文件名(但内容不同)，也可能会产生问题。

Spring Boot 需要一个different approach并允许您实际上直接将 jar 嵌套。

要创建可执行 jar，我们需要将spring-boot-maven-plugin添加到pom.xml。为此，请在dependencies部分的下面插入以下行：

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>

Note

spring-boot-starter-parent POM 包含<executions>配置以绑定repackage目标。如果不使用父 POM，则需要自己声明此配置。有关详情，请参见plugin documentation。

保存您的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:2.1.1.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 ::  (v2.1.1.RELEASE)
....... . . .
....... . . . (log output here)
....... . . .
........ Started Example in 2.536 seconds (JVM running for 2.864)

和以前一样，要退出该应用程序，请按ctrl-c。

接下来要读什么

希望本节提供了一些 Spring Boot 基础知识，并带您开始编写自己的应用程序。如果您是面向任务的开发人员，则可能要跳到spring.io并查看解决特定“我如何使用 Spring 来解决”的getting started指南。问题。我们也有特定于 Spring Boot 的“ How-to”参考文档。

Spring Boot 存储库也有一个一堆 sample您可以运行。示例与其他代码无关(也就是说，您无需构建其余代码即可运行或使用示例)。

否则，下一个逻辑步骤是读取 第三部分，“使用 Spring Boot” 。如果您真的很急，还可以 continue 阅读并了解 Spring Boot 功能 。