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

服务目录（Service Catalog）是平台工程中连接“平台能力提供方”与“应用消费方”的核心契约层。它并非简单的服务列表，而是一个包含元数据、依赖关系、运维策略和交付约束的结构化知识库。在 CI/CD 流水线集成场景下，服务目录充当“单一事实源”，确保每一次部署、每一个变更都能被正确路由、监控和审计。

2.1 服务目录的定义

服务目录是对平台所托管的所有服务及其运行态属性的标准化注册与描述。它通常以 YAML/JSON 文件或数据库记录的形式存在，并对外提供查询与变更接口。一个成熟的服务目录至少包含以下特征：

• 唯一标识：每个服务拥有全局唯一的 ID（如 service:order-svc:v2）。
• 版本化：目录条目本身支持版本管理，与服务代码版本解耦。
• 可编程：通过 API 或 GitOps 方式被 CI/CD 流水线、监控系统和成本分析工具直接调用。
• 可发现：开发者和运维人员可通过统一门户或 CLI 工具检索服务信息。

2.2 核心要素

一个可用的服务目录条目必须包含以下五个核心要素。下表列出了每个要素的字段名称、数据类型和典型示例：

除了上述必填字段，生产级服务目录通常还会包含：

• 依赖关系：上游 API、下游数据库、消息队列等。
• 部署策略：滚动更新、蓝绿部署、金丝雀发布的参数。
• 告警规则：关联的 Prometheus 规则或 PagerDuty 策略。
• 成本标签：用于云成本分摊的部门/项目标签。

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

服务目录在平台工程中扮演着“平台大脑”的角色。它向下对接基础设施和 CI/CD 引擎，向上支撑开发者门户和治理报表。具体来说，其核心角色体现在以下四个方面：

1. 标准化入口：所有服务必须通过目录注册才能获得平台资源（计算、存储、网络）和流水线权限。
2. 自动化驱动：CI/CD 流水线在部署前从目录读取 SLA 和依赖信息，自动生成配置、注入 sidecar、配置健康检查。
3. 治理与合规：平台团队通过目录扫描未注册服务、过期版本、无负责人服务，实施强制升级或回收。
4. 可观测性关联：监控系统根据目录中的服务名称和版本自动关联日志、指标和链路追踪，无需人工打标签。

2.4 服务目录与 CI/CD 流水线的集成模式

在平台工程实践中，服务目录与 CI/CD 流水线的集成通常采用“流水线查询目录”模式，而非“目录驱动流水线”。具体流程如下：

1. 触发阶段：代码合并到主分支后，流水线自动启动。
2. 查询阶段：流水线调用服务目录 API，获取当前服务的版本、SLA、依赖和部署策略。
3. 校验阶段：流水线对比代码中的版本声明与目录中的版本记录，防止版本回退或未注册服务。
4. 构建与部署：根据目录返回的运行时元数据（如端口、健康检查路径）生成容器配置和 K8s 清单。
5. 注册更新：部署成功后，流水线自动更新目录中的版本字段和运行时状态。

2.5 服务目录的常见反模式

在实施服务目录时，团队容易陷入以下误区。请对照检查你的平台设计：