jenkins pipeline技巧

说明：声明式流水线写得顺手之后，总会碰到几个绕不过去的问题——跑得太慢、要在机器之间传文件、并发构建互相打架、上线前要人等拍板、命令偶发失败。这篇把六个高频技巧逐个拆开，讲清楚每个参数是干什么的、什么时候用、坑在哪。

总览：六大技巧定位

这六个不是互相独立的。真实的生产流水线通常就是「parallel 跑测试 + lock 占住环境 + input 等人审批 + timeout 兜底超时」，最后用 script 处理声明式写不出的动态逻辑。结尾有一份组合实战。

一、parallel 并行

把原本串行执行的多个 stage 同时跑，显著缩短流水线总时长。常用于互不依赖的测试套件、多平台构建。

1.1 参数

声明式里 parallel 是一个阶段容器，本身没有「参数」参数，但它内部每个分支都是标准 stage，并且有一个关键开关：

脚本式（Scripted）用 parallel 步骤，形态不同：

parallel(
  failFast: true,                       // 脚本式把开关放第一个键值
  '单元测试': { node { sh 'make unit' } },
  '端到端':   { node { sh 'make e2e'  } }
)

1.2 场景与示例

场景 A（快速失败）：提交前的多重校验，任一不过就别浪费时间跑其他的。
场景 B（攒齐结果）：跑多组测试，希望一次看到哪组挂了，而不是第一组挂了就停。

stage('质量门禁') {
  parallel(
    failFast: true,                    // A：任一失败立刻停
    '单元测试':   { stage('Unit'){ steps{ sh 'make unit' } } },
    '代码扫描':   { stage('Scan'){ steps{ sh 'make sonar' } } },
    '构建产物':   { stage('Build'){ steps{ sh 'make build' } } }
  )
}

stage('全量测试') {
  parallel {                           // B：默认 failFast:false，跑完所有
    stage('Web E2E'){ steps{ sh 'make e2e-web' } }
    stage('API E2E'){ steps{ sh 'make e2e-api' } }
  }
}

注意坑：parallel 内的 stage 不能再嵌套 parallel（声明式限制）；且 parallel 默认不共享工作区，需要共享文件请用下面的 stash。另外并行分支越多，占用的 executor 越多，注意节点并发上限。

二、stash / unstash 跨节点传文件

Jenkins 的 workspace 是按节点隔离的：在节点 A 构建出的产物，节点 B 默认看不到。stash 把文件打包暂存到 Controller 端（内存/磁盘临时区），unstash 在另一处恢复。它是「临时传递」，区别于持久化的 archiveArtifacts。

2.1 stash 参数

2.2 unstash 参数

2.3 场景与示例

场景：构建机（Maven 节点）编译出 jar，部署机（deploy 节点，无 JDK）需要这个 jar。或者并行分支 A 产出、分支 B 之后要消费。

stage('Build') {
  agent { label 'maven' }
  steps {
    sh 'mvn package'
    stash name: 'app-jar', includes: 'target/*.jar', allowEmpty: false
  }
}
stage('Deploy') {
  agent { label 'deploy' }            // 另一个节点
  steps {
    unstash 'app-jar'                 // 把 jar 恢复到本节点 workspace
    sh 'scp target/*.jar server:/opt/app/'
  }
}

stash vs archiveArtifacts：stash 是「流水线内部短时传递」，不长久保留、不显示在构建页；archiveArtifacts 会把产物保存下来供下载和历史追溯。要留存交付物用后者，要跨节点搬运用前者。

三、lock / milestone 并发控制

当多个构建可能同时操作同一资源（同一个生产环境、同一个共享许可证）时，需要「互斥」；当新构建已经排队、旧的还在等人审批时，需要「让新的赢」。两者配合是生产发布的标准姿势。

3.1 lock 参数

用法：可放在 options { } 里（整段加锁），也可放在 steps 里用 lock(resource:'x'){...} 局部加锁。

3.2 milestone 参数

3.3 场景与示例

场景 A（lock）：两条流水线都可能部署到 prod-cluster，绝不能同时进行，否则互相覆盖。
场景 B（milestone）：构建 #10 还在 input 等人审批，构建 #11 已经跑完并准备部署。应该让 #11 赢，取消 #10 的审批——否则 #10 被批准后会拿旧代码上线。

stage('Deploy Prod') {
  options {
    lock(resource: 'prod-cluster', quantity: 1, label: '生产集群')
    milestone(1)                       // 走到这就标记"我是最新的"
  }
  steps {
    input message: '确认发布生产？', submitter: 'ops-lead'
    milestone(2)                       // 审批通过后再标记一次
    sh 'deploy.sh'
  }
}

