Jenkins Shared Libraries

官方文档：

https://www.jenkins.io/doc/book/pipeline/shared-libraries/#writing-libraries

pipeline shared-library 通过一个共享的 Library，把共享的方法抽象到一个库里面，供多个 pipeline 使用。

Jenkins Shared Libraries是一种扩展Jenkins Pipeline的技术，通过编写Shared Libraries可以实现自定义的Steps，将流水线逻辑中重复或共通的部分进行抽象和封装。实践中每个DevOps团队都应该通过维护一个或多个Shared Libraries项目再结合第三方的Jenkins插件定制团队自己的Jenkins流水线。

1.Shared Libraries项目初始化

Shared Libraries项目的工程化首先要选型构建工具，这里选择 gradle：

gradle 安装请移步：https://www.cnblogs.com/vitoboy/p/12487648.html

使用 gradle 初始化一个空项目：

mkdir shared-lib

cd shared-lib

gradle init

Select type of project to generate:
  1: basic
  2: cpp-application
  3: cpp-library
  4: groovy-application
  5: groovy-library
  6: java-application
  7: java-library
  8: kotlin-application
  9: kotlin-library
  10: scala-library
Enter selection (default: basic) [1..10] 1

Select build script DSL:
  1: groovy
  2: kotlin
Enter selection (default: groovy) [1..2] 1

Project name (default: shared-lib):

注意这里选择的是1: basic的项目模板，这是因为 jenkins shared lib 项目的目录结构与常见 maven 工程结构不同，所以我们初始化一个空白的 gradle 工程，后边手动配置出项目的具体结构。

根据官方文档 Extending with Shared Libraries 中描述 Shared Libraries 的目录结构：

(root)
+- src                     # Groovy source files
|   +- org
|       +- foo
|           +- Bar.groovy  # for org.foo.Bar class
+- vars 
|   +- foo.groovy          # for global 'foo' variable
|   +- foo.txt             # help for 'foo' variable
+- resources               # resource files (external libraries only)
|   +- org
|       +- foo
|           +- bar.json    # static helper data for org.foo.Bar

一个 shared libraries 项目的标准代码结构由三部分组成：

src目录中是标准的 Groovy 代码
vars目录中是依赖于 Jenkins 运行环境的 Groovy 脚本
resources目录中是静态资源文件

下面按照 shared libraries 项目的标准结构，在前面使用 gradle 创建的空白项目shared-lib创建对应目录src, var, test, resources(这里比标准目录结构多创建了一个 test 目录将用于存放对 shared libraries 的单元测试用例)：

.
├── build.gradle
├── gradle
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradlew
├── gradlew.bat
├── resources
├── settings.gradle
├── shared-lib.iml
├── src
├── test
└── vars

因为shared-lib项目并不遵循标准的 maven 目录结构，所以需要在 build.gradle 中针对源码目录做出配置，下面修改 build.gradle 项目：

plugins {
    id 'groovy'
}

sourceSets {
    main {
        groovy {
            srcDir 'src'
            srcDir 'vars'
        }
        resources {
            srcDir 'resources'
        }
    }
    test {
        groovy {
            srcDir 'test'
        }
    }
}

repositories {
    mavenCentral()
}

targetCompatibility = 1.8
sourceCompatibility = 1.8

configurations {
    ivy
}

tasks.withType(GroovyCompile) {
    groovyClasspath += configurations.ivy
}

dependencies {
    implementation 'org.codehaus.groovy:groovy-all:2.5.7'
    implementation 'com.cloudbees:groovy-cps:1.29'
    def ivyDep = 'org.apache.ivy:ivy:2.4.0'
    ivy ivyDep
    implementation ivyDep

    testImplementation 'com.lesfurets:jenkins-pipeline-unit:1.1'
    testImplementation 'junit:junit:4.12'
    // spock
    testImplementation 'org.spockframework:spock-core:1.3-groovy-2.5'
    testImplementation 'org.objenesis:objenesis:3.0.1'
    testImplementation 'cglib:cglib-nodep:3.2.12'
}

2.使用JenkinsPipelineUnit编写单元测试

下面通过一个简单例子介绍一下JenkinsPipelineUnit单元测试框架的使用。

在vars中创建一个简单log.groovy脚本：

def info(message) {
    echo "INFO: ${message}"
}

def warn(message) {
    echo "WARNING: ${message}"
}

上面的脚本定义了两个全局方法，正常我们在Jenkinsfile中是这样使用：

@Library('shared-lib') _

log.info 'Starting'
log.warn 'Nothing to do!'

如果需要对Shared Libraries进行集成测试，可以编写Jenkinsfile放到Jenkins中创建Job去运行。但实际开发Shared Libraries的过程中我们需要通过大量的单元测试用例去完成单元测试，并达成一定的测试覆盖率。

如果你对Groovy和Spock还不太熟悉，推荐编写JUnit风格的单元测试，因为Groovy是兼容Java的，可以渐进式的学习，写单元测试只是为了达到测试Jenkins Shared Library的目的，选择适合自己的工具即可。不过还是强烈推荐使用Spock编写更简洁的测试代码。

2.1使用JUnit编写单元测试

下面编写log.groovy的单元测试，创建logTest.groovy:

import com.lesfurets.jenkins.unit.BasePipelineTest
import org.junit.Before
import org.junit.Test
import static org.junit.Assert.*;
import static org.hamcrest.CoreMatchers.*;

class logTest extends  BasePipelineTest {

    def log

