2. 服务目录基础概念：什么是服务目录，服务目录的元数据模型
在平台工程与蓝绿发布门禁的上下文中，服务目录（Service Catalog）并非一个简单的服务列表，而是一个可编程、可查询、可治理的元数据注册中心。它记录了每个服务从开发到生产全生命周期所需的全部结构化信息，是门禁策略执行、依赖分析、变更影响评估的数据基石。
2.1 什么是服务目录
服务目录是平台团队定义并维护的“服务事实源”。它回答了三个核心问题：
- 有什么服务？ —— 服务名称、ID、所属域。
- 谁负责？ —— 负责人、团队、值班组。
- 如何运行？ —— 部署方式、依赖关系、门禁配置。
平台工程视角： 服务目录不是 CMDB 的替代品，而是面向“部署与发布”场景的轻量级元数据层。它只存储门禁决策所需的最小必要字段，避免过度建模。
一个典型的服务目录条目，在蓝绿发布门禁中会这样被使用：
# 服务目录条目示例（YAML 格式）
service:
name: "user-service"
version: "2.1.0"
owner: "team-identity"
dependencies:
- name: "auth-db"
type: "database"
required: true
- name: "notification-svc"
type: "grpc"
required: false
gate:
blue_green:
min_health: 0.9
max_downtime_sec: 30
requires_approval: true
2.2 服务目录的元数据模型
元数据模型定义了服务目录中每个条目的字段结构、类型约束与关系。以下是蓝绿发布门禁场景下的核心元数据模型：
| 元数据字段 | 类型 | 门禁用途 | 示例值 |
|---|---|---|---|
| 名称 | string | 唯一标识，用于门禁策略匹配 | user-service |
| 版本 | semver | 判断蓝绿版本差异，触发回滚门禁 | 2.1.0 |
| 负责人 | string/team | 审批通知、故障定责 | team-identity |
| 依赖关系 | list[object] | 拓扑排序、级联门禁检查 | [{name: "auth-db", type: "database"}] |
| 门禁配置 | object | 定义蓝绿发布的具体阈值与策略 | {min_health: 0.9} |
2.3 核心元数据字段详解
2.3.1 名称（Name）
服务名称必须全局唯一，通常采用“域-服务”的命名规范。门禁系统通过名称精确匹配要发布的服务实例。
- 规范示例：
identity.user-svc、payment.order-svc - 反例：
my-service（无域前缀，容易冲突）
2.3.2 版本（Version）
使用语义化版本（SemVer）：MAJOR.MINOR.PATCH。蓝绿发布门禁利用版本号判断：
- MAJOR 变更： 强制要求人工审批，禁止自动切换。
- MINOR/PATCH 变更： 允许自动门禁检查后切换。
2.3.3 负责人（Owner）
负责人字段记录团队标识而非个人邮箱。门禁系统在以下场景使用该字段：
- 发布审批通知
- 蓝绿切换失败时的告警路由
- 依赖变更时的跨团队协调
2.3.4 依赖关系（Dependencies）
依赖关系是门禁决策中最复杂的元数据。它定义了服务之间的调用拓扑，直接影响蓝绿发布的流量切换顺序。
依赖关系分类：
- 强依赖（required: true）： 下游不可用时，当前服务必须拒绝流量。
- 弱依赖（required: false）： 下游不可用时，当前服务可降级运行。
- 数据依赖： 数据库、缓存、消息队列。
- 服务依赖： gRPC/HTTP 上游服务。
2.4 依赖关系在蓝绿门禁中的关键作用
依赖关系是蓝绿发布门禁中最具挑战性的元数据。错误的依赖声明可能导致流量切换后服务雪崩。以下是依赖关系在门禁中的典型应用：
| 依赖类型 | 门禁检查项 | 蓝绿切换影响 |
|---|---|---|
| 强依赖数据库 | Schema 兼容性、连接池健康 | 新版本必须通过数据库兼容性检查才能接收流量 |
| 强依赖上游服务 | 上游服务版本是否支持当前 API | 上游服务必须先完成蓝绿切换或保持向后兼容 |
| 弱依赖缓存 | 缓存集群可用性（降级允许） | 缓存不可用时，新版本仍可切换，但触发降级告警 |
⚠️ 常见陷阱： 依赖关系遗漏或声明为“弱依赖”但实际为“强依赖”，会导致门禁检查跳过关键路径，蓝绿切换后出现大面积超时。建议每季度进行一次依赖关系审计。
2.5 服务目录的治理原则
- 单一事实源： 服务目录是门禁系统唯一信任的元数据来源，禁止在 CI/CD 脚本中硬编码依赖关系。
- 变更可追溯： 所有元数据变更必须通过 GitOps 流程，保留审计日志。
- 最小必要原则： 只存储门禁决策所需的字段，避免过度建模导致维护成本上升。
- 定期校验： 通过运行时拓扑探测自动校验服务目录中的依赖声明是否与实际调用关系一致。
平台工程最佳实践： 将服务目录的元数据模型定义为 JSON Schema 或 Protobuf，在提交时进行格式校验。门禁系统直接消费 Schema 校验后的结构化数据，避免运行时解析错误。