jira的插件开发流程实践

　　怎么开头呢，因为本身比较懒，博客一直不怎么弄，之后克己一点，多传点本身遇到的问题和经历上来，供本身之后记忆，也供须要的小伙伴少走点弯路吧

　　最近公司项目须要竞标一个运维项目，甲方给予了既定的几种比较经常使用的平台各司其职，并提出了一些定制化要求，让全部竞标厂商，用一样的平台，一样的环境去POC，其中jira就是一种一部分，而后学习过程就开始了。

　　请让我再多一句题外话，说点心得，咱们要作的事情，和想要作的事情，基本上atlassion官方都给予了文档，无奈，本人的英文实在渣到死，更无奈的是，国内关于jira的文档也比较少，只能硬着头皮去看英文，好好就在，它并无想象中那么难懂，做为一个程序员，一些经常使用的界面，配置文件，只要截图贴出来，基本不须要过多的解释，应该就明白个一二了。为何提这个，由于我知道就是我有心想要把我此次学习中碰到的全部问题都写出来，也确定写不全，最全面的文档还要是回归官方文档的，这篇文章，算是给那些想去了解jira插件开发的小伙伴入个门，省的到官网去，都不知道用什么关键字去搜索相关文档 。

　　好了，围绕思惟三部曲开始吧。

1、what--什么是jira插件

　　jira是什么，就很少介绍了，我想能来看这文章的小伙伴，jira确定是已经接触的，直接回到jira插件上，在我理解看来，jira自己有着很强大的功能，我认为一个成熟项目的强大必定是抽象层面的强大，必定不是实现层面的强大，这才是方便扩展的正确作法，也符合设计模式，或者说，也符合人正常思惟模式。因此，若是你想要定制一块功能，融合进你的业务，确定jira自己提供不了 ，这时候，就须要插件了，好比说，jira界面默认是英文的，咱们确定仍是中文比较看的比较熟悉，想找个汉化的，怎么办，官方提供了不一样版本的汉化包，不一样版本汉化程度也不同，有汉化了98%的，也有汉化了60%，对咱们来讲叫作汉化包比较通俗易懂，实质上，它就是一个插件，更直白一点，就是个jar包，也是经过管理员经过在jira插件页面上传插件安装的，再好比说，jira默认支持的字段类型有这些：

那若是，我想要实现一个功能，在界面上就是一个输入框，点开之后，就弹出来一个另外一个系统的页面，用来勾选参数呢？以下图：

这样的功能，怎么实现呢？ok,插件能够帮助你.固然altassian也有本身的插件商城，有收费也有免费的，至于每一个插件的做用，本身看详细解释吧，以下图：

 

二 、HOW - 如何开发jira插件，这是这篇文章介绍的重心

　　1.首先要开发jira插件，必需要安装altassian的sdk，先给出官方地址，上面详细的介绍了安装的方法

https://developer.atlassian.com/docs/getting-started/set-up-the-atlassian-plugin-sdk-and-build-a-project/install-the-atlassian-sdk-on-a-windows-system

   这地址打开后，你会发现，左边的导航连接有不少，实际上，只要照着它的指导，一篇一篇的作一下，就基本问题不大

   这里简单的描述下步骤：

   ①装JAVA配置环境变量

   ②下载SDK，这里以WINDOWS为例，下载以后是个exe文件，一步一步点下去，设置好本身的安装目录，就能够了

   ③验证SDK是否安装成功，windows下CMD输入atlas-version，若是出现如下界面，表明成功

   ④咱们进到它安装目录里看下结构：

　　理论上，安装完成后，应该有图中的几个目录，忽略我模糊的部分，看下这个目录名称，基本能看到这个sdk由什么构成 ，有maven ,jre,还有bin下各类各样bat文件，ok,进一步联想一下，后面的话，应该会有各类各样的maven指令从中央库去down jar吧。（OK，心理活动就到这里）

 

　　2.到这一步，SDK已经安装完毕，而后让咱们开始开发插件之旅吧，首先咱们得定义一个目录吧，用来放插件代码的位置，为了方便吧，咱们就在当前目录建立一个文件夹 叫作 myPlugin  如图：

　　而后cmd 进入此目录，敲atlas-create-jira-plugin 回车会出现如下界面,这里备注一下，后面会有屡次操做cmd界面的动做，我会一一解释是每一步是用来干吗的，由于我本地已经开发过，中间依赖的jar包已经由maven从atlassian中央库down下来了，第一次若是安装的话，不一样的指令操做可能会触发down jar包的，等等就好（我记得有个web容器的war包，里面包含tomcat中间件，有260M。。。。祝君好运）：

　　这个界面出来以后，是须要咱们继续输入信息的，并非就看看就行，熟悉maven的应该知道即将输入的是什么，这里不对maven的东西作过多赘述了，设置好groupId和artifactid 还有version就行，这里version,它自动会默认生成一个1.0.0-SNAPSHOT快照版本号，若是不想改，继续回车就行，而后会碰到package,这个是指定代码的包名路径的，同version同样，会有默认的值，和上面groupid的设置的值同样，若是不修改的话，继续回车，最后确认上面输入的信息，若是赞成就输入"Y",反之就输入“N”，确认之后，会出现build的过程信息，以下图：

