Jenkins共享库目录规范解析

Jenkins Shared Library 连载学习笔记 · 第 1 天

📚 今日主题：共享库概念入门与目录规范

一、理论知识点

1.1 什么是 Jenkins Shared Library？

Jenkins Shared Library（共享库）是一种代码复用机制，允许将通用的流水线逻辑、函数、类封装成可复用的模块，在多个 Pipeline 项目中共享调用。

核心价值：

• ✅ 消除流水线代码重复
• ✅ 统一企业级 CI/CD 规范
• ✅ 降低维护成本
• ✅ 提升流水线安全性与可测试性

1.2 共享库目录结构规范

shared-library/
├── vars/                    # 全局变量/函数目录
│   ├── myBuild.groovy       # 可直接在 Pipeline 中调用的函数
│   └── deploy.groovy
├── src/                     # Groovy 源代码目录（包结构）
│   └── com/
│       └── example/
│           └── utils/
│               └── Helper.groovy
├── resources/               # 静态资源文件（JSON/YAML/配置）
│   └── config.json
├── test/                    # 单元测试目录
│   └── vars/
│       └── myBuildTest.groovy
└── Jenkinsfile              # 共享库自身的测试流水线

关键区别：

二、实操步骤

2.1 创建第一个共享库函数（vars 目录）

文件路径： vars/helloWorld.groovy

// vars/helloWorld.groovy
// 可直接在 Pipeline 中通过 helloWorld() 调用

def call(String name = 'DevOps') {
    echo "👋 Hello, ${name}! Welcome to Jenkins Shared Library."
}

return this

在 Pipeline 中调用：

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

pipeline {
    agent any
    stages {
        stage('Demo') {
            steps {
                script {
                    helloWorld('Jenkins')  // 直接调用，无需前缀
                }
            }
        }
    }
}

2.2 配置共享库（Jenkins 全局配置）

1. 进入 Jenkins → 系统管理 → 系统配置
2. 找到 Global Pipeline Libraries
3. 添加新库：
   • Name: my-shared-library
   • Default version: main 或 master
   • Retrieval method: Modern SCM (推荐 Git)
   • Project repository: https://github.com/your-org/shared-library.git

2.3 使用 @Library 注解加载

// 方式 1：加载默认版本
@Library('my-shared-library') _

// 方式 2：加载指定分支/标签
@Library('my-shared-library@v1.0.0') _

// 方式 3：加载多个库
@Library(['lib1', 'lib2@feature-branch']) _

三、生产踩坑清单

四、【深度进阶对比】

📌 第 1 天 vs 前置基准（常规 Pipeline）

易混淆点辨析：

• ❌ 误区： vars/ 和 src/ 可以混用
• ✅ 正解： vars/ 用于全局函数（无需 import），src/ 用于类（需 import 包路径）

明日预告： 第 2 天将深入 src/ 包类开发，学习 Groovy 类编写、import 机制、@NonCPS 注解使用。

五、今日核心代码汇总

// ✅ 完整可运行示例：vars/standardBuild.groovy

def call(Map config = [:]) {
    def projectName = config.get('projectName', 'unknown')
    def buildType = config.get('buildType', 'maven')
    
    echo "🚀 开始构建项目：${projectName}"
    echo "📦 构建类型：${buildType}"
    
    if (buildType == 'maven') {
        sh 'mvn clean package -DskipTests'
    } else if (buildType == 'npm') {
        sh 'npm install && npm run build'
    }
    
    echo "✅ 构建完成：${projectName}"
}

return this

调用方式：

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

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                script {
                    standardBuild(projectName: 'my-app', buildType: 'maven')
                }
            }
        }
    }
}

📝 学习建议： 今日内容为基础概念，建议在本地搭建 Jenkins 测试环境，实际创建共享库仓库并验证调用流程。明日将进入代码开发阶段，难度提升。