1. 程式人生 > >SpringBoot 2.0.5.RELEASE 中文翻譯筆記Getting Started

SpringBoot 2.0.5.RELEASE 中文翻譯筆記Getting Started

Getting Started

如果你在開始使用SpringBoot或者是"Spring"時,請首先閱讀本章節. 它回答了一些基本的問題,“它是什麼?”,“能做什麼”,“為什麼選擇它”. 本章介紹了SpringBoot,以及一些安裝說明然後我們將構建第一個SpringBoot應用程式,並討論一些核心的問題。

Introducing Spring Boot

SpringBoot可以輕鬆的構建獨立執行的基於Spring的應用程式。我們對Spring平臺與一些其他的第三方庫依賴進行了一些整合. 因此大多數的應用程式僅僅只需要少量 的配置就可以執行。

你可以使用SpringBoot建立Java應用程式,它支援java -jar

或者是更為傳統的war部署.我們將提供一個命令列工具卡來執行 “spring scripts”.

我們的主要目標是:

  • 為所有Spring的開發提供快速且廣泛的入門體驗
  • 開箱即用
  • 提供一系列對大型專案通用的非功能性功能(例如嵌入式伺服器,安全性,指標,執行狀況檢查和外部化配置).
  • 絕對沒有程式碼生成,也不需要XML配置。

System Requirements

為以下構建工具提供了顯式構建支援:

Build Tool Version
Maven 3.2+
Gradle 4.4+

Servlet Containers

Spring Boot 支援如下嵌入式容器:

Name Servlet Version
Tomcat 9.0 3.1+
Jetty 9.4 3.1+
Undertow 1.4 3.1+

你可以部署你的Spring Boot到任意Servlet 3.1+相容的容器.

Installing Spring Boot

Spring Boot 可以使用 “classic” JAVA開發工具安裝為命令列工具. 無論哪種方式, 你需要Java SDK v1.8 或者更高版本. 在這之前, 你可以通過以下命令來檢查你當前所安裝的JAVA版本:

$ java -version

如果你是一名新的JAVA開發者,或者想體驗一下Spring Boot, 你可以嘗試使用

Spring Boot CLI (Command Line Interface) . 除此之外, 請繼續閱讀 “classic” 安裝說明.

Installation Instructions for the Java Developer

您可以像使用任何標準Java庫一樣使用Spring Boot. 為此,請在classpath中包含相應的spring-boot-*.jar 檔案. Spring Boot 不需要任何特殊工具整合, 因此你可以使用任意的IDE或文字編輯器. 此外,Spring Boot應用程式沒有什麼特別之處, 因此,您可以像執行任何其他Java程式一樣執行和除錯Spring Boot應用程式。

雖然您可以複製Spring Boot jar,但我們通常建議您使用支援依賴關係管理的構建工具 (例如Maven 或者 Gradle).

Maven Installation

Spring Boot 相容 Apache Maven 3.2+. 如果您還沒有安裝Maven, 你可以檢視https://maven.apache.org/.

TIP: On many operating systems, Maven can be installed with a package manager. If you use OSX Homebrew, try brew install maven. Ubuntu users can run sudo apt-get install maven. Windows users with https://chocolatey.org/[Chocolatey] can run choco install maven from an elevated (administrator) prompt.

Spring Boot 依賴使用 org.springframework.boot groupId. 通常, 你的 Maven POM 檔案繼承spring-boot-starter-parent 專案和宣告對一個或多個“Starters”的依賴 Spring Boot也提供一個可選的Maven plugin來建立一個可執行的Jar。

