# 开始

如果你要开始使用 Spring boot,或者一般的“ Spring”,那么请阅读这一部分。它回答了基本的“什么?”、“怎么做?”和“为什么?”的问题。它包括对 Spring 启动的介绍,以及安装说明。然后,我们将带领你构建你的第一个 Spring 启动应用程序,并在此讨论一些核心原则。

# 1. 引入 Spring 引导

Spring 引导帮助你创建可以运行的独立的、基于生产级别 Spring 的应用程序。我们对 Spring 平台和第三方库持有一种固执己见的观点,这样你就可以在开始时尽量减少麻烦。大多数 Spring 启动应用程序只需要很少的 Spring 配置。

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

我们的主要目标是:

  • 为所有 Spring 开发提供一种从根本上更快且广泛获得的入门体验。

  • 在需求开始偏离默认值时,不要拘泥于常规,但要尽快摆脱。

  • 提供一系列非功能特性,这些特性是大型项目类所共有的(例如嵌入式服务器、安全性、度量、健康检查和外部化配置)。

  • 绝对不需要代码生成,也不需要 XML 配置。

# 2. 系统要求

Spring Boot2.6.4 要求Java 8 (opens new window)并且兼容到并包括 Java17。Spring Framework 5.3.16 (opens new window)或以上也是必需的。

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

Build Tool 版本
Maven 3.5+
Gradle 6.8.x、6.9.x 和 7.x

# 2.1. Servlet 集装箱

Spring 启动支持以下嵌入式 Servlet 容器:

Name Servlet 版本
Tomcat 9.0 4.0
Jetty 9.4 3.1
Jetty 10.0 4.0
Undertow 2.0 4.0

你还可以将 Spring 引导应用程序部署到任何 Servlet 3.1+ 兼容容器。

# 3. 安装 Spring 启动

Spring 启动可以与“经典”Java 开发工具一起使用,也可以作为命令行工具安装。无论哪种方式,你都需要Java SDK v1.8 (opens new window)或更高的值。在开始之前,你应该使用以下命令检查当前的 Java 安装:

$ java -version

如果你是 Java 开发的新手,或者你想要尝试 Spring 引导,那么你可能想要首先尝试Spring Boot CLI(命令行接口)。否则,请继续阅读“经典”安装说明。

# 3.1.Java 开发人员的安装说明

你可以以与任何标准 Java 库相同的方式使用 Spring boot。要做到这一点,在你的 Classpath 中包含适当的spring-boot-*.jar文件。 Spring 启动不需要任何特殊的工具集成,因此可以使用任何 IDE 或文本编辑器。此外, Spring 引导应用程序没有什么特别之处,因此你可以像运行任何其他 Java 程序一样运行和调试 Spring 引导应用程序。

尽管你Coul复制了 Spring 引导 JAR,但我们通常建议你使用支持依赖管理的构建工具(例如 Maven 或 Gradle)。

# 3.1.1. Maven 安装

Spring 引导与 Apache Maven 3.3 或更高版本兼容。如果尚未安装 Maven,则可以按照maven.apache.org (opens new window)中的说明进行操作。

在许多操作系统上, Maven 都可以安装一个包管理器。
如果你使用 OSX Homebrew,请尝试brew install maven
Ubuntu 用户可以运行sudo apt-get install maven
具有Chocolatey (opens new window)的 Windows 用户可以从提升的(管理员)提示符中运行choco install maven

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

关于开始使用 Spring boot 和 Maven 的更多详细信息,可以在 Maven 插件的参考指南入门部分 (opens new window)中找到。

# 3.1.2. Gradle 安装

Spring 引导与 Gradle 6.8、6.9 和 7.x 兼容。如果尚未安装 Gradle,则可以按照gradle.org (opens new window)中的说明进行操作。

Spring 启动依赖项可以通过使用org.springframework.boot``group来声明。通常,你的项目声明依赖于一个或多个“Starters”。 Spring Boot 提供了一个有用的Gradle plugin,可用于简化依赖项声明并创建可执行 JAR。

Gradle 包装纸

当你需要构建一个项目时, Gradle 包装器提供了一种很好的“获取” Gradle 方式。它是一个小的脚本和库,你可以在代码旁边提交它来引导构建过程。详见docs.gradle.org/current/userguide/gradle_wrapper.html (opens new window)

关于开始使用 Spring boot 和 Gradle 的更多详细信息,可以在 Gradle 插件的参考指南入门部分 (opens new window)中找到。

# 3.2.安装 Spring boot cli

Spring 引导 CLI(命令行界面)是一种命令行工具,你可以使用它来快速地使用 Spring 进行原型设计。它允许你运行Groovy (opens new window)脚本,这意味着你有一个熟悉的类似 Java 的语法,而不需要那么多样板代码。

你不需要使用 CLI 来处理 Spring 引导,但是这是一种在没有 IDE 的情况下使 Spring 应用程序脱离地面的快速方法。

# 3.2.1.手动安装

你可以从 Spring 软件库下载 Spring CLI 发行版:

尖端快照分布 (opens new window)也是可用的。

