jira插件开发和过程中遇到的问题

最近公司要做一个jira系统的一个插件，用来统计公司员工的一个任务分数列表。花了将近一个月的时间，终于做了出来，做的过程遇到很多问题，百度上查找基本没有这方面的资料，很头疼，全是一点一点的查资料尝试解决了。下面把这个开发的流程和遇到的一些问题分享出来，希望能给以后开发的人一些帮助。（ps我开发的系统是mac，和windows上开发差别不大，用wins也可以参考）

进行开发时强烈推荐，把你的项目放到git上面，并且新建两个分支用来开发（dev1，dev2），master分支存放你已经成功开发顺利运行的一个阶段代码，新建的分支用来下一阶段的开发，当你进行摸索，实验的时候把工程搞坏了可以直接从master分支再来，dev1分支可以用来开发后台+前端，dev2可以用来只开发前端，因为在开发过程中后台或前台每次修改都要重启atlas-run，这个重启很费时间，我就新建了分支dev2只用来操作前端，只改前端时可以用命令atlas-cli热部署不用重启，当前端功能测试成功后，就可以把代码整合到dev1分支上，很大提高开发效率（我刚开始就在不断的新建工程，从头开始浪费了很多时间）

下面会有很多链接，大部分需要才能看，基本上都是英文，可以用谷歌翻译和中文差不多。

先整体说下几部分

1.jira插件开发环境的搭建

2.jira插件是由组件(34个组件)组成，根据你的功能需要，选择合适的组件，然后进行逻辑编写

3.对完成的插件进行部署

以上是个整体的过程下面具体说下

1.jira插件开发环境的搭建

https://developer.atlassian.com/server/framework/atlassian-sdk/

上面链接是官方的一个入门教程,先装sdk，再构建项目。试着先跟着教程走一遍，把教程的例子跑成功。下面加几点备注

--a-----------------------------------------

安装sdk的版本要选择和你公司合适的，查看jira版本，jira->设置-->系统-->系统信息里的jira信息里可以查看到

下载sdk，链接右下方可以找到历史版本

https://marketplace.atlassian.com/apps/1210951/atlassian-plugin-sdk-mac-os-x?hosting=server&tab=overview

ps(这里有点很奇怪的是公司用的版本要比这里最新sdk版本对应的jira server版本要高，我没搞懂，只好选择最新的)

--b-----------------------------------------

sdk是jira给开发人员提供的一个开发插件的工具包，包括一些命令，api，和tomcat容器。开发之前先安装好sdk，安装好后看下atlas-version命令信息中的maven环境变量用的是不是sdk安装成功后目录里的maven，因为之前装过maven的，它会使用你系统环境变量中的maven，所以如果不是sdk目录下的请改下maven的环境变量。

--c-----------------------------------------

执行命令atlas-create-jira-plugin构建好项目，用idea/eclipse打开项目可能会报缺少jar包的错，需要按下面的图设置下maven，然后同步，build一下，

--d-----------------------------------------

sdk安装完成后，/bin下面的内容就是开发插件过程中使用到的命令，下面是官方的命令列表有相关说明

https://developer.atlassian.com/server/framework/atlassian-sdk/command-reference/

在按照官方文档执行命令atlas-create-jira-plugin构建项目后，下面命令atlas-create-jira-plugin-module,atlas-run，atlas-debug，atlas-clean，atlas-cli（基本开发只用到这几个命令）时一定要切换到所构建项目的目录下，不然会报下面错误

--e-----------------------------------------

项目构建好后，开始运行，如果你选择的sdk是按照教程选择的版本（6.2.9），运行命令atlas-run后，登陆localhost；2990/jira/，可能会显示jvm内存不足这个错误页面，原因查找是因为jvm内存太小，但jvm内存调大后还是不行，最后找到一个方法就是在atlas-run命令后面加个参数--jvmargs "-Xms512m -Xmx768m"完美解决

如果你选择的是最新的几个sdk版本，（比如我用的6.3.10），可能会出现下面错误,很多jar包找不到(No such file or directory)，这种情况查了很多资料没有找到有效的解决方法，但好消息是并不会影响插件的开发。。。下面给个一种很多人采用的处理的方法(ps我试了不行，不知为何，如果有人成功了还请分享下)

https://confluence.atlassian.com/jirakb/jira-throws-java-io-filenotfoundexception-warnings-after-upgrade-869007981.html

