[置顶] jira的插件开发流程实践

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

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

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

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

一、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上面的效果吧：

 

三、why-为什么要开发插件？

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

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