Java的REST模型版本控制好工具

Question

I am looking for tools that can support changing the version of the model used in REST services. Ideally, these tools would transform my pojo and configuration files to create a service available with the desired version of my model. Although I do not need to perform reverse transformations in my particular case, I am open to using a tool that does both. One solution I am considering is adding custom annotations (version + name) to my pojo and generating JSON/XML based on the version number. However, this approach feels like reinventing the wheel. For example, a change from version 1 to version 1.1 could involve adding a "birthdate" field to the "Person" object.

如果您使用版本1.0访问API，则不会获得出生日期属性 - 它仅在版本1.1中可用。我希望有工具支持使这些服务可用，我可以配置假设我的pojo（目前类似于1.1版本），我想提供一个1.0版本，它不显示这些值。

对模型的其他法律更改可能是删除属性或重命名属性（甚至重命名实体）。

编辑2： Digital Joel在评论中提到，关于API版本控制的讨论，您应该阅读https://stackoverflow.com/posts/9789756/。

版本控制的简单方法当然是不进行向后兼容的API更改，但业务变化并非总是可能的。 我关注的是如何使这些更改更易处理，因此提出了这个问题。

编辑3： 我已经寻找可以帮助这个过程的工具，但还没有与rest良好连接的东西。 这是我迄今为止找到的链接：

• http://wiki.pmease.com/display/xmt/What%27s+XMT （看起来像是一个库，用于帮助序列化pojos到具有版本控制的xml中）

- Knubo

Answer 1

如一条答案所述，可能没有自动进行API版本控制的工具可用。

我们可以采用以下两步方法解决这个挑战：

1）API版本信息 有很多关于最佳实践的争论。 最流行的两种是：

(i) URI redesign - putting version info in URI like
http://something.com/v1.0/resource1/ or
http://something.com/resource1?ver=1.0

(ii) Using HTTP Header - putting version info in Accept/Content-Type
header keeping URI intact like 
#
GET /something/ HTTP/1.1 
Accept: application/resource1-v1.0+json

2) 使用json/xml库维护同一pojo的多个版本

一旦我们拥有版本信息，我们就可以相应地生成资源。 有许多json和xml库，我们可以使用这些库来维护同一pojo的多个版本，并根据版本仅序列化所需的属性。 Google gson java库在这方面表现出色。请查看 https://sites.google.com/site/gson/gson-user-guide#TOC-Versioning-Support

public class Person{

@Since(1.0)
private String firstname;

@Since(1.0)
private String lastname;

@Since(1.1)
private String birthdate;

}

- shashankaholic

---

非常好的回应。Gson库看起来很匹配。 - Knubo

太好了！我不知道gson有版本支持。你值得获得奖励。 - digitaljoel

当时间耗尽且没有人能够超越他的答案时，我一定会支付赏金的 :-) - Knubo

是的，我的意思是他的回答比我的更好，所以我投了他的票，这样他比我得到更多的票，即使你没有授予奖励，他也会得到它。 - digitaljoel

同样，我想自己尝试一下。我能想到的唯一另一个解决方案是使用ESB来拦截和转换请求。 - aliasmrchips

Answer 2

我不知道有没有自动版本控制RESTful API的工具。如果你想要了解关于RESTful API版本控制的最佳实践，可以阅读Best practices for API versioning?。

当我在规划RESTful API时，我花了很多时间研究这个问题，我们得出的结论是，我们会以一种不引入破坏性变化的方式进行演进。如果需要进行破坏性变化，那么我们会将其公开为一个新资源，而不是尝试在自定义标头或MIME类型中使用版本信息。但是，对于你的问题，这意味着需要我付出更多的努力，这更加激励我避免进行破坏性变化。

至于工具方面，我非常怀疑你能找到一款可以自动完成支持多个版本的RESTful API所需更改的工具。这将需要一款能够理解你的模型的两个版本之间的差异以及你的API中所有交互的工具。

如果您正在遵循REST的HATEOAS原则，那么给定位置的所有目标也都包含在响应中，这种情况下，您可以使用类似于Spring MVC中REST支持请求映射的方式，在所有URL中保留版本号，从客户端提供单个入口点，但您仍需要为每个版本维护控制器和模型。

- digitaljoel

---

谢谢提供参考 - 我会将其添加到我的问题中，因为重要的是让首先找到这个问题的人了解如何对API进行版本控制，然后再解决如何在代码中实现此操作的问题。 - Knubo

Answer 3

这可能不是你期望的答案，因为我不使用开源外部工具来代替我完成大量工作。我使用自己的工具。

我使用Jersey。我在@Path声明中包含/vx/。

由于REST API代表合同，我不相信自动创建。但是，我已经在一个不太复杂的Maven插件中做了一个XLST工具。我维护简洁的XML版本，并在gensrc中将其转换为Jersey类。

我发现v1具有特定的路径和矩阵/查询参数，该设计在当时是独特的。 当我开发v2时，我经常发现需要支持其他参数或重构我的URL以更好地理解。 我只需要更改xml文件。

我的生成引擎将创建MyAPIv1.java和MyAPIv2.java的Jersey层，并根据需要进行注释。

所以我想保留版本控制，并且自动/工具可能会有害。

再次强调，使用规范是完全控制但不完全实现薄层的好方法。

这里没有香烟，但这可能会有所帮助。

- Jaime Garza

Answer 4

只是一个想法，但是让你的API向后兼容不是更好吗？这样你只需要为你的代码仓库进行版本控制，而那会更加轻松。

- Tom

Answer 5

你是在谈论开发世界中的版本控制（为用户提供API版本控制）还是运行时内容协商？

如果是前者，可以看看像Maven、Ivy、Gradle这样的工具。我个人使用Maven，因为我最熟悉它，但它们都允许你发布带有版本的JAR文件，以达到此目的。

- Rick Mangi

---

我在谈论API的版本控制。 - Knubo

如果您想将版本打包成JAR文件以分发给用户进行构建，请查看Maven。 - Rick Mangi

关于我的问题 - 它与Maven无关 - 我正在寻找用于版本控制REST Web服务API的工具，而不是如何对构建系统使用的组件进行版本控制。 - Knubo

我猜你说的“版本化API”不是很清楚。API只是你作为服务开发者和想要使用你的服务的客户之间的契约。这就是为什么我问你是否指的是版本化你正在分发的jar文件，还是在服务器端进行版本控制，以便检测客户端是否正在请求API的1.0版或2.0版（内容协商）。 - Rick Mangi