Jenkins 插件开发：自定义构建步骤（Java/Groovy）

核心概念

1. 构建步骤本质
   自定义构建步骤需继承hudson.tasks.Builder类，实现perform()方法定义执行逻辑。

2. 关键组件

   • Descriptor类：管理插件配置（UI/持久化）
   • DataBoundConstructor：绑定UI配置参数
   • config.jelly：定义配置界面（Jelly语法）

Java 实现示例

1. 构建步骤类

package io.jenkins.plugins.demo;

import hudson.Extension;
import hudson.Launcher;
import hudson.model.AbstractBuild;
import hudson.model.BuildListener;
import hudson.tasks.BuildStepDescriptor;
import hudson.tasks.Builder;
import org.kohsuke.stapler.DataBoundConstructor;

public class CustomStep extends Builder {
    private final String message; // 配置参数
    
    @DataBoundConstructor
    public CustomStep(String message) {
        this.message = message;
    }
    
    @Override
    public boolean perform(AbstractBuild<?,?> build, Launcher launcher, BuildListener listener) {
        listener.getLogger().println("[自定义步骤] 执行中...");
        listener.getLogger().println("配置消息: " + message);
        // 在此添加核心逻辑（如调用外部工具）
        return true; // true=成功, false=失败
    }
    
    @Extension
    public static final class DescriptorImpl extends BuildStepDescriptor<Builder> {
        @Override
        public String getDisplayName() {
            return "自定义构建步骤";
        }
        
        @Override
        public boolean isApplicable(Class<?> jobType) {
            return true; // 适用于所有任务类型
        }
    }
}

2. 配置文件 (src/main/resources/io/jenkins/plugins/demo/CustomStep/config.jelly)

<?jelly escape-by-default='true'?>
<j:jelly xmlns:j="jelly:core" xmlns:f="/lib/form">
    <f:entry title="显示消息" field="message">
        <f:textbox default="Hello Jenkins!" />
    </f:entry>
</j:jelly>

Groovy 脚本实现（Pipeline 兼容）

// 在 Jenkinsfile 中直接使用
pipeline {
    agent any
    stages {
        stage('Custom Step') {
            steps {
                script {
                    echo "Groovy 自定义步骤"
                    // 调用Java类或直接写逻辑
                    def result = sh(script: 'echo "执行命令"', returnStatus: true)
                    if (result != 0) {
                        error "步骤失败"
                    }
                }
            }
        }
    }
}

开发流程

1. 环境准备

   mvn archetype:generate -Dfilter="io.jenkins-ci.archetypes:"
   

2. 关键操作

   • 调试：mvn hpi:run 启动测试实例
   • 打包：mvn package 生成 .hpi 插件
   • 安装：Jenkins 管理界面 → 上传插件

3. 扩展建议

   • 参数验证：在Descriptor中重写doCheck[FieldName]方法
   • 环境变量：通过build.getEnvironment(listener)获取
   • 文件操作：使用FilePathAPI（跨平台安全路径）

注意事项

1. 兼容性
   在pom.xml中指定最低Jenkins版本：

   <properties>
       <jenkins.version>2.346.3</jenkins.version>
   </properties>
   

2. 日志规范

   • 成功日志：listener.getLogger().println()
   • 错误处理：throw new AbortException("错误描述")

3. 测试要点

   • 模拟AbstractBuild和BuildListener对象
   • 验证配置持久化（重启后参数保留）

完整文档参考：Jenkins Plugin Tutorial