Spring Boot 参考文档翻译part2

最新推荐文章于 2024-09-21 22:45:23 发布

某科学の超电磁炮

最新推荐文章于 2024-09-21 22:45:23 发布

阅读量172

点赞数

文章标签： spring spring boot

原文链接：https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/

版权

2. 入门

如果您正在开始使用Spring Boot(通常称为“Spring”)，请先阅读这一节。它回答了“什么?””、“如何?”和“为什么?”的问题。它包括对Spring Boot的介绍，以及安装说明。然后，我们将带领您构建您的第一个Spring Boot应用程序，并讨论一些核心原则。

2.1. 介绍Spring Boot

Spring Boot帮助您创建可以运行的独立的、基于Spring的生产级应用程序。我们对Spring平台和第三方库有默认的配置，所以您可以毫不费力地开始。大多数Spring引导应用程序只需要很少的Spring配置。
您可以使用Spring Boot创建可以通过使用Java -jar或更传统的war部署启动的Java应用程序。我们还提供了一个运行“spring脚本”的命令行工具。
我们的主要目标是：

为所有Spring开发提供一个快速且可广泛访问的入门体验。
开箱即用，但当需求开始与默认值有所出入，可以很快摆脱困境。
提供一系列大型项目(如嵌入式服务器、安全性、度量、运行状况检查和外部化配置)常见的非功能性特性。
完全不需要代码生成，也不需要XML配置。

2.2. 系统要求

Spring Boot 2.4.2要求Java 8，兼容Java 15(包括)。还需要Spring Framework 5.3.3或以上版本。
为以下构建工具提供了显式构建支持:

构建工具	版本
Maven	3.3+
Gradle	6（6.3或更高版本）。还支持5.6.x，但已弃用

2.2.1. Servlet容器

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

名称	servlet版本
Tomcat 9.0	4.0
Jetty 9.4	3.1
Undertow 2.0	4.0

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

2.3. 安装Spring Boot

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

$ java -version

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

2.3.1. Java开发人员的安装说明

您可以像使用任何标准Java库一样使用Spring Boot。为此，在类路径中包含适当的spring-boot-*.jar文件。Spring Boot不需要集成任何特殊的工具，所以您可以使用任何IDE或文本编辑器。此外，Spring Boot应用程序没有什么特别之处，因此您可以像运行任何其他Java程序一样运行和调试Spring Boot应用程序。
虽然您可以复制Spring Boot jars，但我们通常建议您使用支持依赖项管理的构建工具(如Maven或Gradle)。

Maven安装

Spring Boot兼容Apache Maven 3.3及以上版本。如果您还没有安装Maven，可以按照Maven .apache.org上的说明进行安装。

在许多操作系统上，Maven都可以通过包管理器安装。如果您使用OSX Homebrew，请尝试brew install 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。
更多关于如何开始使用Spring Boot和Maven的细节可以在Maven插件参考指南的入门部分找到。

Gradle安装

Spring Boot与Gradle 6（6.3或更高版本）兼容。还支持Gradle 5.6.x，但不建议使用该支持，在将来的版本中将删除该支持。如果尚未安装Gradle，则可以按照gradle.org上的说明进行操作。

Gradle Wrapper :当你需要构建一个项目时，Gradle包装器提供了一种很好的“获取”Gradle的方式。它是一个小脚本和库，您可以与代码一起提交，以引导构建过程。详情请参见docs.gradle.org/current/userguide/gradle_wrapper.html。
更多关于Spring Boot和Gradle入门的细节可以在Gradle插件参考指南的入门部分找到。

2.3.2. 安装Spring Boot CLI

Spring Boot CLI(命令行接口)是一个命令行工具，您可以使用它快速创建Spring原型。它允许您运行Groovy脚本，这意味着您可以使用熟悉的类似java的语法，而不需要那么多样板代码。
您不是非通过CLI来使用Spring Boot不可，但这绝对是启动Spring应用程序的最快方法。

手动安装

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