The following listing shows a typical pom.xml file:

	<?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 http://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>{spring-boot-version}</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>
		<!-- Add Spring repositories -->
		<!-- (you don't need this if you are using a .RELEASE version) -->
		<repositories>
			<repository>
				<id>spring-snapshots</id>
				<url>https://repo.spring.io/snapshot</url>
				<snapshots><enabled>true</enabled></snapshots>
			</repository>
			<repository>
				<id>spring-milestones</id>
				<url>https://repo.spring.io/milestone</url>
			</repository>
		</repositories>
		<pluginRepositories>
			<pluginRepository>
				<id>spring-snapshots</id>
				<url>https://repo.spring.io/snapshot</url>
			</pluginRepository>
			<pluginRepository>
				<id>spring-milestones</id>
				<url>https://repo.spring.io/milestone</url>
			</pluginRepository>
		</pluginRepositories>
	</project>

通過spring-boot-starter-parent 來使用Spring Boot時一個不錯的選擇, 但它可能並不適合所有的場景. 有時候你也許需要繼承不同的parent POM, 或者你不想要預設的配置. 在這些情況下, 參見 Section 13.2.2,""Using Spring Boot without the Parent POM"使用匯入範圍的替代解決方案。.

Installing the Spring Boot CLI

Spring Boot CLI (Command Line Interface) 是一個命令列工具使用它你可以快速的構建Spring原型的工程.它允許你執行Groovy指令碼, 這意味著您擁有熟悉的類似Java的語法,而沒有太多的樣板程式碼。 CLI不是構建Spring Boot的必要工具,但它絕對是讓Spring應用程式開始執行的最快方法。

Manual Installation

您可以從Spring軟體庫下載Spring CLI發行版:

下載完成後,請按照解壓縮的存檔中的INSTALL.txt說明進行操作. 綜上所述, 這是一個 spring script (spring.bat for Windows) 在.zip 檔案中的bin/目錄下 . 另外, 你可以使用java -jar.jar 檔案 (該指令碼可幫助您確保正確設定類路徑).

Installation with SDKMAN!

SDKMAN! (軟體開發包管理器) 可以管理多個版本的各種二進位制的SDKs,包括Groovy和Spring Boot CLI. 獲取SDKMAN!和安裝Spring Boot 可以通過如下命令: commands:

	$ sdk install springboot
	$ spring --version
	Spring Boot v{spring-boot-version}

如果您為CLI開發功能並希望輕鬆訪問您構建的版本,請使用以下命令:

	$ sdk install springboot dev /path/to/spring-boot/spring-boot-cli/target/spring-boot-cli-{spring-boot-version}-bin/spring-{spring-boot-version}/
	$ sdk default springboot dev
	$ spring --version
	Spring CLI v{spring-boot-version}

前面的說明安裝了一個名為devspring本地例項.它指向您的目標構建位置, 所以每次重建Spring Boot時,spring都是最新的。

您可以通過執行以下命令來檢視它:

	$ sdk ls springboot

	================================================================================
	Available Springboot Versions
	================================================================================
	> + dev
	* {spring-boot-version}

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

OSX Homebrew Installation

如果你是Mac系統,你可以使用Homebrew, 你可以通過下面的命令安裝Spring Boot:

	$ brew tap pivotal/tap
	$ brew install springboot

Homebrew 安裝 spring/usr/local/bin.

NOTE:如果你沒有看到公式, 你brew的版本可能過時了。在這種情況下, 可以執行 brew update更新版本.

MacPorts Installation

如果你是Mac系統,你可以使用MacPorts, 你可以通過下面的命令安裝Spring Boot:

	$ sudo port install spring-boot-cli

Command-line Completion

Spring Boot CLI為BASH andzsh 提供命令完成的指令碼.您可以在任何shell中獲取指令碼(也稱為spring),或者將其放入個人或系統範圍的bash完成初始化中.在Debian system, 系統範圍的指令碼位於/shell-completion/bash中,當新shell啟動時,該目錄中的所有指令碼都會執行。

例如,如果已使用SDKMAN安裝,則手動執行指令碼,使用下面的命令:

	$ . ~/.sdkman/candidates/springboot/current/shell-completion/bash/spring
	$ spring <HIT TAB HERE>
	  grab  help  jar  run  test  version

NOTE: 如果你使用Homebrew或者MacPorts安裝Spring Boot CLI, 命令列完成指令碼會自動在shell中註冊。

Windows Scoop Installation

如果你是windows系統,請使用 Scoop,安裝命令如下:

	> scoop bucket add extras
	> scoop install springboot

Scoop 安裝 spring~/scoop/apps/springboot/current/bin.

NOTE: 如果您沒有看到應用清單,你安裝的scoop也許過時了.在此情況下執行 scoop update 進行更新.

Quick-start Spring CLI Example

您可以使用以下Web應用程式來測試您的安裝。首先,建立一個名為app.groovy的檔案,如下所示:

	@RestController
	class ThisWillActuallyRun {

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

	}

然後從shell執行它,如下所示:

	$ spring run app.groovy

NOTE: 第一次執行程式會比較慢, 因為會下載依賴.隨後執行就會較快。

Hello World!

=== Upgrading from an Earlier Version of Spring Boot 如果要從早期版本的Spring Boot升級, 檢查"migration guide" 開啟wiki,提供詳細的升級說明。另請檢視“發行說明”,瞭解每個版本的“新的和值得注意的”功能列表。

升級到新版本時, 一些屬性被重新命名或者移除. Spring Boot 一種分析應用程式環境和啟動時列印診斷的方法, 還可以在執行時臨時遷移屬性。可以通過新增如下依賴,啟用此功能:

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

WARNING: 延遲新增到環境的屬性(例如使用@PropertySource時)將不會被考慮在內

NOTE:完成遷移後,請確保從專案的依賴項中刪除此模組。

要升級現有CLI安裝,請使用相應的軟體包管理器命令 (for example, brew upgrade) , 如果手動安裝CLI,請參考standard instructions, 記住要更新PATH環境變數刪除任何舊的引用.

Developing Your First Spring Boot Application

本節介紹如何開發一個簡單的“Hello World!”Web應用程式,該應用程式突出了Spring Boot的一些主要功能.我們使用Maven來構建這個專案,因為大多數IDE都支援它.

spring.io網站包含許多使用Spring Boot的“入門”指南guides. 如果您需要解決特定問題, 可以先檢視那裡.您可以通過轉到start.spring.io並從依賴關係搜尋器中選擇“Web”啟動器來快捷執行以下步驟。這樣做會生成一個新的專案結構,以便您可以立即開始編碼。 Check有關更多詳細資訊,請檢視Spring Initializr documentation

在開始之前,開啟終端並執行以下命令以確保安裝了有效的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.3.9 (bb52d8502b132ec0a5a3f4c09453c07478323dc5; 2015-11-10T16:41:47+00:00)
	Maven home: /usr/local/Cellar/maven/3.3.9/libexec
	Java version: 1.8.0_102, vendor: Oracle Corporation

NOTE: 此示例需要在其自己的資料夾中建立。後續說明假定您已建立合適的資料夾,並且它是您當前的目錄。

Creating the POM

我們需要建立一個 pom.xml 檔案. 這個 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 http://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>{spring-boot-version}</version>
		</parent>

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


		<!-- (you don't need this if you are using a .RELEASE version) -->
		<repositories>
			<repository>
				<id>spring-snapshots</id>
				<url>https://repo.spring.io/snapshot</url>
				<snapshots><enabled>true</enabled></snapshots>
			</repository>
			<repository>
				<id>spring-milestones</id>
				<url>https://repo.spring.io/milestone</url>
			</repository>
		</repositories>
		<pluginRepositories>
			<pluginRepository>
				<id>spring-snapshots</id>
				<url>https://repo.spring.io/snapshot</url>
			</pluginRepository>
			<pluginRepository>
				<id>spring-milestones</id>
				<url>https://repo.spring.io/milestone</url>
			</pluginRepository>
		</pluginRepositories>
	</project>

上面的清單應該為您提供有效的構建. 你可以通過執行mvn package 來進行測試(現在, 你可以忽略"jar will be empty - no content was marked for inclusion!" 的警告).

NOTE: A此時,您可以將專案匯入IDE(大多數現代Java IDE都包含對Maven的內建支援). 為簡單起見,我們繼續為此示例使用純文字編輯器。

Adding Classpath Dependencies

Spring Boot提供了許多“Starters”,可以將jar新增到classpath.我們的示例應用程式已經在POM的父節中使用了spring-boot-starter-parent. spring-boot-starter-parent是一個特殊的啟動器,提供有用的Maven預設值。它還提供了一個依賴項管理部分(dependency-management),以便您可以省略依賴項的version版本標記。

其他“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依賴項:

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

如果你再次執行 mvn dependency:tree ,您會看到現在有許多其他依賴項,包括Tomcat Web伺服器和Spring Boot本身。

Writing the Code

要完成我們的應用程式,我們需要建立一個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) throws Exception {
			SpringApplication.run(Example.class, args);
		}

	}

