javarest接口实例（揭秘RESTEasy如何完美支持JAVA）

威哥 2023-04-21 20:19:41 452

javarest接口实例（揭秘RESTEasy如何完美支持JAVA）apache Tomcat[6] 9Java Development Kit[5] (JDK)1.8.0-131 (amd64)放心，在这个过程中，我们不会浪费时间精力去重复做些数据处理之类的事情。我们会通过 JBoss RESTEasy来进行搭建。而确保该微服务的轻量级，目的是为了向大家展示，在一个全新或者现存的微服务前端，建立一个 RESTful接口，真的非常简单。与此同时，我会进一步证明，通过 RESTEasy构建的微服务具备很大的灵活性，不仅可以兼容包括 JSON，XML在内的多种数据传输格式，还支持将其部署到 Apache Tomcat[1]服务器而非 JBoss企业应用平台 (EAP)[2]上。诚然，每个工具都有自己的优势，但是我认为先在 KISS原则 [3]下探讨技术可用性会很有帮助，然后才是根据软件的长期目标和需求来决定应该为服务架构添加哪些特性。本文中提到的代码示例都可以

javarest接口实例（揭秘RESTEasy如何完美支持JAVA）(1)

作者 | Lyndsey Padget

译者 |月满西楼

本文来自公众号“EAWorld”，ID：eaworld

今天我们来聊聊 Java中的微服务。虽说 Java EE提供了一个强大的平台，供我们创建、部署和管理企业级微服务，但在本文中，我将展示如何创建一个尽可能小的 RESTful微服务。

放心，在这个过程中，我们不会浪费时间精力去重复做些数据处理之类的事情。我们会通过 JBoss RESTEasy来进行搭建。而确保该微服务的轻量级，目的是为了向大家展示，在一个全新或者现存的微服务前端，建立一个 RESTful接口，真的非常简单。

与此同时，我会进一步证明，通过 RESTEasy构建的微服务具备很大的灵活性，不仅可以兼容包括 JSON，XML在内的多种数据传输格式，还支持将其部署到 Apache Tomcat[1]服务器而非 JBoss企业应用平台 (EAP)[2]上。诚然，每个工具都有自己的优势，但是我认为先在 KISS原则 [3]下探讨技术可用性会很有帮助，然后才是根据软件的长期目标和需求来决定应该为服务架构添加哪些特性。

本文中提到的代码示例都可以在 GitHub[4]上查阅，包括“starter” 和 “final”这两个分支。下面是我采用的环境，当然你的实际情况可能有所不同:

Java Development Kit[5] (JDK)1.8.0-131 (amd64)
apache Tomcat[6] 9
apache Maven[7] 3.5.0
Eclipse Java EE IDE[8] 4.7.0 (Oxygen)
Linux Mint[9] 18.2 (Sonya)64位

就技术而言...

微服务 [10]是一种体积小、更为精炼的服务，其目标是“做好一件事”。微服务之间通过一些接口进行交互是很普遍的现象。如果该接口可以通过 web访问 (使用 HTTP)，那么它就是一个 web服务。部分 web服务是基于 RESTful这种架构风格的，另一些则不是。注意，微服务并不都是 web服务，web服务并不都是 RESTful web服务，RESTful web服务也并不都是微服务！

javarest接口实例（揭秘RESTEasy如何完美支持JAVA）(2)

REST和 XML……能否共存？

如果你此前在使用 RESTful web服务时，没用过除 JSON 以外的文本数据交换格式 [11]来进行内容传输，那么你可能会认为二者是不相关的。但是回想下，REST是定义 API的一种架构风格，REST和 JSON这两者又碰巧一起流行起来 (注意，这并非偶然)。XML多年的发展使其拥有大量的客户群，能够接纳和提供 XML数据传输格式的 RESTful web服务不管是对那些已经依赖于这类内容交互系统的组织，还是对仅仅是更熟悉 XML的用户来说，都非常有用。当然，通常情况下，JSON依然是首选，因为其消息体更小，但有时 XML只是一个更简单的“sell”。拥有一个能同时支持这两种格式的 RESTful微服务是最理想的 ;从部署的角度来说，它不仅简洁，具备可扩展性，还有足够的灵活性，可以支持不同类型的内容，从而满足那些其他有调用需求的应用程序。

为什么选择 RESTEasy？