　　出现build success，就表明一个插件工程建立成功，让咱们看下目录结构：

　　这个工程，很显然是个maven工程，ok,那么能够看出来上面执行的atlas-create-jira-plugin指令是什么意思了，至关于按照咱们须要的插件名称，版本等信息，创建一个maven工程,咱们再看下这个目录的深层次结构，这里直接导入eclipse或者intellJ里看吧，更加直观一下如图：

　　能够看到，自动生成了不少文件，咱们能够本身点开看看写了些什么，程序员么，最不缺少的应该就是联想，这几个文件，对java开发来讲，应该都是常见的东西，因此很少作描述了，这里只提一个文件，就是atlassian-plugin.xml ，在继续说以前，我先问一个问题，jira也是一个web工程，引用大量的jar包，其中也有不少是maven工程构建的jar,怎么区分，哪些是插件，哪些不是插件呢？聪明的小伙伴，必定懂我问的意思，没错，就是这个文件，atlassian-plugin.xml，正由于这个文件，因此才能识别它是个插件，固然此文件的做用不只仅是识别功能，咱们能够打开这文件内容看看如图：

　　是否是不懂什么意思？不懂就对了，我也不懂，可是即便不懂，有一些节点的关键字，咱们应该是有一种程序员的敏锐性去理解的，好比i18n，这确定是国际化的资源文件，plugin-info节点确定是对当前插件的一些描述信息，而后有的节点里有location属性，里面的路径，应该就是上图中，须要引用的文件的相对路径，恩，其余的应该看不出来了

　　ok,到这边就算大体对这个工程，有个结构上的熟悉了

　　3.当咱们已经新建好一个插件工程后，下一步咱们就要思考了，咱们要作的这个插件，究竟是要作什么？别急，jira会指导你下一步要作什么，先进入 咱们刚新建的插件工程里，也就是pom.xml所在的那级目录下（E:\Atlassian\myPlugin\MyPlugin），而后敲下atlas-create-jira-plugin-module指令，出现下图：

　　除了down jar包的信息以外，最后跳出了34种plugin module，并须要你继续输入，解释一下，jira支持的插件类型一共就屏幕上列出来的这34种，每一种都有它应该使用的场景，如一开始，我贴图中的，想作一个自定义类型字段的插件，那么应该是什么？看下第4种Custom Field（自定义字段），由于我此次poc的所用到的就两种（还有一种是workflow post function），其余的插件类型，我就不发表意见了，抛砖引玉，回归官网文档上，全部的插件类型，这个只有去官网文档上去找了（关键字就是plugin module,左边的导航栏里有个plugin module index ），上面有很详细的解释，以及属性设置，这里我选4，回车

Enter New Classname MyCustomField:      ----------------------------------让你输入一个类名，默认叫作MyCustomField，我改为TestCustomField

Enter Package Name com.test.zt.jira.customfields: :------------------------输入包名，默认是com.test.zt.jira.customfields，保持默认吧

Show Advanced Setup? (Y/y/N/n) N: :----------------------------是否采用高级安装，这里咱们选择N，以前选过一次Y，还有一大堆要设置的地方，采用默认吧，小伙伴大家选Y能够试一下，根据屏幕的提示，继续定制一下

Add Another Plugin Module? (Y/y/N/n) N: :---------------------------------是否须要在增长一个插件类型？看来，同一个maven工程里，咱们能够增长不少插件类型，这里咱们就简单一点选N ，不须要

而后，就开始build了，截图以下：

　　由于以前已经导入过eclipse里了，因此，不在windows浏览了，直接在eclipse里观察，看看目录结构有什么变化

　　红色部分是新增的文件，看下名字，就是咱们上面在cmd中输入的信息，这边有个编译错误，当个小插曲吧

　　The type java.util.Optional cannot be resolved. It is indirectly referenced from required .class files

 java.util.Optional是1.8才出的特性,项目中maven导入进来时候，却指定的版本是1.5，因此引用jdk有问题吧，由于maven工程建立是由SDK建立的，这里不过多纠结为何是引用1.5了，直接eclipse改为1.8jdk,

　　先看下新增的那个类，TestCustomField.java，也是自动builder，而后继承了TextCFType，咱们先什么都不用改，里面的方法，暂时也不用管什么意思 ，既然是作插件，目的就是快捷，方便二次开发，若是要去完全研究透源码，代价太大了，何况也不现实，jira不开源，即便有开源的地方，也是方便于二次开发的部分。好比rest api，那个是有源码能够参考的。

　　ok,咱们看下最重要的一个文件，atlassian-plugin.xml，多了如下部分：

　　customfield-type这种类型 就是自定义字段类型，里面不少属性 好比name,i18n-name-key 等等，这些应该设置什么值，这里很少数了，仍是那句话，去官网查这种类型的插件相关文档，官方有整个一页的介绍，仍是那句话，抛砖引玉，就和写java同样，随时备着jdk的javadoc，用的时候就去查

