2. 共享库目录结构：vars、src、resources 的作用与规范

Jenkins 共享库的目录结构是版本准入的物理基础。一个标准共享库仓库包含三个顶层目录：vars、src 和 resources。每个目录承载不同职责，遵循不同的加载与作用域规则。理解这三者的分工，是设计可复用、可测试、可准入的共享库的前提。

2.1 目录总览与职责对比

2.2 vars 目录：全局变量与步骤定义

vars 目录是共享库最常用的入口。每个 .groovy 文件定义了一个全局变量或流水线步骤，文件名即变量名。文件内实现 call 方法，Pipeline 脚本可直接调用。

2.2.1 文件命名规范

• 小写驼峰命名： 如 buildDockerImage.groovy、notifySlack.groovy。
• 避免关键字冲突： 不要使用 Jenkins 内置步骤名（如 sh、echo、stage）。
• 可选帮助文档： 同名 .txt 文件（如 buildDockerImage.txt）提供步骤说明，在 Jenkins Pipeline Syntax 中可见。

2.2.2 代码结构规范

// vars/buildDockerImage.groovy
def call(Map config = [:]) {
    // 参数校验
    String imageName = config.imageName ?: error("imageName is required")
    String dockerfile = config.dockerfile ?: 'Dockerfile'
    // 核心逻辑
    sh "docker build -t ${imageName} -f ${dockerfile} ."
}

2.3 src 目录：Groovy 类与面向对象封装

src 目录遵循标准 Groovy 包路径结构，用于封装复杂业务逻辑。类文件通过 import 语句引入，支持继承、接口、静态方法等面向对象特性。

2.3.1 目录与包路径规范

2.3.2 类设计规范

• 单一职责： 每个类只封装一个领域逻辑，如版本校验、Git 操作、制品上传。
• 显式构造函数： 避免使用隐式无参构造，明确参数依赖。
• 静态方法 vs 实例方法： 工具类优先使用静态方法；需要状态管理的场景使用实例方法。

// src/org/team/utils/VersionCheck.groovy
package org.team.utils

class VersionCheck {
    static boolean isSemanticVersion(String version) {
        return version ==~ /^\d+\.\d+\.\d+(-[a-zA-Z0-9.]+)?$/
    }
}

2.4 resources 目录：静态资源管理

resources 目录存放流水线运行时需要的静态文件，如 JSON 配置文件、Shell 模板、YAML 定义等。通过 libraryResource 步骤按需加载。

2.4.1 典型使用场景

• 配置模板： 如 resources/templates/deploy.yaml.tpl，在流水线中填充变量后使用。
• 准入规则文件： 如 resources/rules/version-policy.json，定义版本准入策略。
• 辅助脚本： 如 resources/scripts/pre-check.sh，在节点上执行。

2.4.2 加载方式

// 加载 resources 目录下的文件
def policy = libraryResource 'rules/version-policy.json'
def template = libraryResource 'templates/deploy.yaml.tpl'

2.5 目录规范总结与准入检查清单