4. 服务目录概念：服务目录的定义、核心要素与平台工程角色

服务目录是平台工程中连接“基础设施能力”与“业务应用”的核心元数据层。它并非简单的服务列表，而是一个可查询、可关联、可审计的运行时知识库，记录了每个服务的身份、归属、依赖与承诺。在 DORA 度量体系中，服务目录是计算变更失败率、部署频率、前置时间和恢复时间的实体锚点——没有准确的服务目录，所有度量都将失去归属对象。

4.1 服务目录的定义

服务目录（Service Catalog）是一个集中式、权威且持续更新的注册中心，用于记录组织内所有生产服务的元数据。它区别于 CMDB（配置管理数据库）的关键在于：服务目录聚焦于服务级抽象，而非底层 CI（配置项）；它强调所有者责任与服务等级承诺，而非单纯的资产盘点。

4.2 核心要素

一个生产级服务目录至少包含以下四个核心要素。缺少任何一项，目录都将退化为“僵尸清单”，无法支撑效能评估与故障回溯。

4.3 服务目录在平台工程中的角色

在平台工程拓扑中，服务目录处于开发者门户与基础设施控制面之间的枢纽位置。它向下对接 Kubernetes 集群、数据库、消息队列等资源，向上暴露给 Backstage、Kratix 等开发者门户，作为服务创建、变更、退役的唯一入口。

具体角色可归纳为以下四点：

1. 黄金路径的导航器：开发者通过服务目录发现“我应该使用哪个数据库模板”“这个服务的 CI/CD 模板在哪里”。目录中的 template 字段直接链接到平台工程定义的黄金路径。
2. 变更风险的评估器：当某个底层基础设施（如 Redis 集群）计划升级时，服务目录的依赖关系图可以快速列出所有受影响的服务及其所有者，从而计算变更的“爆炸半径”。
3. DORA 度量的实体锚点：所有部署事件、告警事件、故障事件都必须关联到服务目录中的唯一服务 ID。没有目录，度量将退化为“按团队聚合”的粗粒度统计，无法定位到具体服务。
4. 治理与合规的审计点：服务目录记录每个服务的 生命周期状态（active / deprecated / retired）、数据分类（PII / non-PII）、合规标签（PCI / HIPAA）。平台工程团队可以据此实施自动化门禁，例如：禁止未标记 PII 的服务写入生产数据库。

4.4 服务目录的典型数据结构

以下是一个 YAML 格式的服务目录条目示例，展示了核心要素在实际平台中的表达方式。该结构可直接被 Backstage、Kratix 或自研门户解析。

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payment-gateway
  annotations:
    github.com/project-slug: org/payment-gateway
    pagerduty.com/service-id: "P12345"
spec:
  type: service
  lifecycle: production
  owner: team-payment
  system: payment-platform
  dependsOn:
    - component:user-db
    - resource:redis-cluster
  providesApis:
    - payment-api
  slo:
    - name: availability
      target: 99.95
      sli: http_request_success_rate
    - name: latency
      target: 200
      sli: p99_latency_ms
      unit: ms

4.5 服务目录在平台工程中的位置

从平台工程的分层架构来看，服务目录位于开发者体验层与资源编排层之间。它不直接管理基础设施，而是为上层门户提供“服务上下文”，为下层编排提供“配置参数”。

4.6 服务目录与 DORA 度量的映射

服务目录中的每个字段都直接或间接支撑 DORA 四大指标的采集与计算。下表展示了映射关系：