Jira 的插件系统

本文是对 Jira 的插件系统的调研和总结

插件是软件系统中非常常见的一部分，无论是前后端的开发框架，亦或是我们使用的 IDE、浏览器，或者是我们日常接触到的其他各种软件系统。插件作为一种灵活、可定制和可扩展的软件模块，让用户能够根据自己的需求对软件进行定制化配置和功能增强。它们被设计成可以在不改变主系统代码的情况下添加到主系统中，并能够与主系统进行交互和协同工作。插件可以被视为主系统的补充，通过增加新的功能或修改现有功能，满足用户个性化的需求。

在 SaaS 领域中，插件也扮演着非常重要的角色。它们满足用户对于个性化、定制化、扩展性和协作的需求，使 SaaS 应用程序更加灵活、强大和适应不同用户的需求。同时，插件也为开发者提供了一个扩展和创新的平台，促进 SaaS 生态系统的繁荣和发展。插件对于 SaaS 系统的作用主要体现在以下几点：

• 功能扩展：插件可以为 SaaS 应用程序增加新的功能和特性。用户可以根据自己的需求选择并安装适合的插件，以扩展主系统的功能，满足个性化的业务需求。

• 定制化：插件允许用户根据自己的需求自定义和定制 SaaS 应用程序。用户可以根据自己的偏好和工作流程，选择和配置不同的插件，使系统更符合其独特的业务需求。

• 合作与整合：插件可以促进不同系统和服务之间的协同合作和整合。通过插件，不同的 SaaS 应用程序可以无缝集成和共享数据，提供更加一体化的解决方案，为用户创造更大的价值。

在设计插件体系时，有必要全面考虑开发者、用户和主系统的不同需求。重点是确保开发者能够轻松地开发和管理插件，主系统能够无缝地集成和渲染插件，同时用户能够方便地发现和安装适合自己的插件。一个成熟的插件系统至少要提供以下几个能力：

• 插件开发：需要提供一套完善的开发工具和环境，以支持开发者快速开发、测试和调试插件。这包括生成插件模板、调试工具、API 文档和 SDK 等。

• 插件集成：需要提供简单而强大的集成机制，使开发者可以轻松地将自己的插件集成到主系统中。这包括提供丰富的 API 接口，以及与主系统的数据和功能进行交互的能力。

• 插件市场：需要提供一个插件市场或应用商店，让开发者可以将自己开发的插件发布或销售给用户。这样可以促进插件生态的繁荣，并为用户提供更多选择和增值服务。

接下来，介绍一下 Jira 的插件系统。Jira 是 Atlassian 公司出品的项目与事务跟踪工具，被广泛应用于缺陷跟踪、客户服务、需求收集、流程审批、任务跟踪、项目跟踪和敏捷管理等工作领域。

CLI

Atlassian 的插件需要使用 Forge 平台进行开发，Jira 作为 Atlassian 的一个产品，也同样使用 Forge 来开发插件。在开发之前，首先要安装 CLI 工具，然后完成登陆设置之后，即可开发插件应用程序了。下面，以开发一个简单 Hello World 为例，主要经历以下步骤：

login 使用 Atlassian API token 登陆
create 选择模板即可创建一个插件应用程序
deploy 构建、编译并部署插件应用的代码
install 将已部署的应用安装到具有必要 API 访问权限的站点上

Forge 使用 JSX 语法开发插件应用，比如我们创建一个 IssuePanel 类型的插件应用，实现计数器功能，代码如下：

import ForgeUI, { render, Fragment, Text, IssuePanel, Button, useState, } from "@forge/ui";

const App = () => {
  const [count, setCount] = useState(0);
  return (
    <Fragment>
      <Text>{count}</Text>
      <Button
        onClick={() => {
          setCount(count + 1);
        }}
        text="click"
      />
    </Fragment>
  );
};

export const run = render(
  <IssuePanel>
    <App />
  </IssuePanel>
);

manifest.yml 文件中是关于插件的配置，可以直接使用模版生成的代码，不用做任何修改：

