4. 服务目录数据结构：服务元数据模型、版本控制策略、依赖关系描述
服务目录的数据结构是 CI/CD 接口调用的核心契约。平台工程团队需要定义一套标准化的元数据模型，确保每个服务在目录中具备唯一的身份标识、可追溯的版本信息以及清晰的依赖图谱。本节将围绕服务元数据模型、版本控制策略和依赖关系描述三个维度展开，并给出可落地的数据结构定义。
4.1 服务元数据模型
服务元数据模型是服务目录的“身份证”，它定义了服务在平台中的注册、发现和运维所需的核心字段。一个完整的元数据模型应包含以下四类属性：
| 属性类别 | 字段示例 | 说明 |
|---|---|---|
| 标识属性 | service_id, service_name, owner_team |
全局唯一标识，用于接口调用时的路由和鉴权 |
| 运行时属性 | runtime_type, port, health_check_path |
描述服务的部署形态和健康检查方式 |
| 构建属性 | build_tool, artifact_repo, dockerfile_path |
CI 流水线所需的构建上下文 |
| 治理属性 | sla_level, compliance_tags, lifecycle_stage |
用于服务治理和合规审计 |
以下是一个标准化的服务元数据 JSON 示例，展示了 CI/CD 接口调用时传递的完整结构：
{
"service_id": "svc-20250301-abc123",
"service_name": "user-auth-service",
"owner_team": "platform-identity",
"runtime": {
"runtime_type": "kubernetes",
"port": 8080,
"health_check_path": "/healthz",
"replicas": 3
},
"build": {
"build_tool": "maven",
"artifact_repo": "nexus://internal-repo",
"dockerfile_path": "./Dockerfile",
"base_image": "eclipse-temurin:17-jre"
},
"governance": {
"sla_level": "gold",
"compliance_tags": ["pci-dss", "gdpr"],
"lifecycle_stage": "production"
}
}
实践建议： 元数据模型应保持“核心稳定、扩展灵活”的原则。建议将治理属性设计为键值对（key-value）结构，以便在不破坏接口契约的前提下支持未来新增的合规标签或自定义属性。
4.2 版本控制策略
服务目录中的每个服务实例都需要版本控制，以支持灰度发布、回滚和依赖追溯。版本控制策略需要覆盖两个层面：服务版本（Service Version）和目录版本（Catalog Version）。
4.2.1 服务版本（SemVer 语义化版本）
服务版本遵循 MAJOR.MINOR.PATCH 格式，由 CI 流水线在构建时自动生成并注册到目录中。版本变更规则如下：
- MAJOR：不兼容的 API 变更，需要更新依赖方的接口适配。
- MINOR：向下兼容的功能新增，依赖方无需修改代码。
- PATCH：向下兼容的问题修复，仅涉及内部实现变更。
4.2.2 目录版本（Catalog Version）
目录版本用于追踪服务元数据本身的变更历史，例如 owner_team 变更、健康检查路径调整等。目录版本采用单调递增的整数序列，每次元数据更新时自动 +1。
| 版本类型 | 格式 | 触发条件 | 接口调用影响 |
|---|---|---|---|
| 服务版本 | 1.2.3 |
代码提交、构建完成 | 影响依赖解析和部署策略 |
| 目录版本 | 42 |
元数据编辑、标签更新 | 影响目录同步和缓存刷新 |
注意： 服务版本和目录版本是正交的。一个服务版本（如 1.2.3）可以对应多个目录版本（如 42、43），因为运维人员可能在未发布新代码的情况下调整了元数据（如修改健康检查路径）。CI/CD 接口调用时，必须同时传递这两个版本号，以确保调用方获取到正确的服务配置。
4.3 依赖关系描述
服务目录中的依赖关系描述了服务之间的调用链和数据流。依赖关系描述需要支持显式依赖（编译期/运行时强依赖）和隐式依赖（配置共享、基础设施依赖）两种类型。
4.3.1 依赖关系数据结构
依赖关系采用有向无环图（DAG）模型，每个依赖项包含以下字段：
{
"service_id": "svc-20250301-abc123",
"dependencies": [
{
"target_service_id": "svc-20250301-def456",
"dependency_type": "runtime",
"version_constraint": ">=2.0.0 <3.0.0",
"protocol": "grpc",
"endpoint": "user-auth-service:8080"
},
{
"target_service_id": "svc-20250301-ghi789",
"dependency_type": "compile",
"version_constraint": "1.2.x",
"artifact": "com.platform:common-lib:1.2.3"
}
]
}4.3.2 依赖类型说明
| 依赖类型 | 说明 | 版本约束示例 | CI/CD 影响 |
|---|---|---|---|
runtime |
运行时必须存在的下游服务 | ^2.0.0 |
部署顺序控制、健康检查依赖 |
compile |
编译期依赖的库或 SDK | 1.2.x |
构建缓存策略、制品版本锁定 |
config |
共享配置或密钥依赖 | latest |
配置中心同步、密钥轮换触发 |
infra |
基础设施依赖（数据库、消息队列） | vpc-prod |
环境一致性校验、资源预置 |
4.4 服务元数据与依赖关系结构图
下图展示了服务目录中一个典型服务的元数据模型、版本控制策略和依赖关系之间的整体结构：
4.5 依赖关系解析流程
当 CI/CD 接口接收到一个服务的部署请求时，平台需要解析其依赖关系并生成部署顺序。下图展示了依赖关系解析的核心流程：
工程要点： 依赖关系解析是 CI/CD 接口调用中性能敏感的一环。对于大规模微服务集群（超过 500 个服务），建议在服务目录中预计算并缓存拓扑排序结果，避免每次部署请求都重新执行全量 DAG 解析。同时，版本约束校验应支持“宽松匹配”和“严格锁定”两种模式，分别对应开发环境和生产环境。
4.6 数据结构设计原则总结
- 唯一性：每个服务实例通过
service_id+服务版本+目录版本三元组唯一确定。 - 可追溯：版本控制策略确保每次变更都有记录，支持回滚到任意历史版本。
- 可解析：依赖关系采用 DAG 模型，支持拓扑排序和循环依赖检测。
- 可扩展：元数据模型预留自定义属性字段，适应不同团队的治理需求。