5

语义版本控制规范中的第一点指出兼容软件必须声明公共 API。

我想知道 gems 是如何建立这个公共 API 的。似乎它通常是通过自述文件完成的（例如，参见ActiveRecord），感觉它并没有在公共 API 代码和其他代码之间划出严格的界限。一个做得更好的 gem 的例子是Twitter API，将它的公共 API 代码放在API 目录中，但即使在那里，这条线也是灰色的，因为公共 API 的配置方法是在API 目录之外的twitter.rb中定义的。

作为尝试坚持语义版本控制的 gem 的潜在贡献者（这是其中的大多数，因为我们有像 bundler 这样的工具），我想知道哪些方法是公共 API 的一部分，哪些不是。也许我必须查看更多源代码，但是否有明确定义公共 API 的指南？

4

1 回答 1

5

有一些流行的方法来定义公共 API。你选择哪一个主要是一个品味问题。

一种方法是文档。您只需在文档中说明哪些协议是公共 API 的一部分，以及这些协议的合同是什么。YARD 甚至为此提供了预定义的标签。

另一种方法是测试。我认为 Merb 做到了这一点。公共 API 在其 RSpec 测试中进行了描述。私密部分显然也经过了测试，但这些测试位于不同的目录中。

这实际上很酷，因为它允许您将代码更改和语义版本更改联系在一起：每次向公共目录添加测试时，您都需要修改次要版本。每次您在公共目录中删除或修改测试时，您都需要升级主要版本。

或者反过来：在小修订期间，您不得更改或删除测试。

于 2013-04-16T13:46:58.887 回答