雖然這裡的程式碼不多,但還是有很多程式碼。我們將在接下來的幾節中逐步介紹重要部分.

The @RestController and @RequestMapping Annotations

Example 類中的第一個註解是@RestController. 這被稱為_構造型_註釋. 它為閱讀程式碼的人提供了提示,而對於Spring來說,該類扮演著特定的角色. 在這種情況下,我們的類是一個 web @Controller,所以Spring在處理傳入的Web請求時會考慮它。

@RequestMapping 註解提供 “routing” 資訊. 它告訴任意的HTTP request 使用/路徑的請求應該對映到home方法。 @RestController 註解告訴Spring將結果字串直接渲染回撥用者。

TIP: The @RestController and @RequestMapping 註解是Spring MVC的註解. (它們不屬於Spring Boot.) 有關更多詳細資訊,請參閱Spring參考文件中的MVC部分

The @EnableAutoConfiguration Annotation

第二個類級別的註解是 @EnableAutoConfiguration.這個註解告訴 Spring Boot 根據你新增的jar依賴關係“猜測”你想要如何配置Spring。由於spring-boot-starter-web添加了Tomcat和Spring MVC,因此自動配置假定您正在開發Web應用程式並相應地設定Spring。.Starters and Auto-configuration

自動配置旨在與“啟動器”配合使用,但這兩個概念並不直接相關。您可以自由選擇並在首發之外選擇jar依賴項。 Spring Boot仍然盡力自動配置您的應用程式。

