在上一篇
文章中，我们讨论了在Ancronis进行微服务注释的方式和原因，并承诺分享我们在整个Acronis Cyber Platform使用单一API格式的做法。 今天，我们将介绍我们在静态注释检查方面的经验，这又是在公司中引入注释的第一步。
因此，假设您已经具有所有或大多数API的注释。 我们的同事也问我们一个合理的问题：“这些神奇的物体能做什么？”
实际上，可以通过注释直接进行两种类型的检查。 静态检查直接进入Swagger或RAML注释的文本。 他们不需要任何其他东西，可以合理地认为使用正式的微服务合同是他们的第一个优势。
仅当您有可用的服务时才能启动动态检查。 它们有些复杂，因为它们使您可以更深入地研究并检查注释的有效性，测试服务的稳定性，并执行更多操作。 但这是下一篇文章的主题，今天我们将集中讨论静态。
API准则万岁！
为了不让您自己或其他人感到困惑，值得一提的是，创建静态注释检查来控制API注释（以及希望的API本身）与公司要求的一致性。 它既可以是公司采用的惯例，也可以是成熟的Guideline API，它可以正式化为服务准备API的规则。
当我们谈论微服务的多彩世界时，这一点非常重要，因为每个团队可以拥有自己的框架，自己的编程语言，唯一的堆栈或某些特殊的库。 在微服务特定实践的影响下，面向外部观察者的API的显示方式正在发生变化。 这产生了不必要的变化。 为了使生态系统（或平台）的元素有效交互，有必要尽可能“对齐” API。
这是一个示例：仅当资源不存在时，404代码才返回到一个组件的API。 另一个团队将此错误绑定到应用程序逻辑，并且当用户想要购买已在仓库中结束的产品时，API将返回404。
阿特盖耶夫 在这里非常清楚地描述了这些问题。 对404代码的理解上的这种不一致会减慢开发速度并导致错误，这意味着不必要的支持支持或额外的调试时间，但无论如何，都是以金钱来衡量的问题。
公司采用的语法和命名的细节由REST本身的各个方面补充。 开发人员必须回答以下问题：
- POST是否具有幂等性？
- 我们使用什么错误代码，这意味着什么？
- 我可以在错误代码中添加业务逻辑吗？
现在想象每个团队应该对这些答案分别感到困惑。
搜索查询的格式也可以完全不同。 例如，大约有十二种创建示例的方法，其中仅列出具有MacBookPro和频繁病毒攻击的用户。 在处理由数十个微服务组成的大型项目时，搜索查询的语法对于公司的所有版本和产品都是必需的。 而且，如果一个人习惯于指代您开发的产品/服务之一，那么他希望在另一个产品/服务中找到相同的请求和响应结构。 否则，将无法避免惊奇（和悲伤）。
许多公司，尤其是巨头公司，例如
Microsoft ，
PayPal ，
Google ，都有自己的准则，并且经过深思熟虑。 但是，并非总是可以使用其他人的指南，因为它们很大程度上与公司的具体情况有关。 此外，每个人的思维都有不同的结构，规则可能会有所不同，这仅仅是因为人们以这种方式工作比其他方式更方便。
对Acronis需要自己的API指南的了解并不是很快，但是随着开发人员，微服务以及实际上外部客户端和集成的数量不断增加。 在某个时候，架构师团队必须建立统一的规则来声明API，同时要考虑到上述IT巨头的经验以及开发团队已经建立的事实上的实践。
指南API的这种较晚实现的问题之一是现有的已发布API不符合要求，这反过来又导致重新设计接口和保持向后兼容性的额外费用。 因此，如果您的业务模型涉及将来API的集成和发布，那么您需要尽早考虑统一的规则。
当然，准则API的采用并不会自动使所有API都具有构成作用。 每个API必须进行分析，每个开发人员都必须了解新的要求。 因此，我们根据开发的Guideline API进行了RAML自动化检查。
静态分析
首先，您需要确定我们将进行静态分析的内容。 并非所有Guideline API点都可以形式化，因此首先需要突出显示一组规则，这些规则可以从API批注中轻松理解。
在第一个版本中，我们确定了以下规则：
- 检查API说明。 正如我们在上一篇文章中所说的，您可以基于API注释创建漂亮的文档。 这意味着每个资源，查询参数和响应均应具有描述，以将所有必要的信息提供给我们API的任何用户。 这看起来有些琐碎，但是向开发人员显示其注释不包含丰富的描述是多么容易！
- 检查示例的存在和正确性。 API注释语言还允许您描述示例。 例如，作为响应，我们可以添加一个真实服务响应的示例，该示例来自现实生活。 使用示例说明了端点的用法和工作方式，我们通过对批注的静态分析来检查示例。
- 验证HTTP响应代码。 HTTP标准定义了大量代码，但是可以用不同的方式解释它们。 我们的指南规范了代码的使用。 我们还会根据HTTP方法限制不同代码的适用性。 例如，当创建资源时，根据HTTP规范返回代码201。 因此，GET返回201将是一个唤醒调用（代码使用不正确，或者GET创建资源）。 因此，我们的Guideline API禁止此类使用。 此外，架构师对每种方法都有固定的代码集，现在，我们在注释级别以静态模式检查它们。
- 检查HTTP方法。 每个人都知道HTTP协议具有一组标准方法（GET，POST，PUT等），并且还可以使用自定义方法。 我们的Guideline API描述了允许但不允许的（OPTIONS）以及完全禁止的允许方法（只能在建筑师的祝福下使用）。 禁止使用标准的HEAD方法以及任何自定义方法。 所有这些也很容易在合同的注释中进行验证。
- 验证访问权限。 我们希望在2019年不需要授权支持就不需要其他解释。 好的文档应包含有关API支持的角色以及每个角色可用的API方法的信息。 除了记录在注释级别记录的有关角色模型的信息外，还可以使您在动力学方面做更多有趣的事情，但是，我们将在下一篇文章中进行讨论。
- 验证命名。 减轻了使用不同方法命名实体的麻烦。 通常，有两个“阵营”：CamelCase和snake_case的支持者。Camelcase（每个单词以大写字母开头）和snake_case（单词由下划线分隔并且所有内容均以小写字母表示）。 通常使用不同的语言来命名。 例如，Python接受snake_case，而Go或Java采用CamelCase。 我们针对所有项目做出了通用选择，并在API指南中进行了修复。 因此，通过注释，我们可以静态检查资源和参数的名称；
- 验证自定义标题。 这是命名检查的另一个示例，但它专门与正面相关。 在Acronis中，习惯上使用X-Custom-Header-Name形式的格式（尽管已弃用该格式）。 并且我们在注释级别控制其合规性。
- 验证HTTPS支持。 任何现代服务都应支持HTTPS，有些人认为，如今使用HTTP通常是个坏消息。 因此，应该指出RAML或Swagger注释。 微服务支持不带HTTP的HTTPS。
- 验证URI的结构。 在史前时期，即，在Guideline API发行之前，请求URI在不同的服务中看起来有所不同：某处/ api / 2，某处/ api / service_name / v2，依此类推。 现在，在我们的指南中，为我们所有的API定义了标准的URI结构。 该手册描述了它们的外观，以免造成混淆。
- 检查新版本的兼容性。 任何API作者都应记住的另一个因素是向后兼容性。 重要的是要检查基于旧API构建的代码是否可以与新版本一起使用。 基于此更改，可以分为两类：打破向后兼容性和兼容。 每个人都知道无法接受重大更改，并且如果您想大幅“改进”某些东西，开发人员应该发布新版本的API，但是每个人都可能会犯错误，因此我们在静态检查阶段的另一个目标是仅跳过兼容的更改，并对不兼容的更改发誓。 假定注释（如代码）存储在存储库中，因此具有完整的更改历史记录。 因此，我们可以检查HTTP REST的向后兼容性。 例如，添加（方法，参数，响应代码）兼容性不会违反，并且删除可能会导致兼容性下降。 并且可以在注释级别进行检查。
没有说明时
有说明时
结论
为了检查（不，不是服务质量），而是API的质量，需要对批注进行静态分析。 在此阶段，您可以使程序界面彼此对齐，以便人们在清晰易懂的环境中工作，在此环境中一切都是可以预料的。
当然，只有在“手动”检查所有信件很长，昂贵且不可靠的情况下，才有必要在足够大的公司中采取这种形式主义。 一家小型创业公司就不需要它。 至少暂时是这样。 但是，如果将来有像Akronis这样的计划成为独角兽，那么静态检查和Guideline API将为您提供帮助。