在微服务的动态世界中，任何事情都可能发生变化——任何组件都可以使用不同的语言、使用不同的框架和架构进行重写。 只有契约应该保持不变，以便微服务可以在某种永久的基础上与外部交互，而不管内部发生变化。 今天我们将讨论选择描述合约的格式的问题并分享我们发现的工件。
后期准备 и
微服务。 在开发 Acronis Cyber Cloud 时，我们意识到我们无法逃脱它们。 如果没有形式化契约（代表微服务的接口），设计微服务是不可能的。
但是，当产品包含多个组件，并且合同开发成为一项常规活动时，您就会情不自禁地开始考虑流程优化。 很明显，接口（契约）和实现（微服务）必须相互匹配，不同的组件必须以相同的方式做相同的事情，如果没有对所有这些决策进行集中决策，每个团队将被迫花时间一次又一次地得到它们。
亚马逊微服务图来自 Werner Vogelis，亚马逊首席技术官
困境是什么？ 事实上，微服务交互有两种方式——HTTP Rest 和 Google 的 gRPC。 不想陷入 Google 的技术堆栈，我们选择了 HTTP Rest。 HTTP REST 契约注释最常采用两种格式之一进行描述：RAML 和 OAS（以前称为 Swagger），因此每个开发团队都面临着选择其中一种标准的需要。 但事实证明，做出这样的选择可能非常困难。
为什么需要注释？
需要注释，以便外部用户可以轻松地了解可以通过其 HTTP 接口对您的服务执行哪些操作。 也就是说，在基本级别上，注释必须至少包含可用资源的列表、它们的 HTTP 方法、请求正文、参数列表、所需和支持的标头的指示以及返回代码和响应格式。 合约注释的一个极其重要的元素是它们的口头描述（“如果将这个查询参数添加到请求中会发生什么？”，“什么情况下会返回代码 400？”）
然而，当涉及到开发大量微服务时，您希望从书面注释中提取额外的价值。 例如，基于 RAML/Swagger，您可以用大量编程语言生成客户端和服务器代码。 您还可以自动接收微服务的文档并将其上传到您的开发人员门户:)。
结构化合同描述示例
根据合同描述测试微服务的做法不太常见。 如果您已经编写了注释和组件，那么您可以创建一个自动测试来检查服务与各种类型的输入数据的充分性。 服务是否返回注释中未描述的响应代码？ 它能够正确处理明显不正确的数据吗？
此外，不仅合约本身的高质量实现，而且可视化注释的工具也使得简化微服务的工作成为可能。 也就是说，如果架构师定性地描述了契约，那么基于它，设计者和开发者将在其他产品中实现该服务，而无需额外的时间成本。
为了启用其他工具，RAML 和 OAS 都能够添加标准未提供的元数据（).
一般来说，使用微服务合约的创造力范围是巨大的……至少在理论上是这样。
刺猬与蛇的比较
目前，Acronis 的优先开发领域是 Acronis Cyber Platform 的开发。 Acronis Cyber Platform 是第三方服务与 Acronis Cyber Cloud 和代理部分的新集成点。 尽管我们对 RAML 中描述的内部 API 感到满意，但发布 API 的需要再次引发了选择问题：哪种注释标准最适合我们的工作？
最初，似乎有两种解决方案 - 最常见的开发是 RAML 和 Swagger（或 OAS）。 但事实证明，至少不是有2种选择，而是3种或更多。
一方面是 RAML——一种强大而高效的语言。 它很好地实现了层次结构和继承，因此这种格式更适合需要大量描述的大公司——也就是说，不是一个产品，而是许多具有契约公共部分的微服务——身份验证方案、相同的数据类型、错误体。
但RAML的开发商Mulesoft已经加入了Open API联盟，该联盟正在开发 。 因此，RAML暂停了其开发。 想象一下活动的形式，想象一下主要 Linux 组件的维护者离开去微软工作。 这种情况为使用 Swagger 创造了先决条件，Swagger 正在动态开发，并且在最新的第三个版本中，在灵活性和功能方面几乎赶上了 RAML。
如果不是因为一件事而是...
事实证明，并非所有开源实用程序都已更新到 OAS 3.0。 对于Go中的微服务来说，最关键的是缺乏适配性 获取该标准的最新版本。 然而，Swagger 2 和 Swagger 3 之间的区别是 。 例如，在第三个版本中，开发人员：
- 改进的认证方案描述
- JSON 模式支持
- 升级了添加示例的能力
情况很有趣：在选择标准时，您需要将 RAML、Swagger 2 和 Swagger 3 作为单独的替代方案来考虑。 然而，只有 Swagger 2 对开源工具有很好的支持。 RAML 非常灵活......而且复杂，而 Swagger 3 缺乏社区支持，因此您必须使用专有工具或商业解决方案，而这些工具或商业解决方案往往非常昂贵。
而且，如果Swagger中有很多不错的功能，比如现成的门户 ，您可以在其上上传注释并通过详细描述、链接和连接获得其可视化，那么对于更基础且不太友好的 RAML 则没有这样的机会。 是的，您可以在 GitHub 上的项目中搜索某些内容，在那里找到类似的内容并自行部署。 然而，无论如何，都必须有人维护门户，这对于基本使用或测试需求来说不太方便。 此外，swagger 更“无原则”，或者说更自由——它可以从代码中的注释生成，这当然违背了 API 优先原则，并且不受任何 RAML 实用程序的支持。
有一次我们开始使用 RAML 作为一种更灵活的语言，因此我们必须自己做很多事情。 例如，其中一个项目使用实用程序 在单元测试中，仅支持 RAML 0.8。 因此我们必须添加拐杖，以便该实用程序可以“吃掉”RAML 1.0 版本。
需要选择吗？
在致力于完成 RAML 解决方案的生态系统之后，我们得出的结论是，我们需要将 RAML 转换为 Swagger 2，并在其中进行所有自动化、验证、测试和后续优化。 这是利用 RAML 的灵活性和 Swagger 的社区工具支持的好方法。
为了解决这个问题，有两个开源工具应该提供合约转换：
- 是当前不受支持的实用程序。 在使用它时，我们发现它存在许多与“分布”在大量文件上的复杂 RAML 相关的问题。 该程序用 JavaScript 编写，并执行语法树的递归遍历。 由于动态类型，理解这段代码变得很困难，因此我们决定不浪费时间为垂死的实用程序编写补丁。
- - 来自同一家公司的一款工具，声称可以在任何方向上转换任何东西。 迄今为止，已宣布支持 RAML 0.8、RAML 1.0 和 Swagger 2.0。 然而，在我们研究时，效用仍然是 潮湿且无法使用。 开发人员创建了一种 ，使他们能够在未来快速添加新标准。 但到目前为止还行不通。
而这还不是我们遇到的全部困难。 我们管道中的步骤之一是验证存储库中的 RAML 相对于规范是否正确。 我们尝试了几种实用程序。 令人惊讶的是，他们都在不同的地方、用完全不同的脏话咒骂我们的注释。 而且并不总是切中要点:)。
最后，我们选择了一个现已过时的项目，该项目也存在许多问题（有时它会突然崩溃，在使用正则表达式时出现问题）。 因此，我们没有找到一种方法来解决基于免费工具的验证和转换问题，并决定使用商业实用程序。 未来，随着开源工具变得更加成熟，这个问题可能会变得更容易解决。 与此同时，“完成”的劳动力和时间成本对我们来说似乎比商业服务的成本更重要。
结论
毕竟，我们想分享我们的经验，并指出，在选择描述合同的工具之前，您需要明确定义您想从中获得什么以及您愿意投入多少预算。 如果我们忘记开源，已经有大量的服务和产品可以帮助您检查、转换和验证。 但它们很昂贵，有时甚至非常昂贵。 对于大公司来说，这样的成本是可以忍受的，但对于初创公司来说，它们可能会成为一个很大的负担。
确定您稍后将使用的工具集。 例如，如果您只需要显示合同，那么使用 Swagger 2 会更容易，它具有漂亮的 API，因为在 RAML 中您必须自己构建和维护服务。
你的任务越多，对工具的需求就越广泛，而且不同平台的工具也不同，最好立即熟悉可用的版本，以便做出将来成本最小化的选择。
但值得注意的是，当今存在的所有生态系统都是不完美的。 因此，如果公司里有粉丝喜欢在RAML工作，因为“它可以让你更灵活地表达想法”，或者相反，更喜欢Swagger，因为“它更清晰”，那么最好让他们继续工作他们已经习惯了并且想要它，因为任何格式的工具都需要使用文件进行修改。
至于我们的经验，在接下来的文章中，我们将讨论我们基于 RAML-Swagger 架构进行哪些静态和动态检查，以及我们从合约生成哪些文档，以及它们是如何工作的。
只有注册用户才能参与调查。 拜托
您使用什么语言来注释微服务契约？
-
随机存取存储器0.8
-
随机存取存储器1.0
-
招摇 2
-
OAS3（又名）
-
蓝图
-
其他
-
不使用
100 位用户投票。 24 名用户弃权。
来源： habr.com