mirror of
https://github.com/nonebot/nonebot2.git
synced 2025-07-28 00:31:14 +00:00
📝 Docs: 重写教程与进阶指南 (#1604)
Co-authored-by: Johnny Hsieh <32300164+mnixry@users.noreply.github.com>
This commit is contained in:
Ju4tCode
GitHub
@ -1,39 +1,28 @@
|
||||
---
|
||||
sidebar_position: 4
|
||||
description: 在 NoneBot2 框架中添加 Hook 函数
|
||||
sidebar_position: 8
|
||||
description: 在特定的生命周期中执行代码
|
||||
|
||||
options:
|
||||
menu:
|
||||
weight: 50
|
||||
weight: 90
|
||||
category: advanced
|
||||
---
|
||||
|
||||
# 钩子函数
|
||||
|
||||
[钩子编程](https://zh.wikipedia.org/wiki/%E9%92%A9%E5%AD%90%E7%BC%96%E7%A8%8B)
|
||||
> [钩子编程](https://zh.wikipedia.org/wiki/%E9%92%A9%E5%AD%90%E7%BC%96%E7%A8%8B)（hooking），也称作“挂钩”，是计算机程序设计术语，指通过拦截软件模块间的函数调用、消息传递、事件传递来修改或扩展操作系统、应用程序或其他软件组件的行为的各种技术。处理被拦截的函数调用、事件、消息的代码，被称为钩子（hook）。
|
||||
|
||||
> 钩子编程（hooking），也称作“挂钩”，是计算机程序设计术语，指通过拦截软件模块间的函数调用、消息传递、事件传递来修改或扩展操作系统、应用程序或其他软件组件的行为的各种技术。处理被拦截的函数调用、事件、消息的代码，被称为钩子（hook）。
|
||||
|
||||
在 NoneBot2 中有一系列预定义的钩子函数，分为两类：**全局钩子函数**和**事件钩子函数**，这些钩子函数可以用装饰器的形式来使用。
|
||||
在 NoneBot 中有一系列预定义的钩子函数，可以分为两类：**全局钩子函数**和**事件处理钩子函数**，这些钩子函数可以用装饰器的形式来使用。
|
||||
|
||||
## 全局钩子函数
|
||||
|
||||
全局钩子函数是指 NoneBot2 针对其本身运行过程的钩子函数。
|
||||
全局钩子函数是指 NoneBot 针对其本身运行过程的钩子函数。
|
||||
|
||||
这些钩子函数是由其后端驱动 `Driver` 来运行的，故需要先获得全局 `Driver` 对象：
|
||||
|
||||
```python
|
||||
from nonebot import get_driver
|
||||
|
||||
|
||||
driver=get_driver()
|
||||
```
|
||||
|
||||
共分为六种函数：
|
||||
这些钩子函数是由驱动器来运行的，故需要先[获得全局驱动器](./driver.md#获取驱动器)。
|
||||
|
||||
### 启动准备
|
||||
|
||||
这个钩子函数会在 NoneBot2 启动时运行。
|
||||
这个钩子函数会在 NoneBot 启动时运行。很多时候，我们并不希望在模块被导入时就执行一些耗时操作，如：连接数据库，这时候我们可以在这个钩子函数中进行这些操作。
|
||||
|
||||
```python
|
||||
@driver.on_startup
|
||||
@ -43,7 +32,7 @@ async def do_something():
|
||||
|
||||
### 终止处理
|
||||
|
||||
这个钩子函数会在 NoneBot2 终止时运行。
|
||||
这个钩子函数会在 NoneBot 终止时运行。我们可以在这个钩子函数中进行一些清理工作，如：关闭数据库连接。
|
||||
|
||||
```python
|
||||
@driver.on_shutdown
|
||||
@ -53,7 +42,7 @@ async def do_something():
|
||||
|
||||
### Bot 连接处理
|
||||
|
||||
这个钩子函数会在 `Bot` 通过 websocket 连接到 NoneBot2 时运行。
|
||||
这个钩子函数会在任何协议适配器连接 `Bot` 对象至 NoneBot 时运行。支持依赖注入，可以直接注入 `Bot` 对象。
|
||||
|
||||
```python
|
||||
@driver.on_bot_connect
|
||||
@ -61,9 +50,9 @@ async def do_something(bot: Bot):
|
||||
pass
|
||||
```
|
||||
|
||||
### bot 断开处理
|
||||
### Bot 断开处理
|
||||
|
||||
这个钩子函数会在 `Bot` 断开与 NoneBot2 的 websocket 连接时运行。
|
||||
这个钩子函数会在 `Bot` 断开与 NoneBot 的连接时运行。支持依赖注入，可以直接注入 `Bot` 对象。
|
||||
|
||||
```python
|
||||
@driver.on_bot_disconnect
|
||||
@ -71,101 +60,82 @@ async def do_something(bot: Bot):
|
||||
pass
|
||||
```
|
||||
|
||||
### bot api 调用钩子
|
||||
## 事件处理钩子函数
|
||||
|
||||
这个钩子函数会在 `Bot` 调用 API 时运行。
|
||||
|
||||
```python
|
||||
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 后运行。
|
||||
|
||||
```python
|
||||
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 提示
|
||||
关于**事件处理**的流程，可以在[这里](./README.md)查阅。
|
||||
:::
|
||||
|
||||
:::warning
|
||||
|
||||
1.在事件处理钩子函数中，与 `matcher` 运行状态相关的函数将不可用，如 `matcher.finish()`
|
||||
|
||||
2.如果需要在事件处理钩子函数中打断整个对话的执行，请参考以下范例：
|
||||
|
||||
```python
|
||||
from nonebot.exception import IgnoredException
|
||||
|
||||
|
||||
@event_preprocessor
|
||||
async def do_something():
|
||||
raise IgnoredException("reason")
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
共分为四种函数：
|
||||
这些钩子函数指的是影响 NoneBot 进行**事件处理**的函数, 这些函数可以跟普通的事件处理函数一样接受相应的参数。
|
||||
|
||||
### 事件预处理
|
||||
|
||||
这个钩子函数会在 `Event` 上报到 NoneBot2 时运行
|
||||
这个钩子函数会在 NoneBot 接收到新的事件时运行。支持依赖注入，可以注入 `Bot` 对象、事件、会话状态。
|
||||
|
||||
```python
|
||||
from nonebot.message import event_preprocessor
|
||||
|
||||
@event_preprocessor
|
||||
async def do_something():
|
||||
async def do_something(event: Event):
|
||||
pass
|
||||
```
|
||||
|
||||
### 事件后处理
|
||||
|
||||
这个钩子函数会在 NoneBot2 处理 `Event` 后运行
|
||||
这个钩子函数会在 NoneBot 处理事件完成后运行。支持依赖注入，可以注入 `Bot` 对象、事件、会话状态。
|
||||
|
||||
```python
|
||||
from nonebot.message import event_postprocessor
|
||||
|
||||
@event_postprocessor
|
||||
async def do_something():
|
||||
async def do_something(event: Event):
|
||||
pass
|
||||
```
|
||||
|
||||
### 运行预处理
|
||||
|
||||
这个钩子函数会在 NoneBot2 运行 `matcher` 前运行。
|
||||
这个钩子函数会在 NoneBot 运行事件响应器前运行。支持依赖注入，可以注入 `Bot` 对象、事件、事件响应器、会话状态。
|
||||
|
||||
```python
|
||||
from nonebot.message import run_preprocessor
|
||||
|
||||
@run_preprocessor
|
||||
async def do_something():
|
||||
async def do_something(event: Event, matcher: Matcher):
|
||||
pass
|
||||
```
|
||||
|
||||
### 运行后处理
|
||||
|
||||
这个钩子函数会在 NoneBot2 运行 `matcher` 后运行。
|
||||
这个钩子函数会在 NoneBot 运行事件响应器后运行。支持依赖注入，可以注入 `Bot` 对象、事件、事件响应器、会话状态、运行中产生的异常。
|
||||
|
||||
```python
|
||||
from nonebot.message import run_postprocessor
|
||||
|
||||
@run_postprocessor
|
||||
async def do_something():
|
||||
async def do_something(event: Event, matcher: Matcher, exception: Optional[Exception]):
|
||||
pass
|
||||
```
|
||||
|
||||
### 平台接口调用钩子
|
||||
|
||||
这个钩子函数会在 `Bot` 对象调用平台接口时运行。在这个钩子函数中，我们可以通过引起 `MockApiException` 异常来阻止 `Bot` 对象调用平台接口并返回指定的结果。
|
||||
|
||||
```python
|
||||
from nonebot.adapters import Bot
|
||||
from nonebot.exception import MockApiException
|
||||
|
||||
@Bot.on_calling_api
|
||||
async def handle_api_call(bot: Bot, api: str, data: Dict[str, Any]):
|
||||
if api == "send_msg":
|
||||
raise MockApiException(result={"message_id": 123})
|
||||
```
|
||||
|
||||
### 平台接口调用后钩子
|
||||
|
||||
这个钩子函数会在 `Bot` 对象调用平台接口后运行。在这个钩子函数中，我们可以通过引起 `MockApiException` 异常来忽略平台接口返回的结果并返回指定的结果。
|
||||
|
||||
```python
|
||||
from nonebot.adapters import Bot
|
||||
from nonebot.exception import MockApiException
|
||||
|
||||
@Bot.on_called_api
|
||||
async def handle_api_result(
|
||||
bot: Bot, exception: Optional[Exception], api: str, data: Dict[str, Any], result: Any
|
||||
):
|
||||
if not exception and api == "send_msg":
|
||||
raise MockApiException(result={**result, "message_id": 123})
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user