RESTEasy[12]是 Jboss的一个框架，可以用来构建 RESTful web服务。通过 RESTEasy构建的 RESTful web服务，可以根据四个函数库来实现对 XML和 JSON这两种数据传输格式的支持：

resteasy-jaxrs，实现了 JAX-RS 2.0 (用于 RESTful Web服务的 Java API) [13]
resteasy-jaxb-provider，其 JAXB[14]绑定能有效支持 XML
resteasy-jettison-provider，用 Jettison[15]将 XML转换为 JSON
resteasy-servlet-initializer，将服务部署到 Servlet 3.0容器 (在 Tomcat服务器上)

首先，创建一个内含 pom.xml数据包的 web服务项目:

<?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 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>com.lyndseypadget</groupId> <artifactId>resteasy</artifactId> <packaging>war</packaging> <version>0.0.1-SNAPSHOT</version> <name>resteasy</name> <repositories> <repository> <id>org.jboss.resteasy</id> <url>http://repository.jboss.org/maven2/</url> </repository> </repositories> <dependencies> <dependency> <groupId>org.jboss.resteasy</groupId> <artifactId>resteasy-jaxrs</artifactId> <version>3.1.4.Final</version> </dependency> <dependency> <groupId>org.jboss.resteasy</groupId> <artifactId>resteasy-jaxb-provider</artifactId> <version>3.1.4.Final</version> </dependency> <dependency> <groupId>org.jboss.resteasy</groupId> <artifactId>resteasy-jettison-provider</artifactId> <version>3.1.4.Final</version> </dependency> <dependency> <groupId>org.jboss.resteasy</groupId> <artifactId>resteasy-servlet-initializer</artifactId> <version>3.1.4.Final</version> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <version>2.0.2</version> <configuration> <source>1.8</source> <target>1.8</target> </configuration> </plugin> </plugins> <finalName>resteasy</finalName> </build> </project>

（左右滑动可查看全部代码，下同）

这些数据库的大小大概在 830KB。当然，这些直接的依赖环境（dependency），运用 Maven一起构建项目也会带来部分传递性依赖。

javarest接口实例（揭秘RESTEasy如何完美支持JAVA）(3)

接下来，我将用“Maven方法”来构建这个项目，例如在 src/main/java中，使用 Maven构建命令等，不想用 Maven的话，你也可以直接从下载页面 [16]下载 RESTEasy jar数据包。下载的时候不用理会 RESTEasy站点上弹出的这个提示:JBoss仅仅是在尝试引导你采用更“企业化”的方法。你只需点击“继续下载”，来开展后面的操作。

javarest接口实例（揭秘RESTEasy如何完美支持JAVA）(4)

项目设计

下面这个微服务可以用非常简单的方法来演示一些基本概念。如下图所示，它包括 5个等级。

javarest接口实例（揭秘RESTEasy如何完美支持JAVA）(5)

此处，FruitApplication是微服务的切入点。FruitService提供了主要的路径 (/fruits)，同时它也充当了路由器的功能。苹果和水果都是模型；水果包含一些抽象的功能，苹果则会具体地扩展它的功能。

和你设想一致的是，FruitComparator可以提供比较功能。不熟悉 Java comparator的读者，可以在这篇文章中了解一下对象的等同性和比较，这里我用字符来取代。虽然 FruitComparator不是一个模型，但我更喜欢将比较器与它想要比较的对象类型保持相类似的命名。

模型

让我们从 Fruit这级开始

package com.lyndseypadget.resteasy.model; import javax.xml.bind.annotation.XmlElement; public abstract class Fruit { private String id; private String variety; @XmlElement public String getId { return id; } public void setId(String id) { this.id = id; } @XmlElement public String getVariety { return variety; } public void setVariety(String variety) { this.variety = variety; } }

然后 Apple这级对其展开：

package com.lyndseypadget.resteasy.model; import javax.xml.bind.annotation.XmlElement; import javax.xml.bind.annotation.XmlRootElement; @XmlRootElement(name = "apple") public class Apple extends Fruit { private String color; @XmlElement public String getColor { return color; } public void setColor(String color) { this.color = color; } }

以上并不是什么特别惊人的代码，你可能会觉得都不值得拿出来炫耀，就是一个 Java继承的简单实例。但重点在于这两个注释 @XmlElement 和 @XmlRootElement，它们定义了 XML apple结构的样子:

<apple> <id>1</id> <variety>Golden delicious</variety> <color>yellow</color> </apple>

