4. 服务目录数据模型：Entity 与 Catalog 模型、API 与 Component 实体、自定义实体类型

Backstage 服务目录的核心是统一的数据模型。所有被管理的软件组件、API、资源、网站、用户或团队，在 Backstage 中都被抽象为 Entity（实体）。理解 Entity 模型、Catalog 模型以及如何扩展自定义实体类型，是实现容量水位巡检与故障排查的基础。

4.1 Entity 模型：统一的数据结构

每个 Entity 都遵循一个标准化的 YAML/JSON 结构，包含以下核心字段：

4.2 Catalog 模型：实体关系与图谱

Catalog 模型不仅管理单个 Entity，还维护实体之间的 关系图谱。常见关系包括：

• dependsOn：A 依赖 B（如服务依赖数据库）
• provides：A 提供 B（如 Component 提供 API）
• ownedBy：A 归属于 B（如 Component 属于 Team）
• partOf：A 是 B 的一部分（如 Service 是 System 的一部分）

这些关系构成了服务目录的“知识图谱”，是故障排查时进行影响范围分析的基础。

4.3 API 与 Component 实体

在容量水位巡检场景中，Component 和 API 是最常打交道的两种实体类型。

4.3.1 Component 实体

Component 代表一个可独立部署的软件单元（微服务、前端应用、批处理任务等）。其 spec 字段包含：

• type：service、website、library 等
• lifecycle：experimental、production、deprecated
• owner：所属团队实体引用
• system：所属系统实体引用
• subcomponentOf：父组件引用（可选）

4.3.2 API 实体

API 实体描述一个服务对外暴露的接口。其 spec 字段包含：

• type：openapi、asyncapi、graphql、grpc 等
• lifecycle：同 Component
• owner：所属团队
• definition：API 定义内容（如 OpenAPI 规范）
• system：所属系统

4.4 自定义实体类型

当内置的 Component、API、Resource、System 等类型无法满足需求时，Backstage 允许通过 自定义实体类型 扩展数据模型。例如，在容量巡检场景中，可能需要定义 CapacityThreshold 或 MonitorTarget 等新类型。

自定义实体类型的步骤：

1. 定义 Kind：在 catalog 配置中注册新的 kind 名称。
2. 创建实体处理器：实现 EntityProcessor 接口，解析自定义 YAML 格式。
3. 注册到 Catalog：在 packages/backend/src/plugins/catalog.ts 中添加处理器。
4. 编写前端卡片：为自定义实体创建专属的展示组件（EntityCard）。

4.5 实体定义最佳实践

• 命名规范：实体名称使用 kebab-case，如 user-service、payment-api。
• 注解驱动：将容量阈值、监控 URL 等运维信息放在 metadata.annotations 中，避免污染 spec 结构。
• 关系完整性：确保每个 Component 都关联到 owner 和 system，便于故障时快速定位责任团队。
• 自定义类型谨慎使用：优先复用内置类型，仅在模型差异较大时扩展自定义类型，避免 Catalog 模型碎片化。