4. 流水线模板基础：流水线模板的组成要素与 YAML/JSON 语法

流水线模板是 CI/CD 服务目录的核心资产。它将重复的构建、测试、部署逻辑抽象为可复用的参数化定义，使团队无需从零编写流水线，只需填写参数即可生成标准化的交付流程。理解模板的组成要素与语法结构，是构建服务目录的第一步。

4.1 流水线模板的四大组成要素

一个完整的流水线模板由 阶段（Stage）、任务（Job）、步骤（Step） 和 触发器（Trigger） 四层结构构成。它们形成自上而下的嵌套关系：流水线包含多个阶段，每个阶段包含多个任务，每个任务包含多个步骤，而触发器决定流水线的启动条件。

4.2 流水线模板的 YAML/JSON 语法结构

YAML 和 JSON 是流水线模板最常用的两种序列化格式。YAML 因其可读性高、支持注释、缩进结构清晰，成为主流选择；JSON 则在工具链集成和严格校验场景中更受青睐。以下以 YAML 为例展示标准模板结构。

# 流水线模板示例：标准 Java 微服务 CI 流水线
# 文件: pipeline-template-java-ci.yaml

# 模板元数据
name: java-ci-pipeline
version: 1.0.0
description: "标准 Java 微服务 CI 流水线模板"

# 参数定义（服务目录填充入口）
parameters:
  - name: app_name
    type: string
    description: "应用名称"
  - name: java_version
    type: string
    default: "17"
  - name: deploy_env
    type: string
    allowed_values: ["dev", "staging", "prod"]

# 触发器定义
trigger:
  - event: push
    branches: ["main", "develop"]
  - event: pull_request
    branches: ["main"]

# 阶段定义
stages:
  - name: build
    jobs:
      - name: compile
        steps:
          - run: echo "Checking out code..."
          - run: mvn clean compile -Djava.version=${{ parameters.java_version }}
      - name: unit-test
        steps:
          - run: mvn test
  - name: package
    jobs:
      - name: docker-build
        steps:
          - run: docker build -t ${{ parameters.app_name }}:latest .
  - name: deploy
    jobs:
      - name: deploy-to-env
        steps:
          - run: echo "Deploying to ${{ parameters.deploy_env }}..."

4.3 要素详解：阶段、任务、步骤、触发器的配置模式

4.3.1 阶段（Stage）配置

阶段是流水线的顶层逻辑分组。每个阶段可以包含一个或多个任务，阶段之间默认串行执行，但可通过 parallel 属性实现并行阶段。

stages:
  - name: build
    parallel: false   # 阶段内任务串行
    jobs:
      - name: compile
      - name: unit-test
  - name: deploy
    parallel: true    # 阶段内任务并行
    jobs:
      - name: deploy-dev
      - name: deploy-staging

4.3.2 任务（Job）配置

任务定义执行环境、依赖关系和超时策略。每个任务运行在独立的容器或虚拟机中，确保环境隔离。

jobs:
  - name: compile
    image: maven:3.8-openjdk-17   # 执行环境
    timeout: 30                    # 超时分钟
    dependencies: []               # 依赖的上游任务
    steps:
      - run: mvn compile

4.3.3 步骤（Step）配置

步骤是原子操作，支持三种类型：run（执行脚本）、plugin（调用插件）、pipeline（触发子流水线）。

4.3.4 触发器（Trigger）配置

触发器定义流水线的启动条件。常见触发器包括代码事件、定时任务、手动触发和外部 Webhook。

trigger:
  - event: push
    branches: ["main", "release/*"]
    paths: ["src/**", "pom.xml"]   # 仅当这些文件变更时触发
  - event: schedule
    cron: "0 2 * * *"              # 每天凌晨 2 点执行
  - event: manual                  # 手动触发，需带参数
    parameters:
      - name: deploy_env
        type: string

4.4 流水线模板的 YAML/JSON 语法对比

4.5 流水线模板的组成结构图

下图展示了流水线模板的四层组成结构及其嵌套关系，帮助理解从触发器到步骤的完整链路。

4.6 模板参数化与变量引用

服务目录的核心价值在于参数化。模板通过 parameters 块定义可配置项，用户在创建流水线实例时只需填写参数值，无需修改模板逻辑。参数支持类型校验、默认值和枚举约束。

# 参数定义示例
parameters:
  - name: app_name
    type: string
    description: "应用名称"
    required: true
  - name: replicas
    type: integer
    default: 2
    min: 1
    max: 10
  - name: env
    type: string
    allowed_values: ["dev", "staging", "prod"]
    default: "dev"

# 在步骤中引用参数
steps:
  - run: kubectl scale deployment ${{ parameters.app_name }} --replicas=${{ parameters.replicas }}

4.7 模板版本管理与复用策略

流水线模板应纳入版本控制（Git），每个模板文件包含 version 字段。服务目录支持模板的语义化版本（SemVer），用户可指定使用 1.x 或 ^1.2.0 等版本范围。

4.8 模板语法校验与测试

在将模板发布到服务目录之前，必须进行语法校验和逻辑测试。推荐使用以下工具链：

• YAML 校验：yamllint 检查缩进、键值对格式；yq 用于查询和转换 YAML 结构。
• JSON 校验：jsonlint 或 jq 验证 JSON 语法和结构完整性。
• 模板渲染测试：使用服务目录的 CLI 工具（如 catalog-cli validate）模拟参数填充，验证渲染后的流水线是否合法。
• 流水线模拟执行：在沙箱环境中执行渲染后的流水线，验证阶段顺序、任务依赖和步骤命令的正确性。

# 使用 yamllint 校验模板
yamllint pipeline-template-java-ci.yaml

# 使用 yq 提取参数列表
yq eval '.parameters[].name' pipeline-template-java-ci.yaml

# 使用服务目录 CLI 渲染并校验
catalog-cli render --template java-ci --params '{"app_name":"my-app","env":"dev"}' --validate