因为没有约定明显的构造函数:Java使用了隐式的、无参数的默认构造函数，所以一些更微妙的事情在发生。这个无参数的构造函数对 JAXB 施展魔法般效果的工作是十分必要的（本文解释了这一点，以及必要的话，如何用 XMLAdapter来让它工作）。

现在我们有了一个对象：被定义的苹果。它有三个属性: ID、多样性和颜色。

服务

FruitService 被用来作为与微服务交互的主要路径 (/fruits)。在本例中，我使用 @path注释直接在该层级中定义了第一个路径，/fruits/apples。随着 RESTful微服务的扩展，你可能希望在自己的层级中定义多个最终路径 (例如 /apples /bananas /oranges)。

这张苹果的地图帮助我们根据 id跟踪苹果的数据，从而模拟某些类型的数据持久层。利用 getApples方法（常用的 HTTP请求方式）将会返回地图跟踪到的相关苹果数据。GET /apples route是用 @GET和 @path注释定义的，它可以生成数据传输格式 XML或 JSON的内容。

这个方法需要返回一个 List< apple >对象，然后用这个比较器按品种属性来对列表进行排序。

FruitComparator看起来是像这样的:

package com.lyndseypadget.resteasy.model; import java.util.Comparator; public class FruitComparator implements Comparator { public int compare(F f1 F f2) { return f1.getVariety.compareTo(f2.getVariety); } }

注意，如果想要对苹果的一个特定属性进行排序，比如颜色，我们就必须创建一个新的比较器去取代，并取个名字，比如 AppleComparator。

应用程序

在 RESTEasy3.1.x中你需要定义一个扩展应用的层级。RESTEasy示例文档说明这是一个单例模式注册表（singleton registry），如下所示:

package com.lyndseypadget.resteasy; import javax.ws.rs.core.Application; import java.util.HashSet; import java.util.Set; public class FruitApplication extends Application { HashSet singletons = new HashSet; public FruitApplication { singletons.add(new FruitService); } @Override public Set<Class> getClasses { HashSet<Class> set = new HashSet<Class>; return set; } @Override public Set getSingletons { return singletons; } }

如果仅为了说明本例，就不需要对这个层级做太多工作，但是我们需要在 web.xml文件中将它连接起来，这会在后面的章节“web服务连接”中进行介绍。

对象的构建集合

GET /apples调用将返回如下数据：

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <collection> <apple> <id>1</id> <variety>Golden delicious</variety> <color>yellow</color> </apple> </collection>

[ { "apple": { "id": 1 "variety": "Golden delicious" "color": "yellow" } } ]

但是，我们可以将数据更改成看起来稍有点不同：

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <apples> <apple> <id>1</id> <variety>Golden delicious</variety> <color>yellow</color> </apple> </apples>

{ "apples": { "apple": { "id": 1 "variety": "Golden delicious" "color": "yellow" } } }

第二个选项在 XML中看起来更好一些，但是对 JSON产生了不太好的影响。如果你喜欢这个结构，可以用它自己的类型打包 List< Apple >，并修改 FruitService.getApples方法来返回这种类型:

package com.lyndseypadget.resteasy.model; import java.util.ArrayList; import java.util.Collection; import java.util.Collections; import java.util.Comparator; import java.util.List; 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.FIELD) @XmlRootElement(name = "apples") public class Apples { private static Comparator comparator = new FruitComparator; @XmlElement(name = "apple" type = Apple.class) private List apples; public List getApples { Collections.sort(apples comparator); return apples; } public void setApples(Collection apples) { this.apples = new ArrayList(apples); } }

这些注释有效地“重新标记”了根元素，即 collection/list。通过读取用于 javax.xml.bind.annotation的 javadoc文档，你可以尝试用它和不同的 XML Schema映射注释。

当然，如果实在不能搞定一般的方法签名（method signature），则可以编码写入不同的方法——一个用于 XML，另一个用于 JSON。

一些 web服务连接

从将该服务部署到 Tomcat开始，我用一个放在 src/main/webapp/web inf/web.xml的 web应用部署描述符文件。它所包含的内容如下：

