(root) +- src # Groovy源文件| +- org | +- foo | +- Bar。groovy # for org.foo.Bar class +- var | +- foo. barGroovy # for global 'foo'变量| +- foo.txt # help for 'foo'变量+- resources #资源文件(仅限外部库)| +- org | +- foo | +- bar。org.foo.Bar的静态助手数据扩展与共享库
目录
由于在组织中越来越多的项目采用管道，可能会出现普通模式。在各个项目之间共享部分管道，以减少冗余并保持代码“干”，这是有用的。［
管道具有支持创建“共享库”，该“共享库”可以在外部源控件存储库中定义并加载到现有管道中。
定义共享库
共享库是用名称、源代码检索方法(如SCM)和可选的默认版本来定义的。该名称应该是一个简短的标识符，因为它将在脚本中使用。
版本可以是SCM所理解的任何内容;例如，分支、标签和提交散列都可以在Git中工作。您还可以声明脚本是否需要显式请求该库(详细内容如下)，或者是否默认存在该库。此外，如果您在Jenkins配置中指定了一个版本，您可以阻止脚本选择必威国际有限公司不同的版本。
指定SCM的最好方法是使用SCM插件，该插件已经被特别更新，以支持一个新的API来检出任意命名的版本(现代供应链管理选项）。截至本文的写作，最新版本的Git和Subversion插件支持此模式;其他人应该遵循。
如果你的SCM插件没有被集成，你可以选择传统供应链管理并选择任何提供的东西。在这种情况下，您需要包含$ {library.yourLibName.version}在SCM配置的某个地方，以便在签出过程中插件将展开该变量以选择所需的版本。例如，对于Subversion，您可以设置存储库URL来svnserver /项目/ $ {library.yourLibName.version}然后使用版本如树干或分支/ dev或标签/ 1.0．
目录结构
共享库的目录结构如下:
的src目录应该看起来像标准的Java源目录结构。在执行pipeline时，将此目录添加到类路径中。
的var目录存放在管道中作为变量公开的脚本文件。文件的名称是管道中变量的名称。如果你有一个文件叫var / log.groovy有一个函数def信息（消息）...在它里面，你可以像这样访问这个函数log.info“Hello World”在进行中您可以在这个文件中放入任意多的函数。阅读下面的例子和选项。
每一个的基名. groovy文件应该是groovy（〜java）标识符，传统上camelCased．匹配。文本，如果存在，可以包含文档，通过系统的配置进行处理标记格式化器(所以可能真的是HTML, Markdown等，尽管。文本扩展是必需的)。此文档将仅在全局变量参考从导入共享库的管道作业的导航侧栏访问的页面。此外，这些作业必须在生成共享库文档之前成功运行一次。
这些目录中的Groovy源文件得到了与Scripted Pipeline中相同的“CPS转换”。
一个资源目录允许该目录libraryResource.要从外部库中使用的步骤以加载相关的非GROOVY文件。内部库不支持此功能。
根下的其他目录保留用于将来的增强功能。
全球共享库
有几个地方可以定义共享库，这取决于用例。管理Jenki必威国际有限公司ns»配置系统»全球管道库可以配置必要的许多库。
因为这些库是全局可用的，所以系统中的任何管道都可以利用这些库中实现的功能。
这些库被视为“可信赖：”它们可以在Java，Groovy，Jenkins内部API，Jenkins插件或第三方库中运行任何方法。必威国际有限公司这允许您定义库中封装在更高级包装器中的单独不安全的API，以便在任何管道中使用。小心任何能够将提交推入这个SCM存储库的人都可以获得对Jenkins的无限访问权必威国际有限公司．你需要总体/ runscripts.配置这些库的权限（通常将授予Jenkins Administrators）。必威国际有限公司
文件夹级共享库
创建的任何文件夹都可以具有与之关联的共享库。此机制允许将特定库的范围范围用于文件夹或子文件夹内的所有管道。
基于文件夹的库不被视为“可信赖：”它们在Groovy Sandbox中运行，就像典型的管道一样。
自动共享库
其他插件可能会在飞行中添加定义库的方法。例如，GitHub分支来源插件提供了一个“GitHub组织文件夹”项目，允许脚本使用不受信任的库，如github.com/someorg/somerepo没有任何其他配置。在这种情况下，将从中加载指定的GitHub存储库主分支，使用匿名结帐。
使用库
标有共享库隐式加载允许管道立即使用由任何此类库定义的类或全局变量。要访问其他共享库，请访问其他共享库必威国际有限公司Jenkinsfile.需要使用@图书馆注释，指定库的名称：
@图书馆（＇我的共享图书馆＇) _/*使用版本说明符，如分支、标签等*/@图书馆（＇my-shared-library@1.0＇) _/*用一条语句访问多个库*/@图书馆（[＇我的共享图书馆＇，＇otherlib@abc1234＇) _注释可以在脚本中Groovy允许的任何地方。当引用类库时(用SRC /目录)，通常注释在进口陈述：
@图书馆（＇somelib＇)进口com.mycorp.pipeline.somelib.ussfulclass.|
对于只定义全局变量的共享库( 不建议 |
图书馆是解决和加载的编译在它开始执行之前的脚本。这允许Groovy编译器了解静态类型检查中使用的符号的含义，并允许它们在脚本中的类型声明中使用：
@图书馆（＇somelib＇)进口com.mycorp.pipeline.somelib.helper.helper.㈡usersomeLib（Helper Helper）{Helper.Prepare（）返回helper.count()} echo useSomeLib(新的帮手（＇一些文本＇）））然而，全局变量在运行时得到解决。
加载动态库
截至2.7版管道:共享Groovy库插件，有一个新的选项来加载(非隐式)库在脚本中图书馆加载库的步骤动态地，在构建期间的任何时间。
如果您只对使用全局变量/函数感兴趣（来自vars /目录），语法非常简单：
图书馆＇我的共享图书馆＇此后，脚本可以访问来自该库的任何全局变量。
使用SRC /Directory也有可能，但更棘手。而@图书馆注释在编译之前准备脚本的“类路径”图书馆步骤中遇到的脚本已被编译。因此你不能进口或者“静态地”引用库中的类型。
但是，您可以动态地使用库类（无需类型检查），从返回值中通过完全限定名称访问它们图书馆的一步。静态可以使用类似Java语法调用的方法：
库(＇我的共享图书馆＇) .com.mycorp.pipeline.Utils.someStaticMethod ()你也可以访问静态字段，并调用构造函数静态命名方法新的：
defuseroomelib（助手）{//动态：无法声明为帮助程序Helper.Prepare（）返回helper.count ()}deflib =库（＇我的共享图书馆＇）.com.mycorp.pipeline.//预检包echo usersomelib（lib.helper.new（lib.constants.some_text））库版本
在选中“屏蔽”时，或者如果流水线仅按名称引用库，则使用“默认版本”@library（'我的共享 - 库'）_．如果“默认版本”为不是定义时，管道必须指定版本，例如@Library (my-shared-library@master) _．
如果在共享库的配置中启用了“允许覆盖的默认版本”，则@图书馆注释也可能会覆盖为库定义的默认版本。如果需要，这也允许库从不同版本加载“隐式”库。
使用时图书馆步骤您还可以指定版本：
图书馆＇my-shared-library@master＇由于这是一个常规步骤，这个版本可能是计算而不是常数与注释;例如：
图书馆＂我的共享图书馆@＄BRANCH_NAME＂会使用与多分支相同的SCM分支加载库吗必威国际有限公司Jenkinsfile.．另一个例子是，你可以通过参数选择一个库:
属性(([[参数字符串(姓名：＇LIB_VERSION＇，默认值：＇主＇)))))图书馆＂我的共享图书馆@$ {参数个数。LIB_VERSION｝＂请注意,图书馆步骤可能不用于覆盖隐式加载的库的版本。它已经加载了脚本启动的时间，并且可能不会加载给定名称的库两次。
检索方法
指定SCM的最好方法是使用SCM插件，该插件已经被特别更新，以支持一个新的API来检出任意命名的版本(现代供应链管理选项）。从本撰写中，Git和Subversion插件的最新版本支持此模式。
传统供应链管理
尚未更新以支持共享库所需的新功能的SCM插件，仍可通过传统供应链管理选项。在这种情况下，包括$ {library.yourlibrarynamehere.version}如果可以为该特定SCM插件配置分支/标记/ ref。这可确保在签出库的源代码期间，SCM插件将展开此变量以检查库的相应版本。
动态检索
如果只指定库名(可以在后面加上版本号)＠） 在里面图书馆步骤，Jen必威国际有限公司kins将寻找一个名称的预先配置的库。（或者在一个情况下github.com/owner/repo.自动库，它将加载。)
但是，您也可以动态地指定检索方法，在这种情况下，不需要在Jenkins中预定义库。必威国际有限公司下面是一个例子:
图书馆标识符：＇自定义 - lib @ master＇，寻回犬：现代人（[＄类：＇gitscmsource.＇，远程：＇git@git.mycorp.com：my-必威国际有限公司jenkins-utils.git＇，credentialsId：＇我的私钥＇]）最好是参考管道语法为您的SCM提供精确的语法。
请注意，库版本必须在这些情况下应加以说明。
写作库
在基础上，任何有效Groovy代码可以使用。不同的数据结构，公用事业方法等，如：
// src / org / foo / point.groovy包裹org.foo.//三维空间中的点类点｛漂浮x, y, z}访问步骤
库类不能直接调用以下步骤上海或Git.．但是，它们可以实现封闭类的范围之外的方法，这反过来调用管道步骤，例如：
// src / org / foo / zot.grovy包裹org.foo.def支票起飞(回购){gitURL.：＂git@github.com：必威国际有限公司Jenkinsci /$ {回购｝＂｝返回这个然后可以从脚本的流水线调用哪个：
defz =新的org.foo.zot（）z.checkoutfrom（repo）这种方法有局限性;例如，它防止声明超类。
或者，一组脚步可以使用这个在构造函数中或只是一种方法到一个库类：
包裹org.foo.类公用事业实施可序列化的｛def脚步公用事业(步骤){这个.steps =步骤}defMVN.（args）{steps.sh＂$ {steps.tool＇Maven.＇｝/bin/mvn - o$ {arg游戏｝＂}}在课程上保存状态时，如上面，此类必须实施可序列化的界面。这可确保使用该类的管道，如下例所示，可以在Jenkins中正确暂停和恢复。必威国际有限公司
@图书馆（＇跑龙套＇)进口org.foo.ulities.defUtils =.新的公用事业（这个）节点{Utils.mvn＇干净的包＇｝如果库需要访问全局变量，例如env，这些应该以类似的方式将这些明确传递到库类别或方法中。
而不是将众多变量从脚本化管道传递到库中，
包裹org.foo.类公用事业｛静态defMVN.（脚本，args）{script.sh＂$ {script.tool.＇Maven.＇｝/bin/mvn - s$ {script.env.home.｝/必威国际有限公司 jenkins.xml - o$ {arg游戏｝＂}}上面的示例显示脚本被传递给一个静态从脚本化管道调用的方法，如下所示：
@图书馆（＇跑龙套＇)进口静态org.foo.utilities。*节点{mvn这个，＇干净的包＇｝定义全局变量
内部，脚本在var目录将按需实例化为单例。这允许在单个中定义多种方法. groovy提交方便。例如：
var / log.groovy
def信息(消息){呼应＂信息：$ {消息｝＂｝def警告(消息){呼应＂警告:$ {消息｝＂｝
必威国际有限公司Jenkinsfile.
@图书馆（＇跑龙套＇）_ log.info.＇开始＇log.warning.＇无事可做!＇请注意，如果您希望在全局中使用一个字段，以某些状态，请将其注释：
@groovy..transform.field.field.defyourField = [:]defyourfunction ....声明性管道不允许在“脚本”块外的对象上调用方法。（必威国际有限公司詹金斯- 42360）。上面的方法需要放入a内脚本指令:
必威国际有限公司Jenkinsfile.
@图书馆（＇跑龙套＇）_管道{代理无阶段{阶段（＇例子＇){步骤{/ / log.info“开始”(1）脚本{(2)log.info＇开始＇log.warning.＇无事可做!＇}}}}}}| 1 | 该方法调用将失败，因为它位于脚本指令。 |
| 2 | 脚本在声明式管道中访问全局变量所需的指令。 |
|
共享库中定义的变量仅显示在全局变量的引用（在下面管道语法）Jenkins必威国际有限公司加载并使用该库作为成功流水线运行的一部分。 |
|
避免在全局变量中保留状态
避免使用交互或保留状态的方法定义全局变量。使用静态类或实例化类的局部变量。 |
定义自定义步骤
共享库还可以定义与内置步骤类似的全局变量，例如 例如，定义上海或Git.．共享库中定义的全局变量必须用所有小写或“凸丝”命名，以便通过管道正确装载。［
问好,文件var / sayHello.groovy应该创建并应该实施一个调用方法。的调用方法允许以类似于步骤的方式调用全局变量：
/ / var / sayHello.groovydef调用（字符串名称=＇人类＇) {//从这个代码可以调用任何有效的步骤，就像在其他//脚本管道回声＂你好，$ {姓名｝．＂｝然后，管道将能够引用和调用这个变量:
问好＇乔＇问好（）/ *用默认参数调用* /如果使用块调用，则调用方法将接收关闭．类型应该明确定义，以阐明步骤的意图，例如:
/ / var / windows.groovydef调用（封闭体）{node（＇视窗＇） { 身体（） } }然后，管道可以像任何接受block的内置步骤一样使用这个变量:
窗户{蝙蝠＂cmd /？＂｝定义更具结构化的DSL
如果您有很多类似的管道，那么全局变量机制提供了一种方便的工具来构建捕获相似度的高级DSL。例如，所有的Jenkins插件都是必威国际有限公司以相同的方式构建和测试的，所以我们可以编写一个步骤名为buildplugin.：
/ / var / buildPlugin.groovydef调用（地图配置){node {gitURL.：＂https://github.com/必威国际有限公司jenkinsci/$ {config.name.｝-plugin.git.＂上海＇MVN安装＇邮件来：＇…＇，主题：＂$ {config.name.｝插件的构建＂，身体：＇…＇}}
必威国际有限公司Jenkinsfile(照本宣科的管道)
buildplugin.姓名：＇Git.＇使用Groovy还有一个“Builder模式”技巧closure.delegate_first.,它允许必威国际有限公司Jenkinsfile.看起来更像一个配置文件，而不是一个程序，但这更复杂，更容易出错，不推荐使用。
使用第三方库
|
虽然可能，访问第三方库 |
通常可以使用第三方Java库，通常在Maven Central.,从信赖库代码使用@抓住注解。参考葡萄的文档有关详细信息，但简单地说：
@抓住（＇org.apache.commons：Commons-Math3：3.4.1＇)进口org.apache.commons.math3.primes.Primes空白并行化(㈡数数） {如果(! Primes.isPrime(计数)){错误＂$ {数｝没有'＂｝/ /……｝中默认缓存第三方库~ / . groovy /葡萄/在Jenkin必威国际有限公司s控制器上。
加载资源
外部库可以从a中加载附件文件资源/目录使用libraryResource.的一步。参数是一个相对路径名，类似于Java资源加载:
def请求= libraryResource＇com / mycorp / pipeline / somelib / request.json＇该文件作为字符串加载，适合传递给特定的api或保存到工作区使用writeFile．
建议使用唯一的包结构，这样就不会意外地与其他库发生冲突。
预测试图书馆更改
如果您在使用不受信任的库的构建中注意到一个错误，只需单击重播链接以尝试编辑一个或多个源文件，并查看生成的构建是否正常行为。满足结果后，请按照“构建状态”页面的“差异”链接，并将差异应用于库存储库并提交。
（即使对于库所要求的版本是一个分支，而不是像标记这样的固定版本，重放构建将使用完全相同的版本作为原始构建：将不会再次检查库源。）
重播目前不支持受信任库。期间也不支持修改资源文件重播．
定义声明式管道
从2017年9月下旬发布的宣言1.2开始，您也可以在共享库中定义声明性管道。这是一个例子，它将根据构建号码是奇数还是偶数来执行不同的声明性流水线
// vars / ervorodd.grovydef调用（㈡buildNumber) {如果（Buildnumber％2==.0）{管线{代理任何阶段{阶段（＇甚至阶段＇){步骤{echo＂构建数是偶数＂}}}}}}别的{管道{代理任何阶段{阶段(＇奇的舞台＇){步骤{echo＂建造号是奇数＂} } } } } }/ /必威国际有限公司 Jenkinsfile@图书馆（＇我的共享图书馆＇）_ exorodd（currentbuild.getnumber（））只有整个管道S可以在此时的共享库中定义。这只能完成var / * . groovy，只有一个调用方法。在单个构建中只能执行一个声明式管道，如果试图执行第二个，则构建将会失败。
请通过此提交您关于此页面的反馈快速形式．
或者，如果您不希望填写快速表格，您可以简单地指示您是否找到此页面有用吗？