php调用rest接口揭秘RESTEasy若何完善支撑JAVA 微办事中的多种数据格局

译者 |月满西楼

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

本日我们来聊聊 Java中的微做事。
虽说 Java EE供应了一个强大的平台，供我们创建、支配和管理企业级微做事，但在本文中，我将展示如何创建一个尽可能小的 RESTful微做事。

php调用rest接口揭秘RESTEasy若何完善支撑JAVA 微办事中的多种数据格局 GraphQL

放心，在这个过程中，我们不会摧残浪费蹂躏韶光精力去重复做些数据处理之类的事情。
我们会通过 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做事也并不都是微做事！

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一起构建项目也会带来部分通报性依赖。

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

项目设计

下面这个微做事可以用非常大略的方法来演示一些基本观点。
如下图所示，它包括 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:

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

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

不但是“读取”

你可能会创造，很多 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主体的苹果，如下图所示:

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

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

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

通过 id删除 apple 1的数据：

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

小结

在此我们已做生意量了 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/