「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