modules:
  jira:issuePanel:
    - key: hello-world-app-hello-world-panel
      function: main
      title: hello-world-app
      icon: https://developer.atlassian.com/platform/forge/images/icons/issue-panel-icon.svg
  function:
    - key: main
      handler: index.run
app:
  id: ari:cloud:ecosystem::app/xxxxxx-xxxx-xxxx-xxx-xxxxxx

把代码 deploy 和 install 之后，在 Jira 的 Issue 面板中可以看到插件应用的效果。

CLI 工具提供了比较丰富的模版，可以快速创建一个模版项目，在生成的模版上来开发插件代码。通过 deploy 或 tunnel 可以迅速查看代码的效果。

统一设计

Forge 提供了两种选项来构建应用程序的用户界面：UI kit 和 自定义 UI。两者主要是使用场景上的差异，UI Kit 则更适合简单的使用情况；自定义 UI 旨在应对复杂的使用情况并提高开发人员的灵活性。

UI kit 用于简单场景的 Forge 应用程序。UI kit 提供了一系列 Atlassian 组件，这些组件的设计风格与主系统保持一致，可以方便开发者构建出统一风格的界面。而 Hooks 和事件处理程序使 UI kit 应用程序能够处理用户交互。虽然这些概念与 React 相似，但是它们两者完全不同，这些代码是在服务器中执行完成后将视图返回，然后将视图渲染到页面上。

自定义 UI 用于较复杂的设计场景，提高了开发人员灵活性。通过自定义 UI，可以使用静态资源（如 HTML、CSS、JavaScript、图标和图像）定义自己的用户界面。Forge 平台托管这些静态资源，使您的应用能够在 Atlassian 产品上显示自定义 UI。自定义 UI 运行在一个 iframe 內，为应用程序的界面提供了一个隔离的环境来展示。

插件渲染

虽然，Jira 的插件渲染分为两种模式，一种是 UI kit 插件渲染，将插件解析成 HTML 元素，然后渲染到页面上，我们可以将其称为「內联渲染」。另外一种是，自定义 UI 通过 iframe 渲染到页面上，我们可以称之为「內嵌渲染」。

內联渲染

Jira 的內联渲染并不是直接将插件的代码在主系统上执行的。它的渲染方式更像一些 no code 页面的实现方式，是通过接口取出一坨 JSON，然后将这些 JSON 数据渲染到页面上。比如上面提到的计数插件，接口会返回下面的数据：

为了方便阅读，在这里将插件的 UI 层级结构数据展开如下：

{
  "type": "render",
  "aux": {
    "type": "View",
    "children": [
      {
        "children": [
          {
            "children": [
              {
                "type": "String",
                "children": [],
                "props": {
                  "text": "0"
                }
              }
            ],
            "key": "Text.0.0",
            "props": {
              "__auxId": "Text.0",
              "format": "markup"
            },
            "type": "Text"
          },
          {
            "children": [],
            "key": "Button.0.0",
            "props": {
              "__auxId": "Button.0",
              "onClick": {
                "componentKey": "Button.0.0",
                "prop": "onClick"
              },
              "text": "click"
            },
            "type": "Button"
          }
        ],
        "key": "IssuePanel.0",
        "props": {},
        "type": "IssuePanel"
      }
    ]
  }
}

不难发现，与代码中的层级结构是一致的。这类 JSON 数据渲染成 UI 在一些可视化搭建页面的场景中是比较常见的，除了将页面渲染成 UI 还要需要考虑如何支持交互事件。

在上面的例子中，当点击 click 按钮的时候，会发现按钮在 loading:

这是因为在点击按钮的时候，Jira 的插件并不会像 React 那样在浏览器上响应事件并触发重新渲染；而是发送一次数据请求，将点击事件以及上下文数据给到服务器，在服务器上响应该事件，将最终的视图以 JSON 数据的形式给到页面渲染出来。比如，在请求中携带的数据如图所示，其中 extensionData 字段中包含了 issue 信息，而在 effects 字段中是当前触发的点击事件信息。

在请求返回的数据中，会将点击后的视图返回，在 JSON 数据里 text 已经由之前的 0 更新为 1。

