---

一、概述

与任何编程环境一样，在 Jenkins 流水线中，集中化功能、共享公共代码和代码重用都是快速、有效地进行开发的基本技术。这些实践鼓励使用标准方法来调用功能，为更复杂的操作创建构建块并隐藏复杂性。它们还可以用于提供一致性以及鼓励约定优于配置以简化任务。

Jenkins 允许用户完成所有这些操作的 一个关键方法就是，使用共享流水线库。共享流水线库是由存储在代码仓库中的代码组成的，该代码仓库由 Jenkins 自动下载并可供流水线使用。

二、可信库和不可信库

可信库

可信库可以调用/使用 Java 中的任何方法、 Jenkins API 、Jenkins 插件、 Groovy 语言等。对可信库进行更新应该需要适当级别的源码版本控制访问和验证

不可信库

• 不可信代码是被调用和使用限制的代码 调用先前列出的方法类型不允许使用相同的自由度，而且它不能像可信代码那样访问更大的内部对象集合。
• 不可信代码运行在 Groovy 沙箱中，它具有一个可“安全”调用的方法列表。在沙箱中运行时， Jenkins 会监控库代码是否在尝试调用不存在于安全列表中的任何方法。如果是，则停止执行代码并且必须由管理员授予批准。
  

三、内部库与外部库

内部库

这是一种管理库的旧方法，但仍然是一种选择。 Jenkins 包含一个内部 Git 仓库，可用于存储内部库或测试目的。放置在此库中的任何内容对于所有脚本都是可信的，但推送代码到该库的任何人都必须具有相应的管理权限。

内部 Git 仓库有 一个特定的名称： workflowLibs.git 。它可以通过 SSH 访问或 HTTP 访问与 Git 一起工作。

SSH访问

系统管理→全局安全配置

指定一个端口并保存

用户列表

选admin用户

设置

讲linux服务器的公钥粘贴到下方

到linux机器上执行如下命令

git clone ssh://admin@192.168.1.2:22222/workflowlibs.git

HTTP 访问

git clone http://192.168.1.2:8080/workflowLibs.git

一旦复制了 内部仓库 ，它的初始状态为空。要开始使用它，你需要切换到工作目录并创一个新的主分支：

cd workflowLibs/
git checkout -b master

外部库

配置一个外部库

系统管理→系统配置→Global Pipeline Libraries



参数解释：

Name：库的名称（将在脚本中使用它来进行访问）
Default Version:可以是分支或标签
Load implicitly:隐式加载。如果选中，脚本将自动访问这个库，而不需要通过@Library请求它；
Allow default version to be overridden:可以通过在@Library 注解中指定@version 来覆盖默认版本，如@Library('libname@version')_ 
Includ@Library changes in recent job changes:在最近的任务变更集中包含@Library 更改。
		可以通过在注解中添加 changelog = <boolean> 参数来覆盖此设置，如:@Library(value="libname[@version]",changelog=truejfalse)

四、在流水线脚本中使用库

从源码版本控制中自动下载库

加载库到脚本中

如果有内容，那么 workflowlibs 全局内部库将会被自动加载。你可以使用隐式加载复选项指定用于流水线的外部库应该被自动加载。

如果你选择了隐式加载库，你仍然可以使用以下格式的import 语句指定一组方法

//导人 一些方法的合集
import static org.demo.Utilities.*

如果不使用自动加载库的选项，则必须在流水线脚本中使用语句来显式地加载库并使其可用 。有几种不同的方法可以做到这 点

@Library 注解

在基于Java 的语 句中，注解是可以放在代码中以增加（或“注解”）其他代码的元数据。

在使用 Jenkins 流水线语法的情况下，注解结构不仅用作注解， 且能更多地用作另一种语法构造。

具体来说，你可以在流水线脚本中使用 Library 注解来 加载库。要 加载库的名称以及可选的版本都被指定为参数。此处是其基本语法：

@Library ('<libname>[@<version>]')_ [<import statement>]

关于语法有以下要点。

以下是一些简单的示例：

