譯 2.Spring構建REST Web Service

上篇文章我們已經對Spring 已經有了一個初步的認識，接下來本篇文章我們將繼續一起在官網學習新技術。 原文地址：https://spring.io/guides/gs/rest-service/

---

本指南指導您使用Spring創建一個“Hello World”REST Web Service 的過程。

1. 你將會建立什么？

Tips: 上面已經提到，我們將使用Spring創建一個“Hello World”REST Web服務的過程，但是最終的效果是什么樣呢？

我們將構建一個接受HTTP GET請求的服務：

http://localhost:8080/greeting

當我們發出上面的Http Get 請求后，會響應返回下面的JSON 內容。

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

我們也可以帶一個參數進行請求

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

 Name參數值重寫“Word”的默認值，並反映在響應中：

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

2. 你將需要准備什么？

• 大約十五分鍾

• 一個喜歡的文本編輯器或者IDE

• JDK 1.8 or later

• Gradle 4+ or Maven 3.2+

• You can also import the code straight into your IDE:

  • Spring Tool Suite (STS)

  • IntelliJ IDEA

3.如何完成本指南?

像大多數Spriing 入門指南一樣，你可以從頭開始，完成每一步，或者你可以繞過已經熟悉的基本設置步驟。不管怎樣，你最終都會得到工作代碼

3.1 獲取工作代碼

  a.使用Maven構建

  b. 使用Gradle構建

  c. 使用IDE構建

• 閱讀怎么使用 Spring Tool Suite.構建

• 閱讀怎么使用  IntelliJ IDEA 構建

  d.  點擊下載 然后 解壓倉庫源碼

  e. 使用git 克隆

git clone https://github.com/spring-guides/gs-rest-service.git

上面有五種方法，但是由於之后我們會經常使用IDE來完成這些操作，所以這里我們使用IDE 來構建入門指南項目

3.1.1 用STS開始入門指南

本指南引導您使用Spring工具套件（STS）構建一個入門指南。

3.1.1.1 你將會構建什么？

您將選擇Spring指南並將其導入Spring Tool Suite。然后你可以閱讀指南，處理代碼，運行項目。

3.1.1.2 你需要什么？

• 大約15分鍾

• Spring Tool Suite (STS)

• JDK 8 或者更高

3.1.1.3 安裝STS

   如果你還沒有安裝STS，請訪問上面的鏈接。從那里，您可以下載一個副本為您的平台。要安裝它，只需解壓縮下載的存檔文件。

   當你完成后，繼續登陸 STS

3.1.1.4 導入入門指南

   使用STS啟動並運行，從文件菜單打開Import Spring Getting Started Content 向導。

 點擊File ——> New ————> Import Spring Geting Started Content

然后會彈出來一個窗口向導，將為您提供從Spring網站搜索和挑選任何已發布指南的機會。

你可以瀏覽列表，或者輸入搜索詞來立即過濾選項。

當提供即時搜索結果時，該標准適用於標題和描述。支持通配符。

輸入rest ，選擇 Rest Service ,點擊Finish 

 

您可以選擇Maven或Gradle作為構建系統來使用。

您還可以決定是否抓取初始代碼集、完成代碼集，或兩者兼而有之。

對於大多數項目，

• （initial）初始代碼集是一個空的項目，使得您可以通過指南復制和粘貼您的方式
•   (Complete)完整的代碼集是來自已經進入的指南的所有代碼。如果你抓住這兩個，你可以比較你的工作與指南的差異。

最后，你可以讓STS向網站上的指南打開瀏覽器標簽。這會讓你在不離開STS的情況下通過向導工作。

 STS將在您的工作區中創建兩個新項目，導入消耗REST代碼庫（初始和完整），並在STS中打開瀏覽器選項卡，如下所示：

 

Tips: 

gs-rest-service-complete 是完成后的項目

gs-rest-service-initial 是初始化一個空的項目

3.1.2 用Intellij Idea 開始入門指南

 本指南指導您使用Intellij Idea 構建一個入門指南。

3.1.2.1 你將會構建什么？

你會選擇一個Spring指南並導入到iTeliJ的想法中。然后你可以閱讀指南，處理代碼，運行項目。

3.1.2.2 你需要准備什么？

• 15分鍾

• IntelliJ IDEA

• JDK 6  或者更高

3.1.2.3 安裝 IntelliJ IDEA

如果你還沒有安裝 IntelliJ IDEA (Ultimate Edition) ，請訪問上面的鏈接。從那里，您可以下載一個副本為您的平台。要安裝它，只需解壓縮下載的存檔文件。

 當你完成后，繼續啟動Intellij IDEA

3.1.2.4 導入入門指南

要導入現有的項目，需要一些代碼，

點擊下載

或者使用Git 克隆或復制其中一個入門指南，例如REST服務指南：

git clone https://github.com/spring-guides/gs-rest-service.git

下載解壓后如圖所示

使用Intellij IDEA 啟動和運行，點擊歡迎屏幕上的導入項目，或在主菜單上打開文件：

 在彈出對話框中，確保在完整文件夾下選擇Maven的POM.xml或Gradle的build.gradle文件：

這里我們選擇build.gradle

Intellij IDEA 將創建一個項目，所有的代碼從指南准備運行。

保持默認，點擊OK

構建完成后如圖所示

3.2 創建資源表示類

 既然已經建立了項目並建立了系統，就可以創建Web服務。

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