经验：把 milestone 放在 input 前后各一个。前一个起「新的抢跑」作用，后一个确保「批准通过的才算数」。配合 lock 杜绝并发部署。

四、input 人工审批

流水线运行到某处主动暂停，弹出表单等人操作，通过后才继续。是「人在回路」的关键，几乎所有生产发布都需要。

4.1 参数

注意坑：input 本身没有 timeout 参数。要限时必须用 timeout 包裹：timeout(time:30,unit:'MINUTES'){ input ... }，超时则按 timeout 的默认行为（中断）。否则审批窗口会一直开着，executor 也被占着。

4.2 两种写法

写法一：作为 stage 指令（声明式推荐，结构清晰）

stage('发布审批') {
  input {
    message '确认发布到生产？'
    id 'prod-approve'
    ok '批准'
    submitter 'alice,bob'
    submitterParameter 'APPROVER'
    parameters {
      string(name: 'REASON', defaultValue: '', description: '发布原因')
    }
  }
  steps { sh 'deploy.sh' }
}

写法二：作为 step（放在 steps 内，可嵌逻辑）

steps {
  def decision = input(
    message: '是否继续？',
    ok: '继续',
    parameters: [booleanParam(name: 'FORCE', defaultValue: false)]
  )
  if (decision.FORCE) { sh 'force-deploy.sh' }
}

4.3 场景与示例

场景：生产发布前强制二级审批，且只让运维负责人能批，并记录谁批的、为什么批，满足合规审计。

stage('生产发布门禁') {
  input {
    message: '即将发布到 PROD，确认？'
    ok: '确认发布'
    submitter: 'ops-lead,sre'
    submitterParameter: 'APPROVED_BY'
    parameters: [ string(name: 'TICKET', description: '变更单号') ]
  }
  steps {
    echo "由 ${APPROVED_BY} 批准，变更单 ${TICKET}"
    sh 'deploy-prod.sh'
  }
}

五、retry / timeout / waitUntil 容错三件套

流水线跑在真实环境里，会遇到：偶发失败（flaky）、卡死、依赖服务还没起来。这三个步骤分别兜底。

5.1 retry 参数

5.2 timeout 参数

options { timeout(...) } 用在阶段级可设整体上限；timeout(time:..){ steps... } 用在 steps 内可只包裹某个易卡死的命令。

5.3 waitUntil 参数

waitUntil 内放一个返回布尔值的闭包，Jenkins 周期性执行，直到返回 true 或超时。

5.4 场景与示例

场景：① 集成测试偶发超时但重跑就过 → retry；② 某命令可能死循环 → timeout 兜底；③ 刚启动的服务端口还没监听 → waitUntil 轮询就绪。

steps {
  // 1) 重试偶发失败的集成测试
  retry(3) { sh 'make integration-test' }

  // 2) 给可能卡死的步骤上锁死时间
  timeout(time: 10, unit: 'MINUTES') {
    sh './long-migration.sh'
  }

  // 3) 轮询等待服务就绪（最多等 5 分钟）
  timeout(time: 5, unit: 'MINUTES') {
    waitUntil {
      script { return sh(returnStatus: true, script: 'curl -sf http://svc/health') == 0 }
    }
  }
}

注意坑：retry 会重跑整个闭包。如果闭包里有「副作用」（如已发了通知、已建了资源），重试会重复执行——务必保证被重试的逻辑是幂等的。

六、script 逃生舱

声明式流水线语法简洁但有边界：不能用任意循环、动态生成 stage、复杂条件分支。script 块让你在声明式内部「切回 Groovy 全部能力」。

用法与变量作用域

stage('动态逻辑') {
  steps {
    script {
      def targets = ['web','api','worker']      // 块内可见
      def results = [:]
      targets.each { svc ->
        results[svc] = buildJob(svc)              // 调共享库/任意方法
      }
      // 可写复杂 if/循环/异常捕获
      if (results.values().any { it == 'FAIL' }) {
        error('存在失败服务，中止')
      }
    }
  }
}

6.1 场景与示例

场景 A：根据 Git 变更的文件动态决定要构建哪些模块（声明式 when 写不出这种循环）。
场景 B：根据参数 + 外部 API 返回，动态拼出要执行的 stage 列表。

stage('按需构建') {
  steps {
    script {
      def changed = sh(returnStdout: true, script: 'git diff --name-only HEAD~1')
                       .split('\n').toList()
      def modules = changed.collect { it.split('/')[0] }.unique()
      if (modules.isEmpty()) { modules = ['web','api'] }
      modules.each { m ->
        echo "构建模块: ${m}"
        build job: "build-${m}", wait: true
      }
    }
  }
}

原则：能用声明式指令（when / parallel 等）就别用 script；只有当「声明式真的写不出」时才进 script，并保持块小而清晰，便于维护与排错。