揭秘：RESTEasy如何完美支持JAVA 微服务中的多种数据格式

yuanyi928

发布于 2018-07-26 10:16:37

1.4K0

发布于 2018-07-26 10:16:37

文章被收录于专栏：EAWorldEAWorld

本文获得stackify.com授权翻译发表，转载需要注明来自公众号EAWorld。

作者：Lyndsey Padget

译者：月满西楼

原题：Multiple Media Types in Java Microservices with RESTEasy

全文13000字，阅读约需要28分钟

今天我们来聊聊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服务也并不都是微服务！

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)。

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.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;
import com.lyndseypadget.resteasy.model.Apple;
import com.lyndseypadget.resteasy.model.FruitComparator;
@Path("/fruits")
public class FruitService {
private static Map<String, Apple> apples = new TreeMap<String, Apple>();
private static Comparator comparator = new FruitComparator();
@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;
}
}

这张苹果的地图帮助我们根据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 == null) {
        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真的是个非常不错的选择。

原文链接：https://stackify.com/multiple-media-types-java-microservices-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/

[13] https://jcp.org/aboutJava/communityprocess/final/jsr339/index.html

[14] http://www.oracle.com/technetwork/articles/javase/index-140168.html

[15] https://github.com/jettison-json/jettison

[16] http://resteasy.jboss.org/downloads

[17] https://tomcat.apache.org/tomcat-9.0-doc/appdev/deployment.html

[18] https://www.ietf.org/rfc/rfc2616.txt

[19] https://www.getpostman.com/

关于作者：Lyndsey是堪萨斯城（Kansas City, MO.）一位著名的软件工程师和演说家，尽管她过去一直活跃于JAVA领域，但她目前正专注于node js+ES6方面的工作。她长期供职于一些大型企业和创业公司，积累了十多年丰富的软件和web开发方面的实战经验，擅长设计可维护和直观的RESTful API网络接口。她的演讲和博客都是关于微服务方面的内容，Git概念和工作流，以及各种各样的软件技能。Lyndsey积极参与当地的相关组织，鼓励各年龄段的女性在数学和科学领域积极探讨职业问题。想了解关于她的更多相关信息，欢迎访问lyndseypadget.com。

本文参与腾讯云自媒体分享计划，分享自微信公众号。

原始发表：2018-03-26，如有侵权请联系 cloudcommunity@tencent.com 删除

java