Jenkins实践指南-10-Jenkins 插件

6. Jenkin 插件

    Jenkins之所以这么流行，不仅在于本身功能非常齐全，也在于本身插件非常丰富，以下主要介绍平时经常使用的到插件。

6.1 插件安装

    依次点击Manage Jenkins -> Manage Plugins -> Available，搜索插件并安装即可，示意图如下所示：

0601 安装插件.png

6.2 常用插件

6.2.1 Git Parameter

    该插件允许在构建时，选择指定的git分支、标签等，官网地址 ：https://plugins.jenkins.io/git-parameter/。pipeline 示例录下所示：

pipeline {
  agent any
  environment{
     CODE_SUB_DIR_PATH="surpass"
     CODE_GitURL="https://gitlab.surpass.com/surpass/demo.git"
  }
  parameters {
     gitParameter(
        name:"CODE_TAG_BRANCH_NAME",
        type:"PT_BRANCH_TAG",
        branchFilter: "origin/(.*)",
        defaultValue: "test",
        selectedValue:"DEFAULT",
        sortMode:"DESCENDING_SMART",
        useRepository:"${env.CODE_GitURL}",
        description: "请选择branch或tag"
        )
  }
  stages {
    stage("拉取代码"){
           steps{
            checkout([
                    $class:"GitSCM",
                    branches:[[name:"${params.CODE_TAG_BRANCH_NAME}"]],
                    doGenerateSubmoduleConfigurations: false,
                    extensions: [[
                       $class:"RelativeTargetDirectory",
                       relativeTargetDir:"${env.CODE_SUB_DIR_PATH}"
                       ]],
                    gitTool: "Default",
                    submoduleCfg: [],
                    userRemoteConfigs:[[
                       credentialsId:"32eddb12-cd66-444b-859d-ccb61c3864d1",
                       url:"${env.CODE_GitURL}"
                       ]]
                   ]
               )
           }
        }
    }
}

    其主要参数解释如下所示：

• type:主要支持PT_TAG、PT_BRANCH、PT_BRANCH_TAG、PT_REVISION、PT_PULL_REQUEST
• sortMode：主要支持NONE、ASCENDING_SMART、DESCENDING_SMART、ASCENDING、DESCENDING
• useRepository： 默认使用的gitlab仓库地址

6.2.2 build user vars

    通过设置环境变量来获取启动任务的用户名，官网地址：https://plugins.jenkins.io/build-user-vars-plugin/，一般常用于多用户下的Jenkins环境。主要支持的环境变量如下所示：

变量名称	描述信息
BUILD_USER	Full name (first name + last name)
BUILD_USER_FIRST_NAME	First name
BUILD_USER_LAST_NAME	Last name
BUILD_USER_ID	Jenkins user ID
BUILD_USER_GROUPS	Jenkins user groups
BUILD_USER_EMAIL	Email address

    示例用法如下所示：

pipeline{
    agent any
    stages{
        stage("get build user demo"){
            steps{
                script{
                    wrap([$class: 'BuildUser']) {
                      env.BUILD_USER = "${BUILD_USER_ID}"
                   }
                }
            }
        }
        stage("print build  user"){
            steps{
                echo "build user is ${env.BUILD_USER}"
            }
        }
    }
}

6.2.3 Pipeline Utility Steps

    该插件功能非常多，可以用来比较版本大小、查找文件、读取CSV、JSON、YAML等，其官网地址：https://plugins.jenkins.io/pipeline-utility-steps/，我们以读写YAML为示例，如下所示：

def readYamlFile(filePath,imageName){
    if (fileExists(filePath)){
       println("Yaml file path is ${filePath}")
       def data=readYaml(file:filePath)
       println("YAML文件内容：\n${data}")
       def testText=data.spec.template.spec.containers[0][0].image
       data.spec.template.spec.containers[0][0].image=imageName
       println("修改前的镜像地址:${testText}\n修改后的镜像地址:${imageName}")
       return data
    }
    else{
       println("${filePath} not exists,please check !!!")
    }
}

def writeYamlFile(filePath,content,overwrite=true,charset="UTF-8"){
    if (fileExists(filePath)){
        writeYaml(file:filePath,datas:content,overwrite:overwrite,charset:charset)
    }
    else{
       println("${filePath} not exists,please check !!!")
    }
}

6.2.4 HTTP Request

    主要用于发送HTTP请求，比如向企业微信机器人发送消息等，官网地址：https://plugins.jenkins.io/http_request/，HTTP Request支持的参数如下所示：

• url：字符串类型，请示URL地址
• acceptType:枚举类型，HTTP请求Header的Accept的值类型，可以支持的参数如下所示：

