2. 服务目录基础：服务目录的组成要素、服务元数据模型、服务版本管理策略

服务目录（Service Catalog）是CI/CD环境一致性验证的“单一事实源”。它定义了每个环境（开发、测试、预发布、生产）中应该部署哪些服务、以什么版本运行、依赖哪些基础设施。本章深入剖析服务目录的核心组成、元数据模型以及版本管理策略，为后续的自动化验证奠定数据基础。

2.1 服务目录的组成要素

一个标准化的服务目录由以下五大核心要素构成，缺一不可：

2.2 服务元数据模型

服务元数据模型是服务目录的“数据字典”，它定义了每个服务条目如何结构化存储。以下是一个标准化的元数据模型，采用YAML格式描述：

# 服务元数据模型示例
service:
  id: "payment-gateway"
  name: "Payment Gateway Service"
  owner: "team-payment"
  lifecycle: "active"          # active | deprecated | retired

  versions:
    - version: "2.1.0"
      release_date: "2025-03-10"
      status: "current"        # current | previous | next
      environments:
        - name: "dev"
          state: "deployed"
          config_ref: "configs/dev/payment-v2.1.0.yaml"
        - name: "staging"
          state: "deployed"
          config_ref: "configs/staging/payment-v2.1.0.yaml"
        - name: "prod"
          state: "pending"
          config_ref: "configs/prod/payment-v2.1.0.yaml"

  dependencies:
    - name: "redis-cache"
      type: "middleware"
      version: ">=6.2, <7.0"
    - name: "user-auth-api"
      type: "internal-api"
      version: "~1.5"

  consistency_rules:
    - check: "health_endpoint"
      value: "/actuator/health"
      expected_status: 200
    - check: "listening_port"
      value: "8080"
      protocol: "TCP"

2.3 服务版本管理策略

版本管理策略决定了服务目录如何跟踪、升级和回滚服务版本。以下是三种主流策略的对比：

在实际项目中，通常采用混合策略：生产环境使用固定版本锁定，开发环境使用语义化范围约束，而预发布环境则采用GitOps驱动版本进行集成测试。

2.4 版本管理策略的落地对比

为了帮助团队选择最适合的版本管理策略，下表从多个维度进行了详细对比：

2.5 服务目录的版本化存储

服务目录本身也需要版本管理。推荐将服务目录定义文件存储在Git仓库中，与CI/CD流水线绑定：

• 目录结构：每个环境一个目录，每个服务一个YAML文件。
• 变更流程：通过Pull Request修改服务目录，经过审批后合并。
• 自动验证：合并后触发流水线，自动校验目录格式、依赖完整性、版本约束。

# 推荐的服务目录仓库结构
service-catalog/
├── dev/
│   ├── payment-service.yaml
│   ├── user-service.yaml
│   └── notification-service.yaml
├── staging/
│   ├── payment-service.yaml
│   └── user-service.yaml
├── prod/
│   ├── payment-service.yaml
│   └── user-service.yaml
├── shared/
│   └── dependency-definitions.yaml
└── .catalog-validator.yaml    # 验证规则配置