使用 Spring 建構 RESTful Web 服務

原标題：Spring認證|使用 Spring 建構 RESTful Web 服務

本指南将引導您完成使用 Spring 建立“Hello, World”RESTful Web 服務的過程。

你将建造什麼

您将建構一個接受 HTTP GET 請求的服務http://localhost:8080/greeting。

它将以問候語的 JSON 表示形式響應，如下面的清單所示：

{"id":1,"content":"Hello, World!"}

您可以使用name查詢字元串中的可選參數自定義問候語，如以下清單所示：

http://localhost:8080/greeting?name=User

的name參數值将覆寫的預設值World，并反映在響應時，如下面的清單顯示：

{"id":1,"content":"Hello, User!"}

如何完成本指南

與大多數 Spring入門指南一樣，您可以從頭開始并完成每個步驟，也可以繞過您已經熟悉的基本設定步驟。無論哪種方式，您最終都會得到有效的代碼。

要從頭開始，請轉到從 Spring Initializr 開始。

要跳過基礎知識，請執行以下操作：

下載下傳并解壓縮本指南的源代碼庫，或使用Git克隆它：git clone https://github.com/spring-guides/gs-rest-service.git

CD光牒進入 gs-rest-service/initial

跳轉到建立資源表示類。

完成後，您可以根據 中的代碼檢查結果gs-rest-service/complete。

從 Spring Initializr 開始

如果您使用 Maven，請通路Spring Initializr以生成具有所需依賴項 (Spring Web) 的新項目。

以下清單顯示了pom.xml選擇 Maven 時建立的檔案：

Unresolved directive in - include::initial/pom.xml[]

如果您使用 Gradle，請通路Spring Initializr以生成具有所需依賴項 (Spring Web) 的新項目。

以下清單顯示了build.gradle在您選擇 Gradle 時建立的檔案：

Unresolved directive in - include::initial/build.gradle[]

手動初始化（可選）

如果您想手動初始化項目而不是使用前面顯示的連結，請按照以下步驟操作：

導航到https://start.spring.io。此服務包含應用程式所需的所有依賴項，并為您完成大部分設定。

選擇 Gradle 或 Maven 以及您要使用的語言。本指南假設您選擇了 Java。

單擊依賴項并選擇Spring Web。

單擊生成。

下載下傳生成的 ZIP 檔案，該檔案是使用您的選擇配置的 Web 應用程式的存檔。

如果您的 IDE 具有 Spring Initializr 內建，則可以從您的 IDE 完成此過程。

建立資源表示類

現在您已經設定了項目和建構系統，您可以建立您的 Web 服務。

通過考慮服務互動來開始這個過程。

該服務将處理對 的GET請求/greeting，可選擇name在查詢字元串中使用一個參數。該GET請求應200 OK在正文中傳回一個帶有 JSON的響應，表示問候語。它應該類似于以下輸出：

{

  "id": 1,

  "content": "Hello, World!"

}

該id字段是問候語的唯一辨別符，是問候語content的文本表示。

要對問候表示模組化，請建立一個資源表示類。為此，請提供一個普通的舊 Java 對象，其中包含id和content資料的字段、構造函數和通路器，如下面的清單（來自src/main/java/com/example/restservice/Greeting.java）所示：

Unresolved directive in - include::complete/src/main/java/com/example/restservice/Greeting.java[]

此應用程式使用Jackson JSON庫自動将類型執行個體編組Greeting為 JSON。預設情況下，Web Starter 包含 Jackson。

建立資源控制器

在 Spring 建構 RESTful Web 服務的方法中，HTTP 請求由控制器處理。這些元件由@RestController注解辨別，GreetingController下面的清單 (from src/main/java/com/example/restservice/GreetingController.java)通過傳回類的新執行個體來處理GET請求：/greetingGreeting

Unresolved directive in - include::complete/src/main/java/com/example/restservice/GreetingController.java[]

這個控制器簡潔明了，但背後有很多事情要做。我們一步一步分解。

該@GetMapping注釋確定 HTTP GET 請求/greeting被映射到該greeting()方法。

