2. 流水线服务目录概述

流水线服务目录（Pipeline Service Catalog）是组织级 CI/CD 能力的“产品货架”。它将可复用的构建、测试、部署、审批等流水线能力封装为标准服务，供不同业务团队按需订阅和实例化。本章从定义、价值与核心组成三个维度，建立对服务目录的完整认知。

2.1 服务目录的定义

服务目录是一份经过治理的、可检索的流水线能力清单。每个目录项对应一个流水线服务，包含完整的交付物定义：

• 服务名称：如“Java 微服务构建部署”、“前端静态资源发布”。
• 服务描述：适用场景、技术栈、SLA 承诺。
• 模板引用：指向 Jenkinsfile 或流水线 DSL 模板。
• 参数契约：必填/可选参数、类型、默认值、校验规则。
• 触发器定义：Git 事件、定时、手动、API 调用。
• 环境映射：开发/测试/预发/生产环境的差异化配置。
• 版本与变更记录：服务版本号、兼容性说明、更新日志。

服务目录不是静态文档，而是与 Jenkins 等 CI/CD 平台深度集成的元数据层。团队通过目录自助选择服务，系统自动完成模板实例化、参数注入和环境绑定。

2.2 为什么需要流水线服务目录

在组织级 CI/CD 实践中，缺乏服务目录会导致以下典型问题：

2.3 服务目录的典型组成部分

一个完整的流水线服务目录包含四个核心组成部分：模板、参数、触发器、环境。它们共同定义了服务的“是什么”、“怎么配”、“何时跑”、“跑在哪”。

2.3.1 模板（Template）

模板是流水线的执行骨架，通常以 Jenkinsfile（Declarative Pipeline）或共享库形式存在。模板定义了阶段（Stage）、步骤（Step）、后处理（Post）等结构，预留参数化插槽供调用方填充。

// 服务目录模板示例：Java 微服务构建部署
pipeline {
    agent any
    parameters {
        string(name: 'GIT_BRANCH', defaultValue: 'main', description: '目标分支')
        choice(name: 'ENV', choices: ['dev', 'test', 'staging', 'prod'], description: '部署环境')
        booleanParam(name: 'SKIP_TESTS', defaultValue: false, description: '跳过单元测试')
    }
    stages {
        stage('Checkout') { steps { checkout scm } }
        stage('Build') { steps { sh 'mvn clean package' } }
        stage('Test') { when { expression { !params.SKIP_TESTS } } steps { sh 'mvn test' } }
        stage('Deploy') { steps { deployToEnv(params.ENV) } }
    }
    post {
        failure { notifySlack('构建失败') }
        success { notifySlack('构建成功') }
    }
}

2.3.2 参数（Parameter）

参数是模板的“可调旋钮”，决定了同一模板在不同场景下的行为差异。服务目录中的参数定义包含：

• 参数标识：全局唯一的参数名，如 GIT_BRANCH。
• 参数类型：字符串、布尔、选项、密码、文件等。
• 默认值：服务实例化时的初始值。
• 校验规则：正则表达式、枚举范围、必填约束。
• 敏感标记：标记为敏感的参数在日志中自动脱敏。

2.3.3 触发器（Trigger）

触发器定义了流水线的启动条件。服务目录将触发器与模板解耦，允许同一模板绑定多种触发策略：

• Git 事件触发：Push、Pull Request、Tag 创建，支持分支过滤。
• 定时触发：Cron 表达式，适用于夜间构建、定期巡检。
• 手动触发：带参数的手动构建，适用于生产发布审批。
• Webhook 触发：外部系统（Jira、Artifactory）通过 API 触发。
• 上游依赖触发：当前置流水线成功后自动触发下游。

// 服务目录触发器配置示例（YAML 格式）
triggers:
  - type: git_push
    branches: ["main", "release/*"]
    paths: ["src/**", "pom.xml"]
  - type: cron
    schedule: "0 2 * * *"  # 每天凌晨 2 点
  - type: upstream
    jobs: ["dependency-build"]
    result: "SUCCESS"

2.3.4 环境（Environment）

环境是流水线执行的目标上下文，包含基础设施信息、凭据引用、配置变量等。服务目录中的环境定义遵循“环境即配置”原则：

服务目录的四要素并非孤立存在，它们通过元数据层形成有机整体。模板引用参数定义，参数值在触发器触发时注入，环境配置在部署阶段动态加载。这种解耦设计使得流水线服务可以像乐高积木一样灵活组合，同时保持治理一致性。