以上是我在安装sdk到构建项目之间遇到的问题，下面会说说对构建项目的一些解释

项目构建完成后，说下项目一些关键的文件

第一部分是项目的资源自己写的js，css，vm文件，看下atlassion-plugin.xml文件，有个web-resouce标签，这代表一个组件。以后新添加的组件都会在这个文件里追加一个标签，下面给出所有的组件类型共34个，以及一些组件的示例教程。文件中还有个resource就是国际化，第一部分里有个.property文件是key/value形式，key就是对应组件中的i18nkey，页面会显示其中的值

https://developer.atlassian.com/server/jira/platform/about-jira-modules/

https://developer.atlassian.com/server/framework/atlassian-sdk/tutorials/

第二部分是webresource标签，里面标签com.atlassian.auiplugin:ajs是jira自带的AUI包依赖。

resource是引用自己写的js，css等，启动项目时会加载

下面是jira自己提供的AUI，用来画页面的一些demo

https://docs.atlassian.com/aui/6.0.9/docs/inline-dialog.html

这里有一点需要强调一下（当时这个问题花了我两天时间找资料解决.....），先打开你的jira项目，浏览器控制台输入AJS.version查看下版本，这个版本就是aui的版本

然后看下上面给的aui链接里面也有很多版本如下图的version图标位置，在你所写的页面引用AUI文档中的一些demo，demo所在的AUI版本不能大于jira项目中的ajs.version版本，不然引用的demo页面样式可能会不生效。

aui文档中打开左侧每个导航栏里都会有个Included in AUI core，和web resource key

如果是not in core记得要把web resource key添加到atlassion-plugin.xml文件的web-resource标签下

比如

第三部分targer文件，是执行atlas-run命令时生成的，就相当于把项目部署到tomcat里跑起来，当执行atlas-clean时这个文件会被清空，jira项目里的数据也会没了。当项目奇怪的运行不成功时可以使用这个命令，清下重新atlas-run。

注意，AJS提供的js语法需要用AJS.$，基本上和js方法是相似的，可以当作js写。

2.

以上的教程顺利完成后，进行下面的操作时，先确定你要做的功能到底是什么样子，在你们公司的jira系统上是什么功能，可以简单画一画，确定后台和前台的大致逻辑。做这步是确定开发的插件要使用哪些组件构成，确定了组件可以只花时间研究你选择的组件，不会盲无目的。下面用我的例子说下。

我的功能是得到公司jira系统中所有用户的问题评估分数，做个列表展示出来，所以首先确定这个功能的入口在jira的哪里显示。

下面是34个组件

查询资料有直接在项目的页面显示的组件13Project Tab Panel，如图入口出会多个插件导航栏，下面是插件的名字

有直接显示在问题页面里的入口，组件8 issue tab panel如下图位置

以上两种，这个链接是我找的一个教程有具体的例子代码可以参考

http://jiradev.com/tutorials.html

下面说下我使用的入口组件是30 web section 和25 web item两种组合

web section中有个location属性填写admin_plugins_menu时把入口设置到jira的插件导航栏下（注意没有"/"符号,单词别写错了），

具体组件的位置可以自己定义的，看下面链接，把location值改成文档中规定的值位置就随之改变

https://developer.atlassian.com/server/jira/platform/administration-ui-locations/

section是目录，item是section目录下的菜单，要把item设置到哪个目录下，需要关联，通过item中的section属性，填写对应的section组件标签的location/section key，如下图，对应的名字是label标签

入口有了，下面说下和入口接入的页面

需要安装组件31webwork plugin，安装后会指定到页面，有点类似struts2，在action中return，会指定到配置文件中的页面issue-success.vm

安装好webwork plugin组件后，下面和入口进行关联，标签web-item中的link中的请求就是定位到webwork中的action，然后转到页面。这里可以添加个权限，在webwork中有个roles-required属性可以填jira系统中规定的权限名字，这样用户是具有这个权限才能访问(这个功能，只适合管理员使用的插件，若是普通用户没权限的这里就不能访问，并且jira不提供自定义权限，所以不能自己定义哪里用户有哪些特例权限，在这里自己可以在代码中写判断的逻辑，看下面的例子)

webwork的入口action可以用来做权限设置，判断用户是否登陆，是否在某个组中，具体如下