spring-boot-cli-2.4.2-bin.zip
spring-boot-cli-2.4.2-bin.tar.gz
也可以使用最新的快照分发版。
下载完成后，按照解压归档文件中的INSTALL.txt说明操作。总之，在.zip文件的bin/目录中有一个spring脚本(用于Windows的spring.bat)。另外，您也可以使用java -jar和.jar文件(该脚本帮助您确保正确设置了类路径)。

使用SDKMAN!安装

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

$ sdk install springboot
$ spring --version
Spring Boot v2.4.2

如果你为CLI开发特性，并且想要访问你构建的版本，使用以下命令:

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

前面的指令安装一个称为dev实例的spring本地实例。它指向您的目标构建位置，因此每次重建Spring引导时，Spring都是最新的。
您可以通过运行以下命令来查看它：

$ sdk ls springboot

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

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

OSX Homebrew安装

如果您在Mac上并且使用Homebrew，则可以使用以下命令来安装Spring Boot CLI：

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

Homebrew 安装spring到*/usr/local/bin*。

如果没有看到公式，说明brew的安装可能过时了。在这种情况下，运行brew update并重试。

MacPorts安装

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

$ sudo port install spring-boot-cli

命令行补全

Spring Boot CLI包括为BASH和zsh shell提供命令补全的脚本。您可以在任何shell中获取脚本(也称为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 Boot CLI，命令行完成脚本将自动注册到shell中。

Windows Scoop安装

如果您使用的是Windows并使用Scoop，则可以使用以下命令安装Spring Boot CLI：
Scoop安装spring到*~/scoop/apps/springboot/current/bin*。

如果您没有看到应用程序清单，那么您的scoop安装可能已经过时。在这种情况下，运行scoop update并重试。

快速入门Spring CLI示例

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

@RestController
class ThisWillActuallyRun {

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

}

然后从shell运行它，如下所示：

$ spring run app.groovy

应用程序的第一次运行比较慢，因为需要下载依赖项。随后的运行要快得多。

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

2.3.3. 从较早版本的Spring Boot升级

如果要从1.xSpring Boot发行版进行升级，检查项目wiki上的“迁移指南”，它提供了详细的升级说明。也可以在“发布说明”中查看每个版本的“新且值得注意的”特性列表。
升级到新功能版本时，某些属性可能已被重命名或删除。Spring Boot提供了一种在启动时分析应用程序环境并打印诊断的方法，而且还可以在运行时为您临时迁移属性。要启用该功能，请将以下依赖项添加到您的项目中：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-properties-migrator</artifactId>
    <scope>runtime</scope>
</dependency>

较晚添加到环境中的属性(例如使用@PropertySource时)将不会被考虑在内。
迁移完成后，请确保从项目的依赖项中删除此模块。
要升级现有的CLI安装，请使用适当的包管理器命令(例如，brew upgrade)。如果您手动安装CLI，请遵循标准说明，记住更新PATH环境变量以删除任何旧的引用。

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

本节描述如何开发一个小型的“Hello World!”web应用程序，突出了一些Spring Boot的关键特性。我们使用Maven来构建这个项目，因为大多数ide都支持它。

spring.io网站包含许多使用Spring Boot的“入门”指南。如果你需要解决一个特定的问题，首先检查那里。
您可以通过进入start.spring.io来快捷地完成下面的步骤。并从依赖项搜索器中选择“Web”启动器。这样做会生成一个新的项目结构，这样你就可以马上开始编码了。查看Spring Initializr文档了解更多细节。
在开始之前，打开一个终端并运行以下命令，以确保安装了有效的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

这个样例需要在它自己的目录中创建。接下来的说明假设您已经创建了一个合适的目录，并且它是您的当前目录。

2.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.4.2</version>
    </parent>

    <description/>
    <developers>
        <developer/>
    </developers>
    <licenses>
        <license/>
    </licenses>
    <scm>
        <url/>
    </scm>
    <url/>

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

</project>

前面的清单应该为您提供了一个有效的构建。你可以通过运行mvn package来测试它(现在，你可以忽略“jar will be empty - no content was marked for inclusion!”“警告)。

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

2.4.2. 添加类路径依赖

Spring Boot提供了许多“启动器”，允许您将jar添加到类路径中。我们的冒烟测试应用程序使用了POM的parent部分中的spring-boot-starter-parent。spring-boot-starter-parent是一个特殊的启动器，它提供了有用的Maven默认值。它还提供了一个依赖项管理部分，这样您就可以省略“受祝福的”依赖项的版本标记。
其他“启动器”提供您在开发特定类型的应用程序时可能需要的依赖项。由于我们正在开发一个web应用程序，所以我们添加了spring-boot-start -web依赖项。在此之前，我们可以通过运行以下命令来查看当前拥有的内容:

$ 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下面：

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

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

2.4.3. 编写代码

要完成我们的应用程序，我们需要创建一个Java文件。默认情况下，Maven从src/main/java编译源代码，所以你需要创建这个目录结构，然后添加一个名为src/main/java/Example.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) {
        SpringApplication.run(Example.class, args);
    }

}

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