The “main” Method

應用程式的最後一部分是main方法. 這只是遵循應用程式入口點的Java約定的標準方法.我們的main方法通過呼叫run來委託Spring Boot的SpringApplication類。 SpringApplication引導我們的應用程式,啟動Spring,然後啟動自動配置的Tomcat Web伺服器。 我們需要將Example.class作為引數傳遞給run方法,以告訴SpringApplication是主要的Spring元件。args陣列也被傳遞以暴露任何命令列引數。

Running the Example

此時,您的應用程式應該可以工作. 由於您使用了spring-boot-starter-parent POM,因此您可以使用一個有用的執行目標來啟動應用程式. 輸入mvn spring-boot:run從根專案目錄執行以啟動應用程式。您應該看到類似於以下內容的輸出:

	$ mvn spring-boot:run

	  .   ____          _            __ _ _
	 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
	( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
	 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
	  '  |____| .__|_| |_|_| |_\__, | / / / /
	 =========|_|==============|___/=/_/_/_/
	 :: Spring Boot ::  (v{spring-boot-version})
	....... . . .
	....... . . . (log output here)
	....... . . .
	........ Started Example in 2.222 seconds (JVM running for 6.514)
Hello World!

要正常退出應用程式,請按ctrl-c.

Creating an Executable Jar

我們通過建立一個完全自包含的可執行jar檔案來完成我們的示例,我們可以在生產中執行它. 可執行的jars (有時被稱為 “fat jars”)是包含已編譯的類以及程式碼需要執行的所有jar依賴項的歸檔檔案。

Executable jars and Java Java沒有提供載入巢狀jar檔案的標準方法 (jar檔案本身包含在jar中). 如果您要釋出自包含的應用程式,這可能會有問題。

為了解決這個問題,許多開發人員使用"uber" jars. uber jar將所有應用程式依賴項中的所有類打包到一個存檔中. 這種方法的問題在於很難看出應用程式中有哪些庫. 如果在jars中使用相同的檔名(但具有不同的內容),也可能會有問題。

要建立可執行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包含<executions>配置以繫結repackage目標. 如果您不使用父POM,則需要自己宣告此配置。有關詳細資訊,請參閱外掛plugin documentation文件。

儲存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:{spring-boot-version}: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.originaltarget 目錄. 這是Maven在Spring Boot重新打包之前建立的原始jar檔案。

執行這個應用程式, 使用 java -jar 命令, 如下:

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

	  .   ____          _            __ _ _
	 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
	( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
	 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
	  '  |____| .__|_| |_|_| |_\__, | / / / /
	 =========|_|==============|___/=/_/_/_/
	 :: Spring Boot ::  (v{spring-boot-version})
	....... . . .
	....... . . . (log output here)
	....... . . .
	........ Started Example in 2.536 seconds (JVM running for 2.864)

要正常退出應用程式,請按ctrl-c.

What to Read Next

希望本節提供了一些Spring Boot基礎知識,讓您開始編寫自己的應用程式. 如果您是面向任務的開發人員型別,您可能需要跳轉到spring.io並檢視一些入門指南,這些指南解決了具體的“如何使用Spring實現這一點?”問題。我們還有特定於Spring Boot的“操作方法”參考文件。

Spring Boot repository有一堆可以執行的示例. 樣本獨立於其餘程式碼 (也就是說,您不需要構建其餘的來執行或使用示例).