3. 服务目录设计原则：命名规范、元数据标准化、版本管理策略、服务依赖关系建模
服务目录是平台工程的核心数据平面，它不仅是“服务清单”，更是连接开发者、运维与 CI/CD 流水线的统一信息源。设计不良的服务目录会导致命名冲突、元数据冗余、版本混乱以及依赖地狱。本章围绕四项核心原则展开，确保服务目录具备可扩展性、可发现性和自动化友好性。
3.1 命名规范：全局唯一、语义清晰、层级可解析
命名规范是服务目录的“第一道防线”。一个良好的命名体系应满足：全局唯一（避免跨团队冲突）、语义清晰（从名称即可推断服务职责）、层级可解析（支持按域、团队、服务分层检索）。
| 维度 | 推荐做法 | 反例 |
|---|---|---|
| 全局唯一性 | 使用 <domain>-<team>-<service-name> 三段式 |
payment-service（多个团队同名） |
| 语义清晰 | 动词+名词，如 order-create、user-validate |
svc-001、core-api |
| 层级可解析 | 支持 DNS 风格：pay.risk.finance.company.io |
risk-pay-v2-final |
实践建议：在服务目录中强制校验命名正则表达式（如
^[a-z0-9]+(-[a-z0-9]+)*$），并在服务注册时自动拒绝不合规名称。
3.2 元数据标准化：从“自由填写”到“结构化模板”
元数据是服务目录的“血液”。标准化元数据确保 CI/CD 流水线能够自动读取服务属性（如语言栈、端口、健康检查路径），而无需人工维护配置文件。元数据应分为必填字段、自动推导字段和可选扩展字段三层。
关键指标：元数据标准化覆盖率应达到 100%（必填字段）+ 80%（自动推导字段）。低于此标准时，CI/CD 流水线应发出告警，阻止服务部署到生产环境。
3.3 版本管理策略：语义化版本 + 兼容性标记
服务目录中的每个服务都应遵循 SemVer 2.0（MAJOR.MINOR.PATCH）。但仅靠版本号不足以支撑自动化决策，必须附加兼容性标记：
- MAJOR：不兼容的 API 变更，触发下游依赖方强制审查。
- MINOR：向后兼容的功能新增，自动更新下游依赖的版本范围。
- PATCH：向后兼容的缺陷修复，自动触发灰度发布。
| 版本变更类型 | CI/CD 流水线行为 | 服务目录更新动作 |
|---|---|---|
MAJOR 升级 |
阻塞下游流水线，发送审批通知 | 创建新版本条目，旧版本标记为“弃用” |
MINOR 升级 |
自动更新依赖锁定文件，触发集成测试 | 更新元数据中的“最新兼容版本”字段 |
PATCH 升级 |
自动触发金丝雀部署，无人工干预 | 仅更新制品哈希，版本号不变 |
避坑提示：不要将 Git 提交 SHA 或构建号直接作为服务版本号。服务目录中的版本必须与制品仓库（如 Docker Registry、Nexus）中的标签严格对应，否则回滚时将无法定位正确制品。
3.4 服务依赖关系建模：有向无环图 + 运行时拓扑
服务依赖关系是微服务架构中最容易失控的维度。服务目录必须同时维护编译时依赖（如 API 契约、共享库）和运行时依赖（如数据库、消息队列、外部服务）。推荐使用有向无环图（DAG）建模，并定期通过运行时拓扑扫描验证依赖声明的准确性。
3.5 依赖关系建模的自动化校验规则
在服务目录中注册依赖关系时，平台应自动执行以下校验，防止依赖腐化：
- 循环依赖检测：使用拓扑排序算法，发现环时拒绝注册并返回依赖链路径。
- 版本兼容性检查：下游服务声明的版本范围必须包含上游服务的当前版本。
- 运行时拓扑一致性：每 15 分钟对比服务目录中的声明依赖与 Service Mesh（如 Istio）的实际流量拓扑，差异超过 5% 时触发告警。
- 依赖深度限制：单条调用链的依赖深度不得超过 6 层（防止级联故障扩散）。
平台工程价值：当服务目录与 CI/CD 流水线深度集成后，依赖关系建模可以直接驱动“变更影响分析”。例如，当
Payment Service 发布 MAJOR 版本时，流水线自动查询服务目录，找出所有直接或间接依赖它的服务，并暂停其部署流水线，直到依赖方确认兼容。
3.6 设计原则总结矩阵
| 原则 | 核心目标 | CI/CD 集成点 | 失败后果 |
|---|---|---|---|
| 命名规范 | 全局唯一、可解析 | 服务注册时正则校验 | 服务发现混乱、流水线误触发 |
| 元数据标准化 | 结构化、可自动化消费 | 流水线读取元数据生成部署配置 | 人工维护配置、环境差异 |
| 版本管理策略 | 可追溯、可回滚 | 版本变更触发对应流水线阶段 | 回滚失败、依赖锁定失效 |
| 依赖关系建模 | 无环、可观测 | 变更影响分析、部署顺序编排 | 级联故障、调用链断裂 |