gh_mirrors/je/jenkins-library开发者手册：贡献代码、扩展步骤与测试策略

【免费下载链接】jenkins-library Jenkins shared library for Continuous Delivery pipelines. 项目地址: https://gitcode.com/gh_mirrors/je/jenkins-library

gh_mirrors/je/jenkins-library是一个强大的Jenkins共享库，专为持续交付流水线设计。本手册将指导开发者如何贡献代码、扩展流水线步骤以及实施有效的测试策略，帮助你快速融入项目并提升开发效率。

项目概述：Jenkins共享库的核心价值 🚀

Jenkins共享库是实现CI/CD流水线复用的关键组件，而gh_mirrors/je/jenkins-library（以下简称Jenkins Library）更是为开发者提供了丰富的预定义步骤和灵活的扩展机制。通过使用该库，团队可以显著减少重复代码，标准化流水线流程，并快速适应不同项目的需求。

图1：Jenkins Library（Project "Piper"）与SAP CICD解决方案的对比，展示了灵活性与简洁性的平衡

核心特性

• 丰富的预定义步骤：涵盖从代码检查、构建到部署的全流程，如mavenBuild、dockerExecute等
• 灵活的扩展机制：支持多级别定制，从简单配置到完全自定义流水线
• 跨平台支持：兼容多种开发环境和工具链
• 完善的文档：详尽的开发指南和示例，位于documentation/DEVELOPMENT.md

贡献代码：从环境搭建到PR提交 🔧

贡献代码是参与开源项目的核心方式。以下是完整的贡献流程，帮助你顺利提交你的第一个PR。

开发环境准备

1. 基础工具安装

   • 安装Go（版本需与go.mod中指定的一致）
   • 安装Groovy和Maven（用于Jenkins相关开发）
   • 推荐使用VS Code并安装Go插件

2. 代码仓库克隆

   git clone https://gitcode.com/gh_mirrors/je/jenkins-library
   cd jenkins-library
   

3. 环境配置

   • 设置Git用户信息
   • 配置SSH访问GitCode
   • 安装EditorConfig插件以保持代码风格一致

贡献流程

1. 创建分支

   git checkout -b feature/your-feature-name
   

2. 代码开发

   • 遵循项目编码规范
   • 编写单元测试
   • 确保代码通过静态检查

3. 提交代码

   • 遵循约定式提交规范
   • 签署Developer Certificate of Origin (DCO)

4. 创建PR

   • 推送到你的fork仓库
   • 在GitCode上创建Pull Request
   • 等待代码审查并根据反馈修改

⚠️ 注意：所有PR必须通过CI检查，包括单元测试和代码风格检查。详细贡献指南请参考CONTRIBUTING.md。

扩展流水线步骤：三级扩展方案 🔩

Jenkins Library提供了灵活的扩展机制，满足不同场景的定制需求。根据复杂度和复用范围，可以选择以下三种扩展方式：

图2：Jenkins Library的三级扩展方案，从简单配置到完全自定义流水线

1. 配置级扩展（推荐新手）

通过配置文件修改流水线行为，无需编写代码：

• 修改项目配置：在.pipeline/config.yml中设置步骤参数

  general:
    buildTool: maven
  steps:
    mavenBuild:
      goals: clean install
  

• 使用自定义默认值：通过customDefaults参数指定自定义配置文件

2. 阶段级扩展

通过编写Groovy脚本扩展特定阶段：

• 创建扩展文件：.pipeline/extensions/<stageName>.groovy
• 示例：自定义构建阶段

  void call(Map params) {
    echo "Custom build stage"
    params.originalStage() // 调用原始阶段实现
    // 添加自定义逻辑
  }
  return this
  

3. 完全自定义流水线

对于特殊需求，可以完全自定义Jenkinsfile：

@Library('jenkins-library') _

node {
  stage('Checkout') {
    checkout scm
  }
  stage('Build') {
    mavenBuild goals: 'clean install'
  }
  // 更多自定义阶段...
}

测试策略：确保代码质量 🧪

完善的测试是保证流水线稳定的关键。Jenkins Library采用多层次测试策略，包括单元测试、集成测试和端到端测试。

单元测试

• Go代码测试：使用Go内置测试框架，测试文件命名为<filename>_test.go

  go test -tags=unit ./cmd/...
  

• Groovy代码测试：使用Spock框架，测试文件位于test/groovy/

集成测试

• 位于integration/目录
• 使用Docker容器模拟真实环境
• 运行集成测试：

  ./integration/run-tests.sh
  

测试最佳实践

1. Mock外部依赖：使用接口或全局函数指针模拟外部系统
2. 并行测试：使用t.Parallel()提高测试效率
3. 测试覆盖率：目标覆盖率>80%
4. 边界测试：测试错误处理和边界条件

配置管理：层次化配置策略 ⚙️

Jenkins Library采用层次化配置，允许从不同来源合并配置参数，优先级从高到低为：

图3：Jenkins Library的配置层次结构，展示了参数的来源和优先级

1. 步骤参数：直接在步骤调用中传递

   mavenBuild(goals: 'clean install', flags: '-DskipTests')
   

2. 项目配置：.pipeline/config.yml

3. 自定义默认配置：通过customDefaults指定

4. 库默认配置：库内置的默认值

配置示例

# .pipeline/config.yml
general:
  gitSshKeyCredentialsId: git-ssh-key
steps:
  githubPublishRelease:
    uploadAssets:
      - 'target/*.jar'

常见问题与解决方案 ❓

Q: 如何调试流水线步骤？

A: 可以使用VS Code进行调试：

1. 编译带调试信息的二进制：go build -gcflags "all=-N -l" -o piper
2. 配置.vscode/launch.json
3. 设置断点并启动调试

Q: 如何添加新的流水线步骤？

A: 遵循以下步骤：

1. 在resources/metadata/中创建步骤元数据YAML文件
2. 运行go generate生成代码框架
3. 在cmd/目录中实现步骤逻辑
4. 编写测试并更新文档

Q: 贡献的代码需要满足哪些要求？

A: 主要要求包括：

• 遵循项目编码规范
• 提供单元测试
• 签署DCO
• 通过CI检查
• 代码审查通过

总结：成为Jenkins Library贡献者 🎉

通过本手册，你已经了解了如何贡献代码、扩展流水线步骤以及实施测试策略。Jenkins Library是一个活跃的开源项目，欢迎每一位开发者的贡献。无论是修复bug、添加新功能还是改进文档，你的参与都将帮助项目不断发展。

开始你的贡献之旅吧！如有疑问，可以查阅开发指南或在项目中创建issue寻求帮助。

---

本手册基于gh_mirrors/je/jenkins-library项目编写，如需了解更多细节，请参考项目源代码和官方文档。

【免费下载链接】jenkins-library Jenkins shared library for Continuous Delivery pipelines. 项目地址: https://gitcode.com/gh_mirrors/je/jenkins-library