翻譯《Spring Boot Reference Guide》-第二單元.入門

第二單元. 入門

如果你剛開始接觸SpringBoot，或者Spring，從閱讀這章節開始。它會回答基本的“SpringBoot是什麼？”，“怎麼用SpringBoot？”和“何要用SpringBoot？”問題。它包含了SpringBoot介紹，以及安裝說明。然後，我們引導你構建你的第一個SpringBoot應用，並討論一些核心原則。

8. 介紹SpringBoot

SpringBoot使創建可運行的，獨立的，基於Spring的產品級應用變得簡單。我們封裝了Spring平臺和第三方庫，讓你輕鬆入門。大部分SpringBoot應用只需要少量的配置。

你可以使用SpringBoot創建使用java-jar啓動或者傳統的war包部署的java應用。我們還提供運行“spring腳本”的命令行工具。

我們主要目標：

• 爲所有Spring開發提供根本上更快且更廣泛可理解的入門經驗。
• 開箱即用，但可以根據需求快速修改默認配置。
• 提供一系統大型項目通用的非功能型特色功能（例如嵌入式服務，安全性，指標，運行狀況檢查和外部化部署）
• 完全沒有代碼生成，也不需要XML配置。

9. 系統要求

Spring Boot 2.1.5.RELEASE需要Java8並且兼容更高到Java11（包含）。Spring Framework 5.1.7.RELEASE或者更高版本。

爲以下構建工具提供了明確的構建支持：

Build Tool	Version
Maven	3.3+
Gradle	4.4+

9.1 Servlet容器

SpringBoot支持以下嵌入式容器：

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

你也可以使用任何Servlet 3.1+兼容容器來部署SpringBoot應用。

10. 安裝SpringBoot

SpringBoot可以和“經典”Java開發工具一起使用或作爲一個命令行工具安裝。不管哪種方式，你都需要JavaSDK1.8或者更高版本。當你開始之前，你可以使用以下命令來檢查你當前Java安裝版本：

$ java -version

如果你是Java開發新手或者你想嘗試SpringBoot，則可能要先試下SpringBootCLI（命令行界面）。否則，閱讀“經典”安裝說明。

10.1 Java開發人員安裝指南

你可以像使用標準Java庫一樣使用SpringBoot。在classpath下添加適當spring-boot-*.jar文件。SpringBoot不需要特定工具集成，你可以使用任何IDE或者文件編輯器。另外，SpringBoot應用沒有任何特別的，你可以像其他Java程序一樣運行和調試SpringBoot應用。

儘管你可以複製SpringBoot的jar包，但是我們建議你使用支持依賴關係管理的構建工具（例如Maven或Gradle）。

Maven安裝

SpringBoot兼容Apache Maven 3.3或更高版本。如果尚未安裝Maven，則可以按照maven.apache.org上的說明進行操作。

在很多操作系統，Maven被安裝用於包管理。如果你使用OSX Homebrew，可以嘗試brew install maven。Ubuntu用戶可以運行sudo apt-get install maven。Windows用戶可以通過Chocolatey運行choco install maven。

Homebrew是一款Mac OS平臺下的軟件包管理工具,擁有安裝、卸載、更新、查看、搜索等很多實用的功能。

Chocolatey是Windows下的包管理工具。

SpringBoot依賴使用org.springframework.boot.groupId。通常，你的POM文件繼承自spring-boot-starter-parent項目，依賴一個或多個“啓動器”。SpringBoot支持一個可選擇的Maven插件去創建可執行的jars。

下列列表展示一個經典的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>
 <!-- Inherit defaults from Spring Boot -->
 <parent>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-parent</artifactId>
  <version>2.1.5.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>

spring-boot-starter-parent是一種很好的方式去使用SpringBoot，但是它不一定是適合所有情況。有時候你需要繼承另外的父類POM，或者你不喜歡我們默認設置。如果這樣，查看Section 13.2.2 “Using Spring Boot without the Parent POM”，提供一種使用import範圍的解決方案。

