SpringBoot 官方文檔中文版 - 1. 入門指南

前言

最近在看 SpringBoot 的官方文檔，寫的很清晰，但對於中文的不好的同學，比如我自己，總是遇到不認識的詞句，於是乎，我決定把它翻譯出來。

此系列，是結合谷歌翻譯+有道翻譯，以及我英語四級的水平，僅供學習參考，感謝 SpringBoot 官方整理出如此細致的文檔。

截止目前，SpringBoot 的最新版本是 2.5.3，Spring 的最新版本是 5.3.9.

翻譯出來的目錄結構，參考 SpringBoot 的官方文檔，選取中間的核心部分。

SpringBoot 官方文檔地址：https://docs.spring.io/spring-boot/docs/current/reference/html/index.html

1. SpringBoot 介紹

SpringBoot 幫助您創建可以獨立運行的、基於 Spring 的生產級應用程序。我們對 Spring 平台和第三方庫有自己的看法，所以您可以從最簡單的開始。大多數SpringBoot 應用程序只需要很少的 Spring 配置。

您可以使用 SpringBoot 創建 Java 應用程序，通過使用 Java -jar 或更傳統的 war 包進行部署啟動。我們還提供了一個運行 spring 腳本的命令行工具。

我們的主要目標是:

• 為所有 Spring 開發提供一個非常快速和廣泛可訪問的入門體驗。

• 要有自己獨特的見解，但當需求開始偏離默認值時，要迅速離開。

• 提供大類別項目(如嵌入式服務器、安全性、度量、運行狀況檢查和外部化配置)中常見的一系列非功能特性。

• 不要代碼生成，也不需要 XML 配置。

2. 系統要求

SpringBoot2.5.3 需要 Java 8，兼容並包括 Java 16。SpringFramework5.3.9 或更高版本也是必需的。

構建工具的版本要求:

構建工具	版本
Maven	3.5+
Gradle	6.8.x, 6.9.x, and 7.x

Servlet 容器

SpringBoot 支持以下嵌入式 servlet 容器:

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

您還可以將 Spring Boot 應用程序部署到任何 Servlet 3.1+ 兼容的容器中。

3. 安裝 SpringBoot

Spring Boot 可以與 Java 開發工具一起使用，也可以作為命令行工具安裝。無論哪種方式，您都需要 Java SDK v1.8 或更高版本。在開始之前，您應該使用以下命令檢查當前的 Java 安裝:

$ java -version

3.1 Java 開發人員的安裝說明

您可以以與任何標准 Java 庫相同的方式使用 Spring Boot。為此，在類路徑中包含適當的 spring-boot-*.jar 文件。Spring Boot 不需要任何特殊的工具集成，所以您可以使用任何 IDE 或文本編輯器。另外，Spring Boot 應用程序沒有什么特殊之處，因此您可以像運行其他 Java 程序一樣運行和調試 Spring Boot 應用程序。

盡管您可以復制 Spring Boot jar，但我們通常建議您使用支持依賴項管理的構建工具(如Maven或Gradle)。

3.1.1 Maven 安裝

Spring Boot 與 Apache Maven 3.3 或更高版本兼容。如果您還沒有安裝 Maven，可以按照 [Maven .apache.org](Maven .apache.org) 上的說明操作。

在許多操作系統上，Maven 可以與包管理器一起安裝。如果你使用 OSX Homebrew，嘗試 brew install maven。Ubuntu 用戶可以運行 sudo apt-get install maven。使用 Chocolatey 的 Windows 用戶可以在一個提升的(管理員)提示符下運行 choco install maven。

譯者注：現在使用 IDEA，可以很方便地創建 SpringBoot 項目，不用這么復雜。

Spring Boot 依賴使用 org.springframework.boot groupId。通常，Maven POM 文件繼承 spring-boot-starter-parent 項目，並向一個或多個 “starter”聲明依賴項。Spring Boot 還提供了一個可選的 Maven 插件來創建可執行的 jar。

3.1.2 Gradle 安裝

Spring Boot 與 Gradle 6.8、6.9和7.x兼容。如果你還沒有安裝 Gradle，你可以按照gradle.org上的說明操作。

Spring Boot 依賴項可以通過使用 org.springframework.boot 組聲明。通常，您的項目會向一個或多個 “starter” 聲明依賴項。Spring Boot 提供了一個有用的 Gradle 插件，可以用來簡化依賴聲明和創建可執行 jar。

3.2 Spring Boot CLI 安裝

這個用處不大， 暫不翻譯。

具體參考官網：https://docs.spring.io/spring-boot/docs/current/reference/html/getting-started.html#getting-started

4. 開發你的第一個 SpringBoot 程序

spring.io 網站包含許多使用 Spring Boot 的入門指南。如果你需要解決一個特定的問題，首先檢查那里。

您可以通過 start.spring.io並從依賴項搜索器中選擇“Web”啟動器來快捷執行以下步驟。這樣做將生成一個新的項目結構，以便您可以立即開始編碼。更多細節請查看start.spring.io用戶指南。

在我們開始之前，打開終端並運行以下命令，以確保您安裝了有效的 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 文件。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.5.3</version>
    </parent>

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

</project>

前面的清單應該提供一個工作的構建。您可以通過運行mvn package來測試它.

此時，您可以將項目導入 IDE(大多數現代 Java IDE 都包含對 Maven 的內置支持)。為簡單起見，我們在本例中繼續使用純文本編輯器。