一旦下载,请按照解压缩归档文件中的安装.TXT (opens new window)说明进行操作。总之,在.zip文件中的bin/目录中有一个spring脚本(spring.bat用于 Windows)。或者,你可以在.jar文件中使用java -jar(该脚本可以帮助你确保 Classpath 设置正确)。

# 3.2.2.用 SDKMAN 安装!

SDKMAN!(软件开发工具包管理器)可以用于管理各种二进制 SDK 的多个版本,包括 Groovy 和 Spring Boot CLI。得到 SDKMAN!从sdkman.io (opens new window)开始,使用以下命令安装 Spring boot:

$ sdk install springboot
$ spring --version
Spring CLI v2.6.4

如果你为 CLI 开发了功能,并希望访问你构建的版本,请使用以下命令:

$ sdk install springboot dev /path/to/spring-boot/spring-boot-cli/target/spring-boot-cli-2.6.4-bin/spring-2.6.4/
$ sdk default springboot dev
$ spring --version
Spring CLI v2.6.4

前面的指令安装一个spring的本地实例,称为dev实例。它指向你的目标构建位置,因此每次重新生成 Spring 引导时,spring都是最新的。

你可以通过运行以下命令看到它:

$ sdk ls springboot

================================================================================
Available Springboot Versions
================================================================================
> + dev
* 2.6.4

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

# 3.2.3.OSX Homebrew 安装

如果你在 Mac 上使用Homebrew (opens new window),则可以使用以下命令安装 Spring boot cli:

$ brew tap spring-io/tap
$ brew install spring-boot

Homebrew 将spring安装到/usr/local/bin

如果你没有看到公式,那么你安装的 BREW 可能已经过期。
在这种情况下,运行brew update,然后再试一次。

# 3.2.4. MacPorts 安装

如果你在 Mac 上使用MacPorts (opens new window),则可以使用以下命令安装 Spring boot cli:

$ sudo port install spring-boot-cli

# 3.2.5.命令行完成

Spring 引导 CLI 包括为BASH (opens new window)zsh (opens new window)shell 提供命令完成的脚本。你可以在任何 shell 中source该脚本(也称为spring),或者将其放入你的个人或系统范围的 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 启动 CLI,那么命令行完成脚本将自动注册到你的 shell 中。

# 3.2.6.Windows Scoop 安装

如果你在 Windows 上并使用Scoop (opens new window),则可以使用以下命令安装 Spring boot cli:

> scoop bucket add extras
> scoop install springboot

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

如果你没有看到应用程序清单,那么你的 Scoop 安装可能已经过期。
在这种情况下,运行scoop update,然后再试一次。

# 3.2.7.快速启动 Spring CLI 示例

你可以使用下面的 Web 应用程序来测试你的安装。首先,创建一个名为app.groovy的文件,如下所示:

@RestController
class ThisWillActuallyRun {

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

}

然后从一个 shell 中运行它,如下所示:

$ spring run app.groovy
应用程序的第一次运行很慢,因为依赖项是下载的。
后续运行要快得多。