    @Before
    void setUp() {
        super.setUp()
        log = loadScript("vars/log.groovy")
    }

    @Test
    void logInfo() {
        log.info("info message")
        assertThat(helper.methodCallCount("info"), is(1L))
    }

    @Test
    void logWarn() {
        log.warn("warn message")
        assertThat(helper.methodCallCount("warn"), is(1L))
        printCallStack()
    }

}

通过执行gradle test命令运行单元测试。

2.2 使用Spock编写单元测试

由于JenkinsPipelineUnit并不支持Spock Specification，所以我们编写一个PipelineSpecification集成自spock.lang.Specification，这样后边编写Spock测试类时都继承自PipelineSpecification即可。

import com.lesfurets.jenkins.unit.BasePipelineTest
import spock.lang.Specification

class PipelineSpecification extends  Specification {

    @Delegate BasePipelineTest basePipelineTest

    def setup() {
        basePipelineTest = new BasePipelineTest() {}
        basePipelineTest.setUp()
    }

}

注意上面使用@Delegate将com.lesfurets.jenkins.unit.BasePipelineTest的属性和方法外推到PipelineSpecification，所以在PipelineSpecification的子类中可以直接使用这些属性和方法。

下面是使用Spock编写的logTest.groovy测试：

class logGroovyTest extends PipelineSpecification {

    def log

    def setup() {
        log = loadScript("vars/log.groovy")
    }

    def 'log info'() {
        when:
        log.info("info message")
        then:
        helper.methodCallCount("info") == 1
        helper.callStack.find {call -> call.methodName == 'info'}.args[0] == 'info message'
    }

    def 'log warn'() {
        when:
        log.warn('warn message')
        then:
        helper.methodCallCount('warn') == 1
        helper.callStack.find {call -> call.methodName == 'warn'}.args[0] == 'warn message'
    }
}

3.使用第三方库编写自己的库

接下来将介绍在src目录下使用第三方库开发我们自己的库。在src目录下开发自己的库的需求是肯定存在的，我们在var目录中编写自定义Step时会用到Jenkins及其众多插件目前提供的各式各样的Pipeline Step，但有些需求是这些Step无法提供的。例如，在进行构建容器镜像之前我们可能需要访问Harbor(一个Docker镜像仓库)的API获取一些额外的信息，或者访问其他配置纹理系统的Restful API获取信息，这就需要我们的Shared Libraries中提供HTTP Client的功能，显然这个功能可以放到src目录下，而我们不会白手起家，在src目录下编写这个HTTP Client功能的时候，就会用到第三方库了。

Jenkins Shared Libraries 编写库和自定义Step

前面我们使用gradle初始化了 Jenkins Shared Libraries 的开发框架，目录结果如下：

(root)
+- src                     # Groovy source files
|   +- org
|       +- foo
|           +- Bar.groovy  # for org.foo.Bar class
+- vars
|   +- foo.groovy          # for global 'foo' variable
|   +- foo.txt             # help for 'foo' variable
+- resources               # resource files (external libraries only)
|   +- org
|       +- foo
|           +- bar.json    # static helper data for org.foo.Bar
+- test
|  +- fooTest.groovy  # test for 'foo' variable

在这个开发框架下，我们可以再src目录下使用grovvy编写我们自己的库文件，在vars目录下编写结构化的DSL即我们自定义的Jenkins Pipeline Step。vars目录下自定义的Step可以使用src中自定义库的类。下面是关于官方文档Extending with Shared Libraries 中关于在src下编写库和在var下编写自定义Step的例子：

// src/org/foo/Point.groovy
package org.foo;

// point in 3D space
class Point {
  float x,y,z;
}

// vars/buildPlugin.groovy
def call(Map config) {
    node {
        git url: "https://github.com/jenkinsci/${config.name}-plugin.git"
        sh 'mvn install'
        mail to: '...', subject: "${config.name} plugin build", body: '...'
    }
}

var中自定义的Step，可以再test目录中使用[JenkinsPipelineUnit](https://github.com/jenkinsci/JenkinsPipelineUnit)编写单元测试。

使用第三方库开发我们自己的库

官方文档Extending with Shared Libraries 中给出了一个使用第三方库的例子：

@Grab('org.apache.commons:commons-math3:3.4.1')
import org.apache.commons.math3.primes.Primes
void parallelize(int count) {
  if (!Primes.isPrime(count)) {
    error "${count} was not prime"
  }
  // …
}

注意上面的代码中使用@Grab注释来引入第三库，在默认情况下，第三方库会被缓存到Jenkins主机的~/.groovy/grapes目录下。 Grape使用一个内嵌在Groovy中的jar依赖管理器，通过@Grap注解在以在类路径下快速添加maven风格的依赖，方便我们编写Groovy脚本。更多关于Grape的内容可以查看它的文档Dependency management with Grape，在这里你只需要理解使用@Grap注解引入的第三方库依赖是在运行时运行groovy脚本时需要使用的，而如果使用gradle开发和测试shared libraries项目的话，在开发和测试阶段也要在build.gradle中添加对应的第三方库依赖，这是在开发和测试阶段使用的。

参考

Extending with Shared Libraries
扩展共享库
JenkinsPipelineUnit
https://blog.frognew.com/2019/03/jenkins-shared-libraries.html

Jenkins Shared Libraries

1.Shared Libraries项目初始化

2.使用JenkinsPipelineUnit编写单元测试

3.使用第三方库编写自己的库

参考

你可能感兴趣的:(Jenkins Shared Libraries)