如何使用 Errai 将 GWT 与 JAX-RS/RESTEasy 服务器集成？

我想从 GWT 客户端应用程序调用使用 RESTEasy 和 JAX-RS 创建的 REST 服务。使用 Errai 为服务器和客户端使用单一代码库的最佳流程是什么？

我们都喜欢休息。它与供应商、平台和语言无关；调试、实施和访问都很简单；它为您的云、浏览器、移动和桌面应用程序提供了可靠的后端。

Java 开发人员可以使用支持的库JAX-RS http://docs.oracle.com/javaee/6/tutorial/doc/giepu.html, like RESTEasy http://www.jboss.org/resteasy，只需几分钟即可启动并运行 REST 服务器。然后，使用 JAX-RS 客户端 http://docs.jboss.org/resteasy/docs/2.3.4.Final/userguide/html_single/#RESTEasy_Client_Framework，只需几行代码即可从 Java 客户端应用程序调用这些 JAX-RS REST 服务器。

尽管 GWT 与 Java 有很多共同点，但从 GWT 调用 REST 服务可能是一种痛苦的经历。使用请求生成器 https://developers.google.com/web-toolkit/doc/1.6/DevGuideServerCommunication#DevGuideHttpRequests类涉及指定正确的 HTTP 方法、对 URL 进行编码，然后解码响应或创建Overlay http://code.google.com/p/google-web-toolkit/wiki/OverlayTypes对象来表示 REST 服务器发回的数据。对于调用一两个 REST 方法来说，这可能不是一个很大的开销，但在将 GWT 与更复杂的 REST 服务集成时，它确实意味着大量的工作。

这是哪里Errai http://www.jboss.org/errai.htmlErrai 是一个 JBoss 项目，除其他外，在 GWT 中实现 JAX-RS 标准 http://docs.jboss.org/errai/2.0.CR2/errai/reference/html_single/#sid-19398997。理论上，这意味着您可以在 Java 和 GWT 项目之间共享 JAX-RS 接口，从而提供定义 REST 服务器功能的单一源。

从 Errai 调用 REST 服务器仅涉及几个简单的步骤。首先，您需要 REST JAX-RS 接口。这是一个带有 JAX-RS 注释的 Java 接口，它定义了 REST 服务器将提供的方法。该接口可以在 Java 和 GWT 项目之间共享。

@Path("customers")
public interface CustomerService {
  @GET
  @Produces("application/json")
  public List<Customer> listAllCustomers();

  @POST
  @Consumes("application/json")
  @Produces("text/plain")

  public long createCustomer(Customer customer);
}

然后将 REST 接口注入到您的 GWT 客户端类中。

@Inject
private Caller<CustomerService> customerService;

定义了响应处理程序。

RemoteCallback<Long> callback = new RemoteCallback<Long>() {
  public void callback(Long id) {
    Window.alert("Customer created with ID: " + id);
  }
};

最后调用 REST 方法。

customerService.call(callback).listAllCustomers();

很简单吧？

您可能会从此示例中相信 Errai 将为您当前的 JAX-RS 基础设施提供一个简单的解决方案，但不幸的是，这个简单的示例并没有涉及您在尝试结合您的系统时可能会遇到的一些复杂情况。 GWT 和 Java REST 代码库。以下是使用 Errai 和 JAX-RS 时需要注意的一些问题。

您需要实施 CORS

通常，在实现 GWT JAX-RS 客户端时，您将针对外部 REST 服务器调试 GWT 应用程序。除非你实现，否则这不会起作用CORS http://hacks.mozilla.org/2009/07/cross-site-xmlhttprequest-with-cors/，因为默认情况下托管 GWT 应用程序的浏览器不允许您的 JavaScript 代码联系不在同一域中运行的服务器。事实上，您甚至可以在本地开发 PC 上运行 REST 服务器，但仍然会遇到这些跨域问题，因为不同端口之间的调用也受到限制。