//加载 一个库的默认版本
@Library ('mylib')_ 
//加载一个库的指定版本并覆盖默认版本
@Library('yourlib@2.0')_ 
//用一条语句访 问多个库
@Library(['myLib','yourlib@master')
//带导人语句的注解
@Library('mylib@l.0') import static org.demo.Utilities.*

注解会被放置在脚本的开头，脚本式流水线的 node 行上方，或者声明式流水线中pipeline 上方。

库步骤

从Jenkins 2.7 开始，可以在流水线中使用实际的 library 步骤。语法类似于注解：

library "<libname>[@<version>]"

由于这是 一个实际的流水线步骤，因此可以将其放置在流水线中的任何位置。它还允许使用变 量代替参数。例如，你可以将其定义为从内置 BRANCH_NAME 变量代表的当前任何版本中获取共享库。

library "<libname>@$<BRANCH_NAME>"

库指令

在声明式流水线中，我们还有另 一个用于提取库的选项。我们可以使用 libraries 指令指定要加载的库。在指令中，我们可以使用 lib 语句指定库。

五、Jenkins 项目中的库范围

如果在 Jenkins 全局／根级别指定隐式加载 ，则所 有任务都将自动下载库并且库可用。
但是，如果你配置文件夹并隐式地加载一 个指定的共享库，则只有该文件夹中的任务才能自动下载和访问库

六、共享库代码的结构

一个共享库树有 3个子树：src 、vars和 resources 。

src

此区域旨在使用标准 Java 目录结构的 Groovy 文件进行设置（即src/org/foo/bar.groovy),当执行流水线时，它将被添加到类路径中。

示例一：

创建 一个不包 在类中的简单方怯

在外部库创建groovy文件：src/org/demo/build.groovy

build.groovy的内容：

//org.demo.build.groovy
package org.demo
def mvnBuild(args) {
    sh """
        echo "mvn -q ${args} -Dmaven.test.skip=true"
    """
}

在脚本式流水线中引用：

node() {
    def myBuild = new org.demo.build()
    myBuild.mvnBuild("clean install")
}

示例二：

创建 一个封闭类（以便定义超类） ，然后，你可以在类的构造函数或方法中通过将 steps 对象传递给 一个方法来获取访问所有 DSL 步骤的权限。

src/org/demo/Utilities.groovy

//org.demo.Utilities.groovy

class Utilities implements Serializable {
    def steps
    Utilities(steps) {this.steps = steps}
    def mvnBuild(args) {
        steps.sh """
            echo "mvn -q ${args} -Dmaven.test.skip=true"
        """
    }
}

由于我们将其封装在 一个类中，因此该类必须实现 Serializable 以支持在流水线停 止或重新启动 时能保存状态。
脚本式流水线

@Library('share_library') import org.demo.Utilities
def utils = new Utilities(steps)

node() {
    step([$class: 'WsCleanup'])     //清理工作空间
    utils.mvnBuild "clean install"
}

示例三：

其它项（如环境变量）可以用与步骤相同的方式进行传递。在下面的代码中，我们传入 env 对象并在我 的代码中使用它

src/org/demo/Utilities.groovy

//org.demo.Utilities.groovy

class Utilities implements Serializable {
    def env
    def steps
    Utilities(env,steps) {
        this.env = env
        this.steps = steps
    }
    def mvnBuild(args) {
        steps.sh """
            echo "构建号：${env.BUILD_NUMBER}"
            echo "mvn -q ${args} -Dmaven.test.skip=true"
        """
    }
}

脚本式流水线代码：

@Library('share_library') import org.demo.Utilities
def utils = new Utilities(env,steps)

node() {
    step([$class: 'WsCleanup'])     //清理工作空间
    utils.mvnBuild "clean install"
}

示例四（推荐使用）

对于更简单的情况，你只需传人Script 对象，该对象已经可以访问所有内容。在这种情况下，我们将它传递给静态方法：

src/org/demo/Utilities.groovy脚本

//org.demo.Utilities.groovy
package org.demo

class Utilities {
    static def mvnBuild(script,args) {
        script.sh """
            echo "构建号：${script.env.BUILD_NUMBER}"
            echo "mvn -q ${args} -Dmaven.test.skip=true"
        """
    }
}

脚本式流水线代码

@Library('share_library') import static org.demo.Utilities.*

node() {
    step([$class: 'WsCleanup'])     //清理工作空间
    mvnBuild this, "clean install"
}