服務將處理查詢t /greeting  GET 請求，可選地在查詢字符串中使用name參數。GET請求應該返回一個200 OK響應，其中JSON在表示greetin的主體中。它應該看起來像這樣：

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

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

 為了建模問候語表示，您創建一個資源表示類。提供一個字段，構造函數普通java對象，並為ID和content數據訪問：

src/main/java/hello/Greeting.java

package hello;

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;
    }
}

 正如您在下面的步驟中看到的，Spring使用Jackson JSON庫自動將問候類型的實例封送到JSON中。

 接下來，創建將為這些問候服務的資源控制器。

3.3 創建資源Controller

在Spring構建REST Web服務的方法中，HTTP請求由控制器處理。這些組件很容易被@ RESTController注釋標識，下面的GreetingController通過返回Greeting 類的新實例來處理GET請求/greeting：

 src/main/java/hello/GreetingController.java

package hello;

import java.util.concurrent.atomic.AtomicLong;

import org.springframework.web.bind.annotation.RequestMapping;
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();

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

這個控制器簡潔明了，但引擎蓋下還有很多事情要做。讓我們一步一步地打破它。

 @RequestMapping  注解 確保將HTTP請求 /greeting映射到 greeting()方法。

上面的示例不指定GET、PUT、POST等等，因為@RequestMapping 默認映射所有HTTP操作。使用@RequestMapping（Method= GET）來縮小此映射。

@RequestParam將查詢字符串參數name 的值綁定到greeting（）方法的name參數中。 如果請求中缺少name參數，則使用“World”的默認值。

方法體的實現基於計數器的下一個值創建並返回一個帶有id和content屬性的新Greeting對象，並使用問候template 格式化給定name。

 

傳統的MVC控制器和上面的RESTful Web服務控制器之間的一個主要區別在於HTTP響應主體的創建方式。

這個RESTful Web服務控制器只需填充並返回一個Greeting對象，而不是依賴視圖技術將問候數據的服務器端呈現呈現給HTML。

對象數據將作為JSON直接寫入HTTP響應。

此代碼使用Spring 4的新的@RestController注釋，該注釋將類標記為控制器，其中每個方法都返回一個域對象而不是視圖。 它是@Controller和@ResponseBody的縮寫。

@RestController = = @Controller + @ResponseBody 

Greeting對象必須轉換為JSON。 由於Spring的HTTP消息轉換器支持，您不需要手動執行此轉換。

由於Jackson 2位於classpath中，因此會自動選擇Spring的MappingJackson2HttpMessageConverter將Greeting實例轉換為JSON。

3.4 使應用程序可執行

雖然可以將此服務作為傳統WAR文件打包以部署到外部應用程序服務器，但下面演示的更簡單的方法會創建獨立應用程序。

您將所有內容打包到一個單獨的，可執行的JAR文件中，由一個良好的舊Java main（）方法驅動。

一路上，您使用Spring的支持將Tomcat servlet容器作為HTTP運行時嵌入，而不是部署到外部實例。

src/main/java/hello/Application.java

package hello;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
} 

SpringBootApplication是一個方便的注解，它增加了以下所有內容：

• @Configuration將類標記為應用程序上下文的bean定義的來源。
• @EnableAutoConfiguration通知Spring Boot根據類路徑設置，其他bean和各種屬性設置開始添加bean。
• 通常你會為Spring MVC應用程序添加@EnableWebMvc，但Spring Boot在類路徑中看到spring-webmvc時會自動添加。 這將該應用程序標記為Web應用程序並激活關鍵行為，例如設置DispatcherServlet。
• @ComponentScan告訴Spring在hello包中查找其他組件，配置和服務，以便找到控制器。

main（）方法使用Spring Boot的SpringApplication.run（）方法啟動應用程序。你有沒有注意到沒有一行XML？ 沒有web.xml文件。這個Web應用程序是100％純Java，您不必處理配置任何管道或基礎設施。

3.5 構建一個可執行的JAR

您可以使用Gradle或Maven從命令行運行應用程序。 或者您可以構建一個包含所有必需的依賴項，類和資源的可執行JAR文件，並運行該文件。 這使得在整個開發生命周期內跨越不同環境等，將服務作為應用程序發布，版本化和部署變得非常容易。

如果您正在使用Gradle，則可以使用./gradlew bootRun運行該應用程序。 或者您可以使用./gradlew構建構建JAR文件。 然后你可以運行JAR文件：

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

如果您使用的是Maven，則可以使用./mvnw spring-boot：run來運行該應用程序。 或者，您可以使用./mvnw clean包構建JAR文件。 然后你可以運行JAR文件：

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

上述過程將創建一個可運行的JAR。 您也可以選擇構建經典的WAR文件。

記錄輸出顯示。 該服務應該在幾秒鍾內啟動並運行。

3.6 測試 service

 現在這個service已經啟動，我們訪問 http://127.0.0.1:8080/greeting 你將會看到這樣的結果

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

提供一個name參數進行查詢，訪問 http://localhost:8080/greeting?name=User

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

注意content 文本內容已經從 "Hello ,World!" 變成了" Hello, User!"

此更改演示了GreetingController中的@RequestParam排列按預期工作。 name參數已被賦予默認值“World”，但始終可以通過查詢字符串顯式覆蓋。

還要注意id屬性如何從1更改為2.這證明您正在針對多個請求中的同一個GreetingController實例工作，並且它的計數器字段按照預期在每次調用時遞增。

恭喜！ 您剛剛用Spring開發了一個RESTful Web Service。

源碼下載：https://github.com/geekxingyun/JavaEE-Framework-Sample/tree/master/Spring-Build-Restful-Web-Service-Sample