「Jenkins Pipeline」- 在 Jenkinsfile 中使用共享库 @20210202

在Jenkins中，若是共享库被标记为 Load implicitly ，这容许 Pipeline 当即使用共享库中的类和全局变量。

方法1、使用注解（@Library）

要访问其余的共享库，须要在Jenkinsfile中使用@Library注解来指定库名：

@Library('my-shared-library') _

/* Using a version specifier, such as branch, tag, etc */
@Library('my-shared-library@1.0') _

/* Accessing multiple libraries with one statement */
@Library(['my-shared-library', 'otherlib@abc1234']) _

只要符合Groovy语法规范，注解能够写在脚本中的任何地方。当使用类库（src/）时，一般注解会后续import语句：

@Library('somelib')
import com.mycorp.pipeline.somelib.UsefulClass

# 对于仅定义全局变量（vars/）的共享库，或仅须要使用全局变量的 Jenkinsfile 文件，注释模式 @Library('my-shared-library') _ 可能对于保持代码简洁有用。
# 在本质上，符号 _ 是注解，而不是注释一个没必要要的import语句。

# 不建议 import 全局变量/函数，由于这会强制编译器将字段和方法解释为静态（static），即便它们意图须要实例化。 
# 在这种状况下，Groovy 编译器可能会产生使人困惑的错误消息。

在编译脚本期间进行库的解析并加载，这在库开始执行以前。这容许Groovy编译器理解“在静态类型检查中使用的符号”的含义，并容许它们在脚本中的类型声明中使用。例如：

@Library('somelib')
import com.mycorp.pipeline.somelib.Helper

int useSomeLib(Helper helper) {
    helper.prepare()
    return helper.count()
}

echo useSomeLib(new Helper('some text'))

可是全局变量在运行时获得解析。

方法2、动态加载（library）

从 Pipeline: Shared Groovy Libraries 插件的2.7版开始，在脚本中加载（非隐式）共享库有一个新方式：一个library步骤，能够在构建期间的任什么时候间动态加载库。

对于全局变量

若是只对使用全局变量/函数感兴趣（来自 vars/ 目录），则语法很是简单：

library 'my-shared-library'

此后，脚本能够访问该库中的任何全局变量。

对于类库

这种方法也能够直接使用类（src/），可是麻烦一些。由于库在执行以前，它在脚本编译期间进行了加载和解析。注解@Library在编译期间准备脚本的“classpath”。可是在执行到library时，脚本已经被编译，所以你不能再进行import操做或“静态”引用库中的类型。

可是能够动态地使用库的类（不进行类型检查），从library步骤的返回值经过彻底限定名称访问它们。可使用相似Java的语法调用静态方法：

################################################################################
# 使用类库中的静态方法
################################################################################
library('my-shared-library').com.mycorp.pipeline.Utils.someStaticMethod()

################################################################################
# 你也能够访问「static」字段
# 而且调用构造器，就好像定义了一个名为「new」的「static」方法
################################################################################
def useSomeLib(helper) { // dynamic: cannot declare as Helper
    helper.prepare()
    return helper.count()
}
def lib = library('my-shared-library').com.mycorp.pipeline // preselect the package
echo useSomeLib(lib.Helper.new(lib.Constants.SOME_TEXT))

共享库的版本

Default version

（1）在共享库的配置中，当勾选 Load implicitly 选项时，会使用 Default version 选项。
（2）或者在 Pipeline 中只经过名称引用共享库（@Library('my-shared-library') _），也会使用 Default version 选项。
（3）若是在共享库的配置中，没有定义 Default version 选项，则 Pipeline 必须明确指定版本（@Library('my-shared-library@master') _）。

Allow default version to be overridden

启用 Allow default version to be overridden 后，能够在@Library中覆盖默认的版本。这也容许「Load implicitly」的库加载不一样的版本。

library

使用 library 步骤也能够指定版本：library 'my-shared-library@master'

能够经过变量指定版本：library "my-shared-library@$BRANCH_NAME"，测试分支使用测试分支的共享库，能够实现多分支不一样配置。

还能够从parameters中动态获取分支：

properties([parameters([string(name: 'LIB_VERSION', defaultValue: 'master')])])
library "my-shared-library@${params.LIB_VERSION}"

注意，虽然能够在@Library中覆盖默认的版本，可是library步骤可能没法用来覆盖隐含加载的库的版本：由于在脚本启动时已经加载了库，给定名字的库没法加载两次；

拉取共享库的方法

取回共享库可使用 SCM Plugin ，将 SCM Plugin 升级到支持新API的版本，以支持任意命名版本（Modern SCM）。目前（04/25/2019）GIT和SVN支持该功能。

对于旧的SCM插件

在这种状况下，能够为该特定 SCM Plugin 的branch/tag/ref任何地方配置${library.yourlibrarynamehere.version}参数。 这样能够确保在检出库的源代码时， SCM Plugin 会扩展此变量以检出适当的库版本。

动态取回

library identifier: 'custom-lib@master', retriever: modernSCM([
   $class: 'GitSCMSource',
   remote: 'git@git.mycorp.com:my-jenkins-utils.git',
   credentialsId: 'my-private-key'
])

参阅「Pipeline Syntax」来获取精准的语法。！！！库的版本必须指定！！！

关于取回方法

有关取回共享库的细节参考官方的「Retrieval Method」文档。

参考文献

WikiNotes/在 Jenkinsfile 中使用共享库Extending with Shared Libraries/Using libraries