ADR005 目录核心实体

上下文

我们希望将Backstage目录中跟踪的几个核心实体标准化。 这样我们就可以围绕它们构建特定的插件。

决定

Backstage 最终应支持以下核心实体：

** 组件是单个软件 *API 是不同组件之间的界限 ** 资源是运行组件所需的物理或虚拟基础设施

目前，我们将首先实现对 Backstage 目录中组件实体的支持，之后再扩展到 API、资源和其他潜在的有用实体。

组件

组件是一个软件，例如移动应用功能、网站、后端服务或数据管道(列表并不详尽)。 组件可以在源控制中跟踪，也可以使用一些现有的开源或商业软件。 它可以实现供其他组件使用的 API。 反过来，它可能依赖于其他组件实现的 API 或运行时附加到它的资源。

组件实体通常是在组件代码旁边的 YAML 描述文件中定义的，可能看起来像这样(实际模式将不断发展)：

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-component-name
spec:
  type: service

API

应用程序接口构成了一种抽象概念，使大型软件生态系统得以扩展。 因此，应用程序接口是Backstage模型中的一等公民，也是发现生态系统中现有功能的主要途径。

API 由组件实现并明确其边界。 它们可以使用 RPC IDL(如 Protobuf、GraphQL 或类似内容)、数据模式(如 Avro、TFRecord 或类似内容)或代码接口(如 Swift、Kotlin、Java、C++、TypeScript 等语言的框架 API)来定义。 无论如何，组件暴露的 API 都需要采用已知的机器可读格式，这样我们才能在其基础上构建进一步的工具和分析。

应用程序接口通常是根据源控制中的现有定义编制索引的，因此不需要自己的描述符文件，而是像这样存储在目录中(实际模式将不断发展)：

apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: my-component-api
spec:
  type: grpc
  definition: >
    service HelloService {
      rpc SayHello (HelloRequest) returns (HelloResponse);
    }

    message HelloRequest {
      string greeting = 1;
    }

    message HelloResponse {
      string reply = 1;
    }

资源

资源是软件运行时所需的基础架构，如 Bigtable 数据库、Pub/Sub 主题、S3 buckets 或 CDN。 将它们与组件和 API 一起建模，可以让我们在 Backstage 中对其进行可视化并创建相关工具。

资源通常由声明式定义(如 Terraform、GCP Config Connector、AWS Cloud Formation)和/或云提供商的目录(如 GCP Asset Inventory)编制索引，因此不需要自己的描述符文件，而是像这样存储在目录中(实际模式将不断发展)：

apiVersion: backstage.io/v1alpha1
kind: Resource
metadata:
  name: my-component-db
spec:
  type: gcp-spanner
  url: spanner.googleapis.com/projects/prj/instances/my-component-db/databases/my-db

后果

我们将继续充实对 Backstage 目录中组件实体的支持。