2. CI/CD 流水线基础：Jenkins/GitLab CI/CD 核心概念与流水线定义

在数据库迁移版本对齐与接口契约实践中，CI/CD 流水线是承载自动化验证、版本追溯与部署编排的核心载体。本章聚焦 Jenkins 与 GitLab CI/CD 两大主流工具，梳理其核心概念、流水线定义方式及与数据库迁移场景的映射关系。

2.1 核心概念对比

Jenkins 与 GitLab CI/CD 在架构哲学、配置方式、触发机制上存在显著差异。下表从数据库迁移流水线视角进行关键维度对比：

2.2 Jenkins 流水线定义

Jenkins 流水线以 Jenkinsfile 为核心，支持 Declarative（声明式）与 Scripted（脚本式）两种语法。在数据库迁移场景中，推荐使用 Declarative 语法以提升可读性与阶段控制能力。

2.2.1 声明式流水线结构

pipeline {
    agent any

    environment {
        DB_URL = 'jdbc:postgresql://localhost:5432/mydb'
        DB_USER = 'migrator'
        DB_PASS = credentials('db-password')
    }

    stages {
        stage('Checkout') {
            steps {
                checkout scm
            }
        }
        stage('Validate Migration Scripts') {
            steps {
                sh 'flyway -url=$DB_URL -user=$DB_USER -password=$DB_PASS validate'
            }
        }
        stage('Migrate Database') {
            steps {
                sh 'flyway -url=$DB_URL -user=$DB_USER -password=$DB_PASS migrate'
            }
        }
        stage('Contract Verification') {
            steps {
                sh 'mvn test -Dtest=ContractVerificationSuite'
            }
        }
    }

    post {
        failure {
            emailext(
                subject: "数据库迁移失败: ${env.JOB_NAME} - ${env.BUILD_NUMBER}",
                body: "请检查迁移脚本或接口契约变更。",
                to: 'team@example.com'
            )
        }
    }
}

2.2.2 多分支流水线与版本对齐

Jenkins 多分支流水线（Multibranch Pipeline）自动为每个 Git 分支创建对应流水线。在数据库迁移版本对齐中，可利用分支名称映射数据库版本号：

• main 分支：对应生产环境基线版本，仅执行验证（validate）不执行迁移。
• release/1.2.x 分支：对应预发布环境，执行完整迁移与契约测试。
• feature/xxx 分支：对应开发环境，执行增量迁移并生成版本差异报告。

2.3 GitLab CI/CD 流水线定义

GitLab CI/CD 通过 .gitlab-ci.yml 文件定义流水线，天然与 Git 仓库绑定。其 Job 级缓存、制品传递与环境管理能力，非常适合数据库迁移的版本追溯。

2.3.1 典型流水线配置

stages:
  - validate
  - migrate
  - contract-test
  - deploy

variables:
  DB_URL: "jdbc:postgresql://postgres:5432/mydb"
  DB_USER: "migrator"
  FLYWAY_VERSION: "9.16.0"

cache:
  paths:
    - .flyway/

validate-migrations:
  stage: validate
  image: flyway/flyway:${FLYWAY_VERSION}
  script:
    - flyway -url=$DB_URL -user=$DB_USER -password=$DB_PASS validate
  only:
    - main
    - /^release\/.*$/

run-migrations:
  stage: migrate
  image: flyway/flyway:${FLYWAY_VERSION}
  script:
    - flyway -url=$DB_URL -user=$DB_USER -password=$DB_PASS migrate
  artifacts:
    paths:
      - migration-report.json
    expire_in: 30 days
  only:
    - /^release\/.*$/

contract-verification:
  stage: contract-test
  image: maven:3.8-openjdk-11
  script:
    - mvn test -Dtest=ContractVerificationSuite
  artifacts:
    reports:
      junit: target/surefire-reports/TEST-*.xml
  only:
    - merge_requests

2.3.2 环境管理与版本追溯

GitLab CI/CD 提供 Environment 与 Deployment 机制，可记录每次数据库迁移的目标环境与版本号：

• 在 Job 中声明 environment: production，GitLab 自动记录部署历史。
• 通过 CI_COMMIT_TAG 或 CI_PIPELINE_ID 作为迁移版本标识，与 Flyway 的 V__ 命名规范对齐。
• 使用 CI 变量 存储数据库连接串与凭证，避免明文暴露。

2.4 流水线核心流程 SVG 图

下图展示 Jenkins / GitLab CI/CD 在数据库迁移版本对齐场景下的通用流水线阶段与数据流：

2.5 流水线定义最佳实践

结合数据库迁移版本对齐与接口契约验证场景，流水线定义应遵循以下原则：

1. 阶段分离：验证（validate）与执行（migrate）必须分属不同阶段，验证失败时阻止迁移执行。
2. 版本追溯：每次迁移生成包含版本号、时间戳、执行人、变更摘要的报告，作为制品保留。
3. 环境隔离：开发、预发布、生产环境使用独立的数据库连接变量，通过 CI 变量或 Jenkins 凭据管理。
4. 契约先行：接口契约验证应在数据库迁移之后、部署之前执行，确保 API 与数据库结构一致。
5. 失败回滚：在流水线中预留回滚阶段（如 Flyway undo），或通过版本控制实现快速恢复。