如果您使用 RESTEasy，可以通过两种方法实现 CORS。第一个是使用消息体拦截器 http://docs.jboss.org/resteasy/docs/2.3.4.Final/userguide/html_single/#MessageBodyInterceptors界面。您提供 write() 方法，并使用 @Provider 和 @ServerInterceptor 注释来注释您的类。然后使用 write() 方法将“Access-Control-Allow-Origin”标头添加到对任何简单请求的响应中（“简单”请求不设置自定义标头，并且请求正文仅使用纯文本）。

第二种方法处理 CORS 预检请求（对于可能对用户数据产生副作用的 HTTP 请求方法 - 特别是对于除 GET 之外的 HTTP 方法，或者对于某些 MIME 类型的 POST 使用）。这些请求使用 HTTP OPTIONS 方法，并期望在回复中收到“Access-Control-Allow-Origin”、“Access-Control-Allow-Methods”和“Access-Control-Allow-Headers”标头。下面的handleCORSRequest() 方法对此进行了演示。

Note

下面的 REST 接口允许任何和所有 CORS 请求，从安全角度来看这可能不合适。然而，假设在此级别阻止或限制 CORS 将提供任何程度的安全性是不明智的，因为设置代理 http://developer.yahoo.com/javascript/howto-proxy.html代表客户提出这些请求是非常简单的。

@Path("/1")
@Provider
@ServerInterceptor
public class RESTv1 implements RESTInterfaceV1, MessageBodyWriterInterceptor
{
    @Override
    public void write(final MessageBodyWriterContext context) throws IOException, WebApplicationException
    {   context.getHeaders().add(RESTInterfaceV1.ACCESS_CONTROL_ALLOW_ORIGIN_HEADER, "*");
        context.proceed();      
    }

    @OPTIONS
    @Path("/{path:.*}")
    public Response handleCORSRequest(@HeaderParam(RESTInterfaceV1.ACCESS_CONTROL_REQUEST_METHOD) final String requestMethod, @HeaderParam(RESTInterfaceV1.ACCESS_CONTROL_REQUEST_HEADERS) final String requestHeaders)
    {
        final ResponseBuilder retValue = Response.ok();

        if (requestHeaders != null)
            retValue.header(RESTInterfaceV1.ACCESS_CONTROL_ALLOW_HEADERS, requestHeaders);

        if (requestMethod != null)
            retValue.header(RESTInterfaceV1.ACCESS_CONTROL_ALLOW_METHODS, requestMethod);

        retValue.header(RESTInterfaceV1.ACCESS_CONTROL_ALLOW_ORIGIN_HEADER, "*");

        return retValue.build();
    }

}

有了这两种方法，对 REST 服务器的任何调用都将提供适当的响应以允许跨源请求。

您需要接受并使用简单的 POJO 进行响应

简介说明了一个使用 Long 响应的简单 REST 接口。 JAX-RS 的 Java 和 GWT 实现都知道如何序列化和反序列化基元和简单类（例如 java.util 集合）。

在现实世界的示例中，您的 REST 接口将使用更复杂的对象进行响应。这是不同的实现可能发生冲突的地方。

首先，JAX-RS 和 Errai 使用不同的注释来自定义 JSON 和 Java 对象之间的对象编组。 Errai 有 @MapsTo 和 @Portable 等注释，而 RESTEasy（或 Jackson，JSON 编组器 http://docs.jboss.org/resteasy/docs/2.0.0.GA/userguide/html_single/index.html#json）使用 @JsonIgnore 和 @JsonSerialize 等注释。这些注释是相互排斥的：GWT 会抱怨 Jackson 注释，而 Jackson 不能使用 Errai 注释。

简单的解决方案是在其余接口中使用一组简单的 POJO。简单地说，我的意思是具有无参数构造函数的类，并且仅具有与 JSON 对象通过网络传输时出现在其中的属性直接相关的 getter 和 setter 方法。简单的 POJO 可以由 Errai 和 Jackson 使用默认设置进行编组，从而无需处理不兼容的注释。

Errai 和 Jackson 还从不同的地方获取 JSON 字符串中生成的属性的名称。 Jackson 将使用 getter 和 setter 方法的名称，而 Errai 将使用实例变量的名称。因此，请确保您的实例变量和 getter/setter 方法名称完全相同。还行吧：

