java - 为 RESTful 服务创建客户端

Question

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

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

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

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

• 要删除一个人，您的服务将响应成功或失败信息。

从上面的示例中，已经有两个对象可以与客户端共享:person 对象和response 对象。我已经尝试了几种方法来实现这一点:

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

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

   • 人的对象可能包含用于持久化或序列化。客户对此毫不关心
     库，但被迫包含它们。

2. 包括 Map 的一个子类，它不直接与 Person 的对象紧密相关，但包含一些辅助类来设置所需的字段。

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

为您的应用程序发布客户端 jar 的最佳方式是什么

1. 客户易于使用
2. 不会产生紧密耦合和对服务器端更改的一些容忍度

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

Answer 1

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

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

这使事情很好地解耦。

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