# 構建一個RESTful Web服務 本指南將引導您完成使用Spring創建“ Hello，World” RESTful Web服務的過程。 ## 你會建立什么 您將在構建一個將接受HTTP GET請求的服務`[http://localhost:8080/greeting](http://localhost:8080/greeting)`。 它將以問候語的JSON表示形式進行響應，如以下清單所示： ~~~ {"id":1,"content":"Hello, World!"} ~~~ 您可以`name`在查詢字符串中使用可選參數來自定義問候語，如以下清單所示： ~~~ http://localhost:8080/greeting?name=User ~~~ 的`name`參數值將覆蓋的默認值`World`，并反映在響應時，如下面的列表顯示： ~~~ {"id":1,"content":"Hello, User!"} ~~~ ## 你需要什么 * 約15分鐘 * 最喜歡的文本編輯器或IDE * [JDK 1.8](http://www.oracle.com/technetwork/java/javase/downloads/index.html)或更高版本 * [Gradle 4+](http://www.gradle.org/downloads)或[Maven 3.2+](https://maven.apache.org/download.cgi) * 您還可以將代碼直接導入到IDE中： * [springtoolsuite（STS）](https://spring.io/guides/gs/sts) * [IntelliJ IDEA](https://spring.io/guides/gs/intellij-idea/) ## 如何完成本指南 像大多數Spring[入門指南](https://spring.io/guides)一樣，您可以從頭開始并完成每個步驟，也可以繞過您已經熟悉的基本設置步驟。無論哪種方式，您最終都可以使用代碼。 要**從頭開始**，請繼續進行以[Spring Initialize開始](https://spring.io/guides/gs/rest-service/#scratch)。 要**跳過基礎知識**，請執行以下操作： * [下載](https://github.com/spring-guides/gs-rest-service/archive/master.zip)并解壓縮本指南的源存儲庫，或使用[Git](https://spring.io/understanding/Git)對其進行克隆：`git clone[https://github.com/spring-guides/gs-rest-service.git](https://github.com/spring-guides/gs-rest-service.git)` * 光盤進入`gs-rest-service/initial` * 繼續[創建資源表示形式類](https://spring.io/guides/gs/rest-service/#initial)。 **完成后**，您可以根據中的代碼檢查結果`gs-rest-service/complete`。 ## 從Spring初始化開始 如果您使用Maven，請訪問[Spring Initializr](https://start.spring.io/#!type=maven-project&language=java&platformVersion=2.4.3.RELEASE&packaging=jar&jvmVersion=1.8&groupId=com.example&artifactId=rest-service&name=rest-service&description=Demo%20project%20for%20Spring%20Boot&packageName=com.example.rest-service&dependencies=web)以生成具有所需依賴項的新項目（Spring Web）。 以下清單顯示了`pom.xml`選擇Maven時創建的文件： ~~~ <?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> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.4.3</version> <relativePath/> <!-- lookup parent from repository --> </parent> <groupId>com.example</groupId> <artifactId>rest-service</artifactId> <version>0.0.1-SNAPSHOT</version> <name>rest-service</name> <description>Demo project for Spring Boot</description> <properties> <java.version>1.8</java.version> </properties> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> </plugin> </plugins> </build> </project> ~~~ 如果您使用Gradle，請訪問[Spring Initializr](https://start.spring.io/#!type=gradle-project&language=java&platformVersion=2.4.3.RELEASE&packaging=jar&jvmVersion=1.8&groupId=com.example&artifactId=rest-service&name=rest-service&description=Demo%20project%20for%20Spring%20Boot&packageName=com.example.rest-service&dependencies=web)以生成具有所需依賴項的新項目（Spring Web）。 以下清單顯示了`build.gradle`選擇Gradle時創建的文件： ~~~ plugins { id 'org.springframework.boot' version '2.4.3' id 'io.spring.dependency-management' version '1.0.11.RELEASE' id 'java' } group = 'com.example' version = '0.0.1-SNAPSHOT' sourceCompatibility = '1.8' repositories { mavenCentral() } dependencies { implementation 'org.springframework.boot:spring-boot-starter-web' testImplementation('org.springframework.boot:spring-boot-starter-test') } test { useJUnitPlatform() } ~~~ ### 手動初始化（可選） 如果要手動初始化項目而不是使用前面顯示的鏈接，請按照以下步驟操作： 1. 導航到[https://start.spring.io](https://start.spring.io/)。該服務提取應用程序所需的所有依賴關系，并為您完成大部分設置。 2. 選擇Gradle或Maven以及您要使用的語言。本指南假定您選擇了Java。 3. 單擊**Dependencies，**然后選擇**Spring Web**。 4. 點擊**生成**。 5. 下載生成的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`）所示： ~~~ 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。網絡啟動器默認包含杰克遜。 ## 創建一個資源控制器 在Spring的構建RESTful Web服務的方法中，HTTP請求由控制器處理。這些組件由[`@RestController`](https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/web/bind/annotation/RestController.html)注釋標識，并且`GreetingController`以下清單（從中`src/main/java/com/example/restservice/GreetingController.java`）中顯示的內容通過返回該類的新實例來處理`GET`請求：`/greeting``Greeting` ~~~ 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`將查詢字符串參數的值綁定`name`到方法的`name`參數中`greeting()`。如果`name`請求中不存在該參數`defaultValue`，`World`則使用of。 方法主體的實現根據和中的下一個值創建一個`Greeting`具有`id`和`content`屬性的新對象，并返回一個新對象，并使用greeting`counter`格式化給定`name`的對象`template`。 傳統的MVC控制器和RESTful Web服務控制器之間的主要區別在于創建HTTP響應主體的方式。RESTful Web服務控制器填充并返回一個`Greeting`對象，而不是依賴于視圖技術來執行問候語數據到HTML的服務器端渲染。對象數據將作為JSON直接寫入HTTP響應。 該代碼使用Spring[`@RestController`](https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/web/bind/annotation/RestController.html)注釋，該注釋將類標記為控制器，其中每個方法均返回域對象而不是視圖。這是同時包含`@Controller`和的簡寫`@ResponseBody`。 該`Greeting`對象必須轉換為JSON。借助Spring的HTTP消息轉換器支持，您無需手動進行此轉換。由于[Jackson 2](https://github.com/FasterXML/jackson)在類路徑中，[`MappingJackson2HttpMessageConverter`](https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/http/converter/json/MappingJackson2HttpMessageConverter.html)因此將自動選擇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`。或者，您可以使用來構建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 target / gs-rest-service-0.1.0.jar ~~~ 此處描述的步驟將創建可運行的JAR。您還可以構建經典的WAR文件。 顯示日志記錄輸出。該服務應在幾秒鐘內啟動并運行。 ## 測試服務 現在該服務已啟動，請訪問`[http://localhost:8080/greeting](http://localhost:8080/greeting)`，您應該在此處看到： ~~~ {"id":1,"content":"Hello, World!"} ~~~ `name`通過訪問提供查詢字符串參數`[http://localhost:8080/greeting?name=User](http://localhost:8080/greeting?name=User)`。請注意，`content`屬性值如何從`Hello, World!`變為`Hello, User!`，如以下清單所示： ~~~ {"id":2,"content":"Hello, User!"} ~~~ 此更改表明`@RequestParam`in的安排`GreetingController`按預期方式工作。該`name`參數的默認值是，`World`但可以通過查詢字符串顯式覆蓋。 還請注意，`id`屬性是如何從更改`1`為的`2`。這證明您正在針對`GreetingController`多個請求處理同一個實例，并且`counter`在每個調用中它的字段都按預期遞增。 ## 概括 恭喜你！您剛剛使用Spring開發了RESTful Web服務。 -------------------------------- 筆者推薦使用sts創建springboot項目 springboot是spring團隊提供的全新框架，目的是用來簡化新spring項目的初始搭建與開發過程，可以看成是一些庫的集合，該框架使用了特定的方式來簡化配置過程，中心思想是實現“約定大于依賴”，接下來我們新建一個springboot項目，體驗一下： 打開STS New->選擇Spring Boot->選擇Spring Starter Project，點擊Next   其他項與新建maven項目一樣，填寫完成后點擊next； 在這里spring boot版本選擇一個目前官網較為穩定的版本1.5.13，輸入框中選擇想添加的其他依賴，這里我選擇幾個最基本的，點擊next  Finish~~完成后等待STS加載項目需要的配置與依賴。。。 等1分鐘左右，加載完成，我們看一下工程結構  可以看到，項目自動生成了兩個類，和application.properties的默認配置文件，perperties配置文件內容是空的，Application.java文件中，有了一個新的注解@SpringBootApplication，感興趣的朋友可以點進去看一下這個注解的源碼，就能明白它的作用，這里就不做解釋了；  點開pom.xml，我們看一下配置  可以看到，剛才我們選擇的幾個依賴，spring boot都已經為我們自動配置好了（我們只是體驗一下springboot的創建過程，這里我還是先把剛才添加的幾個依賴刪除掉（zookepper、mysql、redis等），只保留框架最基礎的依賴）；  這里瀏覽一下依賴包，springmvc相關的jar包和logback等等都已經自動添加進來，這里就不貼出全部jar包了； 首先，新建一個 TestController  @RestController與@RequestMapping就不做解釋了； TestController編寫完成了，我們右鍵Application.java，Run As -> Java Application，運行一下  通過控制臺輸出信息看到，項目已經啟動成功了，端口號是8080，打開瀏覽器，我們看一下效果   完成~~