nonebot2/website/versioned_docs/version-2.0.0-beta.4/advanced/runtime-hook.md
github-actions[bot] 58d8815f39 🔖 Release 2.0.0-beta.4
2022-06-20 11:40:59 +00:00

3.6 KiB
Raw Blame History

sidebar_position description options
4 在 NoneBot2 框架中添加 Hook 函数
menu
weight category
50 advanced

钩子函数

钩子编程

钩子编程hooking也称作“挂钩”是计算机程序设计术语指通过拦截软件模块间的函数调用、消息传递、事件传递来修改或扩展操作系统、应用程序或其他软件组件的行为的各种技术。处理被拦截的函数调用、事件、消息的代码被称为钩子hook

在 NoneBot2 中有一系列预定义的钩子函数,分为两类:全局钩子函数事件钩子函数,这些钩子函数可以用装饰器的形式来使用。

全局钩子函数

全局钩子函数是指 NoneBot2 针对其本身运行过程的钩子函数。

这些钩子函数是由其后端驱动 Driver 来运行的,故需要先获得全局 Driver 对象:

from nonebot import get_driver


driver=get_driver()

共分为六种函数:

启动准备

这个钩子函数会在 NoneBot2 启动时运行。

@driver.on_startup
async def do_something():
    pass

终止处理

这个钩子函数会在 NoneBot2 终止时运行。

@driver.on_shutdown
async def do_something():
    pass

Bot 连接处理

这个钩子函数会在 Bot 通过 websocket 连接到 NoneBot2 时运行。

@driver.on_bot_connect
async def do_something(bot: Bot):
    pass

bot 断开处理

这个钩子函数会在 Bot 断开与 NoneBot2 的 websocket 连接时运行。

@driver.on_bot_disconnect
async def do_something(bot: Bot):
    pass

bot api 调用钩子

这个钩子函数会在 Bot 调用 API 时运行。

from nonebot.adapters import Bot

@Bot.on_calling_api
async def handle_api_call(bot: Bot, api: str, data: Dict[str, Any]):
    pass

bot api 调用后钩子

这个钩子函数会在 Bot 调用 API 后运行。

from nonebot.adapters import Bot

@Bot.on_called_api
async def handle_api_result(bot: Bot, exception: Optional[Exception], api: str, data: Dict[str, Any], result: Any):
    pass

事件钩子函数

这些钩子函数指的是影响 NoneBot2 进行事件处理的函数, 这些函数可以认为跟普通的事件处理函数一样,接受相应的参数。

:::tip 提示 关于事件处理的流程,可以在这里查阅。 :::

:::warning

1.在事件处理钩子函数中,与 matcher 运行状态相关的函数将不可用,如 matcher.finish()

2.如果需要在事件处理钩子函数中打断整个对话的执行,请参考以下范例:

from nonebot.exception import IgnoredException


@event_preprocessor
async def do_something():
    raise IgnoredException("reason")

:::

共分为四种函数:

事件预处理

这个钩子函数会在 Event 上报到 NoneBot2 时运行

from nonebot.message import event_preprocessor

@event_preprocessor
async def do_something():
    pass

事件后处理

这个钩子函数会在 NoneBot2 处理 Event 后运行

from nonebot.message import event_postprocessor

@event_postprocessor
async def do_something():
    pass

运行预处理

这个钩子函数会在 NoneBot2 运行 matcher 前运行。

from nonebot.message import run_preprocessor

@run_preprocessor
async def do_something():
    pass

运行后处理

这个钩子函数会在 NoneBot2 运行 matcher 后运行。

from nonebot.message import run_postprocessor

@run_postprocessor
async def do_something():
    pass