微服务架构的日志记录_记录微服务的工具和实践

微服务架构的日志记录

我将假设您至少熟悉微服务的概念—松散耦合的服务为业务用例提供离散的解决方案，您可以将它们组合起来以解决当前的需求。 在过去的几年中，建筑模式越来越流行，尽管并不是每个人都完全确定“正确地做”的模样，但它是适合现代需求的概念，并且在可预见的未来将继续存在。

我帮助在柏林组织了Write Docs （对技术文档感兴趣的全球社区） 小组 。 在过去的一个月中，有很多人问我关于为记录使用该模式的微服务和应用程序体系结构推荐的工具和实践的建议。

稍后在Google搜索中发现一些问题，但我发现其他人也提出了同样的问题，但没有具体建议，因此认为是时候提出想法了。 我打算通过这篇文章提出问题，提出一些解决方案，并引起本领域的讨论。 这些只是我的主意，但是我们可以一起确定最佳实践，并为实际工具提供帮助。

定义问题

本质上，每个微服务都是一个“典型”应用程序。 在许多方面，您都可以遵循标准的最佳做法来对其进行记录（如果需要帮助，我建议您参阅“面向开发人员的文档速成课程 ” 一文 ）。 在我看来，开发人员所困的领域是可视化并记录微服务如何交互。

基于主题的文档

在我们进行前瞻性思考之前，我想带大家回到已有一段时间的文档实践，但至少在概念上可以在这里使用。 基于主题的文档将文档分解为离散的概念（主题），然后您可以将其组合起来以适合特定的文档用例。

例如，面向开发人员的入门指南可能将安装 ， 配置和运行主题结合在一起。 用户入门指南可能将配置 ， 运行和命令主题结合在一起。 如您所见，它结合了离散的内容项以适应不同的用例。 听起来有点熟？

请注意，用于基于主题的文档的传统工具可能并不完全适合此用例，因为它通常很昂贵，专有且本身就是整体的。 但是，我们当然可以借用该构想和工具的元素。

显示所有端点

在此Stack Overflow帖子中 ， 发布者询问如何显示所有服务中的所有端点，无论哪个服务是public ， active以及其中的哪个端点相同。 使用上述方法，我们可以创建一个页面，查询所有标记为active和public的服务 ，以及其中的所有端点都是相同的。 如果添加或删除服务或端点，则页面将更新以反映此情况。

显示端点的相交

一个更复杂的需求可能是显示服务如何在应用程序级别进行交互。 服务使用由参数连接的端点调用另一个服务。 或者换一种说法， 用户服务使用其用户ID来查询订单服务，以查找用户已下达的订单。

端点说明

很好，但到目前为止，该方法仅是演示端点功能。 关于这些如何在基于微服务的应用程序中组合在一起的概念解释又如何呢？ 同样，理想情况下，这些解释片段应借鉴我所提到的体系结构范例和基于主题的方法，并且可以在不同的上下文中使用。

与您的代码一样，您应该考虑将这些解释分解为离散的和可重用的组件。 例如，如果用户到达您的应用程序以查看订单状态，则这可能涉及多种服务： 认证 ， 用户记录 ， 订单清单和订单状态 。

到达检查帐户详细信息的用户可能涉及身份验证 ， 用户记录和帐户服务 。 因此，您应该将每个服务的概念性解释分开，可能在服务的存储库中。 实际上，这可能就是您已经在做的。

我建议您在“文档组装”服务中添加额外的文档摘要，其中包含有关每个潜在交叉点如何工作的详细信息。 例如，一个描述用户记录服务如何调用订单服务的文件，另一个描述用户记录服务如何调用帐户服务的文件。 在这样一个简单的示例中，在API文档中包含此说明可能就足够了，但是有时您可能还需要更多。

文档组装服务工具

如何处理各种信息源的组合取决于您。 就像在编码世界中一样，文档世界中有大量可用的工具，您可以决定最适合自己的工具。 为了适应微服务架构，该程序集应该是服务本身，并且您应该考虑可以在容器，无服务器实例或类似环境中愉快运行的工具。 幸运的是，文档生成和托管通常不是高影响力的服务，因此更易于维护。

当前的工具无法为您做任何事情，因此，我将提出一些难题，我认为您可以适应并做好工作，以及它们如何提供帮助。 我还将介绍一些用于不同标记语言的替代方法，但将在评论部分中为您提供进一步的调查研究，或者与我联系 。

由于大多数标记语言和API规范都是可解析的格式，因此，如果我没有提供任何帮助，那么精干的程序员也应该能够推出他们自己的自定义解决方案。

值得注意的是，有些商业服务或类似CMS的系统可以为您处理其中一些流程，但是我觉得这与微服务的思维背道而驰。

转换次数

要启用不同格式的文档组合以简化管理和呈现，您可能需要转换以创建统一格式。

• Pandoc –我最喜欢的工具之一。 在多种标记格式之间转换，但没有API规范格式。
• Swagger2Markup –将Swagger转换为AsciiDoc或Markdown。
• API Spec Converter –在Swagger（V1和2），Open API 3，API Blueprint，RAML，WADL等之间进行转换。
• apib2swagger –将API蓝图转换为Swagger。
• swagger2blueprint –将Swagger转换为API Blueprint。
• Apimatic变压器 （在线）–在包括邮递员在内的各种规格之间转换。
• apiary2postman –将API蓝图转换为Postman。
• Blueman –将API蓝图转换为Postman。
• apib2json –将API蓝图转换为JSON。

包容性

包含是一个术语，我用来表示将一个文档的内容包含在另一个文档中。 您可能称其为链接，包含，交叉引用或其他内容。 但是出于我们的目的，这将是我们如何将各种信息源（API参考和说明性文本链接）包含到一系列用于渲染的文件中。 默认情况下，许多标记语言会为您执行此操作，而其他标记语言则需要“鼓励”。

• 降价不包括在默认情况下的其他文件，但你有选择赫卡尔 ， MultiMarkdown或者，作为你的渲染管线，静态网站生成器的一部分等化身 。
• Asciidoctor是广泛使用的工具链，可用于Asciidoc无缝地处理其他来源。
• 默认情况下，reStructuredText可以包含外部文件 。
• 如果您想进入基于主题的世界，那么dita包括代码和文本的交叉引用。 Docbook具有文本对象，并包含 。

渲染图

每种文档标记语言的默认行为都是将组装好的文件呈现为HTML，PDF，ePub或其他格式，因此请深入了解您选择哪种格式的文档。

创建服务

我无法说明您的文档服务将需要什么，但是应该可以使用容器来管理您的依赖项，然后使用一堆脚本来签出，汇编，呈现和提供文档。 如果您根据提供的内容对服务进行参数化以生成不同的文档，则需要加分。例如，根据需要或用例进行切换以包括单个API或代码片段。

下一步

好的，我承认，在本文中我没有告诉您确切的操作。 相反，我提出了一系列潜在的想法和资源来引发讨论，并且您可能比开始阅读时更明智。

但是，您还能添加什么呢？ 测试将是一个明显的开始，我建议您阅读我先前有关文档测试方面的文章，以获取更多想法。 您可以添加其他服务以不同格式或方式呈现文档，提要支持系统或社交媒体，或为您的API文档创建API。 正如任何微服务爱好者所知，一旦您完成了粉碎整体程序的复杂工作，那么可能性就无穷无尽。

翻译自: https://www.javacodegeeks.com/2017/08/tools-practices-documenting-microservices.html

微服务架构的日志记录