<dependencyManagement>
 <dependencies>
  <dependency>
   <!-- Import dependency management from Spring Boot -->
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-dependencies</artifactId>
   <version>2.1.5.RELEASE</version>
   <type>pom</type>
   <scope>import</scope>
  </dependency>
 </dependencies>
</dependencyManagement>

Gradle安裝

SpringBoot兼容Gradle4.4或更高版本。Gradle，則可以按照gradle.org上的說明進行操作。

SpringBoot依賴使用org.springframework.boot.group。通常，你的項目會依賴一個或多個“啓動器”。SpringBoot提供一個有效的Gradle插件，它可以簡化依賴聲明和創建可執行的jars。

當你需要構建一個工程時，Gradel包裝器提供了一種“obtaining”Gradle的好方法。它是一個小腳本和包，你可以把它們和代碼一起提交，便以引導構建過程。查看細節：docs.gradle.org/4.2.1/userguide/gradle_wrapper.html

更多關於SpringBoot和Gradle的基礎細節，可以查找Getting Started章節Gradle plugin’s參考指南。

10.2 SpringBoot CLI 安裝

該章節忽略

10.3 升級早期版本的SpringBoot

如果你想從早期正式版本的springboot升級，查看項目wiki中的“遷移指南”，它提供詳細的升級介紹。也可以查看“發佈說明”，以獲得每個版本的“新的和值得注意的”特性的列表。

升級到新功能版本時，一些配置可能會重命名或者被移除。SpringBoot提供一種方式去分析你應用的環境和在啓動時打印診斷內容，還可以在運行時爲你臨時遷移屬性。要啓用該特性，添加下方的依賴到你的工程中：

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

晚添加到環境中的屬性，例如使用@PropertySource時，將不被考慮。

一旦你完成遷移，請確保在你的項目依賴中移除該模塊。

要升級現有的CLI安裝，請使用適當的包管理器命令(例如，brew升級)，或者，如果你手動安裝了CLI，請遵循標準說明，記住更新您的PATH環境變量以刪除任何舊的引用。

介紹migrator文章：實戰《Spring Boot 2.1.5》-屬性遷移工具Migrator

11. 開發你的第一個SpringBoot應用

這個章節詳細介紹如何開發一個簡單的“HelloWorld!”網頁應用來體現springboot一些關鍵特徵。我們使用Maven來構建這個項目，大多數IDE都支持Maven。

spring.io網站包含很多使用springboot的“入門”指南。如果你要解決特殊問題，優先從該網站找答案。

你可以通過以下快捷方式：訪問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

這個示例需要在它自己的文件夾中創建。後續說明是假定你已經在創建了適當的文件夾，並且它是你的當前目錄。

11.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.1.5.RELEASE</version>
 </parent>
 <!-- Additional lines to be added here... -->
</project>

前面清單可以給你一個可用的構建。你可以通過運行mvn package來測試。（現在，你可以忽略“jar將是空的-沒有內容被標記爲包含”的警告）

此時，你可以導入該工程到IDE（大部分現代JavaIDE都包含對Maven的內置支持）。爲了簡單起見，我們在本例中繼續使用純文本編輯器。

11.2 添加classpath依賴

SpringBoot提供大量的“啓動器”來讓你添加jar到你的classpath。我們示例應用在pom文件的parent使用了spring-boot-starter-parent。spring-boot-starter-parent是一個特殊的啓動器，它提供有用的Maven默認設置。它也提供依賴管理部分，這樣你在使用“blessed”的依賴就可以忽略version標籤。

因爲blessed不知道如何翻譯。這個功能就是當使用了或者，那在依賴它pom中的依賴時，可以忽略版本。

其他啓動器也提供依賴，當你可能需要開發一個特定類型的應用。之前我們開發網頁應用，我們添加了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依賴在父部分下方：

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

如果你重新運行mvn dependency:tree，你可以看到大量附加的依賴，包含了Tomcat服務和SpringBoot。

11.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請求時會考慮使用它。

spring中關於stereotype annotation的定義有：@Component，@Repository，@Service，@Controller

該@RequestMapping註釋提供“路由”的信息。它告訴Spring任何具有/路徑的HTTP請求都應映射到該home方法。該 @RestController註解告訴Spring使得到的字符串直接返回給調用者。