- NOT_SET
- TEXT_HTML
- TEXT_PLAIN
- APPLICATION_FORM
- APPLICATION_JSON
- APPLICATION_JSON_UTF8 // 若含中文，需要使用这种方式
- APPLICATION_TAR
- APPLICATION_ZIP
- APPLICATION_OCTETSTREAM

• authentication:字符串类型，使用的是HTTP Basic谁，即用户名+密码这种形式
• consoleLogResponseBody:布尔类型，是否将请求的响应body打印出来
• contentType:枚举类型，HTTP请求的Content-Type值类型，同acceptType
• customHeaders:HttpRequestNameValuePair对象数组，HTTP请求Header部分内容，该对象有3个参数。

name:字符串类型，Header名称
value:字符串类型，Header值
maskValue:布尔类型，是否隐藏Header值。若为true,则打印时使用*代替

• httpMode:枚举类型，HTTP方法，有GET(默认)、HEAD、POST、PUT、DELETE、OPTIONS、PATCH等
• httpProxy:字符串类型，HTTP代理地址
• ignoreSslErrors:布尔类型，是否忽略SSL错误
• requestBody:字符串类型，请求的body内容
• timeout:整理，超时时间，单位为秒。默认为0，代表不设置超时时间
• vaildResponseCodes:字符串类型，代表HTTP请求成功的状态码。其支持3种格式的值

- 单状态值：如200，当收到200状态码，表示HTTP请求成功
- 多状态值：当响应状态码符合多个状态码中的一个时，则代表请求成功，多个状态码之间使用逗号分隔。如200,300
- 范围状态值：格式为"From:To"，如200:302，代表收到200~302的响应状态码都算请求成功

• validResponseContent:字符串类型，假设设置其值为：supass.name，则只有当HTTP返回的内容中包含了supass.name时，才算请求成功。
• quiet:布尔类型，是否关闭所有的日志打印，默认为false
• responseHandle:枚举类型，获取HTTP响应内容的方式，其值可以为：

- NONE：不读取响应内容
- LEAVE_OPEN:当执行完请求后，并不会返回响应内容，而是返回一个打开的inputStream，由你自己决定如何读取响应内容，在使用完之后，需要调用inputStream的close方法关闭
- STRING：默认值，将响应内容转换为一个字符串

• outputFile:字符串类型，请求响应内容的输出路径alue:布尔类型，是否隐藏Header值。若为true,则打印时使用*代替

    示例代码如下所示：

