生命周期

KiramiBot 在接收到每个事件时都需要经历一系列的处理步骤，比如广播事件，运行事件响应器，以及调用平台接口。在此过程中，它也会运行被称为生命周期钩子的函数，让开发者有机会在特定阶段运行自己的代码。

在 KiramiBot 中有一系列预定义的钩子函数，可以分为两类：全局钩子函数和事件处理钩子函数，这些钩子函数可以用装饰器的形式来使用。

全局钩子函数

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

启动准备

这个钩子函数会在 KiramiBot 启动时运行。很多时候，我们并不希望在模块被导入时就执行一些耗时操作，如：连接数据库，这时候我们可以在这个钩子函数中进行这些操作。

from kirami.hook import on_startup

@on_startup
async def do_something():
    pass

终止处理

这个钩子函数会在 KiramiBot 终止时运行。我们可以在这个钩子函数中进行一些清理工作，如：关闭数据库连接。

from kirami.hook import on_shutdown

@on_shutdown
async def do_something():
    pass

Bot 连接处理

这个钩子函数会在 Bot 成功连接至 KiramiBot 时运行。支持依赖注入，可以直接注入 Bot 对象。

from kirami.hook import on_bot_connect
from kirami.typing import Bot

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

Bot 断开处理

这个钩子函数会在 Bot 断开与 KiramiBot 的连接时运行。支持依赖注入，可以直接注入 Bot 对象。

from kirami.hook import on_bot_disconnect
from kirami.typing import Bot

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

事件处理钩子函数

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

事件预处理

这个钩子函数会在 KiramiBot 接收到新的事件时运行。支持依赖注入，可以注入 Bot 对象、事件、会话状态。

from kirami.hook import before_event

@before_event
async def do_something(event: Event):
    pass

事件后处理

这个钩子函数会在 KiramiBot 处理事件完成后运行。支持依赖注入，可以注入 Bot 对象、事件、会话状态。

from kirami.hook import after_event

@after_event
async def do_something(event: Event):
    pass

运行预处理

这个钩子函数会在 KiramiBot 运行事件响应器前运行。支持依赖注入，可以注入 Bot 对象、事件、事件响应器、会话状态。

from kirami.hook import before_run

@before_run
async def do_something(event: Event, matcher: Matcher):
    pass

运行后处理

这个钩子函数会在 KiramiBot 运行事件响应器后运行。支持依赖注入，可以注入 Bot 对象、事件、事件响应器、会话状态、运行中产生的异常。

from kirami.hook import after_run

@after_run
async def do_something(event: Event, matcher: Matcher, exception: Exception | None):
    pass

平台接口调用钩子

这个钩子函数会在 Bot 对象调用平台接口前运行。在这个钩子函数中，我们可以通过引起 MockApiException 异常来阻止 Bot 对象调用平台接口并返回指定的结果。

from kirami.exception import MockApiException
from kirami.hook import before_api
from kirami.typing import Bot

@before_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 异常来忽略平台接口返回的结果并返回指定的结果。

from kirami.exception import MockApiException
from kirami.hook import after_api
from kirami.typing import Bot

@after_api
async def handle_api_result(
    bot: Bot, exception: Exception | None, api: str, data: dict[str, Any], result: Any
):
    if not exception and api == "send_msg":
        raise MockApiException(result={**result, "message_id": 123})