使用REST訪問JPA數據 · springboot官方文檔中文版

# 使用REST訪問JPA數據本指南將引導您完成創建通過基于[超媒體的](https://spring.io/guides/gs/rest-hateoas)[RESTful](https://spring.io/understanding/REST)前端訪問關系JPA數據的應用程序的過程。 ## 你會建立什么您將構建一個Spring應用程序，該應用程序允許您`Person`使用Spring Data REST創建和檢索存儲在數據庫中的對象。Spring Data REST具有[Spring HATEOAS](https://projects.spring.io/spring-hateoas)和[Spring Data JPA](https://projects.spring.io/spring-data-jpa)的功能，并將它們自動組合在一起。 Spring Data REST還支持將Spring Data Neo4j，Spring Data Gemfire和Spring Data MongoDB作為后端數據存儲，但這些都不屬于本指南的一部分。 ## 你需要什么 * 約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中： * [彈簧工具套件（STS）](https://spring.io/guides/gs/sts) * [IntelliJ IDEA](https://spring.io/guides/gs/intellij-idea/) ## 如何完成本指南像大多數Spring[入門指南](https://spring.io/guides)一樣，您可以從頭開始并完成每個步驟，也可以繞過您已經熟悉的基本設置步驟。無論哪種方式，您最終都可以使用代碼。要**從頭開始**，請繼續進行“[從Spring Initializr開始”](https://spring.io/guides/gs/accessing-data-rest/#scratch)。要**跳過基礎知識**，請執行以下操作： * [下載](https://github.com/spring-guides/gs-accessing-data-rest/archive/master.zip)并解壓縮本指南的源存儲庫，或使用[Git](https://spring.io/understanding/Git)對其進行克隆：`git clone[https://github.com/spring-guides/gs-accessing-data-rest.git](https://github.com/spring-guides/gs-accessing-data-rest.git)` * 光盤進入`gs-accessing-data-rest/initial` * 繼續[創建域對象](https://spring.io/guides/gs/accessing-data-rest/#initial)。 **完成后**，您可以根據中的代碼檢查結果`gs-accessing-data-rest/complete`。 ## 從Spring Initializr開始如果您使用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=accessing-data-rest&name=accessing-data-rest&description=Demo%20project%20for%20Spring%20Boot&packageName=com.example.accessing-data-rest&dependencies=h2,data-jpa,data-rest)以生成具有所需依賴項（Rest Repositories，Spring Data JPA和H2 Database）的新項目。以下清單顯示了`pom.xml`選擇Maven時創建的文件： ~~~ <？xml版本=“ 1.0”編碼=“ 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> <父母> <groupId> org.springframework.boot </ groupId> <artifactId> spring-boot-starter-parent </ artifactId> <version> 2.4.3 </ version> <relativePath /> <！-從存儲庫中查找父級-> </ parent> <groupId> com.example </ groupId> <artifactId>訪問數據靜止</ artifactId> <version> 0.0.1-SNAPSHOT </ version> <name> accessing-data-rest </ name> <description> Spring Boot的演示項目</ description> <屬性> <java.version> 1.8 </java.version> </ properties> <依賴項> <依賴性> <groupId> org.springframework.boot </ groupId> <artifactId> spring-boot-starter-data-jpa </ artifactId> </ dependency> <依賴性> <groupId> org.springframework.boot </ groupId> <artifactId> spring-boot-starter-data-rest </ artifactId> </ dependency> <依賴性> <groupId> com.h2database </ groupId> <artifactId> h2 </ artifactId> <scope>運行時</ scope> </ dependency> <依賴性> <groupId> org.springframework.boot </ groupId> <artifactId> spring-boot-starter-test </ artifactId> <scope>測試</ scope> </ dependency> </ dependencies> <內部版本> <插件> <插件> <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=accessing-data-rest&name=accessing-data-rest&description=Demo%20project%20for%20Spring%20Boot&packageName=com.example.accessing-data-rest&dependencies=h2,data-jpa,data-rest)以生成具有所需依賴項的新項目（Rest存儲庫，Spring Data JPA和H2數據庫）。以下清單顯示了`build.gradle`選擇Gradle時創建的文件： ~~~ 插件{ id'org.springframework.boot'版本'2.4.3' id'io.spring.dependency-management'版本'1.0.11.RELEASE' id'java' } 組='com.example' 版本='0.0.1-SNAPSHOT' sourceCompatibility ='1.8' 儲存庫{ mavenCentral（） } 依賴項{ 實現'org.springframework.boot：spring-boot-starter-data-jpa' 實現'org.springframework.boot：spring-boot-starter-data-rest' runtime僅'com.h2database：h2' testImplementation'org.springframework.boot：spring-boot-starter-test' } 測試 { useJUnitPlatform（） } ~~~ ### 手動初始化（可選）如果要手動初始化項目而不是使用前面顯示的鏈接，請按照以下步驟操作： 1. 導航到[https://start.spring.io](https://start.spring.io/)。該服務提取應用程序所需的所有依賴關系，并為您完成大部分設置。 2. 選擇Gradle或Maven以及您要使用的語言。本指南假定您選擇了Java。 3. 單擊**Dependencies，**然后選擇**Rest Repositories**，**Spring Data JPA**和**H2 Database**。 4. 點擊**生成**。 5. 下載生成的ZIP文件，該文件是使用您的選擇配置的Web應用程序的存檔。如果您的IDE集成了Spring Initializr，則可以從IDE中完成此過程。 ## 創建一個域對象創建一個新的域對象以呈現一個人，如清單5中的（清單`src/main/java/com/example/accessingdatarest/Person.java`）所示： ~~~ package com.example.accessingdatarest; import javax.persistence.Entity; import javax.persistence.GeneratedValue; import javax.persistence.GenerationType; import javax.persistence.Id; @Entity public class Person { @Id @GeneratedValue(strategy = GenerationType.AUTO) private long id; private String firstName; private String lastName; public String getFirstName() { return firstName; } public void setFirstName(String firstName) { this.firstName = firstName; } public String getLastName() { return lastName; } public void setLastName(String lastName) { this.lastName = lastName; } } ~~~ 該`Person`對象具有名字和姓氏。（還有一個配置為自動生成的ID對象，因此您無需進行處理。） ## 創建個人資料庫接下來，您需要創建一個簡單的存儲庫，如清單1中的`src/main/java/com/example/accessingdatarest/PersonRepository.java`所示： ~~~ package com.example.accessingdatarest; import java.util.List; import org.springframework.data.repository.PagingAndSortingRepository; import org.springframework.data.repository.query.Param; import org.springframework.data.rest.core.annotation.RepositoryRestResource; @RepositoryRestResource(collectionResourceRel = "people", path = "people") public interface PersonRepository extends PagingAndSortingRepository<Person, Long> { List<Person> findByLastName(@Param("name") String name); } ~~~ 該存儲庫是一個界面，可讓您執行涉及`Person`對象的各種操作。它通過擴展[`PagingAndSortingRepository`](https://docs.spring.io/spring-data/commons/docs/current/api/org/springframework/data/repository/PagingAndSortingRepository.html)Spring Data Commons中定義的接口來獲得這些操作。在運行時，Spring Data REST自動創建此接口的實現。然后，它使用[@RepositoryRestResource](https://docs.spring.io/spring-data/rest/docs/current/api/org/springframework/data/rest/core/annotation/RepositoryRestResource.html)批注指示Spring MVC在處創建RESTful端點`/people`。 @RepositoryRestResource不需要導出存儲庫。它僅用于更改導出詳細信息，例如使用/people代替默認值/persons。在這里，您還定義了一個自定義查詢，以`Person`基于檢索對象列表`lastName`。您可以在本指南的后面部分中看到如何調用它。 `@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，因此您無需處理任何管道或基礎結構。 Spring Boot自動啟動Spring Data JPA來創建的具體實現，`PersonRepository`并配置它以使用JPA與后端內存數據庫進行通信。 Spring Data REST建立在Spring MVC之上。它創建了Spring MVC控制器，JSON轉換器和其他bean的集合，以提供RESTful前端。這些組件鏈接到Spring Data JPA后端。當您使用Spring Boot時，這些都是自動配置的。如果您想研究它是如何工作的，請查看`RepositoryRestMvcConfiguration`Spring Data REST。 ### 建立可執行的JAR 您可以使用Gradle或Maven從命令行運行該應用程序。您還可以構建一個包含所有必需的依賴項，類和資源的可執行JAR文件，然后運行該文件。生成可執行jar使得在整個開發生命周期中，跨不同環境等等的情況下，都可以輕松地將服務作為應用程序進行發布，版本控制和部署。如果您使用Gradle，則可以使用來運行該應用程序`./gradlew bootRun`。或者，您可以使用來構建JAR文件`./gradlew build`，然后運行JAR文件，如下所示： ~~~ java -jar build / libs / gs-accessing-data-rest-0.1.0.jar ~~~ 如果您使用Maven，則可以使用來運行該應用程序`./mvnw spring-boot:run`。或者，您可以使用來構建JAR文件，`./mvnw clean package`然后運行JAR文件，如下所示： ~~~ java -jar target / gs-accessing-data-rest-0.1.0.jar ~~~ 此處描述的步驟將創建可運行的JAR。您還可以構建經典的WAR文件。顯示日志記錄輸出。該服務應在幾秒鐘內啟動并運行。 ## 測試應用現在該應用程序正在運行，您可以對其進行測試。您可以使用任何所需的REST客戶端。以下示例使用\* nix工具`curl`。首先，您要查看頂級服務。以下示例顯示了如何執行此操作： ~~~ $ curl http：// localhost：8080 { “ _links”：{ “人們” ： { “ href”：“ http：// localhost：8080 / people {？page，size，sort}”， “ templated”：是 } } } ~~~ 前面的示例提供了該服務器必須提供的功能的第一印象。有一個`people`鏈接位于`[http://localhost:8080/people](http://localhost:8080/people)`。它有一些選項，如`?page`，`?size`和`?sort`。 Spring Data REST使用HAL格式進行JSON輸出。它非常靈活，并提供了一種便捷的方式來提供與所提供數據相鄰的鏈接。以下示例顯示了如何查看人員記錄（目前沒有）： ~~~ $ curl http：// localhost：8080 / people { “ _embedded”：{ “人們” ： [] }, “ _links”：{ “自己” ： { “ href”：“ http：// localhost：8080 / people {？page，size，sort}”， “ templated”：是 }, “搜索” ： { “ href”：“ http：// localhost：8080 / people / search” } }, “頁” ： { “大小”：20， “ totalElements”：0， “ totalPages”：0， “數字”：0 } } ~~~ 當前沒有元素，因此沒有頁面。是時候創建一個新的了`Person`！以下清單顯示了如何執行此操作： ~~~ $ curl -i -H“ Content-Type：application / json” -d'{“ firstName”：“ Frodo”，“ lastName”：“ Baggins”}'http：// localhost：8080 / people HTTP / 1.1 201已創建伺服器：Apache-Coyote / 1.1 位置：http：// localhost：8080 / people / 1 內容長度：0 日期：2014年2月26日，星期三20:26:55 GMT ~~~ * `-i`：確保您可以看到包含標題的響應消息。顯示新創建的URI`Person`。 * `-H "Content-Type:application/json"`：設置內容類型，以便應用程序知道有效負載包含JSON對象。 * `-d '{"firstName": "Frodo", "lastName": "Baggins"}'`：正在發送數據。 * 如果您使用的是Windows，則上面的命令將在[WSL上運行](https://docs.microsoft.com/en-us/windows/wsl)。如果無法安裝WSL，則可能需要用雙引號替換單引號，并轉義現有的雙引號，即`-d "{\"firstName\": \"Frodo\", \"lastName\": \"Baggins\"}"`。請注意，對POST操作的響應如何包含Location標頭。它包含新創建的資源的URI。Spring Data REST還具有兩個方法（RepositoryRestConfiguration.setReturnBodyOnCreate(…)和setReturnBodyOnUpdate(…)），您可以用來配置框架以立即返回剛剛創建的資源的表示形式。RepositoryRestConfiguration.setReturnBodyForPutAndPost(…)是一種啟用創建和更新操作的表示形式響應的快捷方法。您可以查詢所有人，如以下示例所示： ~~~ $ curl http：// localhost：8080 / people { “ _links”：{ “自己” ： { “ href”：“ http：// localhost：8080 / people {？page，size，sort}”， “ templated”：是 }, “搜索” ： { “ href”：“ http：// localhost：8080 / people / search” } }, “ _embedded”：{ “人們” ： [ { “ firstName”：“ Frodo”， “ lastName”：“ Baggins”， “ _links”：{ “自己” ： { “ href”：“ http：// localhost：8080 / people / 1” } } } ] }, “頁” ： { “大小”：20， “ totalElements”：1， “ totalPages”：1 “數字”：0 } } ~~~ 該`people`對象包含一個包含的列表`Frodo`。請注意，它如何包含`self`鏈接。Spring Data REST還使用[Evo Inflector](https://www.atteo.org/2011/12/12/Evo-Inflector.html)來對實體名稱進行復數以進行分組。您可以直接查詢單個記錄，如下所示： ~~~ $ curl http：// localhost：8080 / people / 1 { “ firstName”：“ Frodo”， “ lastName”：“ Baggins”， “ _links”：{ “自己” ： { “ href”：“ http：// localhost：8080 / people / 1” } } } ~~~ 這似乎純粹是基于網絡的。但是，在后臺有一個H2關系數據庫。在生產中，您可能會使用真實的數據庫，例如PostgreSQL。在本指南中，只有一個域對象。在域對象相互關聯的更復雜的系統中，Spring Data REST呈現了附加鏈接，以幫助導航到連接的記錄。您可以找到所有自定義查詢，如以下示例所示： ~~~ $ curl http：// localhost：8080 / people / search { “ _links”：{ “ findByLastName”：{ “ href”：“ http：// localhost：8080 / people / search / findByLastName {？name}”， “ templated”：是 } } } ~~~ 您可以看到查詢的URL，包括HTTP查詢參數`name`。請注意，這與`@Param("name")`接口中嵌入的注釋匹配。以下示例顯示了如何使用`findByLastName`查詢： ~~~ $ curl http：// localhost：8080 / people / search / findByLastName？name = Baggins { “ _embedded”：{ “人”：[{ “ firstName”：“ Frodo”， “ lastName”：“ Baggins”， “ _links”：{ “自己” ： { “ href”：“ http：// localhost：8080 / people / 1” } } } ] } } ~~~ 因為您將其定義為`List<Person>`在代碼中返回，所以它將返回所有結果。如果已將其定義為僅返回`Person`，則它將選擇`Person`要返回的對象之一。由于這可能是不可預測的，因此對于可能返回多個條目的查詢，您可能不想這樣做。您還可以發出`PUT`，`PATCH`和`DELETE`REST調用來分別替換，更新或刪除現有記錄。下面的示例使用一個`PUT`調用： ~~~ $ curl -X PUT -H“ Content-Type：application / json” -d'{“ firstName”：“ Bilbo”，“ lastName”：“ Baggins”}'http：// localhost：8080 / people / 1 $ curl http：// localhost：8080 / people / 1 { “ firstName”：“ Bilbo”， “ lastName”：“ Baggins”， “ _links”：{ “自己” ： { “ href”：“ http：// localhost：8080 / people / 1” } } } ~~~ 下面的示例使用一個`PATCH`調用： ~~~ $ curl -X PATCH -H“ Content-Type：application / json” -d'{“ firstName”：“ Bilbo Jr.”}'http：// localhost：8080 / people / 1 $ curl http：// localhost：8080 / people / 1 { “ firstName”：“ Bilbo Jr.”， “ lastName”：“ Baggins”， “ _links”：{ “自己” ： { “ href”：“ http：// localhost：8080 / people / 1” } } } ~~~ PUT替換整個記錄。未提供的字段將替換為null。您可以PATCH用來更新項目的子集。您還可以刪除記錄，如以下示例所示： ~~~ $ curl -X DELETE http：// localhost：8080 / people / 1 $ curl http：// localhost：8080 / people { “ _links”：{ “自己” ： { “ href”：“ http：// localhost：8080 / people {？page，size，sort}”， “ templated”：是 }, “搜索” ： { “ href”：“ http：// localhost：8080 / people / search” } }, “頁” ： { “大小”：20， “ totalElements”：0， “ totalPages”：0， “數字”：0 } } ~~~ 此超媒體驅動的界面的一個方便方面是，您可以使用curl（或您喜歡的任何REST客戶端）發現所有RESTful端點。您無需與客戶交換正式的合同或接口文檔。 ## 概括恭喜你！您已經開發了具有基于[超媒體的](https://spring.io/guides/gs/rest-hateoas)RESTful前端和基于JPA的后端的應用程序。