def httpRequestSendMessage(address,method,body){
    def response=httpRequest(url:address,
                           acceptType:"APPLICATION_JSON_UTF8",
                           contentType:"APPLICATION_JSON_UTF8",
                           httpMode:method,
                           requestBody:body,
                           ignoreSslErrors:true,
                           validResponseCodes:"200"
                          )
    println("response.status is:${response.status}\nresponse.content:${response.content}")

6.2.5 Allure

    allure是一个轻量级别的多语言测试报告插件，常用于在自动化测试中以WEB形式展示测试报告，官网地址：https://plugins.jenkins.io/allure-jenkins-plugin/，其示例用法如下所示：

post{
  always{
    script{
       allure([
         includeProperties : false,
         jdk:"",
         properties: [],
         reportBuildPolicy: "ALWAYS",
         report: "${env.ALLURE_REPORT_PATH}",
         results: [[ path: "${env.ALLURE_RESULT_PATH}" ]]
       ])
    }
  }
}

    使用注意事项如下所示：

• report：生成allure最终报告的存储路径，其中默认生成的路径为相对于$WORKSPACE的路径
• results：生成allure的中间数据，即生成的原始报告数据，支持多个路径中间数据，其中默认生成的路径为相对于$WORKSPACE的路径

6.2.6 Active Choices

    Active Choices 插件常用于创建动态交互式参数化插件。其官网地址：https://plugins.jenkins.io/uno-choice/，其主要支持的参数类型有：

• Active Choices Parameter
• Active Choices Reactive Parameter
• Active Choices Reactive Reference Parameter

    Active Choices parameters 允许用户为任务参数选择值，参数值如下所示：

• dynamically generated：动态生成(使用Groovy)
• dynamically updated based on other UI parameters：基于其他UI参数进行更新
• multi-valued：多个值
• rendered with a variety of UI controls, including dynamic HTML：使用多种UI控件渲染，包含动态HTML

6.2.6.1 Active Choices Parameter

• 1.Behavior

    Active Choices parameter 使用Groovy脚本动态生成参数列表

• 2.Rendering

    Active Choices parameters 可以生成标准列表选择、复选框和单选框
    可以生成文本框筛选器来筛选选项

0605 Active Choices Parameter 生成参数类型示意图.jpg

图片来自于：https://github.com/jenkinsci/active-choices-plugin/blob/master/docs/images/001.jpg

6.2.6.2 Active Choices Reactive and Reactive Reference Parameters

• 1.Behavior

    与Active Choices Parameter类似，可以使用Groovy脚本为构建任务动态生成参数选项，当UI控件值发生变更时，也可以动态级联更新。

• 2.Rendering Options

    Active Choices Reactive：可以生成标准列表选择、复选框、单选框和文本框筛选器来筛选选项
    Active Choices Reactive Reference：可以生成HTML列表、HTML输入框、动态生成HTML等

0606 Active Choices Reactive and Reactive Reference Parameters 生成参数类型示意图.jpg

图片来自于：https://cdn.jsdelivr.net/gh/jenkinsci/active-choices-plugin@master/docs/images/002.gif

6.2.6.3 Behavior and Rendering Summary

    以下为三种Active Choices parameter的行为和呈现特征对比

0607 Behavior and Rendering Summary summary.jpg

图片来自于：https://cdn.jsdelivr.net/gh/jenkinsci/active-choices-plugin@master/docs/images/003.jpg

6.2.6.4 Active Choices Parameter 示例

6.2.6.4.1 Active Choices Parameter 示例

    以下为在自由风格中的配置，示例如下所示：

0608 Active Choices Parameter 示例演示.png

    主要参数解释如下所示：

• Name 和 Describe

    与常规Jenkins 参数一致，用于一个参数的名称和描述信息

• Script

    动态生成参数所使用的脚本代码，脚本返回必须为java.util.List、java、java.util.Map

• Fallback Script

    主要提供备用选项，在脚本出错时，使用该值

• Choice Type

    主要提供四种不同的类型选择单选框、复选框、列表单选、列表多选

• Enable Filte

    是否启用筛选搜索

6.2.6.4.2 Active Choices Parameter Rendering示例

• 示例-1

0609 Active Choices Parameter Rendering-01.png

• 示例-2

0610 Active Choices Parameter Rendering-02.png

6.2.6.5 pipeline 示例

    通过自由风格来配置Active Choice非常方便，但迁移起来也非常麻烦的，pipeline示例如下所示：

properties([
  parameters([
    [
      $class: "ChoiceParameter",
      choiceType: "PT_SINGLE_SELECT",
      description:"请选择一个省份",
      filterable: true,
      filterLength: 1,
      name: "Province",
      script: [
         $class: "GroovyScript",
         script:[
            classpath: [],
            sandbox: true,
            script: "return ['江苏','浙江','安徽']"
            ],
         fallbackScript:[
           classpath: [],
           sandbox: true,
           script: "return['错误']"
         ]
      ]
    ],
    [
      $class: "CascadeChoiceParameter",
      choiceType: "PT_CHECKBOX",
      name: "City",
      referencedParameters: "Province",
      script: [
         $class: "GroovyScript",
         script:[
            classpath: [],
            sandbox: true,
            script: '''
                if(Province.equals("江苏")){
                   return ["南京:selected","苏州","无锡","常州"]
                } else if(Province.equals("浙江")){
                   return ["杭州:selected","绍兴","宁波","温州"]
                } else if(Province.equals("安徽")){
                   return ["合肥:selected","芜湖","六安","马鞍山"]
                } else {
                   return ["未知城市"]
                }
            '''
            ],
         fallbackScript:[
           classpath: [],
           sandbox: true,
           script: "return['脚本错误']"
         ]
      ]
   ]
 ])
])

pipeline{
    agent any
    options{
        timestamps()
    }

    stages{
        stage("active choice demo"){
            steps{
                echo "Province is:${params.Province}"
                echo "City is:${params.City}"
            }
        }
    }
}

    运行结果如下所示：

0611 activeChoice pipeline 示例.png

注意事项：sandbox需要配置为true，因Jenkins安全策略限制，若为false，可能配置选项无法显示

    常见的Choice Type 如下所示：

• PT_SINGLE_SELECT：下拉单选
• PT_MULTI_SELECT：列表多选
• PT_CHECKBOX：筛选框
• PT_RADIO：单选框

    源码定义如下所示：

/*
* Constants.
*/
// default choice type
public static final String PARAMETER_TYPE_SINGLE_SELECT = "PT_SINGLE_SELECT";
public static final String PARAMETER_TYPE_MULTI_SELECT = "PT_MULTI_SELECT";
public static final String PARAMETER_TYPE_CHECK_BOX = "PT_CHECKBOX";
public static final String PARAMETER_TYPE_RADIO = "PT_RADIO";

// default choice type
public static final String ELEMENT_TYPE_TEXT_BOX = "ET_TEXT_BOX"; 
public static final String ELEMENT_TYPE_ORDERED_LIST = "ET_ORDERED_LIST";
public static final String ELEMENT_TYPE_UNORDERED_LIST = "ET_UNORDERED_LIST";
public static final String ELEMENT_TYPE_FORMATTED_HTML = "ET_FORMATTED_HTML";
public static final String ELEMENT_TYPE_FORMATTED_HIDDEN_HTML = "ET_FORMATTED_HIDDEN_HTML";

源码链接：https://github.com/jenkinsci/active-choices-plugin/blob/master/src/main/java/org/biouno/unochoice/AbstractUnoChoiceParameter.java

6.2.7 邮件通知

    邮件也是日常Jenkins常用的通知方式，Jenkins默认支持

6.2.7.1 使用Jenkins内置邮件通知功能

    以QQ邮箱演示，操作步骤如下所示：

在配置邮箱时，需要确认所使用的邮箱已经打开SMTP服务

• 1. 设置管理员邮箱，如下所示：

0612 设置Jenkins管理员邮箱.png

• 2、配置SMTP服务器信息

0613 测试邮箱配置.png

• 3、在pipeline中Post部分加入发送邮件配置

pipeline{
    agent any
    options{
        timestamps()
    }

    stages{
        stage("Test e-mail Demo"){
            steps{
                echo "Test e-mail demo"
            }
        }
    }

    post{
        success{
            mail(
                from: "[email protected]",
                to:   "[email protected]",
                body: "This is test Jenkins send e-mail,please don't reply",
                subject: "Test e-mail demo"
                )
        }
    }
}

    主要参数解释如下所示：

• from: 发件人地址
• to:收件人地址
• body:邮件正文
• subject:邮件主题

6.2.7.2 使用E-mail Extension 插件通知

    如果觉得Jenkins内置的邮件功能不能满足要求，也可以试试插件E-mail Extension，其官网为：https://plugins.jenkins.io/email-ext/，其主要特色功能：

• 可以定制收件人列表
• 可以将日志以附件形式进行发送
• 可以发送附件

    E-mail Extension使用步骤如下所示：

• 1、配置SMTP服务器信息，如下所示：

0614 配置E-mail Extension SMTP 信息.png

• 2、在pipeline中Post部分加入发送邮件配置

pipeline{
    agent any
    options{
        timestamps()
    }

    stages{
        stage("Test e-mail Demo"){
            steps{
                echo "Test e-mail demo"
            }
        }
    }

    post{
        success{
            emailext (
                to:   "[email protected]",
                subject: "Test e-mail demo",
                body: """
                       JobName:${env.JOB_NAME}
                       BuildNumber:${env.BUILD_NUMBER}
                       BuildURL:${env.BUILD_URL}
                       View console log url:${env.BUILD_URL}console
                      """,
                compressLog: true,
                attachLog: true,
                recipientProviders: [developers(), requestor()],
                )
        }
    }
}

    运行结果如下所示：

0615 运行结果.png

    emailext的主要参数解释如下所示：

• from:可选，为string类型，发件人地址
• to:可选，为string类型，收件人地址
• subject:为string类型，邮件主题
• body:为string类型，邮件正文
• compressLog：为boolean类型，是否压缩日志
• attachLog：可选，为boolean类型，是否将构建日志以附件形式发送
• attachmentsPattern:可选，为string类型，需要发送的附件的路径，支持ANT风格路径表达式
• recipientProviders：可选，List类型，收件人列表类型

    常用的收件人列表类型如下所示

类型名称	功能解释
developers	此次构建所涉及变更的所有提交者列表
requestor	启动构建任务的人
culprits	引发构建失败的，即最后一次构建成功和最后一次构建失败之间的变更提交者列表

6.2.8 Periodic Backup

    Jenkins本身并不提供备份功能，而是使用插件来进行备份。这里推荐使用插件Periodic Backup(https://plugins.jenkins.io/periodicbackup/)来实现备份。操作步骤如下所示：

• 1.Manage Jenkins -> Periodic Backup Manager 如下所示：

0602 Periodic Backup 备份插件.png

• 2.点击Periodic Backup Manager，进行配置

0603 Periodic Backup 备份配置.png

    主要参数如下所示：

• Backup schedule (cron)

    备份的cron表达式，在配置后，可以点击Validate cron syntax进行校验

• File Management Strategy

    设备备份策略，ConfigOnly仅备份配置文件，FullBackup 全量备份，也可以在Excludes list 使用Ant风格路径表达式，排除不希望进行备份的文件

• Storage Strategy

    备份文件的保存格式。

• Backup Location

    备份文件存放位置。需要对文件夹具有相应的读写权限

• 3.备份成功后，在Restore页面，可以看到最近的备份结果

0604 查看备份结果.png

• 4.若需要还原，选中对应的备份文件，点击Restore selected backup即可。