在你最喜欢的 Web 浏览器中打开[localhost:8080](http://localhost:8080)。你应该会看到以下输出:

Hello World!

# 4. 开发你的第一个 Spring 启动应用程序

这一部分描述了如何开发一个小型的“Hello World!”Web 应用程序,该应用程序突出了 Spring Boot 的一些关键功能。我们使用 Maven 来构建这个项目,因为大多数 IDE 都支持它。

spring.io (opens new window)网站包含许多使用 Spring 引导的“入门”guides (opens new window)
如果你需要解决特定的问题,首先检查那里。

你可以通过转到start.spring.io (opens new window)并从依赖项搜索器中选择“web”启动器来快捷下面的步骤。
这样做会生成一个新的项目结构,这样你就可以立即开始编码
检查start.spring.io user guide (opens new window)以获取更多详细信息。

在开始之前,打开一个终端并运行以下命令,以确保安装了有效的 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.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
这个示例需要在它自己的目录中创建。
后续的说明假设你已经创建了一个合适的目录,并且它是你当前的目录。

# 4.1.创建 POM

我们需要从创建一个 Maven pom.xml文件开始。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 https://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.6.4</version>
    </parent>

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

</project>

前面的列表应该为你提供一个可工作的构建。你可以通过运行mvn package来测试它(目前,你可以忽略“ jar 将为空-没有内容被标记为包含!”警告)。

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

# 4.2.添加 Classpath 依赖项

Spring Boot 提供了许多“启动器”,允许你将罐子添加到你的 Classpath。我们的烟雾测试应用程序使用 POM 中parent部分中的spring-boot-starter-parentspring-boot-starter-parent是一种特殊的启动器,它提供了有用的 Maven 默认值。它还提供了一个[dependency-management](使用.html#using.build-systems.dependency-management)部分,这样你就可以省略version标记来表示“有福的”依赖关系。

其他“启动器”提供了在开发特定类型的应用程序时可能需要的依赖关系。因为我们正在开发一个 Web 应用程序,所以我们添加了一个spring-boot-starter-web依赖项。在此之前,我们可以通过运行以下命令查看当前的内容:

$ 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依赖项:

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

如果再次运行mvn dependency:tree,你将看到现在有许多额外的依赖关系,包括 Tomcat Web 服务器和 Spring 引导本身。

# 4.3.编写代码

为了完成我们的应用程序,我们需要创建一个单独的 Java 文件。默认情况下, Maven 从src/main/java编译源代码,因此你需要创建该目录结构,然后添加一个名为src/main/java/MyApplication.java的文件,以包含以下代码:

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@EnableAutoConfiguration
public class MyApplication {

    @RequestMapping("/")
    String home() {
        return "Hello World!";
    }

    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }

}

虽然这里没有太多的代码,但发生了很多事情。在接下来的几节中,我们将介绍重要的部分。

# 4.3.1.restcontroller 和 @requestmapping 注释

我们的MyApplication类的第一个注释是@RestController。这被称为刻板印象注释。它为阅读代码的人提供了提示,并为 Spring 提供了类扮演特定角色的提示。在这种情况下,我们的类是一个 Web@Controller,因此 Spring 在处理传入的 Web 请求时考虑它。

@RequestMapping注释提供了“路由”信息。它告诉 Spring,任何带有/路径的 HTTP 请求都应该映射到home方法。@RestController注释告诉 Spring 将生成的字符串直接呈现给调用方。

@RestController@RequestMapping注释是 Spring MVC 注释(它们不特定于 Spring 引导)。
有关更多详细信息,请参见 Spring 参考文档中的MVC 部分 (opens new window)

# 4.3.2.@enableAutoConfiguration 注释

第二个类级注释是@EnableAutoConfiguration。这个注释告诉 Spring 引导“猜测”你想要如何配置 Spring,基于你添加的 jar 依赖关系。由于spring-boot-starter-web添加了 Tomcat 和 Spring MVC,因此自动配置假定你正在开发一个 Web 应用程序,并相应地设置 Spring。

起动器和自动配置

自动配置的设计是为了与“启动器”很好地配合,但这两个概念并没有直接联系在一起。你可以自由地选择 jar 启动器之外的依赖项。 Spring 启动仍然会尽力自动配置你的应用程序。

# 4.3.3.“主”法

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

# 4.4.运行示例

在这一点上,你的应用程序应该可以工作。因为你使用了spring-boot-starter-parent POM,所以你有了一个有用的run目标,你可以使用它来启动应用程序。从根项目目录中键入mvn spring-boot:run以启动应用程序。你应该会看到类似于以下内容的输出:

$ mvn spring-boot:run

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

如果将 Web 浏览器打开到[localhost:8080](http://localhost:8080),应该会看到以下输出:

Hello World!

要优雅地退出应用程序,请按ctrl-c

# 4.5.创建可执行文件 jar

我们通过创建一个完全自包含的可执行文件 jar 来完成我们的示例,该文件可以在生产环境中运行。可执行 JAR(有时称为“FAT JAR”)是包含你的已编译类以及代码需要运行的所有 jar 依赖项的归档文件。

可执行 JAR 和 Java

Java 没有提供一种标准的方式来加载嵌套的 jar 文件( jar 文件本身包含在 jar 中)。如果你希望分发一个自包含的应用程序,这可能会有问题。

为了解决这个问题,许多开发人员使用“UBER”JAR。 jar UBER 将应用程序的所有依赖项中的所有类打包到一个单独的归档文件中。这种方法的问题在于,很难看到应用程序中有哪些库。如果在多个 JAR 中使用相同的文件名(但具有不同的内容),也可能会有问题。

Spring boot 需要不同的方法,并让你实际上直接嵌套罐子。

要创建可执行文件 jar,我们需要将spring-boot-maven-plugin添加到我们的pom.xml中。要做到这一点,请在dependencies部分下方插入以下行:

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
    </plugins>
</build>
spring-boot-starter-parent POM 包括<executions>配置,以绑定repackage目标。
如果不使用父 POM,则需要自己声明此配置。
有关详细信息,请参见插件文档 (opens new window)

保存pom.xml并从命令行运行mvn package,如下所示:

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

如果查看target目录,应该会看到myproject-0.0.1-SNAPSHOT.jar。该文件的大小应该在 10MB 左右。如果想要查看内部,可以使用jar tvf,如下所示:

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

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

要运行该应用程序,请使用java -jar命令,如下所示:

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

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::  (v2.6.4)
....... . . .
....... . . . (log output here)
....... . . .
........ Started MyApplication in 2.536 seconds (JVM running for 2.864)

和前面一样,要退出应用程序,请按ctrl-c

# 5. 接下来要读什么?

希望这一部分提供了一些 Spring 引导基础知识,并帮助你编写自己的应用程序。如果你是一位面向任务类型的开发人员,你可能希望跳到spring.io (opens new window),并遵循一些开始 (opens new window)指南,这些指南解决了特定的“如何使用 Spring?”问题。我们还有 Spring 特定于引导的“How-to”参考文档。

否则,下一个逻辑步骤是读取 using.html。如果你真的不耐烦了,你也可以跳到前面去读关于 Spring Boot features 的文章。