4、CI/CD 流水线基础：GitHub Actions / YAML 语法、触发条件、Job 与 Step 设计

CI/CD 流水线是现代后端发布的核心引擎。GitHub Actions 作为与代码仓库深度集成的 CI/CD 平台，通过 YAML 声明式配置即可完成构建、测试、部署与回滚。本章将拆解其核心语法、触发策略与任务编排，为后续的 Go 后端发布流水线打下基础。

4.1 YAML 基础语法与 GitHub Actions 结构

GitHub Actions 使用 YAML 1.2 标准，以缩进表示层级关系。一个完整的流水线文件通常包含以下顶层字段：

以下是一个最小化的 Go 后端 CI 流水线示例：

name: Go CI Pipeline

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

env:
  GO_VERSION: '1.22'
  REGISTRY: ghcr.io

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Go
        uses: actions/setup-go@v5
        with:
          go-version: ${{ env.GO_VERSION }}
      - name: Build
        run: go build -o ./bin/app ./cmd/server
      - name: Test
        run: go test ./... -v -race -count=1

4.2 触发条件（on）详解

触发条件决定了流水线何时自动执行。GitHub Actions 支持多种事件类型，按使用频率可分为三类：

4.2.1 分支推送与 PR 触发

最常用的触发方式，适用于代码提交和合并请求场景：

on:
  push:
    branches:
      - main
      - 'release/**'
    paths-ignore:
      - 'docs/**'
      - '*.md'
  pull_request:
    branches:
      - main
    types: [ opened, synchronize, reopened ]

• branches：支持 glob 模式匹配，release/** 匹配所有 release 子分支。
• paths-ignore：当变更仅涉及文档或 Markdown 文件时，跳过流水线执行。
• types：PR 事件子类型，synchronize 表示 PR 分支有新的推送。

4.2.2 定时与手动触发

4.3 Job 与 Step 设计原则

Job 是流水线的执行单元，Step 是 Job 内的最小操作步骤。合理的 Job/Step 设计直接影响流水线的并行效率与可维护性。

4.3.1 Job 依赖与并行

默认情况下，所有 Job 并行执行。通过 needs 关键字可以建立依赖关系：

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: golangci-lint run

  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: go test ./... -race

  build:
    needs: [ lint, test ]    # 等待 lint 和 test 都通过
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: go build -o app .

  deploy:
    needs: [ build ]         # 等待 build 完成
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying..."

上述流水线的执行流程如下：

4.3.2 Step 复用与矩阵策略

Step 可以通过 uses 引用社区 Action 或本地 Action，避免重复代码。矩阵策略（strategy.matrix）允许在多个版本或环境中并行执行同一 Job：

jobs:
  test-matrix:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        go-version: [ '1.21', '1.22' ]
        os: [ ubuntu-latest, windows-latest ]
      fail-fast: false
    steps:
      - uses: actions/checkout@v4
      - name: Setup Go ${{ matrix.go-version }}
        uses: actions/setup-go@v5
        with:
          go-version: ${{ matrix.go-version }}
      - name: Test on ${{ matrix.os }}
        run: go test ./... -v

4.4 上下文与表达式

GitHub Actions 提供丰富的上下文对象，用于在流水线中动态获取信息：

jobs:
  show-context:
    runs-on: ubuntu-latest
    steps:
      - name: Print GitHub context
        run: |
          echo "Event name: ${{ github.event_name }}"
          echo "Branch: ${{ github.ref_name }}"
          echo "Commit SHA: ${{ github.sha }}"
          echo "Runner OS: ${{ runner.os }}"
      - name: Conditional step
        if: github.ref_name == 'main'
        run: echo "This step only runs on main branch"

4.5 流水线可视化与调试

GitHub Actions 提供内置的可视化界面，但理解其底层执行模型有助于排查问题。以下是一个典型的 Step 执行生命周期：

4.6 最佳实践与避坑指南

• Step 命名清晰：每个 Step 的 name 字段应描述其功能，便于在日志中快速定位。
• 避免硬编码：使用 env 或 vars 上下文管理版本号、路径等可变值。
• 缓存依赖：Go 模块依赖可使用 actions/cache 缓存 ~/.cache/go-build 和 vendor 目录，加速后续构建。
• Job 粒度控制：将构建、测试、部署拆分为独立 Job，利用 needs 控制依赖，避免单 Job 过长导致超时。
• 条件执行：使用 if 条件控制 Step 是否执行，例如仅在 main 分支上触发部署。