插件架构与加载机制

本文用于建立 BPMAX 插件开发的整体心智模型，重点解释插件的组成、平台如何加载插件，以及安装与升级时的执行链路。

学习目标

  • 理解 BPMAX 插件的目录结构和职责边界
  • 理解前端、后端、安装脚本和迁移脚本的加载时机
  • 理解插件安装、升级、卸载的基本流程

插件由哪些部分组成

一个标准 BPMAX 插件，通常由以下部分组成：

plugin_task_integration/
├── config.json
├── frontend/
│   └── src/
│       ├── main.ts
│       ├── pages/
│       └── components/
├── server/
│   └── src/
│       ├── controller/
│       ├── service/
│       ├── bootstrap/
│       ├── install/
│       └── config/
└── migrations/

config.json

  • 插件基础信息，如名称、英文名、版本、描述
  • 平台安装、升级、展示插件时使用的元数据
  • 插件安装后写入插件记录的基础来源

其中 en_name 是插件的核心标识。它会被用于：

  • 插件目录命名
  • 安装记录识别
  • 安装脚本和卸载脚本命名
  • 插件升级时识别是否是同一个插件

最小 config.json 例如：

{
  "name": "Task Integration",
  "en_name": "plugin_task_integration",
  "version": "1.0.0",
  "description": "外部任务集成插件"
}

frontend/

  • 插件前端入口文件
  • 路由扩展
  • UI 插槽注册
  • 流程配置组件注册
  • 国际化语言包注册

前端入口不是独立启动一个应用，而是把插件能力注册给平台前端。

server/

  • 插件后端接口
  • 插件服务层
  • 插件模型层
  • Hook 注册
  • 安装与卸载脚本
  • 定时任务

后端目录风格与平台运行环境保持一致。

migrations/

  • 插件独立的数据结构变更
  • 插件升级时需要执行的数据迁移

不是所有插件都需要 migrations/。只有当插件要维护自己的表结构或数据迁移时才需要增加。

平台如何加载插件

开发模式加载

开发模式采用基于 Docker 的本地开发环境。插件代码在本地工程维护，通过编译和文件同步机制注入运行中的平台环境。

整体流程是：

  1. 用 docker-compose 启动本地开发容器
  2. 容器内运行平台环境
  3. 本地插件工程通过挂载方式进入容器
  4. 执行 yarn dev-build-plugin 对当前插件做 watch 和编译
  5. 编译结果被同步到平台运行环境

可以把这条链路理解成：

插件源码 -> watch 编译 -> 构建产物 -> 本地运行环境加载

这种方式的特点是：

  • 适合日常开发调试
  • 平台运行环境与插件开发环境绑定在一起
  • 前端运行的是编译后产物
  • 后端代码会在编译后同步到本地运行环境
  • 与正式运行环境更接近，但仍不等同于安装包安装

安装包模式加载

安装包模式对应正式安装流程。平台大致会执行以下步骤：

  1. 接收插件 zip 包
  2. 解压插件内容
  3. 区分前端、后端、迁移等文件
  4. 写入平台运行环境
  5. 执行安装脚本
  6. 更新插件记录
  7. 触发服务重载
  • 插件包会被平台接收并解压
  • 插件前后端文件会被写入平台运行环境
  • 插件安装脚本会按约定执行
  • 平台会更新插件记录并重载服务

前端加载机制

入口文件

插件前端通常以入口文件作为注册中心。这个文件的职责是注册能力，而不是启动页面框架。

在本地 Docker 开发模式下，前端源码会先经过插件自身的构建流程，再以构建产物的形式进入平台前端运行环境。

路由注册

通过 BPMAX.router.addRoute 注册插件页面。例如：

import TaskDashboard from './pages/TaskDashboard.vue';

BPMAX.router.addRoute({
  path: '/plugin/task-dashboard',
  component: TaskDashboard,
});

这类能力适合：

  • 独立插件页面
  • 配置中心页面
  • 调试或管理页面

UI 插槽注册

通过 BPMAX.ui.register 把组件挂到平台预留插槽中。适合：

  • 给现有页面加按钮
  • 给现有页面增加配置块
  • 在已有列表、详情、操作区中插入插件能力

最小示例如下：

import TaskActionButton from './components/TaskActionButton.vue';

BPMAX.ui.register('Slot.Table.RowActions', TaskActionButton);

流程配置组件注册

流程相关插件通常通过下面两种方式接入平台流程编辑器：

  • BPMAX.flow.metaComponent

  • BPMAX.flow.stepComponent

  • metaComponent：流程级配置

  • stepComponent：环节级配置

国际化消息合并

如果插件需要多语言能力，可以通过 BPMAX.mergeLocaleMessage 注入语言包。现有插件中常见的语言集合包括：

  • en
  • zhCN
  • jaJP

例如：

import zhCN from './languages/zhCN';

BPMAX.mergeLocaleMessage('zhCN', {
  'plugin_task_integration.title': '任务集成',
  ...zhCN,
});

后端加载机制

接口目录约定

插件后端接口通常放在插件后端工程的接口目录下，由平台运行环境按约定识别和加载。

服务目录约定

业务逻辑通常放在服务层目录中。控制器负责：

  • 接收参数
  • 参数校验
  • 调用服务
  • 返回响应

核心业务应尽量放在服务层，避免控制器过重。

Hook 自动注册

平台运行时会初始化 Hook 系统，并准备：

  • think.addPluginHook
  • think.removePluginHook
  • think.emitPluginHook

这意味着插件可以通过约定事件名，把逻辑挂接到平台生命周期中。

定时任务发现方式

定时任务通常放在插件后端工程的定时任务配置目录下，由平台定时任务机制扫描并执行。典型配置如下：

export default {
  cron: '0,15,30,45 * * * *',
  enable: true,
  handle: '/api/plugin_example/auto',
};

插件生命周期

创建

创建新插件时，先复制一个已有插件，再修改 config.json 和目录名。

node create_plugin.js --name={pluginName} --from={copyFrom}

本地开发

本地 Docker 开发模式下，开发阶段通常在插件工程中修改源码，再通过 Docker 环境和开发脚本自动完成编译和拷贝。

其中开发脚本通常会完成两件关键事情：

  • 前端：执行插件前端构建，并输出可供平台读取的产物
  • 后端：监听插件后端源码变化，编译后同步到本地运行环境

安装

正式安装时，平台会接收插件包，把文件写入运行环境并更新插件记录。

升级

如果平台中已经存在同名插件记录，平台会把这次安装视为升级，重点更新：

  • 文件内容
  • 版本号
  • 插件描述和配置元数据

卸载

卸载时通常会：

  • 执行卸载脚本
  • 删除安装写入的文件
  • 把插件记录标记为已删除

推荐阅读