（https://docs.atlassian.com/software/jira/docs/api/7.7.1/index.html，这是jira提供的api方法，和

https://docs.atlassian.com/software/jira/docs/api/REST/7.7.1/相对应，要在后台调用jira service功能，需要熟悉两个文档）

action中在引用jira api功能的class类时，需注意两点，1.是要在MyPluginComponentImpl类中加上要action 中引用的类并加上注解@ComponentImport，get，set可以不加

2.是在webwork中的action中引入时加注解@Inject,保险期间加上get，set，如下图

下面是jira中数据的获取，这里也查阅了很多资料才明白，很重要的一部分，可以分为两大方法获取数据，一种是直接使用jira提供的各种service方法，在后台里直接调用。下面是各种service，（可以把7.7.1改成你要用的版本）

https://docs.atlassian.com/software/jira/docs/api/7.7.1/index.html

这个方法很是一脸懵逼，里面的方法根本看不懂之间的关系，我研究了一两天一点没头绪，果断放弃了，下面说下第二种方法

jira rest api是一直jira提供的可以直接发http请求返回json数据的方法，下面链接是所有的请求列表，启动项目后在浏览器直接按照格式输入会返回一串json，不同的版本，会有区别（这里也可以把7.7.1改成你要的版本）

https://docs.atlassian.com/software/jira/docs/api/REST/7.7.1/

下面仔细说下rest/api/2/search这个请求，后面可以跟jql语法进行查询，这个语法和jira系统中问题页面中的筛选器是一样的，所以这个请求可以根据jql语法获取对应的问题数据，注意jira只提供了搜索问题的jql，比如搜索用户，搜索项目不提供这种jql搜索功能（但是搜索的问题json数据中包含项目，和用户数据，所以可以间接获取到的），下面附上jql语法使用教程

https://confluence.atlassian.com/jiracore/blog/2015/07/search-jira-like-a-boss-with-jql

https://confluence.atlassian.com/jiracoreserver073/advanced-searching-861257209.html#AdvancedSearching-FieldsReference

既然jira提供了这种接口，那么我们怎么在后台操作发送请求获取数据呢，下面是网上一个人写的工具类，可以直接拿来使用

他提供了两种方法，我采用的是第二种，比较简单

http://hanqunfeng.iteye.com/blog/2245848

到这里后台就有了方法可以获取到jira中的数据了。

注意：发请求的jql格式和jira系统中的问题筛选器有点区别的，具体看这

https://developer.atlassian.com/server/jira/platform/jira-rest-api-examples/

说下几种特殊的情况

1.jql=.（点）可以获取所有的问题，startAt是从多少个开始，maxResults是查询多少个，当maxResults=-1时是查询所有，但最多只有1000个，如果大于1000也只取1000个数，这两个参数可以用来分页

2.问题的筛选器和http 请求中的jql参数，有区别，有些用&关联有些用+关联，如果会用筛选器，也可以把筛选器中的jql保存到我的收藏里，然后使用http请求/rest/api/2/filter/favourite，获取之前保存的筛选器信息，返回的json中有个参数就是要发送的jql语法，可以直接拿来使用，虽然麻烦点，也是一种解决方法

3.提供一种获取jira中所有用户的方法，发送http请求 rest/api/2/user/search?username=.(点)，同理最大只能是1000个可以分页获取

到这里后台可以获取jira中数据，那怎么和页面关联起来？，前面发送http请求可以直接获取数据，那我在页面调用ajax发送请求也是可以获取到json数据的，但是得到的数据一般不是你想要的格式，所以还要处理，如果在页面用 js处理，逻辑简单点还可以，复杂些的就满足不了了，下面提供一种方法，自己可以新建一个jira rest api，这里要使用组件14Rest Plugin Module，你发送自己定义的请求可以获取你在后台处理过的json数据，下面是教程，包括页面的一些东西（该教程很大程度上帮助了我，希望你们耐心照着教程走一遍，会收获不小）

https://comsysto.github.io/kitchen-duty-plugin-for-atlassian-jira/tutorial/02-step-00-getting-started/

组件完成后就可以在前台发送请求调用自己的rest api然后在页面处理（我写的rest api主要逻辑是获取jira数据，组装成我想要的table body然后显示在页面）

3.

当插件完成后，运行atlas-package打包，targer目录下会生成一个jar，然后到公司jira中的插件管理里上传该jar，成功后就完成了