Spring Boot 2.2.2.RELEASE 版本中文参考文档

写在前面

在我初次接触MongoDB的时候，是为了做一个监控系统和日志分析系统。当时在用Java操作MongoDB数据里的数据的时候，都是在网上查找Demo示例然后完成的功能，相信大家也同样的体会，网上大都是这种一个入门的小Demo，很少有深入讲解的。功能调通后，自己琢磨效率方面的问题，便开始自己的瞎尝试之路，然后在产品启动阶段初始化多个MongoClient对象，搞了一个类似于连接池一类的池子，完成之后打心眼里觉得自己真是个小机灵鬼。 大概过了一年，为了系统地学习MongoDB的一些高级特性，在网上寻找Blog和Mooc无果后，我便把眼光落到了MongoDB提供的官方文档上。从看文档开始，我就觉得原来的认知太浅了。MongoDB Java Driver官方的文档一开始就介绍MongoClient已经做好连接池一类的机制，而软件开发人员只需要在创建对象阶段设置好参数即可。 后来慢慢地越来越意识到，一个新的技术入门最好的方式就是从阅读官方的文档开始，而像Spring、MongoDB这类技术的官方文档，入门、高级特性都写得很详细。用正确的方法做正确的事情。 关于Spring Boot的参考文档翻译，是因为后来的工作中开始大规模地用Spring Boot的技术，自己在学习的过程中，发现Spring Boot比较新的版本的参考文档一般都只有英语的，一些社区在自发进行翻译的文档版本都不是最新的。在学习的过程中，正好把参考文档的翻译也整理出来，也算是一种归档。如有疑问，欢迎大家一起交流。

关于文档内容，有几点需要声明下：

• 由于时间有限，文档先初步先把Maven方式使用Spring Boot部分翻译出来，Gradle方式和Spring CLI翻译部分后续如果有需要会整理出来。
• 文档是从Spring Boot官方文档的第二部分开始的，因为第一部分只是提供了Spring Boot参考文档的导览。
• 关于翻译的信、达、雅。我只能尽力做到“信”和“达”，“雅”确实因为能力不够达不到。文档有一些单词的翻译，在不能做到信的情况下，我会把英文参考文档中的单词或者原文贴出来，大家可以自行体会官方文档想要表达的意图。

开始

如果您是从Spring Boot或“Spring”开始的，请先阅读本节。它回答了基本的“什么”，如何”和“为什么”问题。它包括对Spring Boot的介绍以及安装说明。然后，我们将引导您构建第一个Spring Boot应用程序，并在讨论过程中讨论一些核心原理。

2.1 介绍Spring Boot

Spring Boot使创建可运行的独立，生产级基于Spring的应用程序变得容易。我们对Spring平台和第三方库持固执己见[opinionated]的观点，这样您就可以以最小的麻烦[fuss]开始使用。大多数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配置。

2.2 系统要求

Spring Boot 2.2.2.RELEASE需要Java 8，并且与Java 13（包括）兼容。 还需要Spring Framework 5.2.2.RELEASE或更高版本。

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

2.2.1 Servlet容器

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

2.3 安装Spring Boot

Spring Boot可以与“经典” Java开发工具一起使用，也可以作为命令行工具安装。 无论哪种方式，都需要Java SDK v1.8或更高版本。

在开始之前，您应该使用以下命令检查当前的Java安装版本：

$ java -veriosn

如果您不熟悉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 jar，但是我们通常建议您使用支持依赖关系管理的构建工具（例如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依赖项使用的groupId为org.springframework.boot。 通常，您的Maven POM文件是从spring-boot-starter-parent项目继承的，并声明对一个或多个“Starters”的依赖关系。Spring Boot还提供了一个可选的Maven插件来构建可执行jar。

以下清单显示了一个典型的pom.xml文件：

    4.0.0

    com.example
    myproject
    0.0.1-SNAPSHOT

    
    
        org.springframework.boot
        spring-boot-starter-parent
        2.2.2.RELEASE
    

    
    
    
        
    
    
        
    
    
        
    
    

    
    
        
            org.springframework.boot
            spring-boot-starter-web
        
    

    
    
        
            
                org.springframework.boot
                spring-boot-maven-plugin
            
        
    