public class Test
{
    private int count;
    public int getCount() {return count;}
    public void setCount(int count) {this.count = count;}
}

这会导致问题：

public class Test
{
    private int myCount;
    public int getCount() {return myCount;}
    public void setCount(int count) {this.myCount = count;}
}

其次，人们很容易向这些 REST 数据对象添加额外的方法来实现某些业务功能。然而，如果您这样做，不久之后您就会尝试使用 GWT 不支持的类，并且您可能会惊讶地发现：GWT 不支持 https://developers.google.com/web-toolkit/doc/latest/DevGuideCodingBasicsCompatibility：日期格式化、克隆数组、将字符串转换为字节[]...这样的例子不胜枚举。因此，最好坚持 REST 数据对象的基础知识，并使用组合或基于组件的设计等完全在 REST 数据对象继承树之外实现任何业务逻辑。

Note

如果没有 @Portable 注释，您将需要在 ErraiApp.properties 文件中调用 REST 接口时手动列出 Errai 所使用的所有类 http://docs.jboss.org/errai/2.0.CR2/errai/reference/html_single/#sid-5931328_Marshalling-AliasedMappingsofExistingInterfaceContracts.

Note

您还需要远离地图。看this bug https://issues.jboss.org/browse/ERRAI-295了解详情。

Note

您不能在 JSON 服务器返回的对象层次结构中使用嵌套参数化类型。看this bug https://issues.jboss.org/browse/ERRAI-319 and 这个论坛帖子 https://community.jboss.org/thread/200995了解详情。

Note

Errai 对 byte[] 有问题。请改用列表。看这个论坛帖子 https://community.jboss.org/message/742912更多细节。

您需要使用 Firefox 进行调试

当使用 GWT 通过 REST 接口发送大量数据时，您必须使用 Firefox 调试应用程序。根据我自己的经验，将一个小文件编码为 byte[] 并通过网络发送它会导致 Chrome 中出现各种错误。当 JSON 编码器尝试处理损坏的数据时，会抛出各种不同的异常；在 GWT 应用程序的编译版本中或在 Firefox 上调试时未看到的异常。

不幸的是，Google 未能使其 Firefox GWT 插件与 Mozilla 的新发布周期保持同步，但您经常可以在 GWT Google Groups 论坛中找到 Alan Leung 发布的非官方版本。这个链接 https://groups.google.com/forum/#!starred/google-web-toolkit/7OR5LM1POzI有一个适用于 Firefox 12 的 GWT 插件版本，并且这个链接 https://groups.google.com/forum/?fromgroups#!topic/google-web-toolkit/EoTbKTvJRyk有适用于 Firefox 13 的版本。

您需要使用 Errai 2.1 或更高版本

只有 Errai 2.1 或更高版本才会生成与 Jackson 兼容的 JSON https://issues.jboss.org/browse/ERRAI-295，如果您尝试将 GWT 与 RESTEasy 集成，这是必须的。杰克逊编组可以使用启用

RestClient.setJacksonMarshallingActive(true);

or

<script type="text/javascript">
  erraiJaxRsJacksonMarshallingActive = true;
</script>

您需要为高级功能创建单独的 JAX-RS 接口

如果您的 JAX-RS REST 接口返回高级对象，例如ATOM http://docs.jboss.org/resteasy/docs/2.0.0.GA/userguide/html_single/index.html#Atom（或者更重要的是，导入像 org.jboss.resteasy.plugins.providers.atom.Feed 这样的类），您需要将 REST 接口拆分为两个 Java 接口，因为 Errai 不知道这些对象，并且这些类可能不处于可以轻松导入到 GWT 中的状态。

一个接口可以保存普通的旧式 JSON 和 XML 方法，而另一个接口可以保存 ATOM 方法。这样您就可以避免在 GWT 应用程序中引用未知类的接口。

Note

Errai 目前仅支持 JSON 编组 http://docs.jboss.org/errai/2.0.0.Final/errai/reference/html_single/#sid-9470133，尽管将来您可能能够定义自定义编组器。