　　而后再看下，两个vm文件,由于本人volecity不熟悉，都是现查现用，这两个文件 一个叫edit，一个叫view，顾名思义，一个是编辑的时候，显示的样子，一个是查看的时候显示的样子，这么想没什么概念，可是你联想下ira页面操做的时候，建立问题和编辑问题，还有查看问题这三种行为的时候，而后就能明白一二了，并且，前台这种渲染模板文件采用的是volecity,也不支持什么jsp,html,ftl等，貌似只支持volecity

　　4.OK，至此，插件开发完毕（虽然在这里什么都没作，都是用的默认的代码，将来若是有定制化的话，流程上就须要去改变java类，显示的话就须要vm文件），下面，让咱们将这个插件部署到jira中去，养兵千日，用兵一时，总要在jira上能用起来吧？

　　这边提到两个部署环境，固然，官方没有这些概念，这是我站在开发角度，定义个两个名称吧，第一个叫作正式环境  一个叫作开发环境，前者就是指咱们正常使用的jira环境，正常上传插件，就可使用， 后者是依赖SDK，自动构建出的一个web环境，版本号与SDK版本有关，这就是上面我提到，有个260M左右的web容器，此开发环境是免费的，默认连的它的h2 database,若是要换成其余什么库，好比sqlserver,那么启动后就会提示你须要licence了，因为SDK下的最新，里面的jira版本可能也比较新，破解可能还不大好被破解，因此，这里不麻烦了，采用它默认的h2数据库，

　　好吧，咱们开发的话，可能更多要关注这个开发环境了，首先，要启动这个环境吧。一样，cmd先进入 咱们上面建的插件的根目录，也就是pom.xml所在的目录（为何总是说这个pom.xml，这个pom.xml能够打开看一下，也是别有一番洞天） 输入：atlas-run 或者 atlas-debug 回车  (这些指令从哪里来？还记得sdk安装后的bin目录么，进去看看吧)，而后就是漫长的等待，又开始down jar包 还有那个最恐怖的web容器的包，全部须要的东西都down完以后，就开始启动tomcat了，启动成功后，就能够访问jira了，地址是：http://localhost:2990/jira/ 这里提下，由于是开发，可能须要debug调试，那么就采用atlas-debug启动，默认debug端口是5005

      此刻环境也运行起来了，该将咱们开发的插件，部署到环境中去了，一样，从新开一个cmd先进入 咱们上面建的插件的根目录 敲atlas-mvn package回车，会出现不少打包信息，还有junit测试的信息，由于必需要junti测试经过以后，才能正确打成jar包，这个junit代码，就是上面我贴图中的，test/java包里的代码，junit类也是build自动生成的，若是屡次test不经过，能够直接把代码改改，经过校验，正确打包后，会出现如下界面：

　　打包成功后，会在插件工程的target目录（此目录里的内容一样别有一番洞天，web容器，日志，jira上的全部操做的产生的文件，等等都在这个目录里，介绍不完，大部分还算属于一个正常点web工程运行时结构，因此理解起来的话应该仍是大部分能看懂的）出现jar包信息，如图

　　并会自动部署到tomcat里，能够看到tomcat conlose运行日志 如图：

　　之后若是须要从新部署的话，就执行atlas-mvn package指令就能够，固然插件自己必需要先支持热部署（默认已是true），不然部署是无效的，修改pom.xml以下图：

　　当插件开发完毕，能够上正式环境的时候，就把这个不带tests的jar，经过插件管理页面上传到正式环境就能够正常使用了，这里提下可能会遇到日志可能会报一个错误，也是纠结到死，明明是SDK自动建立出来的代码，运行时竟然报错，报依赖找不到： 

Unsatisfied dependency expressed through constructor argument with index 0 of type [com.atlassian.jira.issue.customfields.persistence.CustomFieldValuePersister]:

　　这个官方也有过说明，看日志也会给你解释的访问地址，缘由仍是内部采用各类spring版本的兼容性问题，这里不赘述了，大概提一下，构造函数的参数上要加上@ComponentImport注解，类上要加上@ExportAsService注解 

　　正常的话，到这里部署完毕，看看jira上面的效果吧：

 

3、why-为何要开发插件？

　　其实，在what中已经提到了，在how中，我作了一个自定类型的字段，可是有那么多种插件类型，针对无数的场景，若是我想在某一个工做流中，想实现某一次提交后，触发另外一个功能（好比，改变某个字段的值，或者调用第三方系统的rest 或者 webservcie，根据返回结果再触发下一个流程等等），这依旧是一个插件类型，上面提到过，叫作workflow post function ，开发插件是为了让咱们的定制化更加深刻，更加符合咱们的需求。当你以为jira现有功能，不能知足你的时候，考虑插件吧，不管是什么场景，我想都应该有对应的解决方案的。

　　最后，仍是那句话，抛砖引玉，但愿这篇文章，能给更多的刚入门的作二次开发的小伙伴们，提供一个入口，不至于像我开始那样，处处找相关的关键字，无从下手。