第44章 NodeBB 可用钩子(Hooks)详解
可用钩子(Hooks)
以下是 NodeBB 中所有钩子的清单,供想为 NodeBB 开发插件的开发者参考。更多信息请查阅《为 NodeBB 编写插件》
大多数情况下,当你想与 NodeBB 集成时,都需要挂接到 NodeBB 内部处理的某个环节。这通过我们的插件钩子系统,由插件附加一个监听器来实现。钩子分为四类:filter(过滤器)、action(动作)、static(静态)和 response(响应)钩子。
Filter 钩子
Filter 作用于内容本身,当你想在内容流经 NodeBB 时对其进行修改,filter 会非常有用。
比如,可以用 filter 把帖子中所有 "apple" 替换为 "orange"。类似地,filter 也可以用来美化内容(如代码高亮),或过滤脏话(敏感词过滤)。
NodeBB 调用 filter 钩子时,通常会以对象的形式传入一个参数,你必须按相同的结构返回数据——因为可能有多个插件在监听同一个钩子,大家预期的是同一种对象结构。我们不强制要求返回完全相同的对象,但建议这么做。
NodeBB 会按顺序执行所有已注册的监听器,等待它们全部返回数据(无论是否修改过)之后,才继续后续执行。
检查传入的数据
filter 载荷的具体结构因钩子而异,最稳妥的办法是在第一次挂接监听器时先把参数打印出来看看:
plugin.myMethod = async (data) => {
console.log(require('util').inspect(data, { depth: 1 }));
return data;
};
有几点需要留意:
- 单数和复数形式的钩子,载荷结构通常不同。例如 filter:topic.get 收到的是 { topic, uid }(单个主题),而 filter:topics.get 收到的是 { topics, uid }(数组)。针对其中一个写的代码不能直接用于另一个。
- 务必返回载荷对象——返回 undefined 会导致后续监听器和核心代码拿不到数据。
- 要防范字段缺失,因为其他插件(或未来的核心改动)可能改变字段:if (!data || !data.topic) { return data; }。
在 filter 中报告错误
有些 filter 允许插件拒绝或否决正在进行的操作(例如在用户创建前校验用户名)。不同钩子的约定并不统一,请查看调用代码是如何消费结果的:
- 大多数校验类 filter 期望你抛出一个错误,错误消息是一个翻译键。NodeBB 会把翻译后的消息展示给用户,并中止该操作。
plugin.checkUsernameOnCreate = async (data) => {
// filter:user.create — 通过抛错来拒绝
if (isReserved(data.user.username)) {
throw new Error('[[myplugin:error.reserved-username]]');
}
return data;
};
- 少数 filter 则期望你在载荷上设置 error 属性后正常返回。filter:username.check 就是这样一个钩子:
plugin.checkUsername = async (data) => {
// filter:username.check — 通过设置 data.error 来拒绝
if (isReserved(data.username)) {
data.error = new Error('[[myplugin:error.reserved-username]]');
}
return data;
};
拿不准时,可以去 NodeBB 源码中找到该钩子的触发位置,看看它读取的是抛出的错误还是返回的 error 字段。
Action 钩子
Action 顾名思义,就是在 NodeBB 执行某个动作时被触发。如果你想在某个事件发生后异步做一些事情,action 钩子会很合适。
例如,可以用 action 钩子在特定用户发帖时通知管理员。其他用途还包括记录分析数据,或在新用户注册后自动发送欢迎帖。
Action 钩子可能携带数据载荷,也可能没有,但 NodeBB 明确不会关心监听器返回了什么(也不会使用返回的数据)。
NodeBB 会同时执行某个 action 钩子的所有已注册监听器,不会等待响应就继续执行。如果你需要 NodeBB 等待你的处理结果,应该用 filter/static 钩子。
Static 钩子
Static 钩子触发后会等待你完成某些处理再继续。它们与 action 钩子类似,区别在于 action 触发后 NodeBB 立即继续执行,而 static 钩子会给你一段时间运行自定义逻辑,之后再恢复执行。
NodeBB 会传入数据载荷,并同时执行所有已注册的监听器。它会等待所有监听器返回(或执行返回回调)之后才继续。
Response 钩子
Response 钩子按顺序执行,在此之前与 action 钩子类似。一旦某个监听器向客户端发送了响应,其后的所有插件钩子都会被完全跳过,包括核心代码的默认响应。
Response 钩子适用于一个或多个插件可能选择向客户端发送错误、或将其重定向到别处的场景。其结构设计保证了冲突可以避免。
不得不说,NodeBB 中的 response 钩子并不多。核心中唯一的一个是 response:middleware.authenticate,它允许插件向受保护的路由添加自己的认证策略。此时 NodeBB 会像中间件一样传入 req 和 res,插件可以选择响应,也可以不响应。NodeBB 会检查响应头是否已发送,如果尚未向客户端发送响应,则继续往下执行。
举例来说,用户访问受保护的路由时,NodeBB 会对未登录用户触发 response:middleware.authenticate,如果没有任何插件做出响应,就继续执行默认行为,即展示 "Not Allowed" 页面。
钩子列表
请查阅自动生成的钩子列表。该列表由 NodeBB 代码库自动生成,不保证始终完整。
特殊钩子
NodeBB 代码库中还有一些特殊钩子,没有在自动生成的钩子页面中列出。它们被收录在这里,因为要么很有用,要么脱离上下文难以理解。
页面构建钩子
除了在某些动作时执行的钩子外,每次页面加载时(无论是直接访问还是页面跳转)还会触发一组钩子:
- filter:.build 在特定页面加载时触发,取决于所渲染的模板文件。例如 /recent 页面的视图来自 recent.tpl,因此插件可以订阅 filter:recent.build,在 recent 页面每次加载时做出响应。
注意,并不保证该钩子只在那个特定页面触发。插件也可以选择渲染同一个模板,这同样会触发该钩子。 - response:router.page 在每次页面加载时、任何处理(模板生成等)之前被调用。
- filter:middleware.render 在每次页面加载时被调用,适合需要为所有页面追加或修改数据的场景。它在大部分处理完成之后被调用。
组件渲染钩子 filter:widget.render:
插件定义的组件需要告知 NodeBB 组件中包含什么内容(如 html 及其他相关数据)。这通过每次渲染组件时触发的一个插件钩子来处理。钩子名称由组件名决定:如果某个组件的 widget 属性为 mywidget,那么它被渲染时就会触发 filter:widget.render:mywidget 钩子。
更多信息请查阅编写组件的相关页面。
如何使用钩子
NodeBB 会在每个插件中查找 plugin.json。该文件通过 library 属性定义了一个入口文件,你的钩子监听逻辑就写在这个入口文件里。
在同一个文件中,hooks 数组用于把 library 中的监听方法挂接到 NodeBB 的钩子上。quickstart 插件里有一个很好的示例。
同样,在入口文件 library.js 中定义了钩子的具体逻辑。