有其他 HTTP 動詞（例如@PostMappingPOST）的伴随注釋。還有一個@RequestMapping注釋，它們都源自，并且可以用作同義詞（例如@RequestMapping(method=GET)）。

@RequestParam将查詢字元串參數的值綁定name到方法的name參數中greeting()。如果name請求中沒有該參數defaultValue，World則使用of 。

方法主體的實作建立并傳回一個新Greeting對象，該對象具有id和content屬性，該對象基于來自counter和的下一個值，并name通過使用 greeting 來格式化給定的template。

傳統 MVC 控制器和前面展示的 RESTful Web 服務控制器之間的主要差別在于 HTTP 響應主體的建立方式。這個 RESTful Web 服務控制器不依賴于視圖技術來執行伺服器端将問候資料呈現為 HTML，而是填充并傳回一個Greeting對象。對象資料将作為 JSON 直接寫入 HTTP 響應。

此代碼使用 [email protected]注釋，它将類标記為控制器，其中每個方法傳回域對象而不是視圖。它是同時包含@Controller和的簡寫@ResponseBody。

該Greeting對象必須轉換為 JSON。由于 Spring 的 HTTP 消息轉換器支援，您無需手動進行此轉換。因為Jackson 2在類路徑上，是以MappingJackson2HttpMessageConverter會自動選擇Spring來将Greeting執行個體轉換為 JSON。

@SpringBootApplication 是一個友善的注釋，它添加了以下所有内容：

@Configuration：将類标記為應用程式上下文的 bean 定義源。

@EnableAutoConfiguration：告訴 Spring Boot 根據類路徑設定、其他 bean 和各種屬性設定開始添加 bean。例如，如果spring-webmvc在類路徑上，此注釋将應用程式标記為 Web 應用程式并激活關鍵行為，例如設定DispatcherServlet.

@ComponentScan：告訴 Spring 在包中查找其他元件、配置和服務com/example，讓它找到控制器。

該main()方法使用 Spring Boot 的SpringApplication.run()方法來啟動應用程式。您是否注意到沒有一行 XML？也沒有web.xml檔案。該 Web 應用程式是 100% 純 Java 的，您無需處理任何管道或基礎設施的配置。

建構一個可執行的 JAR

您可以使用 Gradle 或 Maven 從指令行運作應用程式。您還可以建構包含所有必要依賴項、類和資源的單個可執行 JAR 檔案并運作它。建構一個可執行的 jar 可以很容易地将服務作為應用程式在整個開發生命周期中、跨不同環境等進行傳遞、版本化和部署。

如果您使用 Gradle，則可以使用./gradlew bootRun. 或者，您可以使用./gradlew build并運作 JAR 檔案來建構JAR 檔案，如下所示：

java -jar build/libs/gs-rest-service-0.1.0.jar

如果您使用 Maven，則可以使用./mvnw spring-boot:run. 或者，您可以建構 JAR 檔案，./mvnw clean package然後運作 JAR 檔案，如下所示：

java -jar target/gs-rest-service-0.1.0.jar

此處描述的步驟建立了一個可運作的 JAR。您還可以建構經典的 WAR 檔案。

顯示日志輸出。該服務應該會在幾秒鐘内啟動并運作。

測試服務

現在服務已啟動，請通路http://localhost:8080/greeting，您應該看到：

{"id":1,"content":"Hello, World!"}

name通過通路提供查詢字元串參數http://localhost:8080/greeting?name=User。請注意content屬性的值如何從Hello, World!變為Hello, User!，如下面的清單所示：

{"id":2,"content":"Hello, User!"}

此更改表明 中的@RequestParam安排GreetingController按預期工作。該name參數已被賦予預設值，World但可以通過查詢字元串顯式覆寫。

還要注意id屬性如何從1變為2。這證明您正在GreetingController跨多個請求處理同一個執行個體，并且它的counter字段在每次調用時都按預期遞增。

總結

恭喜！您剛剛使用 Spring 開發了一個 RESTful Web 服務。