声明式流水线进阶
基础篇能跑通简单流水线，生产流水线还需要：参数化触发、条件跳过、并行加速、超时重试和灵活的控制流。
本篇目标：掌握 options、parameters、when、并行 stage、input 与 catchError，写出健壮的生产流水线。
1. options：流水线级控制
options 放在 pipeline 顶层，作用于整条流水线：
options {
timestamps() // 日志时间戳
timeout(time: 1, unit: 'HOURS') // 整条流水线超时
buildDiscarder(logRotator(numToKeepStr: '30', daysToKeepStr: '30')) // 构建保留
disableConcurrentBuilds() // 同 Job 禁止并发
skipDefaultCheckout() // 跳过默认 checkout（手动控制）
ansiColor('xterm') // 彩色日志
}
disableConcurrentBuilds() 与多分支disableConcurrentBuilds() 会让同 Job 串行构建。多分支流水线里这是按分支并发的——不同分支仍可并行。注意与"允许并发构建"的系统设置配合。
2. parameters：参数化构建
pipeline {
parameters {
choice(name: 'ENV', choices: ['dev', 'staging', 'prod'], description: '部署环境')
string(name: 'IMAGE_TAG', defaultValue: '', description: '镜像版本（留空自动取 BUILD_NUMBER）')
booleanParam(name: 'SKIP_TEST', defaultValue: false, description: '跳过测试')
}
stages {
stage('显示参数') {
steps {
echo "环境: ${params.ENV}"
echo "镜像: ${params.IMAGE_TAG ?: "v${BUILD_NUMBER}"}"
if (params.SKIP_TEST) {
echo '跳过测试'
}
}
}
}
}
触发方式：UI 上 Build with Parameters，或 API：
curl -X POST "$JENKINS_URL/job/$JOB/buildWithParameters" \
--user "$USER:$TOKEN" \
--data "ENV=staging&IMAGE_TAG=v1.2.3"
参数用 params.XXX 引用（不要用裸变量名，避免与作用域冲突）。
3. when：条件执行 stage
stage('部署到生产') {
when {
branch 'main' // 仅在 main 分支
environment name: 'ENV', value: 'prod' // 且环境参数为 prod
}
steps {
sh 'kubectl apply -f deploy/'
}
}
常用条件：
| 条件 | 作用 |
|---|---|
branch 'xxx' | 按分支名（多分支流水线可用通配 'main' / 'release-*'） |
environment name:'ENV', value:'prod' | 按环境变量 |
expression { return params.DEPLOY == 'yes' } | 任意 Groovy 表达式 |
not { branch 'main' } | 取反 |
beforeAgent true | 在分配 Agent 前判断（省资源） |
// 组合：仅 main 分支且带 release tag
when {
allOf {
branch 'main'
expression { env.GIT_TAG != null }
}
}
4. 并行 stage
独立的任务可以并行，显著缩短构建时间：
stage('并行测试') {
parallel {
stage('单元测试') {
steps { sh 'mvn test -Dgroups=unit' }
}
stage('集成测试') {
steps { sh 'mvn test -Dgroups=integration' }
}
stage('静态扫描') {
steps { sh 'mvn sonar:sonar' }
}
}
}
// 动态并行：按矩阵生成（脚本式辅助）
stage('按环境构建') {
steps {
script {
def envs = ['dev', 'staging', 'prod']
def branches = [:]
envs.each { e ->
branches[e] = {
echo "构建 ${e}"
sh "make build ENV=${e}"
}
}
parallel branches
}
}
}
并行与资源
并行 stage 会同时占用多个 Executor。默认 failFast false（一个失败其他继续）；想"一损俱损"用 parallel { ... } 内 failFast true。
5. input：人工确认
部署到关键环境前，插入人工确认门：
stage('等待人工确认') {
input {
message "确认部署到生产？"
ok "确认部署"
parameters {
string(name: 'APPROVER', defaultValue: '', description: '审批人')
}
}
steps {
echo "审批人: ${APPROVER}"
sh 'kubectl apply -f deploy/prod/'
}
}
超时自动放弃：
options {
timeout(time: 1, unit: 'HOURS') // 1 小时未确认则取消
}
6. catchError 与 script 块
声明式里需要 Groovy 逻辑时，用 script {} 包裹。catchError 能捕获失败继续执行：
stage('测试（失败不阻断）') {
steps {
catchError(buildResult: 'UNSTABLE', stageResult: 'FAILURE') {
sh 'mvn test' // 失败后流水线继续，构建标记 UNSTABLE
}
}
}
// 脚本块内做逻辑判断
stage('判断发布方式') {
steps {
script {
if (params.ENV == 'prod' && env.GIT_BRANCH == 'main') {
echo '生产发布：走滚动更新'
} else {
echo '非生产：直接 apply'
}
}
}
}
7. 流水线结构最佳实践
pipeline {
agent any
options { ... }
parameters { ... } // 1. 参数化
environment { ... } // 2. 环境变量（含凭证）
stages {
stage('预处理') { ... } // 3. 校验参数、checkout
stage('构建') { ... } // 4. 编译打包
stage('测试') { ... } // 5. 单元/集成测试（可并行）
stage('质量') { ... } // 6. 静态扫描
stage('产物') { ... } // 7. 归档/上传制品
stage('部署') { ... } // 8. 部署（可按 when 分支）
}
post {
always { cleanWs() }
success { notify() }
failure { notify() }
}
}
保持 stage 职责单一
每个 stage 只做一件事，命名用"动宾短语"（编译打包、执行测试、部署生产）。失败的 stage 一目了然，也方便并行和 when 控制。
8. 练习与验收
练习 A
- 给流水线加
choice/string/booleanParam三个参数，用 Build with Parameters 验证 - 用
when { branch 'xxx' }让某 stage 只在特定分支执行 - 把单元测试和集成测试改成
parallel
练习 B
- 在部署 stage 前加
input人工确认，体验 Build 卡住等待审批 - 用
catchError让测试失败不阻断后续 stage，构建结果变 UNSTABLE - 用
options { disableConcurrentBuilds() }触发两个并发构建，观察排队
验收清单
- 会用
parameters实现参数化构建，用params.XXX引用 - 会用
when按分支/环境/表达式做条件执行 - 会用
parallel并行 stage 和failFast - 会用
input做人工审批门 - 会用
catchError/script处理异常和动态逻辑 - 能组织出职责单一、结构清晰的流水线
下一篇：Pipeline 语法参考。