2

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

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

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

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

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

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

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

    • 客户端代码与您的服务器代码紧密耦合。服务器端的任何更改都需要客户端在同一版本中进行更新。

    • Person 的对象可能包含用于持久化或序列化的依赖项或注释。客户不关心这个
      库，而是被迫包含它们。

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

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

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

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

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

4

1 回答 1

4

这是一个常见问题，与用于通信的协议无关。

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

这可以使事情很好地解耦。

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

于 2013-02-21T22:54:01.830 回答