vars

你可以在一 个Groovy文件的vars区域 定义可能想要用于流水线 中变量 的任何方法。

示例

vars/timedCommand.groovy

// vars/timedCommand.groovy
def setCommand(commandToRun) {
    cmd = commandToRun
}
def getCommand() {
    cmd
}
def runCommand() {
    timestamps {
        cmdOut = sh(script:"${cmd}",returnStdout:true).trim()
    }
}
def getOutput() {
    cmdOut
}

cmd 和cmdOut 在此处不是字段，而是按需创建的对象。

脚本式流水线代码：

@Library('share_library')_

node() {
    step([$class: 'WsCleanup'])     //清理工作空间
    timedCommand.cmd = 'echo 123'
    echo timedCommand.cmd 
    timedCommand.runCommand() 
    echo timedCommand.getOutput()
}

全局变量的自动文档引用

在vars目录下创建文件timedCommand.txt

内容为：

# 变量文档说明
xxxx

当执行过使用timedCommand变量的流水线后，在流水线语法→全局变量


可以看到有关timedCommand变量的文档说明

像使用步骤一样使用全局变量

你可以创建全局变量定义，其行为类似于流水线脚本中的步骤。也就是说，它们可以像常规流水线步骤 一样被调用 。
解决这个问题的方法是在全局变量的定义中定义 call 方法。

示例一：

vars/timedCommand2.groovy

//vars/timedCommand2.groovy
def call(cmd,logFilePath) {
    timestamps {
        cmdOutput = sh(script:"${cmd}",returnStdout:true).trim()
    }
    echo cmdOutput
    writeFile file:"${logFilePath}", text:"${cmdOutput}"
}

脚本式流水线：

@Library('share_library')_

node() {
    step([$class: 'WsCleanup'])     //清理工作空间
    timedCommand2 'ls -la','test.log'
}

示例二

脚本式流水线

@Library('share_library')_

node() {
    step([$class: 'WsCleanup'])     //清理工作空间
    timedCommandWindow {
    	echo "在Windows上执行"
    }
    timedCommandLinux {
    	echo "在Linux上执行"
    }
}

示例三（推荐使用）

我们可以扩展调用机制来创建 一个简单的框架，使得我们在脚本中使用“步骤”更简单并且更像是具有多个值的标准 DSL 调用

这是通过将参数传递给 一个映射， 并在步骤中的其他处理环节引用映射来实现的。

vars/timedCommand3.groovy

//vars/timedCommand3.groovy

def call(body) {
    //收集赋值并传送到我们的映射中
    def settings= [:]
    body.resolveStrategy = Closure.DELEGATE_FIRST
    body.delegate = settings
    body()

    timestamps {
        cmdOutput = sh(script:"${settings.cmd}",returnStdout:true).trim()
    }
    echo cmdOutput
    writeFile file:"${settings.logFilePath}", text:"${cmdOutput}"
}

通过 def settings = ［］ 语法声明了 一个Groovy 映射。然后将传参保存在映射中，然后我们可以执行任何步骤。这里用于 delegate 的引用与 Groovy能有关。

脚本式流水线：

@Library('share_library')_

node() {
    step([$class: 'WsCleanup'])     //清理工作空间
    timedCommand3 {
        cmd = 'ls -la'
        logfilePath = 'log.out'
    }
}

这种方式最有价值的地方在于，允许我们使用命名参数调用函数，并且无关参数的顺序，这可以使我们的流水线脚本中的代码更简单且更容易理解和维护。

resources

非Groovy 文件可以存储在此目录中。它们可以通过外部库中的 libraryResource 步骤加载。

语法：

def datafile = libraryResource 'org/conf/data/lib/datafile.ext'

六、使用第三方库

七、直接加载代码

groovy调用其它groovy脚本定义的方法

八、从外部 SCM 加载代码

依赖远程 加载器插件 （Pipeline Remote Loader plugin )

九、回放外部代码和库

可以直接修改代码，并点击运行，旨在验证修改的代码，并不会改变原来的代码，主要用于临时验证代码

十、深入研究可信与不可信代码

十一、参考文章

《Jenkins2权威指南》
Jenkins 设置共享库
Jenkins共享库使用