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現有功能，不能知足你的時候，考慮插件吧，不管是什麼場景，我想都應該有對應的解決方案的。

　　最後，仍是那句話，拋磚引玉，但願這篇文章，能給更多的剛入門的作二次開發的小夥伴們，提供一個入口，不至於像我開始那樣，處處找相關的關鍵字，無從下手。