4.2 添加類路徑依賴

Spring Boot 提供了許多“啟動器”，允許您將 jar 添加到類路徑中。我們的冒煙測試應用程序使用 POM 的父部分中的 spring-boot-starter-parent。spring-boot-starter-parent 是一個特殊的啟動器，它提供了有用的 Maven 缺省值。它還提供了一個依賴項管理部分，這樣您就可以省略其他依賴項的版本標記。

其他“starter”提供了在開發特定類型的應用程序時可能需要的依賴項。因為我們正在開發一個 web 應用程序，所以我們添加了一個 spring-boot-start-web 依賴項。在此之前，我們可以通過運行以下命令來查看當前擁有的內容:

$ mvn dependency:tree

[INFO] com.example:myproject:jar:0.0.1-SNAPSHOT

mvn dependency:tree命令打印你的項目依賴項的樹狀表示。您可以看到 spring-boot-starter-parent 本身不提供依賴項。要添加必要的依賴項，編輯 pomo .xml，並在 parent 部分的正下方添加 spring-boot-start-web 依賴項:

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

如果您再次運行mvn dependency:tree，您會看到現在有許多額外的依賴項，包括 Tomcat web 服務器和 Spring Boot 本身。

4.3 寫代碼

要完成應用程序，我們需要創建一個 Jav a文件。默認情況下，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 and @RequestMapping 注解

MyApplication 類上的第一個注解是 @RestController。這被稱為原型注釋。它為閱讀代碼的人們以及 Spring 提供了類扮演特定角色的提示。在本例中，我們的類是一個 web @Controller，所以 Spring 在處理傳入的 web 請求時考慮它。

@RequestMapping 注釋提供了“路由”信息。它告訴 Spring，任何帶有 / 路徑的 HTTP 請求都應該映射到 home 方法。@RestController 注釋告訴 Spring 將結果字符串直接呈現給調用者。

@RestController 和 @RequestMapping 注釋是 Spring MVC 注釋(它們不是特定於 Spring Boot 的)。有關更多細節，請參閱 Spring 參考文檔中的 MVC 部分。

4.3.2 @EnableAutoConfiguration 注解

第二個類級注釋是 @EnableAutoConfiguration。這個注釋告訴 Spring Boot 根據您添加的 jar 依賴項“猜測”您想要如何配置 Spring。由於 Spring -boot-start-web 添加了 Tomcat 和 Spring MVC，自動配置假定您正在開發一個 web 應用程序，並相應地設置 Spring。

Starters 和 Auto-configuration：自動配置被設計成與“starter”一起工作，但是這兩個概念並沒有直接聯系在一起。您可以在啟動器之外自由選擇 jar 依賴項。Spring Boot 仍然在盡力自動配置應用程序。

4.3.3 main 方法

應用程序的最后一部分是主方法。這是一個標准方法，它遵循應用程序入口點的 Java 約定。我們的主方法通過調用 run 來委托給 Spring Boot 的SpringApplication 類。SpringApplication 會引導我們的應用程序，啟動 Spring，而 Spring 又會啟動自動配置的 Tomcat web 服務器。我們需要將MyApplication.class 作為參數傳遞給 run 方法，告訴 SpringApplication 哪個是主 Spring 組件。args 數組也被傳遞以公開任何命令行參數。

4.4 運行示例

此時，您的應用程序應該可以工作了。由於您使用了 spring-boot-starter-parent POM，因此您可以使用一個有用的運行目標來啟動應用程序。輸入mvn spring-boot:run從根項目目錄啟動應用程序。你應該看到類似如下的輸出:

$ mvn spring-boot:run

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

如果你打開一個 web 瀏覽器到 localhost:8080，你應該看到以下輸出:

Hello World!

要優雅地退出應用程序，請按 ctrl-c。

4.5 創建可執行的 jar 包

我們通過創建一個完全自包含的可執行 jar 文件來完成我們的示例，這個 jar 文件可以在生產環境中運行。可執行jar(有時稱為“胖jar”)是包含已編譯類以及代碼運行所需的所有 jar 依賴項的歸檔文件。

Java 沒有提供加載嵌套 jar 文件(本身包含在jar中的jar文件)的標准方法。如果您希望分發一個自包含的應用程序，這可能會有問題。

為了解決這個問題，許多開發人員使用 “uber”jar。一個超級 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-parent POM 包括 配置來綁定重新打包目標。如果不使用 parent 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.5.3: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

您還應該看到一個小得多的文件，名為 myproject-0.0.1-SNAPSHOT.jar。target 目錄中的原始文件。這是 Spring Boot 重新打包之前 Maven 創建的原始 jar 文件。

要運行該應用程序，請使用 java -jar 命令，如下所示:

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

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

和前面一樣，要退出應用程序，請按 ctrl-c。

5. 接下來讀什么

希望本節提供一些 Spring Boot 基礎知識，幫助您編寫自己的應用程序。如果您是面向任務類型的開發人員，您可能希望跳過 spring.io，並查看一些入門指南，解決具體的“我如何用 Spring 做那個?”問題。我們還有 Spring boot 特定的“How-to”參考文檔。

否則，下一個合乎邏輯的步驟就是 use.html 進行閱讀。如果您真的沒有耐心，也可以提前閱讀 Spring Boot 的特性。

每天學習一點點，每天進步一點點。