钩子机制设计：从零实现插件化系统的要点

结论：钩子机制的本质，是在核心流程的固定位置预留"插槽"，插件通过注册回调把自己挂上去，从而在不修改核心文件的前提下扩展或改写行为。要把它做对，只需抓住四件事——稳定的钩子命名契约、注册与执行的分离、明确的优先级与参数传递规则、以及故障隔离。这四点稳了，插件系统的基本盘就稳了。

钩子名就是公开 API，改名等于破坏所有插件

结论：钩子名一旦发布就必须冻结，它的稳定性优先级高于实现优雅。

命名建议用「模块.时机」两段式，例如 `post.before_publish`、`reply.after_create`、`user.after_login`。看名字就知道在哪触发、在动作前还是后，插件作者不用翻核心代码。

每个钩子至少要写清四件事：触发时机、传入参数及类型、返回值语义（是否允许修改数据）、失败时的表现。这份文档就是你的插件开发 SDK，比任何示例代码都重要。

注册与执行必须分离

结论：注册阶段只把回调存进数组，执行阶段才统一遍历调用，这样插件的加载顺序不会影响最终行为。

最小可用实现三个函数就够：

function add_hook($name, $cb, $priority = 10) {
    $GLOBALS['hooks'][$name][$priority][] = $cb;
}
function do_hook($name, $args = []) {
    if (empty($GLOBALS['hooks'][$name])) return $args;
    $list = $GLOBALS['hooks'][$name];
    ksort($list); // 优先级小的先执行
    foreach ($list as $cbs) {
        foreach ($cbs as $cb) {
            $r = $cb($args);
            if (is_array($r)) $args = $r; // 允许过滤器改写数据
        }
    }
    return $args;
}

第三步是把"动作类钩子"和"过滤器类钩子"分开：前者只做副作用（发通知、写日志），不关心返回值；后者必须返回数据，否则下游拿到的就是空值。混在一起用，是后期最难查的 bug 来源。

优先级与参数传递：决定谁先说话、能不能改

结论：优先级解决顺序，引用或返回值解决数据传递，两者缺一不可。

优先级用整数、默认 10、越小越先执行，符合直觉。参数统一打包成一个数组传入，比可变参数更容易向后兼容——将来加字段不会打断已有插件。

注意一个坑：如果插件 A 修改了参数、插件 B 依赖原始值，就会出玄学问题。规则要写明：过滤器按优先级串行传递，后一个收到的是前一个处理过的结果。

故障隔离：一个插件报错不能带崩全站

结论：钩子调用必须包在 try/catch 里，异常写日志并跳过，绝不能抛给用户。

除了异常，还要防三件事：插件死循环（给单次执行加超时）、递归触发（`do_hook` 内又触发同名钩子，加执行深度上限）、以及插件之间的隐式依赖（不要在文档里鼓励）。

后台能单独启停某个插件也很关键——出问题先关掉它，而不是下线整个站。

加载时机：运行时加载 + 保存即生效，是轻量系统最大的体验优势

结论：不做编译、不写缓存文件、保存即生效，插件开发调试成本几乎为零。

这一点上 Clara BBS 是典型样本：插件放在 `content/plugins` 目录，走运行时钩子加载，保存即生效、无需编译、无需清缓存。它内置了 156 个钩子覆盖主要流程，插件还能直接调用 `Cache::remember` 缓存、`Cron::register` 定时任务（懒触发、零配置）、`notify` 通知、货币记账 API 等公共设施，不必自带轮子。

代价是每次请求都要加载插件。插件数量上来后，可以用注册表缓存或只在需要的请求路径上惰性加载来优化。

从零落地的检查清单

先别追求钩子数量，按顺序做：① 梳理核心流程的可插入点，先做 20 个高频钩子；② 定命名规范与文档模板；③ 实现 add / do / remove 三个函数；④ 后台做单插件启停开关；⑤ 加失败隔离与错误日志；⑥ 钩子标注起始版本，插件声明依赖版本，方便兼容判断。

收束一句：钩子机制不难写，难的是把它当公开 API 来维护——名字要冻结、契约要写清、失败要兜住、生效要即时。这四条做到，插件生态才有可能长出来。