<?xml version="1.0"?> <!DOCTYPE web-app PUBLIC "-//Sun Microsystems Inc.//DTD Web Application 2.3//EN" "http://java.sun.com/dtd/web-app_2_3.dtd"> <web-app> <display-name>resteasy</display-name> <context-param> <param-name>javax.ws.rs.core.Application</param-name> <param-value>com.lyndseypadget.resteasy.FruitApplication</param-value> </context-param> <context-param> <param-name>resteasy.servlet.mapping.prefix</param-name> <param-value>/v1</param-value> </context-param> <listener> <listener-class> org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap </listener-class> </listener> <servlet> <servlet-name>Resteasy</servlet-name> <servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class> </servlet> <servlet-mapping> <servlet-name>Resteasy</servlet-name> <url-pattern>/v1/*</url-pattern> </servlet-mapping> </web-app>

没错，“servlet-name”表示 servlet(即 Service)的名称是 Resteasy。servlet-mapping url-pattern (/v1/*)要求 Tomcat服务器将包含该模式的传入请求传输到 Resteasy服务。关于如何建立这个文件的更多信息，以及可用的不同选项，请参阅 Tomcat的应用程序部署文档 [17]。

构建及部署

从项目的根目录中，可以运行以下内容来构建 WAR(web application resource，web应用程序资源)文件:

mvn clean install

这将在 target文件夹中创建一个包含 WAR文件的新文件夹。虽然用 Maven或其他工具来部署该文件也可以，但我只用一个简单的复制命令就可以。需要注意的是，每次将 WAR重新部署到 Tomcat服务器时，应该首先暂停服务器运行，并删除服务应用程序文件夹 (在本例中，是这个文件夹：< tomcatDirectory >/webapps/resteasy)和旧的 WAR文件 (< tomcatDirectory >/webapps/resteasy.war)。

[sudo] cp target/resteasy.war <tomcatDirectory>/webapps/resteasy.war

如果此时 Tomcat服务器正在运行，那么会即刻部署 web服务。如果不是，下次服务器启动时，该服务也会被自动部署上去。然后就可以通过如下地址访问 web服务：http://< tomcatHost >:< tomcatPort >/resteasy/v1/fruits/apples。我的范例中是这个地址 http://localhost:8080/resteasy/v1/fruits/apples。

通过“内容协商（Content negotiation）”测试服务

内容协商（Content negotiation）是一种机制，它可以提供不同资源 (URI)的表现形式。最基本的，这意味着可以:

详细设置 Accept header，以指示希望从服务中接受的内容类型
详细设置 Content-Type header，以指示发送给服务的内容类型

要获取更多关于内容协商（Content negotiation）和 header的信息，请参阅 RFC 2616[18]的第 12和 14章。在本例中，你真正需要了解的是:

@Produces annotation（注释）指明了该方法能够生成哪些内容 (这将尝试匹配请求上的 Accept header)。
@Consumes annotation（注释）指明了该方法能够使用哪些内容 (这将尝试匹配请求的 content-type header)。

如果您试图对一个有效端点进行 HTTP调用，但是内容不能被协商，这意味着没有 @Produces匹配该 Accept数据，或者没有 @Consumes匹配 Content-Type数据，将被返回 HTTP状态码 415:不支持的数据传输格式。

返回常见数据传输格式的 GET调用实际上可以直接进入浏览器。对于 GET /apples这样的调用，默认情况下您将获得 XML:

javarest接口实例（揭秘RESTEasy如何完美支持JAVA）(6)

不过，使用像 Postman[19]这类工具可能会更有帮助，因为它明确地指定 Accept header作为 application/xml:

javarest接口实例（揭秘RESTEasy如何完美支持JAVA）(7)

这两种方法都返回了一些有效但没有多大意义的 XML，即一个空的苹果列表。但是这里有一些很酷的东西。将 Accept header更改为 application/json，太好了，瞧！JSON*生效*了:

javarest接口实例（揭秘RESTEasy如何完美支持JAVA）(8)

不只是“读取”

你可能会发现，很多 RESTful web服务的例子，都是只读的，部分也不会有进一步的提示，比如如何去创建、更新和删除这些操作。虽然我们现在已经有了 web服务的框架，但这是一个不能更改的空列表，这并没多大意义。所以我们应该运用一些其他方法，将苹果添加到这个列表中或从列表中将其删除。

package com.lyndseypadget.resteasy; import java.util.ArrayList; import java.util.Collections; import java.util.Comparator; import java.util.List; import java.util.Map; import java.util.TreeMap; import javax.ws.rs.Consumes; import javax.ws.rs.DELETE; import javax.ws.rs.GET; import javax.ws.rs.POST; import javax.ws.rs.Path; import javax.ws.rs.PathParam; import javax.ws.rs.Produces; import javax.ws.rs.core.MediaType; import javax.ws.rs.core.Response; import com.lyndseypadget.resteasy.model.Apple; import com.lyndseypadget.resteasy.model.FruitComparator; @Path("/fruits") public class FruitService { private static Comparator comparator = new FruitComparator; private static Map apples = new TreeMap; private static int appleCount = 0; @GET @Path("/apples") @Produces({ MediaType.APPLICATION_XML MediaType.APPLICATION_JSON }) public List getApples { List retVal = new ArrayList(apples.values); Collections.sort(retVal comparator); return retVal; } @GET @Path("/apples/{id}") @Produces({ MediaType.APPLICATION_XML MediaType.APPLICATION_JSON }) public Response getApple(@PathParam("id") String id) { Apple found = apples.get(id); if(found == ) { return Response.status(404).build; } return Response.ok(found).build; } @DELETE @Path("/apples/{id}") public Response deleteApple(@PathParam("id") String id) { apples.remove(id); return Response.status(200).build; } @POST @Path("/apples") @Consumes({ MediaType.APPLICATION_XML MediaType.APPLICATION_JSON }) public Response createApple(Apple apple) { String newId = Integer.toString( appleCount); apple.setId(newId); apples.put(newId apple); return Response.status(201).header("Location" newId).build; } }

如此，就增加了一些新的功能:

通过 id检索苹果数据 (如果在地图中没有找到，则返回状态代码 404)
通过 id删除苹果数据
创建新的苹果数据 (如果成功的话，返回状态代码 201)

这些方法完善了很多功能，确保了服务可以按照预期工作。更新苹果 (使用 @PUT和 /或 @PATCH)，以及更多的关于端点、逻辑和管理持久性方面的功能操作，都留给读者你们来练习吧。

当我们再次进行构建和部署时会发现 (如果用 Maven或者 Tomcat来进行设置，请参阅上文“构建和部署”)，现在已经可以在服务中创建、检索和删除苹果了。而且即使不在服务器上做任何重新配置，也可以在 XML和 JSON之间进行选择性调用。

来创建一个拥有“application/json”内容类型和 JSON主体的苹果，如下图所示:

javarest接口实例（揭秘RESTEasy如何完美支持JAVA）(9)

这是另一个例子:创建一个具有“application/xml”内容类型和 XML主体的苹果。

javarest接口实例（揭秘RESTEasy如何完美支持JAVA）(10)

在 XML中检索所有的苹果数据:

javarest接口实例（揭秘RESTEasy如何完美支持JAVA）(11)

在 JSON中通过 id检索 apple 2的数据：

javarest接口实例（揭秘RESTEasy如何完美支持JAVA）(12)

通过 id删除 apple 1的数据：

javarest接口实例（揭秘RESTEasy如何完美支持JAVA）(13)

在 JSON中检索所有苹果的数据：

javarest接口实例（揭秘RESTEasy如何完美支持JAVA）(14)

小结

在此我们已经探讨了 RESTEasy架构如何在 Java web服务中无缝支持 XML和 JSON数据传输格式。我还解释了 REST、Media type(数据传输格式)、web服务和微服务之间的技术差异，因为在这些术语中有很多容易混淆的灰色地带。

我这里列举的例子可能有点勉强，生活中我其实从来没有真正需要过水果相关的数据，我也没有在食品行业工作过。之所以用水果来举例，是因为我觉得这个“规模”能有助于大家理解微服务的概念，你也可以想象其他例如蔬菜，罐头或海鲜这样的微服务是如何共同构成一个食物分配系统。现实世界中，食品杂货店的食物分配系统实际上非常复杂，它必须考虑到包括销售、优惠券、过期日期、营养信息等各方面的问题。

当然，你可以选择其他方式去对系统进行分割，但当你需要一种快速高效、轻量级工具来支持多种数据格式时，RESTEasy真的是个非常不错的选择。

参考地址：

[1]、[2]、[6] https://tomcat.apache.org/

[3] https://en.wikipedia.org/wiki/KISS_principle

[4] https://github.com/lyndseypadget/resteasy-demo

[5] http://www.oracle.com/technetwork/java/javase/downloads/index.html

[7] https://maven.apache.org/

[8] https://www.eclipse.org/downloads/

[9] https://linuxmint.com/edition.php?id=237

[10] https://stackify.com/what-are-microservices/

[11] https://www.iana.org/assignments/media-types/media-types.xhtml

[12] http://resteasy.jboss.org/