这种渲染模式，同样也遵循 UI=f(state) 这个公式，只不过这里的 f 是一个 FaaS，通过函数化服务将视图以 JSON 结构化的数据表达出来。这与 React Server Component 以及 Server-Driven UIs 类似，但是在实现上更为彻底，将包括事件在內的所有计算都放在了 FaaS 上，客户端只需将 JSON 解析出 UI 即可。

这么做的好处在于：

• 加载快 在主系统渲染插件的时候，只需加载较少的静态资源；也不需要实例化多个 iframe 上下文；而且还可以根据需要做一些缓存

• 安全性好 所有的权限、安全等都是在 FaaS 里面完成，安全性更高

• 多端适配 只有静态渲染在端上完成，可以较好的处理多端适配的问题

内嵌渲染

对于复杂的场景来说，需要使用自定义 UI 来实现插件，自定义 UI 是通过 iframe 內嵌到在主系统的页面中：

iframe 內嵌存在一些体验问题，比如弹框遮挡等，它比较适合比空间比较大的插件。

数据通信

插件获取上下文数据 

对于 UI kit 插件可以使用 useProductContext 来访问当前插件的上下文数据：

import ForgeUI, { useProductContext, Text, Macro, render } from '@forge/ui';

const App = () => {
  const context = useProductContext();
  return <Text>All info about my context: {JSON.stringify(context)}</Text>;
};

export const run = render(<Macro app={<App />} />);

对于自定义 UI 插件使用 getContext 来访问当前插件的上下文数据：

import { view } from "@forge/bridge";

const context = await view.getContext();

插件监听事件

import { events } from '@forge/bridge';
  events.on('JIRA_ISSUE_CHANGED', (data) => {
  console.log('JIRA_ISSUE_CHANGED (Forge)', data);
});

安全性

Forge 平台通过沙箱环境、数据隔离、身份验证等方式来保证安全性，接下来重点介绍一下沙箱。Forge 通过沙箱化应用程序来控制应用程序的执行。这包括两个主要部分：用户界面安全和应用程序运行时。

用户界面安全 由于自定义 UI 应用程序由 Atlassian 托管，这些应用程序在用户浏览器中沙箱化的环境中运行的静态资源。这些是使用內容安全策略（CSP）实现的，该策略提供了对常见安全漏洞（如跨站脚本攻击（XSS）和数据注入）的保护。使用 UI kit 时，是通过声明式 UI 来构建用户界面，UI 函数的沙箱化可以保证渲染的用户界面更加安全，因为没有应用程序代码在浏览器中执行。这种沙箱化还利用了 Forge 后端基础架构使用的安全性和隔离机制。

应用程序运行时 Forge 运行时将应用程序与其执行环境隔离开来。在独立的环境中运行应用程序，进而限制了应用程序的操作。例如：应用程序无法在不同站点之间意外泄露客户数据；应用程序无法干扰或修改其他正在运行的应用程序。

插件类型

总结来看大约有以下几种类型：

action 菜单，当被点击后会触发弹窗等交互，比如 jira-issue-action

panel 面板，在面板区域內渲染插件內容，比如 jira-issue-panel

page 页面，独立的系统业务页面，比如 jira-project-page

trigger 触发器，包括定时任务、产品事件和 HTTP 请求 三种触发方式

除此之外，还支持 Custom field、background script 等几种方式类型的。

插件市场

插件市场相对来说比较直观。主要是分为两部分，其一是插件的安装和卸载，其二是插件的初始化数据配置或数据授权。这部分不做进一步介绍。

总结

本文主要是通过对 Jira 的一些调研，来介绍一下 Jira 的插件体系，包括 Jira 的插件开发、集成等。它里面的一些实现方式，还是能让人有一些启发。参考如下资料：

• https://www.atlassian.com/

• https://developer.atlassian.com/

• https://www.slideshare.net/GoAtlassian/forge-ui-a-new-way-to-customize-the-atlassian-user-experience

• https://www.youtube.com/watch?v=24OQjUKHqgY&ab_channel=AtlassianDeveloper