CI/CD / 系统课时

为共享步骤设计输入参数

为共享步骤设计输入参数

共享步骤如果把镜像名、构建命令或环境信息写死,业务流水线仍会被共享库实现细节绑住。更稳妥的做法是把变化点设计成明确参数,为常用值提供默认值,并在入口处校验必要参数。

学习目标

  • 能区分共享步骤中的必填参数与合理默认值
  • 能使用 Map 为共享步骤设计稳定的调用接口
  • 能在执行副作用操作前完成参数校验

用 Map 承载可变化输入

共享步骤经常会随着业务增加参数。如果采用多个位置参数,调用者必须记住参数顺序,后续插入新参数也容易破坏已有 Jenkinsfile。使用 Map 后,调用处直接写出参数名,可读性和扩展性都更好。

例如封装一个 Maven 构建步骤时,可以让 jdk 和 skipTests 使用默认值,只要求调用者提供真正因项目而变化的 module。

groovy
def call(Map config = [:]) {
    String module = config.module
    String jdk = config.get('jdk', '17')
    boolean skipTests = config.get('skipTests', false) as boolean

    // 必填项在执行 shell 命令前失败,避免产生难定位的半执行状态。
    if (!module?.trim()) {
        error 'buildJava requires parameter: module'
    }

    echo "Building ${module} with JDK ${jdk}, skipTests=${skipTests}"
    String testOption = skipTests ? '-DskipTests' : ''
    sh "mvn -B -pl '${module}' package ${testOption}".trim()
}

这是 vars/buildJava.groovy 的片段示例,依赖 Jenkins Pipeline 运行上下文提供 echo、error 和 sh。module 没有安全的通用默认值,因此设为必填;jdk 和 skipTests 则有明确且可预测的默认行为。

让调用端表达意图

配置好共享库后,Jenkinsfile 只需要声明当前项目与默认策略不同的部分。假设共享库名称为 ci-library,调用可以写成:

groovy
@Library('ci-library') _

pipeline {
    agent any

    stages {
        stage('Build') {
            steps {
                buildJava(
                    module: 'service-api',
                    skipTests: true
                )
            }
        }
    }
}

预期输出

text
Building service-api with JDK 17, skipTests=true

随后 Maven 会执行 mvn -B -pl 'service-api' package -DskipTests,其详细日志取决于实际项目。调用端没有传入 jdk,因此共享步骤使用默认值 17;这种默认值应属于团队明确约定的构建策略,而不是为了少写参数随意指定。

参数校验要靠近入口

共享库越多人使用,越不能依赖调用者自行保证输入正确。必填值缺失时,应在公共步骤入口立即失败,而不是等到 Maven、Docker 或部署工具收到空字符串后才报错。

例如省略 module 后,前面的步骤会调用 Jenkins 的 error 终止当前流水线。

groovy
buildJava(skipTests: true)

预期输出

text
ERROR: buildJava requires parameter: module

这是片段示例,需要放在已经加载共享库且允许调用 buildJava 的 Jenkins Pipeline 上下文中。实际控制台还会包含 Jenkins 生成的阶段和构建日志,因此只需核对错误信息及流水线失败状态。

控制共享接口的变化

参数设计的关键是把业务需要决定的内容与共享库内部实现分开。模块名、目标环境等业务差异适合作为参数;临时文件路径、内部辅助方法等实现细节通常不应暴露给 Jenkinsfile。

新增可选能力时,优先增加带默认值的命名参数,使旧调用仍能保持原行为。删除参数、改变默认语义或把可选参数改成必填参数,则可能破坏已有流水线,应当作为接口兼容性变化处理。

一个稳定的共享步骤应让 Jenkinsfile 说明“我要构建哪个模块、采用哪些策略”,而不是要求业务项目理解共享库内部如何拼接命令。这样才能在不批量修改业务流水线的情况下持续重构共享库实现。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

为共享步骤设计输入参数

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通