Java REST HATEOAS 示例 · HowToDoInJava 中文系列教程

# Java REST HATEOAS 示例 > 原文： [https://howtodoinjava.com/resteasy/writing-restful-webservices-with-hateoas-using-jax-rs-and-jaxb-in-java/](https://howtodoinjava.com/resteasy/writing-restful-webservices-with-hateoas-using-jax-rs-and-jaxb-in-java/) 代表性狀態轉移（ [REST](https://restfulapi.net) ）是一種設計習語，它使用 Web 的無狀態客戶端 - 服務器架構將 REST Web 服務表示為 URL 標識的資源。 REST 風格的架構由客戶端和服務器組成。客戶端向服務器發起請求；服務器處理請求并返回適當的響應。請求和響應圍繞“資源”的“表示”的傳遞而構建。資源可以是可以解決的任何連貫且有意義的概念。資源的表示形式通常是捕獲資源當前或預期狀態的文檔。 > 來源： [http://en.wikipedia.org/wiki/Representational_State_Transfer](https://en.wikipedia.org/wiki/Representational_State_Transfer) 。請注意，此示例應用應部署在 **JBOSS 7 服務器**上。如果您使用的是其他服務器，則需要更新[**這篇文章**](//howtodoinjava.com/resteasy/resteasy-tomcat-hello-world-application/)中提到的`pom.xml`和`web.xml`文件。 ```java Table of Contents What is HATEOAS? Java REST HATEOAS Example Creating maven blank project Adding required dependencies in pom.xml Registering a new module or service Defining GET,PUT,POST and DELETE methods Annotating model classes Analyze the result ``` ## 1\. 什么是 HATEOAS？ [HATEOAS](https://restfulapi.net/hateoas/) 是對 REST 的約束，它表示 REST 應用的客戶端只需要知道一個固定的 URL 即可訪問它。應該通過返回的資源表示中包含的超鏈接從該 URL 動態發現任何資源。理想情況下，您應該僅向最終用戶提供您的服務根 URI。從此以后，用戶必須能夠發現您服務中的所有其他 URI。可以使用當前資源表示中的“鏈接”來發現這些 URI。在下面給出的示例應用中，我們將看到 HATEOAS 的演示。請記住，給定示例項目中的 HATEOAS 實現僅用于演示。在企業級應用中，建議使用任何第三方 API 或某些自定義實現（最好使用注解）。 ## 2\. Java REST HATEOAS 示例讓我們創建一個 Java REST 應用，并在其響應中添加 HATEOAS 鏈接。 #### 2.1 創建 Maven 項目創建 Maven 項目就像在命令提示符下執行以下命令一樣簡單。我假設您已經在系統中安裝了 maven。 ```java mvn archetype:generate -DgroupId=com.demo.rest -DartifactId=sampleRestApp -DarchetypeArtifactId=maven-archetype-webapp -DinteractiveMode=false ``` 如果您尚未安裝 maven，請轉到 maven 的主頁并下載最新版本。現在將上述項目轉換為 Eclipse 支持的項目。下面的命令將生成`.project`文件和其他 Eclipse 依賴項。 ```java mvn eclipse:eclipse -Dwtpversion=2.0 ``` #### 2.2 更新`pom.xml`中的 Maven 依賴項現在該為新創建的 Maven 項目提供所需的依賴項了。以下是必需的依賴項。將它們添加到`pom.xml`文件中。 ```java <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 http://maven.apache.org/maven-v4_0_0.xsd"> <modelversion>4.0.0</modelversion> <groupid>com.demo.rest</groupid> <artifactid>demoResteasyApplication</artifactid> <packaging>war</packaging> <version>1.0-SNAPSHOT</version> <name>demoResteasyApplication Maven Webapp</name> <url>http://maven.apache.org</url> <repositories> <repository> <id>jboss</id> <url>http://repository.jboss.org/maven2</url> </repository> </repositories> <dependencies> <dependency> <groupid>junit</groupid> <artifactid>junit</artifactid> <version>3.8.1</version> <scope>test</scope> </dependency>  <dependency> <groupid>org.jboss.resteasy</groupid> <artifactid>resteasy-jaxrs</artifactid> <version>2.3.1.GA</version> <scope>provided</scope> </dependency>  <dependency> <groupid>org.jboss.resteasy</groupid> <artifactid>resteasy-jaxb-provider</artifactid> <version>2.3.1.GA</version> </dependency>  <dependency> <groupid>org.jboss.resteasy</groupid> <artifactid>resteasy-multipart-provider</artifactid> <version>2.3.1.GA</version> </dependency> <dependency> <groupid>net.sf.scannotation</groupid> <artifactid>scannotation</artifactid> <version>1.0.2</version> </dependency> </dependencies> <build> <finalname>demoResteasyApplication</finalname> </build> </project> ``` #### 2.3 注冊新的模塊或服務隨著 **jax-rs 2.x** 的發布，我們無需在`web.xml`中指定任何內容。 Jax-rs 現在掃描`@ApplicationPath`注解以注冊新的應用模塊。 ```java package com.demo.rest; import java.util.Arrays; import java.util.HashSet; import java.util.Set; import javax.ws.rs.ApplicationPath; import javax.ws.rs.core.Application; import com.demo.rest.service.UserService; @ApplicationPath("/") public class ApplicationConfig extends Application { @SuppressWarnings("unchecked") public Set<class <?>> getClasses() { return new HashSet<class <?>>(Arrays.asList(UserService.class)); } } ``` 我們的模塊類如下所示： ```java @Path("/user-management") public class UserService { //Some code } ``` 上面的模塊注冊代碼將注冊一個新的應用`"/user-management"`，并將所有相關的相對資源請求轉發到此應用/模塊。 #### 2.4 定義 REST 方法 - GET，PUT，POST 和 DELETE 如上所述，REST 服務映射了資源表示形式和將更改其內部表示形式的操作。這些動作應被視為等同于數據庫的`SELECT`，`INSERT`，`UPDATE`和`DELETE`操作。如果我們談論 HTTP 協議，則可以將它們映射到 GET，PUT，POST 和 DELETE 方法。其中： * **GET** 方法將返回資源表示形式 * **PUT** 將修改資源的內部狀態 * **POST** 通常用于添加新資源，但本質上不是 * **DELETE** 用于刪除資源現在，讓他們了解`user-management`模塊。 1. **GET** 應該返回所有用戶或單個用戶表示。 2. **PUT** 方法應用于修改單個用戶的表示。 3. **POST** 方法應用于創建新的用戶資源。 4. 同樣，應該使用 **DELETE** 方法從系統中刪除用戶。 ```java package com.demo.rest.service; import java.net.URI; import java.net.URISyntaxException; import java.util.ArrayList; import javax.ws.rs.Consumes; import javax.ws.rs.DELETE; import javax.ws.rs.DefaultValue; import javax.ws.rs.GET; import javax.ws.rs.POST; import javax.ws.rs.PUT; import javax.ws.rs.Path; import javax.ws.rs.PathParam; import javax.ws.rs.Produces; import javax.ws.rs.QueryParam; import javax.ws.rs.core.Response; import com.demo.rest.model.User; import com.demo.rest.model.Users; @Path("/user-management") public class UserService { @GET @Path("/") @Produces("application/vnd.com.demo.user-management+xml;charset=UTF-8;version=1") public UserService getServiceInfo() { return new UserService(); } @GET @Path("/users") @Produces("application/vnd.com.demo.user-management.users+xml;charset=UTF-8;version=1") public Users getAllUsers() { User user1 = new User(); user1.setId(1); user1.setFirstName("demo"); user1.setLastName("user"); user1.setUri("/user-management/users/1"); User user2 = new User(); user2.setId(2); user2.setFirstName("demo"); user2.setLastName("user"); user2.setUri("/user-management/users/2"); Users users = new Users(); users.setUsers(new ArrayList()); users.getUsers().add(user1); users.getUsers().add(user2); return users; } @GET @Path("/users/{id}") @Produces("application/vnd.com.demo.user-management.user+xml;charset=UTF-8;version=1") public User getUserById(@PathParam("id") int id) { User user = new User(); user.setId(id); user.setFirstName("demo"); user.setLastName("user"); user.setUri("/user-management/users/" + id); return user; } @POST @Path("/users") @Consumes("application/vnd.com.demo.user-management.user+xml;charset=UTF-8;version=1") public Response createUser(User user, @DefaultValue("false") @QueryParam("allow-admin") boolean allowAdmin) throws URISyntaxException { System.out.println(user.getFirstName()); System.out.println(user.getLastName()); return Response.status(201) .contentLocation(new URI("/user-management/users/123")).build(); } @PUT // @Path("/users/{id: [0-9]*}") @Path("/users/{id}") @Consumes("application/vnd.com.demo.user-management.user+xml;charset=UTF-8;version=1") @Produces("application/vnd.com.demo.user-management.user+xml;charset=UTF-8;version=1") public User updateUser(@PathParam("id") int id, User user) throws URISyntaxException { user.setId(id); user.setFirstName(user.getFirstName() + "updated"); return user; } @DELETE @Path("/users/{id}") public Response deleteUser(@PathParam("id") int id) throws URISyntaxException { return Response.status(200).build(); } } ``` #### 2.5 注解模型類到目前為止，我們已經創建了我們的服務類。現在該創建資源表示形式了，用戶可以使用它。如果您還記得，HATEOAS 堅持您的應用應該有一個起點，此后，用戶與應用的每次交互都應該是狀態轉移。狀態傳輸所需的信息應來自當前資源表示，即每次重新表示應提供嵌套狀態傳輸的機制。讓我們用 [**JAXB 注解**](https://howtodoinjava.com/jaxb/jaxb-annotations/)來注解我們的服務和模型類，然后我們將看到在什么程度上遵循了 HATEOAS 準則。 **`Users.java`（用戶集合的表示形式）** ```java package com.demo.rest.model; import java.util.ArrayList; import javax.xml.bind.annotation.XmlAccessType; import javax.xml.bind.annotation.XmlAccessorType; import javax.xml.bind.annotation.XmlElement; import javax.xml.bind.annotation.XmlRootElement; @XmlAccessorType(XmlAccessType.NONE) @XmlRootElement(name = "users") public class Users { @XmlElement(name="user") private ArrayList users; public ArrayList getUsers() { return users; } public void setUsers(ArrayList users) { this.users = users; } } ``` **`User.java`（單個用戶的表示形式）** ```java package com.demo.rest.model; import java.io.Serializable; import javax.xml.bind.annotation.XmlAccessType; import javax.xml.bind.annotation.XmlAccessorType; import javax.xml.bind.annotation.XmlAttribute; import javax.xml.bind.annotation.XmlElement; import javax.xml.bind.annotation.XmlRootElement; @XmlAccessorType(XmlAccessType.NONE) @XmlRootElement(name = "user") public class User implements Serializable { private static final long serialVersionUID = 1L; @XmlAttribute(name = "id") private int id; @XmlAttribute(name="uri") private String uri; @XmlElement(name = "firstName") private String firstName; @XmlElement(name = "lastName") private String lastName; public int getId() { return id; } public void setId(int id) { this.id = id; } 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; } public String getUri() { return uri; } public void setUri(String uri) { this.uri = uri; } } ``` **添加了 JAXB 注解的`UserService.java`（服務根的表示）** ```java package com.demo.rest.service; import java.net.URI; import java.net.URISyntaxException; import java.util.ArrayList; import javax.ws.rs.Consumes; import javax.ws.rs.DELETE; import javax.ws.rs.DefaultValue; import javax.ws.rs.GET; import javax.ws.rs.POST; import javax.ws.rs.PUT; import javax.ws.rs.Path; import javax.ws.rs.PathParam; import javax.ws.rs.Produces; import javax.ws.rs.QueryParam; import javax.ws.rs.core.Response; import javax.xml.bind.annotation.XmlAccessType; import javax.xml.bind.annotation.XmlAccessorType; import javax.xml.bind.annotation.XmlElement; import javax.xml.bind.annotation.XmlRootElement; import com.demo.rest.model.User; import com.demo.rest.model.Users; @XmlAccessorType(XmlAccessType.NONE) @XmlRootElement(name = "user-management") @Path("/user-management") public class UserService { @XmlElement(name = "users") private String uri1 = "/user-management/users"; @XmlElement(name = "report") private String uri2 = "/user-managemet/generate-report"; public String getUri1() { return uri1; } public void setUri1(String uri1) { this.uri1 = uri1; } public String getUri2() { return uri2; } public void setUri2(String uri2) { this.uri2 = uri2; } @GET @Path("/") @Produces("application/vnd.com.demo.user-management+xml;charset=UTF-8;version=1") public UserService getServiceInfo() { return new UserService(); } @GET @Path("/users") @Produces("application/vnd.com.demo.user-management.users+xml;charset=UTF-8;version=1") public Users getAllUsers() { User user1 = new User(); user1.setId(1); user1.setFirstName("demo"); user1.setLastName("user"); user1.setUri("/user-management/users/1"); User user2 = new User(); user2.setId(2); user2.setFirstName("demo"); user2.setLastName("user"); user2.setUri("/user-management/users/2"); Users users = new Users(); users.setUsers(new ArrayList()); users.getUsers().add(user1); users.getUsers().add(user2); return users; } @GET @Path("/users/{id}") @Produces("application/vnd.com.demo.user-management.user+xml;charset=UTF-8;version=1") public User getUserById(@PathParam("id") int id) { User user = new User(); user.setId(id); user.setFirstName("demo"); user.setLastName("user"); user.setUri("/user-management/users/" + id); return user; } @POST @Path("/users") @Consumes("application/vnd.com.demo.user-management.user+xml;charset=UTF-8;version=1") public Response createUser(User user, @DefaultValue("false") @QueryParam("allow-admin") boolean allowAdmin) throws URISyntaxException { System.out.println(user.getFirstName()); System.out.println(user.getLastName()); return Response.status(201) .contentLocation(new URI("/user-management/users/123")).build(); } @PUT // @Path("/users/{id: [0-9]*}") @Path("/users/{id}") @Consumes("application/vnd.com.demo.user-management.user+xml;charset=UTF-8;version=1") @Produces("application/vnd.com.demo.user-management.user+xml;charset=UTF-8;version=1") public User updateUser(@PathParam("id") int id, User user) throws URISyntaxException { user.setId(id); user.setFirstName(user.getFirstName() + "updated"); return user; } @DELETE @Path("/users/{id}") public Response deleteUser(@PathParam("id") int id) throws URISyntaxException { return Response.status(200).build(); } } ``` #### 2.6 驗證 HATEOAS 鏈接因此，我們為一個簡單的演示編寫了許多代碼。現在，該測試我們的代碼了。我正在使用 [**RESTClient**](https://addons.mozilla.org/en-US/firefox/addon/restclient/ "restclient firefox plugin") 來驗證 API 輸出。您可以選擇自己的驗證方式。我已經在 **eclipse juno** 上運行的 **JBOSS 7.1 服務器運行時環境**中部署了以上應用。如果要部署在某些獨立的 jboss 實例上，也可以嘗試。讓我們一一點擊應用 URL： 1. **根服務 API** 此 API 返回服務根的表示形式。它具有用于用戶收集的 **uri** 和用于 API 的一個附加**鏈接**來生成用戶報告。 ![user-management root api](https://img.kancloud.cn/72/dd/72ddad57bb3373ad9682fb629931e49b_938x423.png "user-management") 2. **獲取所有用戶集合** 此表示具有用戶數據和 **uri** 的快照，可在其中提取特定用戶的所有其他信息。 ![users collection](https://img.kancloud.cn/4f/29/4f29658082592482d19e079c80f6748b_938x469.png "users") 3. **根據 ID 獲取用戶** 此表示應提供用戶資源和其他鏈接（如果有）的每個相關細節。 ![get user by id](https://img.kancloud.cn/69/5b/695bc7c6588b73b0eebd8bf9796498c5_946x375.png "user") 4. **不帶媒體類型添加用戶** 添加用戶資源后，應將其添加到用戶集合中。因此，在幾乎所有集合類型表示中， **POST** 都應該隱式地可用。在這里，用戶將被添加到用戶集合中，因此我們會將其發布在“`/user-management/users`”上。添加帖子時，我們必須聲明我們要發布的媒體類型。如果未指定，則會發生以下錯誤。響應代碼 415（不支持的媒體類型） ![create-unsupported-media-type](https://img.kancloud.cn/b6/1d/b61d239b0c37991113b258f52fff8e9f_946x449.png "create-unsupported-media-type") 5. **在請求標頭中添加正確的媒體類型** 讓我們向請求標頭添加正確的媒體類型。 ![add-content-type](https://img.kancloud.cn/fd/29/fd292f3ce853412277411cca4eea07a9_561x271.png "add-content-type") 6. **使用正確的媒體類型創建** 現在，應該創建一個新用戶，并返回到創建資源的“鏈接”。 ![create-success with correct media type](https://img.kancloud.cn/f8/51/f851cd355b5645dd57bd4a6369b33c09_943x572.png "create-success") 7. **刪除用戶** 刪除資源時，使用“HTTP DELETE”。不得使用任何媒體類型或請求正文。資源應在資源鏈接本身上刪除。 ![delete user](https://img.kancloud.cn/70/a8/70a8b75ca48763f4b68c12803a7df0c8_937x349.png "delete") 因此，這就是在通過 REST HATEOAS 進行的連續 API 調用之間，應用狀態應如何更改，而其下一個狀態應從當前狀態表示中進行定向的方式。我在這里完成了寫作，剩下的工作就是讓您對這個例子更加滿意。從下面給定的下載鏈接，下載上面的源代碼文件并使用它。 [**源碼下載**](https://drive.google.com/file/d/0B7yo2HclmjI4eWJ4czV6QVpmdDA/view?usp=drive_web "Download rest sample project") 學習愉快！