CI/CD / 系统课时
为共享步骤设计输入参数
为共享步骤设计输入参数
共享步骤如果把镜像名、构建命令或环境信息写死,业务流水线仍会被共享库实现细节绑住。更稳妥的做法是把变化点设计成明确参数,为常用值提供默认值,并在入口处校验必要参数。
学习目标
- 能区分共享步骤中的必填参数与合理默认值
- 能使用 Map 为共享步骤设计稳定的调用接口
- 能在执行副作用操作前完成参数校验
用 Map 承载可变化输入
共享步骤经常会随着业务增加参数。如果采用多个位置参数,调用者必须记住参数顺序,后续插入新参数也容易破坏已有 Jenkinsfile。使用 Map 后,调用处直接写出参数名,可读性和扩展性都更好。
例如封装一个 Maven 构建步骤时,可以让 jdk 和 skipTests 使用默认值,只要求调用者提供真正因项目而变化的 module。
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,调用可以写成:
@Library('ci-library') _
pipeline {
agent any
stages {
stage('Build') {
steps {
buildJava(
module: 'service-api',
skipTests: true
)
}
}
}
}预期输出
Building service-api with JDK 17, skipTests=true随后 Maven 会执行 mvn -B -pl 'service-api' package -DskipTests,其详细日志取决于实际项目。调用端没有传入 jdk,因此共享步骤使用默认值 17;这种默认值应属于团队明确约定的构建策略,而不是为了少写参数随意指定。
参数校验要靠近入口
共享库越多人使用,越不能依赖调用者自行保证输入正确。必填值缺失时,应在公共步骤入口立即失败,而不是等到 Maven、Docker 或部署工具收到空字符串后才报错。
例如省略 module 后,前面的步骤会调用 Jenkins 的 error 终止当前流水线。
buildJava(skipTests: true)预期输出
ERROR: buildJava requires parameter: module这是片段示例,需要放在已经加载共享库且允许调用 buildJava 的 Jenkins Pipeline 上下文中。实际控制台还会包含 Jenkins 生成的阶段和构建日志,因此只需核对错误信息及流水线失败状态。
控制共享接口的变化
参数设计的关键是把业务需要决定的内容与共享库内部实现分开。模块名、目标环境等业务差异适合作为参数;临时文件路径、内部辅助方法等实现细节通常不应暴露给 Jenkinsfile。
新增可选能力时,优先增加带默认值的命名参数,使旧调用仍能保持原行为。删除参数、改变默认语义或把可选参数改成必填参数,则可能破坏已有流水线,应当作为接口兼容性变化处理。
一个稳定的共享步骤应让 Jenkinsfile 说明“我要构建哪个模块、采用哪些策略”,而不是要求业务项目理解共享库内部如何拼接命令。这样才能在不批量修改业务流水线的情况下持续重构共享库实现。