springboot 2.1.8官方文档翻译--1.Part ISpring Boot 文档总体介绍和 Part II简单实例尝试
目录
Part I. Spring Boot 文档
1. 关于该文档的描述
2. 获取帮助
3. 入门
4.spring boot的运行
5. 学习spring boot的特征
6.生产环境
7. 高级的操作
Part II. 准备开始
8. 介绍Spring Boot
9. 系统要求
9.1 jar包管理工具
9.2 Servlet容器
10. 安装Spring Boot
10.1 Java 开发环境安装说明
10.1.1 Maven 安装
10.1.2 Gradle 安装
10.2 安装 the Spring Boot CLI
10.2.1 Manual 安装
10.2.2 安装SDKMAN!
10.2.3 OSX Homebrew 安装
10.2.4 MacPorts 安装
10.2.5 Command-line 补全
10.2.6 Windows Scoop安装
10.2.7 Quick-start Spring CLI 实例
10.3 升级Spring Boot
11. 开发你的第一个Spring Boot Application
11.1 创建 POM文件
11.2 增加Classpath Dependencies
11.3 编写Code
11.3.1 @RestController and @RequestMapping 注解
11.3.2 @EnableAutoConfiguration 注解
11.3.3 “main” 方法
11.4 运行 Example
11.5 创建一个 Executable Jar
12. What to Read Next
Part I. Spring Boot 文档
本节将简要概述Spring Boot参考文档。它作为文档其它部分的参照。
1. 关于该文档的描述
The Spring Boot说明文档能够呈现的形式：
- HTML
- EPU
最新文档下载地址：docs.spring.io/spring-boot/docs/current/reference.
该说明文档的拷贝可以供你自己使用，也可以分享给他人。不管是打印还是电子档，你都不需要为这些拷贝支付任何费用，而且每一个拷贝文档都包含本版权声明。
2. 获取帮助
如果你在使用spring boot的时候遇到了问题，通过以下方式寻求帮助：
- 到该链接下How-to documents。它们为最常见的问题提供解决方案。
- 学习Spring基础知识。因为Spring Boot是基于许多其他Spring项目来完成的。查看 spring.io的网站里面有许多的参考文档。如果您是从Spring开始的，可以尝试其中的一个guides。
- 如果要提问的话。对于spring boot 的问题，我们会一直关注 stackoverflow.com网站上大家提出来的问题，并作出解答。
- 如果spring boot本身的bug，你可以在GitHub上提问github.com/spring-projects/spring-boot/issues.
3. 入门
如果你刚刚开始使用spring boot或者一般来说来说是spring，建议从该下面开始the following topics：
- 0基础开始：Overview | Requirements | Installation
- 教程： Part 1 | Part 2
- 运行你的第一个实例： Part 1 | Part 2
4.spring boot的运行
准备好开始使用Spring Boot了吗?使用需要涵盖的内容：
- 搭建系统管理：Maven | Gradle | Ant | Starters
- 简单练习：Code Structure | @Configuration | @EnableAutoConfiguration | Beans and Dependency Injection
- 运行你的代码：IDE | Packaged | Maven | Gradle
- 打包：Production jars
- spring boot ctl：Using the CLI
5. 学习spring boot的特征
想要了解更多spring boot的核心内容吗？The following content is for you:
- 核心的特征：SpringApplication | External Configuration | Profiles | Logging
- Web应用：MVC | Embedded Containers
- 数据：SQL | NO-SQL
- 消息：Overview | JMS
- 测试：Overview | Boot Applications | Utils
- 扩展：Auto-configuration | @Conditions
6.生产环境
当你准备将你的spring boot项目进行生产上线的时候，我们提供了一些你喜欢的小操作
- 管理端口：Overview | Customization
- 连接的选择：HTTP | JMX
- 监控：Metrics | Auditing | Tracing | Process
7. 高级的操作
最后，我们为一些大神级别用户提供了一些操作
- Spring启动应用程序部署：Cloud Deployment | OS Service
- 构建工具插件：Maven | Gradle
- 扩展：Application Properties | Auto-configuration classes | Executable Jars
Part II. 准备开始
如果您正在开始使用Spring Boot，或者一般来说是“Spring”，那么从阅读本节开始。它回答了最基本的“是什么”、“怎么用”、“为什么”的问题。它包括了spring boot的基本使用介绍，以及安装介绍。然后，我们将引导你构建你的第一个Spring引导应用程序，并在此过程中讨论一些核心原则。
8. 介绍Spring Boot
Spring Boot能够很容易的去创建独立运行的、生产级别的spring-based应用程序。我们有spring平台自己的函数库，也有第三方的函数库，以至于启动spring boot程序不会很麻烦。大部分spring boot项目不需要太多的配置信息。
你能够通过spring boot创建java application应用，通过使用指令 java -jar 或者传统的war包部署即可。我们也提供了一些命令行工具如“spring scripts”
我们主要的目的是：
- 为所有的spring开发提供一个更加快速和更加普遍的启动
- 采用的是一种开箱即用的模式，尽量去避免默认配置的偏离
- 提供一系列对大型项目类来说很常见的非功能特性（例如嵌入式服务器[embedded servers]、安全[security]、度量[metrics]、健康检查[health checks]和扩展配置[externalized configuration]）
- 完全没有代码配置和XML配置的需求
9. 系统要求
Spring Boot 2.1.8.RELEASE要求jdk 8一直兼容到jdk12以及更高。
9.1 jar包管理工具
| Build Tool | Version |
|---|---|
| Maven |
3.3+ |
| Gradle |
4.4+ |
9.2 Servlet容器
Spring Boot支持以下嵌入式servlet容器:
| Name | Servlet Version |
|---|---|
| Tomcat 9.0 |
4.0 |
| Jetty 9.4 |
3.1 |
| Undertow 2.0 |
4.0 |
10. 安装Spring Boot
Spring Boot可以与 “classic” Java开发工具一起使用，也可以作为命令行工具安装。无论哪种方式，都要求Java SDK v1.8 甚至更高。在你开始之前，你应该使用以下命令检查你目前的Java安装情况:
$ java -version如果你是java开发新手或者你只是试验一下spring boot，您可能首先去尝试Spring Boot CLI(命令行接口)。或者请继续阅读安装说明。
10.1 Java 开发环境安装说明
您可以像使用任何标准Java库一样使用Spring Boot。
在你的classpath路径下包含spring-boot-*.jar。Spring Boot不需要任何特殊的工具集成，所以您可以使用任何IDE或文本编辑器。而且spring boot没有说明特别之处，运行和debug的方式和任何一个java应用程序一样。
尽管您可以拷贝Spring Boot 的各种jar包，但是我们推荐使用jar包管理工具[build tool]，例如：Maven、Gradle
10.1.1 Maven 安装
Spring Boot要求Apache Maven 3.3或更高版本。如果你没有安装过maven，可以查看其他官方文档maven.apache.org.
Spring Boot 依赖于org.springframework.boot。你的maven pom文件必须继承至spring-boot-starter-parent项目以及声明一个或者多个“starter”，Spring Boot还提供了可选的Maven插件来创建可执行 jars。
下面展示了一个经典的pom文件：
4.0.0
com.example
myproject
0.0.1-SNAPSHOT
org.springframework.boot
spring-boot-starter-parent
2.1.8.RELEASE
org.springframework.boot
spring-boot-starter-web
org.springframework.boot
spring-boot-maven-plugin
*对于spring-boot-starter-parent的继承是最好的spring boot启动方式，但是还是可以继承和使用其他的方式，具体详看Section 13.2.2, “Using Spring Boot without the Parent POM”
10.1.2 Gradle 安装
Spring Boot使用Gradle 4.4及更高版本兼容。如果你没有安装gradle，请看另外一篇官方文档 gradle.org.
Spring Boot依赖于org.springframework.boot和maven同样的方式，不在累述。
10.2 安装 the Spring Boot CLI
The Spring Boot CLI (Command Line Interface)是一个命令行工具，您可以使用Spring快速创建原型。它允许您运行Groovy脚本，也意味着你虽然有一个类似于java的语法，但是没有了更多的样板代码
可能您不需要使用CLI来运行Spring Boot，但是它绝对是启动Spring Boot最快的方式。
10.2.1 Manual 安装
您需要从Spring软件库中下载Spring CLI发布的版本:
- spring-boot-cli-2.1.8.RELEASE-bin.zip
- spring-boot-cli-2.1.8.RELEASE-bin.tar.gz
下载好之后，按照未打包归档文件中的 INSTALL.txt说明操作。总之，那里会有一个spring脚本（spring.bat [windows下]），该脚本首先从zip包下解压，存在于bin/文件夹下。
你要么选择 使用java -jar或者.jar（该脚本帮助您确保正确设置了类路径）
10.2.2 安装SDKMAN!
SDKMAN! (The Software Development Kit Manager) 可用于管理各种二进制sdk的多个版本，包括Groovy and the Spring Boot CLI.获取地址 sdkman.io， 使用以下命令安装Spring Boot:
$ sdk install springboot
$ spring --version
Spring Boot v2.1.8.RELEASE如果你为CLI开发了一些功能，并且想要方便地访问你构建的版本，可以使用以下命令:
$ sdk install springboot dev /path/to/spring-boot/spring-boot-cli/target/spring-boot-cli-2.1.8.RELEASE-bin/spring-2.1.8.RELEASE/
$ sdk default springboot dev
$ spring --version
Spring CLI v2.1.8.RELEASE在前面的说明中，安装的是一个本地的spring实例称之为dev实例。它指向您的目标构建（build）位置，每次都需要重新构建（rebuild）spring boot项目
您可以通过运行以下命令来查看它：
$ sdk ls springboot
================================================================================
Available Springboot Versions
================================================================================
> + dev
* 2.1.8.RELEASE
================================================================================
+ - local version
* - installed
> - currently in use
================================================================================10.2.3 OSX Homebrew 安装
如果你在Mac上使用Homebrew ，你可以使用以下命令安装Spring Boot CLI:
$ brew tap pivotal/tap
$ brew install springbootHomebrew 将spring 安装到 /usr/local/bin.
10.2.4 MacPorts 安装
如果你在Mac上使用MacPorts，你可以使用以下命令安装Spring Boot CLI:
$ sudo port install spring-boot-cli10.2.5 Command-line 补全
Spring Boot CLI为BASH和zsh shell提供命令行补全的脚本。您可以在任意shell中获取脚本(也称为spring)，或者将其放入到您的个人或he system-wide的bash的初始化补全。在Debian系统上，The system-wide scripts 在/shell-completion/bash文件夹下，当新shell启动时，将执行该目录中的所有scripts（脚本）。
$ . ~/.sdkman/candidates/springboot/current/shell-completion/bash/spring
$ spring
grab help jar run test version 10.2.6 Windows Scoop安装
如果你在windows上使用Scoop，你可以使用以下命令安装Spring Boot CLI:
> scoop bucket add extras
> scoop install springbootScoop 安装spring 到~/scoop/apps/springboot/current/bin.
*如果你没有看到应用程序清单，你的安装可能是过时的scoop。在这种情况下，运行scoop updat并重试。
10.2.7 Quick-start Spring CLI 实例
您可以使用以下web应用程序来测试您的安装。先创建一个名为app.groovy的文件，如下所示:
@RestController
class ThisWillActuallyRun {
@RequestMapping("/")
String home() {
"Hello World!"
}
}然后从shell运行它，如下所示:
$ spring run app.groovy**应用程序的第一次运行比较慢，因为需要下载依赖项。后续运行要快得多。
在web浏览器中打开localhost:8080。你可以看到以下输出:
Hello World!10.3 升级Spring Boot
如果你是从1.x开始升级Spring Boot的话，查看 “migration guide” on the project wiki这个上面提供了非常详细的说明。还可以查看“release notes” ，以获得每个版本的“新特性和值得注意的特性。
当升级新功能版本时，某些属性可能已重命名或删除。Spring Boot提供了一种方法来分析应用程序的环境并在启动时打印诊断信息，并且在运行时为您临时迁移属性。要启用该功能，请在项目中添加以下依赖项:
org.springframework.boot
spring-boot-properties-migrator
runtime
**之后添加到环境中的属性，例如使用@PropertySource时，将不被考虑。
**完成迁移后，请确保从项目的依赖项中删除此模块。
要升级现有的CLI安装，请使用适当的包管理器命令(例如，brew升级)。如果您手动安装CLI，请遵循标准说明，记住更新PATH环境变量以删除任何旧的引用。
11. 开发你的第一个Spring Boot Application
本节描述如何开发一个简单的“Hello World!”web应用程序，突出Spring Boot的一些关键特性。我们使用Maven来构建这个项目，因为大多数IDE都支持它。
**在使用Spring Boot的时候，spring.io中包含了很多入门参考guides 。如果您需要解决某个特定的问题，请首先查看该文档。你可以通过查看 start.spring.io来简化下面的步骤， 从依赖项搜索器中选择“Web”启动器。这样做会生成一个新的项目结构这样样你就可以马上开始编码了。查看 Spring Initializr documentation文档细节（讲了一大堆，其实就是告诉你通过ide快捷创建项目）**
开始之前，打开终端并运行以下命令，以确保安装了有效的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 Corporation11.1 创建 POM文件
我们需要通过创建一个maven的pom文件开始。pom.xml是我们创建项目的一个配置文件。打开您最喜欢的文本编辑器，并添加以下内容:
4.0.0
com.example
myproject
0.0.1-SNAPSHOT
org.springframework.boot
spring-boot-starter-parent
2.1.8.RELEASE
上面的内容需要提供了一个可工作的工作环境（working build）。我们测试可以通过运行mvn package（您可以忽略“jar是空的——没有内容!”警告），因为上面知识测试maven启动。没有写任何代码。
11.2 增加Classpath Dependencies
pring Boot提供了许多“Starters”，方便您将jar添加到类路径中。我们的示例应用程序已经在POM的父类部分中使用了spring-boot-starter-parent。spring-boot-starter-parent是一个特殊的启动器，提供了有用的Maven默认设置。它还提供了一个 dependency-management部分，所以你可以忽略版本标签。
当你在开发特定类型的应用程序时，您可能需要对其他“Starters”提供依赖项。例如我们正在开发一个web应用程序，我们需要增加spring-boot-starter-web 依赖。在此之前，我们可以看看我们目前有什么，可以运行以下命令:
$ mvn dependency:tree
[INFO] com.example:myproject:jar:0.0.1-SNAPSHOTmvn dependency:tree 将会以tree的形式打印出所有的依赖项，您可以看到spring-boot-starter-parent本身不提供任何依赖项。如果要添加必要的依赖项，编辑pom.xml文件，在parent 部分的下面添加spring-boot-starter-web依赖项：
org.springframework.boot
spring-boot-starter-web
如果再次运行mvn dependency:tree，您会看到现在有许多附加的依赖项，包括Tomcat web服务器和Spring Boot本身。
11.3 编写Code
开始完成我们的应用，首先需要创建一个Java文件。默认情况下，Maven 执行的源文件在src/main/java下面，因此，需要创建该文件夹结构，然后添加一个名为src/main/java/Example.java的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);
}
}我们将在接下来的几节中逐步介绍重要的部分。
11.3.1 @RestController and @RequestMapping 注解
第一个注解在我们上面的例子Example 类中的@RestController注解。这个就是众所周知的原型注释。它为阅读代码和Spring的人提供提示，告诉他们这个类扮演着特殊的角色。在这个例子上，我们的类是一个Web Controller，所以当处理web发送过来的请求时，spring就会考虑到它。
** @RestController and @RequestMapping 是SpringMvc注解（它们并不是springboot里面新的定义），想要理解更多可以看这篇文章 MVC section**
11.3.2 @EnableAutoConfiguration 注解
第二个类级注释是EnableAutoConfiguration，这个注释告诉Spring Boot根据您所添加的jar依赖项“猜测”您希望如何配置Spring。通过spring-boot-starter-web增加了Tomcat 和Spring MVC，auto-configuration会自动猜测你在开发web应用和在相应地设置spring。
**自动配置被设计成可以很好地与其他“Starters”一起工作，但这两个概念并没有直接联系在一起。您可以在启动程序之外自由地选择jar依赖项。Spring Boot仍会尽力的自动配置应用程序。**
11.3.3 “main” 方法
我们的应用程序的最后一部分是main方法。这只是一个标准方法，它遵循应用程序入口点的Java约定。我们的main方法通过调用run来委托Spring Boot的SpringApplication类。SpringApplication启动我们的应用程序，启动Spring，而Spring又启动自动配置的Tomcat web服务器。我们需要通过Example.class作为run方法的参数来告诉SpringApplication哪个是主要的Spring部分。args数组也被用来传递显示任意的命令行参数。
11.4 运行 Example
这个部分，你的应用要开始运行了。因为你在pom文件中添加了spring-boot-starter-parent，你有一个run，可以使用它来启动应用程序。你可以在命令行执行mvn spring-boot:run来启动你的程序，你能看到输出类似如下:
$ mvn spring-boot:run
. ____ _ __ _ _
/\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
\\/ ___)| |_)| | | | | || (_| | ) ) ) )
' |____| .__|_| |_|_| |_\__, | / / / /
=========|_|==============|___/=/_/_/_/
:: Spring Boot :: (v2.1.8.RELEASE)
....... . . .
....... . . . (log output here)
....... . . .
........ Started Example in 2.222 seconds (JVM running for 6.514)通过浏览器，输入localhost:8080，你能看的：
Hello World!如果你想优雅的关闭应用，可以使用ctrl-c
11.5 创建一个 Executable Jar
我们通过创建一个完全只包含了可执行jar文件来完成我们的示例，该项目也可以在生产环境中运行。Executable jar(有时称为“fat jar”)是包含编译类以及代码需要运行的所有jar依赖项的归档文件。
Executable jars and Java
java并没有提供一个标准的方式去加载jar 文件（jar文件本身包含在ja中），如果您希望发布一个自定义的比较完整的应用程序，这可能会有问题。
如何解决这个问题，一些开发者使用“uber”jar，uber jar将应用程序的所有依赖项中的所有类打包到一个单独的归档文件中。这种方式会导致你去看library的时候非常的困难。如果在多个jar中使用相同的文件名(但内容不同)，也可能会出现问题。Spring Boot采用了一种不同的方法，允许您直接嵌套jar。
要创建一个executable jar，我们需要在pom文件中添加spring-boot-maven-plugin，我们只需要在依赖项部分下面插入以下行
org.springframework.boot
spring-boot-maven-plugin
保持你的pom文件，从命令行运行 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.1.8.RELEASE:repackage (default) @ myproject ---
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------如果查看目标目录，应该会看到myproject-0.0.1- snap .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.1.8.RELEASE)
....... . . .
....... . . . (log output here)
....... . . .
........ Started Example in 2.536 seconds (JVM running for 2.864)停止的话使用ctrl-c 。
12. What to Read Next
主要是一些总结，没啥必要翻译，链接：https://docs.spring.io/spring-boot/docs/2.1.8.RELEASE/reference/html/getting-started-whats-next.html