Skip to main content

创建目录图

概览​

Backstage 中的软件目录旨在使用实体及其关系来捕捉人类的心智模型，而不是详尽无遗地列出所有可能的事物。 重点是附加以这些实体为中心的功能和视图。 确定目录结束和外部世界开始的 "边缘 "对于确保目录的范围适当至关重要。 Backstage 软件目录是组织和发现软件组件和服务的集中枢纽。 虽然它擅长提供这些概念的高层次概览，但它可能不是实时跟踪组件和服务之间动态关系的理想解决方案。 通过在图中的节点上附加适当的工具，可以实现实时视图。注释并开发定制的前端插件值得注意的是，不应将 Backstage 软件目录视为真相的最终来源，相反，建议将 Backstage 目录作为一种缓存机制，利用 REST API 向目录用户界面和其他 Backstage 插件传递信息。 建议采用 GitOps 方法修改 Backstage 中的 YAML 文件，将版本库中的 YAML 文件视为真相的主要来源，并使用 Scaffolder 通过用户界面进行修改，然后在版本库中生成包含更新更改的拉取请求。

用于构建目录图的描述符组件​

实体：节点是图数据库的基本构件，用于表示实体及其属性。

种类：这些大类用于对相关实体进行分组。 类型 "用于对实体进行高级分类，如 "服务"、"数据库 "或 "团队"。 类型 "通常用于过滤目录中的实体，并对所管理的实体类型进行高级概述。

关系：这些是目录中不同实体之间的链接。 关系表达了不同实体之间的关系，如依赖关系或所有权关系。 采用者可以使用关系帮助用户浏览目录并理解不同实体之间的关系。

规格：规范或 "Spec "是一种模式，概述了 Backstage 目录中实体的数据结构。 它定义了实体的属性、关系、数据类型和约束条件，确保数据的一致性和准确性，同时允许跨组件和插件轻松共享和消费数据。 规范在创建或扩展实体时非常有用，有助于提高数据的可重用性和互操作性。 规范部分可完全自定义，用户可以创建自己的组件和插件来呈现信息。

类型：这些是更具体的类别，用于对特定 Kind 中的实体进行分类。 类型提供了更细化的实体分类，如 "前端服务 "或 "后端服务"。 类型通常用于提供有关实体的更多上下文和信息，帮助用户了解实体在更广泛系统中的角色和功能。

注释：这些键值对可以附加到目录中的实体。 它们通常用于为实体添加附加信息或元数据。 注释通常用于提供自动工具或脚本使用的信息，并为处理实体的人提供进一步的上下文，或将插件引向外部世界。

开箱即用​

目录使用描述符作为节点，而关系开箱即可获得以下用例：

  • 所有权跟踪 * 库存 * 搜索 * 生命周期跟踪 * 实时信息源跟踪 * 依赖关系映射 * API 暴露

跟踪资产​

建议的方法是用目录信息文件来表示信息，用户自己可以管理这些文件。 虽然基于资源库内容的自动分类可能会有所帮助，但建议只用它来生成初始文件，然后让人工来维护。 原因是自动化有时会失效，因此必须确保这种元数据的准确性和可靠性。 简而言之，人类应该治理这种元数据，以保持其完整性。

知名可追踪资产​

组件

  • 服务 * 网站 * 库 * 数据管道 * 机器学习模型 * 第三方软件组件：建议为所有第三方目录信息文件建立一个单独的 repo。

资源

  • 云基础设施服务

所有权--用户--分组

  • 业务单位 * 团队 * 产品领域

命名策略：

  • Ldap：内部 ldap 用户名作为实体名称。例如，owners:user
    或 user
    。

所有权战略：

**基于团队的所有权：**系统中所有权的概念是以团队为中心的；因此，"owner "字段必须根据规定的一套规则引用一个小队的 LDAP 名称。 虽然可能会出现所有权归属于个人的情况，但这种偏离可能会带来挑战。 在这种情况下，用户可以通过网络界面收到通知，强调这种偏离是例外情况，需要纠正。 为确保遵守该系统，模型中的每个实体都应有一个指定的所有者，最好是 LDAP 层次结构中的一个有效团队。

**功能所有权：**要跟踪产品中特定功能的所有权及其相互关系，有两种方法可供选择：引入新组件类型如 "功能"，或创建一个新的种类尽管如此，我们还是建议选择前一种方法，引入一种新的类型，如 "特征"，因为它不太复杂，风险也较低。

**LDAP 不能反映组织结构：**如果将 Workday 或类似系统作为真实信息源，并利用 LDAP 查找用户属性，那么最好在各种系统之上开发一个层，以建立一个整个组织都能查询的统一 API，而不仅仅是 Backstage。

** 应用程序**

  • OpenApi * AsyncApi * graphQL * gRPC

API 可以列出联网的服务或库，识别形成系统间边界的 API 尤其有用。 有一些注意事项需要牢记：

** 应用程序版本：**主要 API 版本可被视为不同的 API，可以为每个版本创建单独的实体实例(例如，metadata.name: my-api-v1 和 metadata.name

)。但是，对于次要或补丁级变化，不建议采用这种方法。

**详细内容：**不建议过于细化，因为目前形式的目录可能不是一个很好的表达平台。

**应用程序接口之间的关系：**我们的想法是，你有一个服务组件，它公开了一个应用程序接口，然后，不是应用程序接口消耗其他应用程序接口，而是组件消耗其他应用程序接口。

**前端应用程序接口(BFF)的后端：***建议为前端和后端服务分别创建不同的组件，前端组件的类型为 "网站"，后端组件的类型为 "服务"。 这是因为 BFF API 是为特定用户界面量身定制的，并不供其他人使用，因此没有必要将其纳入目录。

**API 注册表：**探索组织内的所有应用程序接口是应用程序接口注册中心的典型用例。

参考模型​

**C4型号：**您可以查看C4 型号它定义了一种可视化软件架构的模式。