为RESTful服务创建客户端

Question

在构建RESTful服务时，我总是遇到如何开发可以分发给系统用户的客户端库的问题。

举一个简单的例子，假设有一个实体调用者，并且您希望通过RESTFul服务支持基本的CRUD功能。

• 要保存一个人，客户端需要调用POST方法并传递 适当的数据结构，比如JSON。

• 要按生日查找人员，您的服务将回复包含人物对象列表的回复

• 要删除某个人，您的服务将成功回复或 失败的消息。

从上面的示例中，已经有两个可以与客户端共享的对象：person对象和响应对象。我尝试过几种方法来实现这个目标：

1. 在客户端库中包含服务器调用的Person对象。这种方法的缺点是：

   • 客户端代码与服务器代码紧密结合。任何 服务器端的更改将要求客户端在更新期间进行更新 相同的版本。

   • Person的对象可能包含用于的依赖项或注释 持久性或序列化。客户对此没有任何关注 图书馆，但被迫包括它们。

2. 包含一个Map子类，它与Person的对象没有直接关系，但包含一些帮助器类来设置必需的字段。

   • 松散耦合，但当服务器的数据结构发生变化时，可能会导致无提示错误。
3. 使用Apache Thrift，WADL或Json Schema等描述性文件在编译期间生成客户端对象。这解决了对象依赖的问题，但仍然创建了一个硬依赖。这几乎就像为SOAP创建WSDL一样。但是，这种方法并没有被广泛使用，有时很难找到例子。

为您的应用程序发布客户端jar的最佳方法是什么，以便

1. 方便客户使用
2. 不会为服务器端更改创建紧密耦合和一些容差

如果您回答的是更好的API文档，那么从Java注释和POJO生成这些文档的好工具是什么。

Answer 1

这是一个常见问题，无论用于通信的协议如何。

在我们最近一直在使用的一些REST API（基于JAX-RS）中，我们创建了DTO对象。这些只是愚蠢的POJO（有一些额外的注释，JAXB会自动为我们做一些编组/解组）。我们将它们构建为子模块（在maven中）并将它们作为JAR提供，以便使用我们的API的任何其他项目可以根据需要使用DTO。显然，如果您想提供自己的客户端库，它可以使用这些DTO。将它们作为单独的JAR（任何应用程序都可以依赖）提供意味着客户端不会引入他们不需要的疯狂依赖项（您的整个服务器端代码）。

这可以很好地解决问题。

另一方面，您确实不需要提供客户端。毕竟这是REST。如果您的REST API构造良好并遵循HATEOAS原则，则您的API应易于抓取/浏览，即您不需要任何其他描述性方案。如果您需要WADL或其他类似的结构，您的API可能不是非常RESTful。