構建RESTful Web服務的過程

本指南將引導您完成使用 Spring 創(chuàng)建“Hello, World”RESTful Web 服務的過程。

你將建造什么

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

它將以 JSON 表示的問候進行響應，如以下清單所示：

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

您可以在查詢字符串中使用可選name參數(shù)自定義問候語，如以下清單所示：

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

name參數(shù)值覆蓋默認值World并反映在響應中，如以下清單所示：

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

你需要什么

• 約15分鐘
• 最喜歡的文本編輯器或 IDE
• JDK 1.8或更高版本
• Gradle 4+或Maven 3.2+
• 您還可以將代碼直接導入 IDE：
  • 彈簧工具套件 (STS)
  • IntelliJ IDEA

如何完成本指南

像大多數(shù) Spring入門指南一樣，您可以從頭開始并完成每個步驟，也可以繞過您已經(jīng)熟悉的基本設置步驟。無論哪種方式，您最終都會得到工作代碼。

要從頭開始，請繼續(xù)從 Spring Initializr 開始。

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

• 下載并解壓縮本指南的源存儲庫，或使用Git克隆它：git clone https://github.com/spring-guides/gs-rest-service.git
• 光盤進入gs-rest-service/initial
• 繼續(xù)創(chuàng)建資源表示類。

完成后，您可以對照中的代碼檢查結(jié)果gs-rest-service/complete。

從 Spring Initializr 開始

您可以使用這個預先初始化的項目并單擊 Generate 下載 ZIP 文件。此項目配置為適合本教程中的示例。

手動初始化項目：

1. 導航到https://start.spring.io。該服務提取應用程序所需的所有依賴項，并為您完成大部分設置。
2. 選擇 Gradle 或 Maven 以及您要使用的語言。本指南假定您選擇了 Java。
3. 單擊Dependencies并選擇Spring Web。
4. 單擊生成。
5. 下載生成的 ZIP 文件，該文件是根據(jù)您的選擇配置的 Web 應用程序的存檔。

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

你也可以從 Github 上 fork 項目并在你的 IDE 或其他編輯器中打開它。

創(chuàng)建資源表示類

現(xiàn)在您已經(jīng)設置了項目和構建系統(tǒng)，您可以創(chuàng)建您的系統(tǒng) Web 服務。

從考慮服務交互開始這個過程。

該服務將處理對 的GET請求/greeting，可以選擇name在查詢字符串中使用參數(shù)。該GET請求應200 OK在表示問候的正文中返回帶有 JSON 的響應。它應該類似于以下輸出：

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

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

要對問候表示建模，請創(chuàng)建一個資源表示類。為此，請?zhí)峁┮粋€普通的方法 Java 對象，其中包含用于id和content數(shù)據(jù)的字段、構造函數(shù)和訪問器，如以下清單（來自
src/main/java/com/example/restservice/Greeting.java）所示：

package com.example.restservice;

public class Greeting {

	private final long id;
	private final String content;

	public Greeting(long id, String content) {
		this.id = id;
		this.content = content;
	}

	public long getId() {
		return id;
	}

	public String getContent() {
		return content;
	}
}

此應用程序使用Jackson JSON庫將類型的實例自動編組Greeting為 JSON。網(wǎng)絡啟動器默認包含 Jackson。

創(chuàng)建資源控制器

在 Spring 構建 RESTful Web 服務的方法中，HTTP 請求由控制器處理。這些組件由@RestController注釋標識，GreetingController下面的清單 (from )通過返回類的新實例來
src/main/java/com/example/restservice/GreetingController.java處理GET請求：/greetingGreeting

package com.example.restservice;

import java.util.concurrent.atomic.AtomicLong;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class GreetingController {

	private static final String template = "Hello, %s!";
	private final AtomicLong counter = new AtomicLong();

	@GetMapping("/greeting")
	public Greeting greeting(@RequestParam(value = "name", defaultValue = "World") String name) {
		return new Greeting(counter.incrementAndGet(), String.format(template, name));
	}
}復制

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

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

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

