3. 服务目录概念：服务目录的定义、服务目录在平台工程中的作用、服务目录与开发者门户的关系
3.1 服务目录的定义
服务目录（Service Catalog）是平台工程中一个结构化的、可搜索的、经过治理的“菜单”，它列出了平台团队向开发者提供的所有标准化服务、基础设施组件和运行环境。每个服务条目都包含明确的元数据、版本信息、依赖关系、SLA 以及自助式部署入口。
在 CI/CD 服务目录环境部署的上下文中，服务目录不仅仅是静态的列表，而是一个可执行的资产库。开发者可以通过服务目录发现、请求、配置和部署经过平台团队预审和治理的服务，而无需理解底层基础设施的复杂性。
核心特征：
- 标准化：所有服务遵循统一的定义模板和版本规范。
- 可发现：提供搜索、过滤和分类能力，帮助开发者快速找到所需服务。
- 可执行：支持“一键部署”或“API 触发部署”，直接对接底层 CI/CD 管道。
- 治理化：包含审批流、配额管理、合规检查和成本标签。
3.2 服务目录在平台工程中的作用
服务目录是平台工程从“构建平台”转向“运营平台”的关键桥梁。它解决了平台团队与开发者之间的信息不对称和协作摩擦。
| 作用维度 | 具体说明 | 平台工程价值 |
|---|---|---|
| 抽象复杂性 | 将 Kubernetes 集群、数据库、消息队列等底层资源封装为“服务” | 降低开发者认知负荷，提升交付速度 |
| 治理与合规 | 内置安全基线、成本标签、环境隔离策略 | 确保所有部署符合组织规范，减少安全风险 |
| 复用与标准化 | 提供经过验证的服务模板，避免重复造轮子 | 减少碎片化，提升运维一致性 |
| 自助服务 | 开发者可自行选择服务、配置参数并触发部署 | 消除等待平台团队手动配置的瓶颈 |
| 成本与资源可视化 | 每个服务条目关联成本估算和资源配额 | 帮助团队做预算规划和资源优化 |
实践建议：在构建服务目录初期，优先纳入“黄金路径”服务（如标准化的 Spring Boot 应用、Node.js 微服务、PostgreSQL 实例），而不是试图覆盖所有可能的服务类型。这有助于快速验证服务目录对开发者效率的提升效果。
3.3 服务目录与开发者门户的关系
服务目录与开发者门户（Developer Portal）是平台工程中两个紧密关联但职责不同的概念。开发者门户是面向开发者的统一入口和用户体验层，而服务目录是门户背后的核心数据模型和业务逻辑层。
下图展示了服务目录与开发者门户在平台工程架构中的位置关系：
从架构上看，两者的关系可以总结为以下关键点：
- 门户是前端，目录是后端：开发者门户负责展示和交互，服务目录负责存储和逻辑。门户通过 API 调用服务目录获取服务列表、详情和部署配置。
- 目录驱动门户的内容：门户上展示的“服务卡片”、“部署按钮”、“版本选择器”等 UI 元素，其数据源均来自服务目录。目录中定义的治理规则（如“生产环境需要二级审批”）会直接影响门户上的操作流程。
- 目录是治理核心，门户是体验窗口：平台团队在服务目录中配置策略（如配额、合规标签、成本上限），开发者通过门户感知这些策略（如部署时看到成本估算、配额不足时收到提示）。
- 双向反馈闭环：开发者通过门户提交的服务请求、部署反馈、评分数据，可以回流到服务目录，帮助平台团队优化服务定义和治理策略。
常见误区：不要将服务目录与开发者门户混为一谈。如果只建设门户而没有服务目录，门户将沦为静态文档站，无法实现自助部署和治理自动化。反之，如果只建设服务目录而没有门户，开发者将被迫通过命令行或 API 直接操作目录，体验差且难以推广。
3.4 服务目录的核心元数据模型
一个标准化的服务目录条目通常包含以下元数据字段。这些字段在平台工程中用于自动化部署、成本核算和合规审计。
| 元数据类别 | 字段示例 | 用途 |
|---|---|---|
| 标识信息 | service_id, name, version, owner_team | 唯一标识服务，支持版本管理和团队归属 |
| 部署配置 | runtime, cpu_request, memory_limit, replicas | 定义服务运行时的资源需求和扩缩容策略 |
| 依赖关系 | dependencies: [db_id, cache_id, queue_id] | 声明服务依赖的其他服务或基础设施 |
| 治理策略 | approval_required, cost_center, compliance_tags | 控制部署审批、成本归属和合规检查 |
| CI/CD 集成 | pipeline_id, git_repo, deploy_trigger | 关联具体的 CI/CD 管道和代码仓库 |
| 环境映射 | environments: [dev, staging, prod] | 定义服务可部署的目标环境列表及环境差异 |
以下是一个简化的服务目录条目示例（YAML 格式）：
apiVersion: catalog.platform.io/v1
kind: Service
metadata:
name: user-service
version: 2.1.0
owner: team-identity
spec:
runtime: spring-boot:3.2
resources:
cpu: 1
memory: 2Gi
dependencies:
- postgresql:14
- redis:7
environments:
- name: dev
replicas: 1
approval: false
- name: prod
replicas: 3
approval: required
pipeline:
repo: https://git.company.com/identity/user-service
trigger: push-to-main
cost:
center: eng-identity
estimated_monthly: 120.00
关键设计原则：服务目录的元数据模型应保持“够用但不过度”。初期建议只包含标识信息、部署配置和 CI/CD 集成三个核心类别，随着平台成熟度提升再逐步加入治理策略和成本模型。过度设计会导致平台团队维护负担过重，降低目录的采纳率。