共享库

多个团队、几十个仓库如果各自写一份 Jenkinsfile，很快会出现"同一逻辑四种写法"的混乱。**共享库（Shared Library）**把公共步骤、函数、工具类集中到一个 Git 仓库，所有流水线复用同一份实现。

本篇目标：能搭建一个共享库仓库，编写并引用自定义步骤，理解组织级流水线规范。

---

1. 共享库目录结构

一个共享库本质是一个 Git 仓库，遵循固定目录约定：

shared-library/
├── src/                      # Groovy 类（定义变量、工具类、入口）
│   └── org/example/
│       ├── PipelineUtils.groovy
│       └── Constants.groovy
├── vars/                     # 全局变量（流水线中直接调用的步骤）
│   ├── notifySuccess.groovy
│   ├── notifyFailure.groovy
│   └── deployK8s.groovy
└── resources/                # 资源文件（模板、配置文件）
    └── k8s/deployment.yaml

• vars/：每个 .groovy 文件暴露一个可在流水线直接调用的全局步骤（notifySuccess()）；
• src/：普通 Groovy 类，用 new org.example.X() 或 @Field 引用；
• resources/：可被 libraryResource() 读取的静态文件。

2. 注册共享库

Manage Jenkins → System → Global Pipeline Libraries

Name: my-shared-lib
Default version: main（或分支 / tag）
Source Code Management: Git
Project Repository: https://gitlab.company.com/devops/jenkins-shared-library.git
Credentials: gitlab-token
Load implicitly: 可选（勾选后无需 @Library 直接可用）

用版本号控制共享库

Default version 设为稳定分支或 Tag（如 v1.2.0）。共享库发布新版本 = 打 Tag；要让某仓库用固定版本，流水线里 @Library('my-shared-lib@v1.2.0') _。避免所有人被 main 上未验证的改动影响。

3. 编写共享库步骤

3.1 一个 vars/ 步骤

// vars/notifySuccess.groovy
def call(Map config = [:]) {
    // 从 config 读参数，有默认值
    def channel = config.channel ?: 'default'
    def message = config.message ?: '构建成功'

    // 调用通知 API（示例）
    sh """
        curl -X POST 'http://notify.internal/send' \
          -H 'Content-Type: application/json' \
          -d '{"channel":"${channel}","message":"${message}"}'
    """
}

流水线中调用：

pipeline {
    agent any
    post {
        success { notifySuccess(channel: 'ci', message: "构建 ${BUILD_NUMBER} 成功") }
        failure { notifyFailure() }
    }
}

3.2 src/ 类：封装逻辑

// src/org/example/PipelineUtils.groovy
package org.example

class PipelineUtils {
    static String imageTag(String base, String suffix = '') {
        return "${base}:${suffix ?: 'latest'}"
    }
}

// 流水线中
def utils = new org.example.PipelineUtils()
echo utils.imageTag('registry/app', "v${BUILD_NUMBER}")

3.3 读取 resources 模板

// vars/deployK8s.groovy
def call(Map config) {
    def namespace = config.namespace
    def manifest = libraryResource('k8s/deployment.yaml')
    writeFile file: 'deploy.yaml', text: manifest
    sh "kubectl apply -n ${namespace} -f deploy.yaml"
}

4. 组织级流水线规范

共享库最大的价值是把"团队规范"固化成代码。典型组织级流水线模板：

// Jenkinsfile（每个业务仓库只需这一份）
@Library('my-shared-lib') _

pipeline {
    agent any
    options { timestamps() }
    stages {
        stage('Checkout') {
            steps { checkout scm }
        }
        stage('Build') {
            steps { buildApp() }        // 共享库：编译打包
        }
        stage('Test') {
            steps { runTests() }        // 共享库：单测/集测
        }
        stage('Image') {
            when { branch 'main' }
            steps { buildPushImage() }  // 共享库：构建镜像并推送
        }
        stage('Deploy') {
            when { branch 'main' }
            steps { deployK8s(namespace: 'prod') }
        }
    }
    post {
        always { cleanWs() }
        success { notifySuccess(channel: 'ci') }
        failure { notifyFailure() }
    }
}

规范的好处：

• 新项目接入 = 复制一份模板 Jenkinsfile，不用重写构建逻辑；
• 升级构建工具（如 Maven → Gradle）只改共享库一处；
• 凭证、镜像仓库地址、通知渠道集中配置，业务仓库不感知。

共享库与仓库的边界

共享库放"平台级"通用逻辑（构建工具、部署、通知、扫描）。业务相关的参数（模块列表、环境清单）应放业务仓库的 Jenkinsfile 或配置，不要让共享库写死业务细节。

5. 版本与权限治理

实践	说明
版本化发布	用 Tag 发布，@Library('...@version') 固定版本
灰度验证	先在测试团队用 @Library('...@main') 验证，再打 Tag
代码评审	共享库改动走 MR + 评审，禁止直接 push main
权限最小化	共享库仓库写权限只给平台团队
单元测试	共享库 Groovy 类可配 JUnit 测试，保护核心逻辑

---

6. 练习与验收

练习 A

1. 建一个 jenkins-shared-library 仓库，按标准目录放一个 vars/notifyResult.groovy
2. 在 Manage Jenkins 注册共享库（默认分支 main）
3. 在流水线中 @Library('...') _ 并调用 notifyResult()，确认执行

练习 B

1. 添加一个 src/org/example/ImageHelper.groovy，封装镜像 tag 生成逻辑，在流水线调用
2. 把默认版本改成 v1.0.0，在流水线用 @Library('my-shared-lib@v1.0.0') 固定版本
3. 把 resources/ 里放一个 manifest 模板，用 libraryResource() 读取并渲染

验收清单

• 能搭建共享库仓库并理解 vars / src / resources 的分工
• 会在 Manage Jenkins 注册共享库并设置默认版本
• 会用 @Library 引用共享库，支持版本固定
• 能编写 vars 步骤和 src 类并在流水线调用
• 理解组织级流水线模板 + 共享库的协作模式
• 知道共享库的版本发布与权限治理

下一篇：构建触发与调度。