@RestController和@RequestMapping注解

我们的示例类中的第一个注释是@RestController。这被称为stereotype (构造型)注释。它为阅读代码的人提供了提示，并为Spring提供了该类扮演特定角色的提示。在本例中，我们的类是web @Controller，因此Spring在处理传入的web请求时考虑它。
@RequestMapping注释提供了“路由”信息。它告诉Spring，任何带有/路径的HTTP请求都应该映射到home方法。@RestController注释告诉Spring将结果字符串直接呈现给调用者。

@RestController和@RequestMapping注释是Spring MVC注释(它们不是Spring Boot特有的)。更多细节请参阅Spring参考文档中的MVC部分。

@EnableAutoConfiguration注解

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

启动器和自动配置：自动配置被设计为能够很好地与“启动器”一起工作，但是这两个概念并没有直接联系在一起。您可以自由地选择启动器之外的jar依赖项。Spring Boot仍然尽力自动配置应用程序。

"main"方法

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

2.4.4. 运行示例

此时，您的应用程序应该可以工作了。因为您使用了spring-boot-starter-parentPOM，所以您有一个有用的run目标，可以用来启动应用程序。输入mvn spring-boot:run从项目根目录运行应用程序。您应该会看到类似如下的输出:

$ mvn spring-boot:run

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

如果您打开一个web浏览器到localhost:8080，您应该看到以下输出:
Hello World!
要正常退出该应用程序，请按ctrl-c。

2.4.5. 创建一个可执行的Jar

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

可执行jar和Java：Java没有提供加载嵌套jar文件(本身包含在jar中的jar文件)的标准方法。如果您希望发布一个自包含的应用程序，那么这可能会产生问题。
为了解决这个问题，许多开发人员使用“uber”jars。一个uber jar将所有应用程序依赖项中的所有类打包到一个归档文件中。这种方法的问题是很难看到应用程序中有哪些库。如果在多个jar中使用相同的文件名(但内容不同)，也会产生问题。
Spring Boot采用了一种不同的方法，它允许您直接嵌套jar。
要创建一个可执行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-parentPOM包括配置来绑定repackage目标。如果不使用父POM，则需要自己声明此配置。详情请参阅插件文档。
保存你的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.4.2: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的小得多的文件。这是Maven在被Spring Boot重新打包之前创建的原始jar文件。
要运行该应用程序，使用java -jar命令，如下所示:

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

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

与前面一样，要退出应用程序，请按ctrl-c。

2.5. 接下来要读什么

希望本节提供了一些Spring Boot基础知识，并帮助您编写自己的应用程序。如果您是一名面向任务的开发人员，那么您可能希望跳转到spring.io，并查看一些入门指南，这些指南解决了具体的“我如何用Spring做到这一点?””问题。我们也有特定于Spring引导的“如何”参考文档。
另外，下一个逻辑步骤是学习使用Spring Boot。如果您真的没有耐心，您也可以跳过这一步，阅读Spring Boot的特性。