spring-boot-starter-parent是使用Spring Boot的一种好方法，但可能并非始终适合。 有时您可能需要从其他父POM继承，或者您可能不喜欢我们的默认设置。在这些情况下，请参阅使用 不带父POM的Spring Boot以获得使用导入范围的替代解决方案。

Gradle安装

2.3.2 安装Spring Boot CLI

2.3.3 从较早版本的Spring Boot升级

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是用于构建项目的配方[recipe]。打开您喜欢的文本编辑器并添加以下内容：

    4.0.0

    com.example
    myproject
    0.0.1-SNAPSHOT

    
        org.springframework.boot
        spring-boot-starter-parent
        2.2.2.RELEASE
    

    
    
        
    
    
        
    
    
        
    
    

    

上面的清单应为您提供有效的构建。您可以通过运行mvn package命令对其进行测试（目前，您可以忽略“jar will be empty - no content was marked for inclusion!”警告）。

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

2.4.2 添加类路径依赖

Spring Boot提供了许多“启动器”，使您可以将jar添加到类路径中。我们的冒烟测试应用程序在POM的父部分中使用spring-boot-starter-parent。 spring-boot-starter-parent是一个特殊的启动器，提供有用的Maven默认值。它还提供了一个依赖项管理部分，以便您可以省去最佳版本的依赖项的标签。

其他“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本身不提供任何依赖关系。要添加必要的依赖关系，请编辑pom.xml并在父部分的正下方添加spring-boot-starter-web依赖关系：

    
        org.springframework.boot
        spring-boot-starter-web
    

如果再次运行mvn dependency:tree，则会看到现在还有许多其他依赖项，包括Tomcat Web服务器和Spring Boot本身。

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注解

Example类的第一个注释是@RestController。这被称为stereotype注解。它为人们阅读代码提供了提示，对于Spring来说，类扮演了特定角色。在这种情况下，我们的类是一个Web @Controller，因此Spring在处理传入的Web请求时会考虑使用它。

@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-parent父POM，因此您具有一个有用的运行目标，可以用来启动该应用程序。 从根项目目录输入命令 mvn spring-boot:run 以启动应用程序。 您应该看到类似于以下内容的输出：

$ mvn spring-boot:run

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::  (v2.2.2.RELEASE)
....... . . .
....... . . . (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文件来结束本节示例。可执行jar（有时称为“fat jar”）是包含您的已编译类以及代码需要运行的所有jar依赖项的归档文件。

可执行jar和Java

Java没有提供加载嵌套jar文件（jar中本身包含的jar文件）的标准方法。如果您要分发独立的应用程序，则可能会出现问题。 为了解决这个问题，许多开发人员使用“超级[uber]”容器。 超级[uber] jar将来自应用程序所有依赖项的所有类打包到一个存档中。这种方法的问题在于，很难查看应用程序中包含哪些库。如果在多个jar中使用相同的文件名（但具有不同的内容），也可能会产生问题。

Spring Boot采用了另一种方法，实际上允许您直接嵌套jar。

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

    
        
            org.springframework.boot
            spring-boot-maven-plugin
        
    

spring-boot-starter-parent的POM包含配置以绑定重新打包目标。 如果不使用父POM，则需要自己声明此配置。 有关详细信息，请参见 插件文档。

保存您的pom.xml并从命令行运行mvn软件包，如下所示：

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

如果查看target目录，则应该看到 myproject-0.0.1-SNAPSHOT.jar 包。该文件的大小应为10 MB左右。如果想看到内部结构，可以使用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.2.2.RELEASE)
....... . . .
....... . . . (log output here)
....... . . .
........ Started Example in 2.536 seconds (JVM running for 2.864)
 

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

第二章节结束。

 

---

后续其他章节和Java相关知识和资料会在公众号同步更新，关注下咯~