@RequestParam將查詢字符串參數(shù)的值綁定name到方法的name參數(shù)中greeting()。如果name請求中沒有參數(shù)，則使用defaultValueof World。

方法體的實現(xiàn)創(chuàng)建并返回一個新Greeting對象，該對象具有id和content基于下一個值的屬性，并使用 greetingcounter格式化給定的格式。nametemplate

傳統(tǒng) MVC 控制器和前面顯示的 RESTful Web 服務控制器之間的一個關鍵區(qū)別是 HTTP 響應主體的創(chuàng)建方式。這個 RESTful Web 服務控制器不是依靠視圖技術來執(zhí)行服務器端將問候數(shù)據(jù)呈現(xiàn)為 HTML，而是填充并返回一個Greeting對象。對象數(shù)據(jù)將作為 JSON 直接寫入 HTTP 響應。

此代碼使用 Spring@RestController注釋，它將類標記為控制器，其中每個方法都返回域?qū)ο蠖皇且晥D。它是同時包含@Controller和的簡寫@ResponseBody。

該Greeting對象必須轉(zhuǎn)換為 JSON。感謝 Spring 的 HTTP 消息轉(zhuǎn)換器支持，您無需手動進行此轉(zhuǎn)換。因為Jackson 2在類路徑上，所以會自動選擇 Spring
MappingJackson2HttpMessageConverter將Greeting實例轉(zhuǎn)換為 JSON。

@SpringBootApplication是一個方便的注釋，它添加了以下所有內(nèi)容：

• @Configuration: 將類標記為應用程序上下文的 bean 定義源。
• @EnableAutoConfiguration：告訴 Spring Boot 根據(jù)類路徑設置、其他 bean 和各種屬性設置開始添加 bean。例如，如果spring-webmvc位于類路徑上，則此注釋將應用程序標記為 Web 應用程序并激活關鍵行為，例如設置DispatcherServlet.
• @ComponentScan: 告訴 Spring 在包中查找其他組件、配置和服務com/example，讓它找到控制器。

該main()方法使用 Spring Boot 的SpringApplication.run()方法來啟動應用程序。您是否注意到?jīng)]有一行 XML？也沒有web.xml文件。這個 Web 應用程序是 100% 純 Java，您不必處理任何管道或基礎設施的配置。

構建一個可執(zhí)行的 JAR

您可以使用 Gradle 或 Maven 從命令行運行應用程序。您還可以構建一個包含所有必要依賴項、類和資源的單個可執(zhí)行 JAR 文件并運行它。構建可執(zhí)行 jar 可以在整個開發(fā)生命周期、跨不同環(huán)境等中輕松地作為應用程序交付、版本化和部署服務。

如果您使用 Gradle，則可以使用./gradlew bootRun. 或者，您可以使用構建 JAR 文件./gradlew build，然后運行 ?JAR 文件，如下所示：

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

如果您使用 Maven，則可以使用./mvnw spring-boot:run. 或者，您可以使用構建 JAR 文件，./mvnw clean package然后運行該 JAR 文件，如下所示：

java -jar 目標/gs-rest-service-0.1.0.jar

此處描述的步驟創(chuàng)建了一個可運行的 JAR。您還可以構建經(jīng)典的 WAR 文件。

顯示記錄輸出。該服務應在幾秒鐘內(nèi)啟動并運行。

測試服務

現(xiàn)在服務已經(jīng)啟動，訪問
http://localhost:8080/greeting，您應該會看到：

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

通過訪問提供name查詢字符串參數(shù)
http://localhost:8080/greeting?name=User。content請注意屬性的值如何從Hello, World!變?yōu)?span style="color:rgb(0,0,153);">Hello, User!，如以下清單所示：

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

這一變化表明，@RequestParam安排在GreetingController按預期工作。該name參數(shù)已被賦予默認值，World但可以通過查詢字符串顯式覆蓋。

還要注意id屬性是如何從1變?yōu)?的2。這證明您正在GreetingController跨多個請求處理同一個實例，并且其counter字段在每次調(diào)用時都按預期遞增。

概括

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

審核編輯：湯梓紅