@RestController與@RequestMapping註解是SpringMVC的註解。（它們不是特定於SpringBoot）有關更多詳細信息，請參見Spring參考文檔中的MVC部分 。

@EnableAutoConfiguration註解

第二個類級別註解是@EnableAutoConfiguration。這個註解告訴了SpringBoot基於你添加的jar依賴去“猜測”你打算如何配置Spring。由於spring-boot-starter-web添加Tomcat和SpringMVC，自動配置就假定你在開發一個web應用並設置spring相應配置。

自動配置被設計用於更好的服務於“Starters”，但是這兩個觀念沒有直接的關聯。你可以自由添加和選擇啓動器以外的jar包依賴。SprinBoot依然會盡可能的自動配置你的應用。

“main”方法

我們應用的最終部分是main方法。這是一個標準的方法，它遵循應用程序入口點的Java約定。我們main方法委託SpringBoot的SpringApplicaiton類調用run方法。SpringApplication引導我們應用，啓動Spring，這反過來又啓動了自動配置的TomcatWeb服務器。我們需要通過Excmple.class作爲一個參數到run方法來告訴SpringApplication，哪個是主要的Spring組件。args數組也傳遞公開命令行參數。

11.4 運行Excmple

這個時候，你的應用程序應該可以工作。之前你使用了spring-boot-starter-parent的POM，你有一個有用的run目標，你可以用來啓動應用程序。在項目根目錄輸入mvn spring-boot:run來啓動應用程序。你應該可以看到類似以下的輸出：

$ mvn spring-boot:run
  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =|_||___/=/_/_/_/
 :: Spring Boot ::  (v2.1.5.RELEASE)
....... . . .
....... . . . (log output here)
....... . . .
........ Started Example in 2.222 seconds (JVM running for 6.514)

如果你通過web瀏覽器訪問localhost:8080，你應該可以看到以下的輸出：

Hello World!

要正常退出該應用程序，請按ctrl-c。

11.5 創建可執行jar

我們創建一個在生產環境中完全獨立可執行的jar文件來結束我們的示例。可執行jar（有時候稱“fatjars”）是包含你所有已編譯的class文件以及代碼運行所依賴的jar包的歸檔文件。

Java沒有提供一種標準的方式去加載嵌套的jar文件（jar中本身包含的jar文件）。如果你要發佈一個自包含的應用，可能會有問題。

爲了解決這個問題，很多開發者使用了“uber”jar。unberjar將應用程序所有依賴項的類文件打包成一個單獨的歸檔。這種方法的問題在於，很難查看應用程序中包含哪些庫。如果在多個jar中使用相同的文件名（但具有不同的內容），也可能會產生問題。

SpringBoot採用另一種方法，實際上允許你直接嵌套jar。

要創建可執行jar包，我們需要添加spring-boot-maven-plugin到我們的pom.xml中。爲此，在你的依賴部分下方插入以下行：

<build>
 <plugins>
  <plugin>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-maven-plugin</artifactId>
  </plugin>
 </plugins>
</build>

spring-boot-starter-parent的POM包含了配置去綁定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.1.5.RELEASE:repackage (default) @ myproject --
[INFO] -----------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ----------------------------------------------------------------------

如果你查看targer目錄，你應該可以看到myproject-0.0.1-SNAPSHOT.jar。這個文件差不多10MB。如果你要窺視內部，你可以使用jar tvf，如下：

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

你應該可以在targer目錄看到更小的文件myproject-0.0.1-SNAPSHOT.jar.original。這是Maven在SpringBoot重新打包之前創建的原始jar文件。

要運行該應用程序，請使用以下java -jar命令：

$ java -jar target/myproject-0.0.1-SNAPSHOT.jar
  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =|_||___/=/_/_/_/
 :: Spring Boot ::  (v2.1.5.RELEASE)
....... . . .
....... . . . (log output here)
....... . . .
........ Started Example in 2.536 seconds (JVM running for 2.864)

要退出該應用程序，請按ctrl-c。