Hook 机制与平台事件接入

本文介绍 BPMAX 插件体系中的 Hook 机制，包括插件如何注册事件处理逻辑，以及平台如何触发这些 Hook。

学习目标

  • 理解 Hook 的注册与触发机制
  • 理解哪些场景适合使用 Hook
  • 学会设计低耦合的插件扩展方式

Hook 机制概览

Hook 的作用是让插件在不修改平台主流程代码的前提下，挂接额外逻辑。

常见收益：

  • 降低耦合
  • 便于扩展
  • 便于多个插件共享平台事件

Hook 的执行方式

一般流程是：

  1. 平台在运行时准备 Hook 容器
  2. 插件启动时注册事件处理函数
  3. 平台在特定时机触发对应事件
  4. 插件处理函数接收上下文并执行业务逻辑

插件侧接入方式

在插件中注册 Hook

典型写法如下：

think.addPluginHook('workflow.step.active', async function (context) {
  return context;
});

如果需要把 Hook 转给服务层处理，可以写成：

think.addPluginHook('workflow.step.active', async function (context) {
  await think.service('plugin_task_integration_hook').handleStepActive(context);
  return context;
});

在 Hook 中调用插件服务

Hook 回调里不要堆太多业务逻辑，建议尽量转到服务层处理。

例如：

export default class PluginTaskIntegrationHookService extends think.Service {
  async handleStepActive(context) {
    const { step, project } = context;

    if (!step?.plugin_task_integration?.enabled) {
      return;
    }

    await this.service('plugin_task_integration').createTaskFromStep({
      project_id: project.guid,
      step_id: step.guid,
      config: step.plugin_task_integration,
    });
  }
}

Hook 返回值与异常处理

如果 Hook 参与主流程，返回值和异常都会影响调用结果。设计时要先明确：

  • 这个 Hook 是否允许失败
  • 失败后是否应阻断主流程
  • 是否需要降级处理

适合用 Hook 的场景

流程事件

例如环节激活、流转、完成后触发附加动作。

自定义鉴权处理器

适合把第三方鉴权逻辑注册到平台统一调用链中。

组织架构同步

适合监听组织、用户、团队等事件，触发同步或补偿动作。

第三方回调分发

适合在统一回调入口下按事件类型分发给不同插件。

回调分发可以先写成最简单的映射结构：

const callbackHandlers = {
  'task.created': 'handleTaskCreated',
  'task.completed': 'handleTaskCompleted',
};

const method = callbackHandlers[eventType];

if (method) {
  await this.service('plugin_task_integration_callback')[method](payload);
}

不适合用 Hook 的场景

以下场景更适合直接做页面、接口或服务，而不是强行使用 Hook：

  • 纯页面展示
  • 一次性配置保存
  • 简单 CRUD

典型案例

鉴权处理器注册

插件可以通过 Hook 把自定义鉴权逻辑注册给平台的 API 调用链。

组织同步事件

插件可以监听团队、用户、组织相关事件，在平台主流程之外完成同步。

常见问题

Hook 注册了但没有触发

  • 事件名写错
  • 插件未被加载
  • 触发条件未满足

Hook 抛错影响主流程

如果 Hook 参与主流程，就必须提前定义错误策略，避免把非关键附加逻辑变成全局阻塞点。

多个插件同时监听同一事件

这种情况是允许的，但要注意：

  • 执行顺序
  • 共享数据修改
  • 重复副作用

下一步