Gymterview
middle

Что такое atlassian-plugin.xml и какие модули плагина существуют?

atlassian-plugin.xml — центральный дескриптор P2-плагина, определяющий метаданные плагина и перечисляющий все модули (точки расширения), которые плагин предоставляет.

Базовая структура

Пример
<atlassian-plugin key="com.example.my-plugin" name="My Jira Plugin"
                  plugins-version="2">
    <plugin-info>
        <description>Описание плагина</description>
        <version>1.0.0</version>
        <vendor name="Example Corp" url="https://example.com"/>
        <param name="plugin-icon">images/plugin-icon.png</param>
        <param name="atlassian-data-center-status">compatible</param>
        <param name="atlassian-data-center-compatible">true</param>
    </plugin-info>
</atlassian-plugin>

Основные типы модулей

Модуль Назначение Пример key
REST Module REST-эндпоинты (JAX-RS) <rest>
Servlet Module HTTP-сервлеты, веб-страницы <servlet>
Web Item Ссылки в UI Jira <web-item>
Web Section Секция для группировки web-items <web-section>
Web Panel HTML-панели в страницах Jira <web-panel>
Web Resource CSS, JS ресурсы <web-resource>
Component Spring-компонент плагина <component>
Component Import Импорт компонента из Jira <component-import>
Workflow Function Расширения workflow <workflow-function>
Custom Field Type Кастомный тип поля <customfield-type>
Listener Обработчик событий <listener>
Report Отчёт <report>
Примеры объявления модулей в XML
<!-- REST Module -->
<rest key="my-rest" path="/myapi" version="1.0">
    <description>REST API плагина</description>
</rest>

<!-- Servlet Module -->
<servlet key="my-servlet" class="com.example.MyServlet">
    <url-pattern>/my-page</url-pattern>
</servlet>

<!-- Web Item -->
<web-item key="my-link" section="jira.issue.tools" weight="100">
    <label>Мой пункт меню</label>
    <link>/plugins/servlet/my-page?issueKey=${issue.key}</link>
    <condition class="com.atlassian.jira.plugin.webfragment.conditions.UserLoggedInCondition"/>
</web-item>

<!-- Web Panel -->
<web-panel key="my-panel" location="atl.jira.view.issue.right.context" weight="200">
    <label>Дополнительная информация</label>
    <resource name="view" type="velocity" location="templates/my-panel.vm"/>
    <context-provider class="com.example.MyPanelContextProvider"/>
</web-panel>

<!-- Web Resource -->
<web-resource key="my-resources" name="Plugin Resources">
    <dependency>com.atlassian.auiplugin:ajs</dependency>
    <resource type="download" name="app.js" location="js/app.js"/>
    <resource type="download" name="styles.css" location="css/styles.css"/>
    <context>atl.general</context>
</web-resource>

<!-- Workflow Function -->
<workflow-function key="my-postfunction"
                   class="com.example.MyPostFunctionFactory">
    <function-class>com.example.MyPostFunction</function-class>
    <orderable>true</orderable>
    <unique>false</unique>
    <resource name="view" type="velocity" location="templates/postfunction-view.vm"/>
</workflow-function>

<!-- Custom Field Type -->
<customfield-type key="my-field" class="com.example.MyCustomField">
    <name>Моё кастомное поле</name>
    <resource name="view" type="velocity" location="templates/field-view.vm"/>
    <resource name="edit" type="velocity" location="templates/field-edit.vm"/>
</customfield-type>

Частые ошибки

  • Дублирование key в модулях — key должен быть уникальным в рамках плагина
  • Объявление component-import для сервисов, которые уже доступны через Spring Scanner @ComponentImport
  • Неправильная секция (section/location) для web-item/web-panel — элемент просто не появляется в UI
  • Отсутствие <condition> для web-item — пункт меню виден всем, включая анонимных пользователей

Как используется в 2026

  • XML-дескриптор остаётся обязательным для P2-плагинов, но содержимое минимизируется за счёт аннотаций
  • Spring Scanner 2.x — стандарт, 1.x считается устаревшим
  • Параметр atlassian-data-center-compatible=true обязателен для публикации на Marketplace
  • Atlassian рекомендует минимизировать количество модулей для ускорения загрузки плагина

На собеседовании: покажите знание основных типов модулей и их назначения. Отметьте, что plugins-version="2" означает формат P2 (OSGi). С Spring Scanner 2.x многие модули (component, component-import) можно объявлять через аннотации, но workflow-function и custom-field-type по-прежнему требуют XML.