Jenkins - 共享库（Shared Libraries）

1 - 由来与演进

在Jenkins 1.x中，对于job的配置大多是基于图形界面的，也就是说，要在GUI页面手动设置相关的job参数。
随着不同类型和用途的job越来越多，参数越来越复杂，难以有效地管理数量庞大的图形界面配置信息，也无法有效追踪和记录配置的更改。

在Jenkins 2.0中，基于Pipeline，用户可以在一个 JenkinsFile 中快速实现一个项目的从构建、测试以到发布的完整流程，灵活方便地实现持续交付。
并且通过“pipeline script from SCM”方式，可以保存这个流水线的定义，进行版本化管理。

在实际使用中，一开始大都会制作一个尽可能通用的pipeline脚本样例，让搭建者只需要修改几个赋值参数就可以在项目中应用。
但不可避免的是，不同的项目往往有不同的需求，随着定制化需求越来越多，加入了不同的功能实现代码，导致pipeline也会越来越复杂，可读性差，也不利于维护。
而且随着pipeline数目不断的增多，将会发现同一类型和用途的pipeline，它们的很多功能其实是相同的，这时如果对某个功能做改动，往往需要更新数量众多的JenkinsFile。

针对pipeline的扩展和管理问题，共享库功能（Shared Libraries）应运而生。
共享库可以将整个pipeline脚本的实现和复杂度封装到Shared Library中，在各种项目之间共享pipeline核心实现，减少冗余代码。
也就是说，Shared Libraries的方式抽象了各种项目之间共享的代码（甚至整条完整的pipeline），有效降低了使用pipeline的复杂度。
而且通过外部源代码控制（SCM）的方式，保证所有job在构建的时候会调用最新的共享库代码。

简而言之，共享库（Jenkins Shared Library） 是一个可以在 Jenkins Pipeline 中共享和重复使用的代码库。
通常在版本控制系统中存储和维护 Pipeline 代码的公共部分，并将其作为其他 Pipeline 的依赖项进行加载，在多个 Jenkins 实例上共享

2 - 目录结构

共享库中存储的每个文件都是一个groovy的类，每个文件（类）中包含一个或多个方法，每个方法包含groovy语句块。
Shared Library遵循固定的代码目录结构：

+- doc  # 存放帮助文档和示例信息
|   +- ReadMe.md
|   +- doc.txt
+- src                     # Groovy source files，存放共享代码，例如类和辅助函数，需要先导入才能在pipeline中使用
|   +- org
|       +- foo
|           +- Bar.groovy  # for org.foo.Bar class
+- vars  # 存放pipeline中使用的函数，可以全局使用且无须导入
|   +- foo.groovy          # for global 'foo' variable
|   +- foo.txt             # help for 'foo' variable
+- resources               # resource files (external libraries only)，存放流水线中使用的资源（配置文件、Shell脚本等）
|   +- org
|       +- foo
|           +- bar.json    # static helper data for org.foo.Bar

src目录：

• 标准的Java源目录结构，存放编写的groovy类，执行流水线时，此目录将添加到类路径
• 存放一些特定的功能实现，文件格式为.groovy

vars目录：

• 存放可从Pipeline访问的全局脚本(标准化脚本)，这些脚本文件在流水线中作为变量公开
• 使用驼峰（camelCased）命名方式，文件格式为.groovy
• 在.groovy文件中，可以通过import的方式，引入src目录的类库

resources目录：

• 从外部库中使用步骤来加载相关联的非Groovy文件

doc目录：

• 存放pipeline的相关文档说明
• 一般包含ReadMe.md文件

3 - 使用共享库

3.1 全局设置

涉及插件：Pipeline: Groovy 和Pipeline: Groovy Libraries,用于配置共享库。

选择新增共享库

填写共享库名称和版本信息

填写共享库的链接信息

3.2 全局共享库

• Manage Jenkins >> Configure System >> Global Pipeline Libraries
• 可以添加一个或多个全局可用的共享库，也就是说任何Pipeline都可以利用这些库中实现的功能。
• 通过配置SCM，可以保证在每次构建时都能获取到指定Shared Library的最新代码
• 需要为共享库设置一个名称，便于在Jenkinsfile中引用，并且设置一个默认版本
  

3.3 非全局共享库

• 可以为文件夹和任务的配置中单独指定Pipeline Libraries
• 如果在多个级别的文件夹或目录都配置了Pipeline Libraries，最终生效的是最小级别的配置
  

4 - 加载与引用

• 标记为Load implicitly的共享库允许流水线立即使用任何此库定义的类或全局变量。
• 为了访问其他共享库， Jenkinsfile 需要使用 @Library 注解， 指定库的名字。
• 通过import 语句引用类库时 (在 src/ 目录下)
• 对于只定义了全局变量 (vars/)的共享库, 或者只需要一个全局变量的 Jenkinsfile 文件, 注解模式@Library('my-shared-library') _有助于保持代码简洁。
• 不建议 import 一个全局变量/函数, 由于这将强制编译器 将字段和方法解释为 static。

5 - 参考信息

• https://www.jenkins.io/zh/doc/book/pipeline/shared-libraries/
• https://www.cnblogs.com/yehewudi/p/12699971.html