nonebot2/website/docs/advanced/driver.md
Ju4tCode 18beb63d55
📝 Docs: 重写教程与进阶指南 ()
Co-authored-by: Johnny Hsieh <32300164+mnixry@users.noreply.github.com>
2023-03-24 16:34:21 +08:00

9.3 KiB
Raw Blame History

sidebar_position description options
0 选择合适的驱动器运行机器人
menu
weight category
10 advanced

选择驱动器

驱动器 (Driver) 是机器人运行的基石,它是机器人初始化的第一步,主要负责数据收发。

:::important 提示 驱动器的选择通常与机器人所使用的协议适配器相关,如果不知道该选择哪个驱动器,可以先阅读相关协议适配器文档说明。 :::

:::tip 提示 如何安装驱动器请参考安装驱动器。 :::

驱动器类型

驱动器的类型有两种:

  • ForwardDriver:即客户端型驱动器,多用于使用 HTTP 轮询,连接 WebSocket 服务器等情形。
  • ReverseDriver:即服务端型驱动器,多用于使用 WebHook接收 WebSocket 客户端连接等情形。

客户端型驱动器具有以下两种功能:

  1. 异步发送 HTTP 请求,自定义 HTTP MethodURLHeaderBodyCookieProxyTimeout 等。
  2. 异步建立 WebSocket 连接上下文,自定义 WebSocket URLHeaderCookieProxyTimeout 等。

服务端型驱动器通常为 ASGI 应用框架,具有以下功能:

  1. 协议适配器自定义 HTTP 上报地址以及对上报数据处理的回调函数。
  2. 协议适配器自定义 WebSocket 连接请求地址以及对 WebSocket 请求处理的回调函数。
  3. 用户可以向 ASGI 应用添加任何服务端相关功能,如:添加自定义路由

配置驱动器

驱动器的配置方法已经在配置章节中简单进行了介绍,这里将详细介绍驱动器配置的格式。

NoneBot 中的客户端和服务端型驱动器可以相互配合使用,但服务端型驱动器仅能选择一个。所有驱动器模块都会包含一个 Driver 子类,即驱动器类,他可以作为驱动器单独运行。同时,客户端驱动器模块中还会提供一个 Mixin 子类,用于在与其他驱动器配合使用时加载。因此,驱动器配置格式采用特殊语法:<module>[:<Driver>][+<module>[:<Mixin>]]*

其中,<module> 代表驱动器模块路径<Driver> 代表驱动器类名,默认为 Driver<Mixin> 代表驱动器混入类名,默认为 Mixin。即,我们需要选择一个主要驱动器,然后在其基础上配合使用其他驱动器的功能。主要驱动器可以为客户端或服务端类型,但混入类驱动器只能为客户端类型。

特别的,为了简化内置驱动器模块路径,我们可以使用 ~ 符号作为内置驱动器模块路径的前缀,如 ~fastapi 代表使用内置驱动器 fastapi。NoneBot 内置了多个驱动器适配,但需要安装额外依赖才能使用,具体请参考安装驱动器。常见的驱动器配置如下:

DRIVER=~fastapi
DRIVER=~aiohttp
DRIVER=~httpx+~websockets
DRIVER=~fastapi+~httpx+~websockets

获取驱动器

在 NoneBot 框架初始化完成后,我们就可以通过 get_driver() 方法获取全局驱动器实例:

from nonebot import get_driver

driver = get_driver()

内置驱动器

None

**类型:**服务端驱动器

NoneBot 内置的空驱动器,不提供任何收发数据功能,可以在不需要外部网络连接时使用。

DRIVER=~none

FastAPI默认

**类型:**服务端驱动器

FastAPI is a modern, fast (high-performance), web framework for building APIs with Python 3.6+ based on standard Python type hints.

FastAPI 是一个易上手、高性能的异步 Web 框架,具有极佳的编写体验。 FastAPI 可以通过类型注解、依赖注入等方式实现输入参数校验、自动生成 API 文档等功能,也可以挂载其他 ASGI、WSGI 应用。

DRIVER=~fastapi

FastAPI 配置项

fastapi_openapi_url

类型:str | None
默认值:None
说明:FastAPI 提供的 OpenAPI JSON 定义地址,如果为 None,则不提供 OpenAPI JSON 定义。

fastapi_docs_url

类型:str | None
默认值:None
说明:FastAPI 提供的 Swagger 文档地址,如果为 None,则不提供 Swagger 文档。

fastapi_redoc_url

类型:str | None
默认值:None
说明:FastAPI 提供的 ReDoc 文档地址,如果为 None,则不提供 ReDoc 文档。

fastapi_include_adapter_schema

类型:bool
默认值:True
说明:FastAPI 提供的 OpenAPI JSON 定义中是否包含适配器路由的 Schema

fastapi_reload

:::warning 警告 不推荐开启该配置项,在 Windows 平台上开启该功能有可能会造成预料之外的影响!替代方案:使用 nb-cli 命令行工具以及参数 --reload 启动 NoneBot。

nb run --reload

开启该功能后,在 uvicorn 运行时FastAPI 提供的 ASGI 底层,即 reload 功能的实际来源asyncio 使用的事件循环会被 uvicorn 从默认的 ProactorEventLoop 强制切换到 SelectorEventLoop

相关信息参考 uvicorn#529uvicorn#1070uvicorn#1257

后者(SelectorEventLoop)在 Windows 平台的可使用性不如前者(ProactorEventLoop),包括但不限于

  1. 不支持创建子进程
  2. 最多只支持 512 个套接字
  3. ...

具体信息参考 Python 文档

所以,一些使用了 asyncio 的库因此可能无法正常工作,如:

  1. playwright

如果在开启该功能后,原本正常运行的代码报错,且打印的异常堆栈信息和 asyncio 有关(异常一般为 NotImplementedError 你可能就需要考虑相关库对事件循环的支持,以及是否启用该功能。 :::

类型:bool
默认值:False
说明:是否开启 uvicornreload 功能,需要在机器人入口文件提供 ASGI 应用路径。

app = nonebot.get_asgi()
nonebot.run(app="bot:app")
fastapi_reload_dirs

类型:List[str] | None
默认值:None
说明:重载监控文件夹列表,默认为 uvicorn 默认值

fastapi_reload_delay

类型:float | None
默认值:None
说明:重载延迟,默认为 uvicorn 默认值

fastapi_reload_includes

类型:List[str] | None
默认值:None
说明:要监听的文件列表,支持 glob pattern默认为 uvicorn 默认值

fastapi_reload_excludes

类型:List[str] | None
默认值:None
说明:不要监听的文件列表,支持 glob pattern默认为 uvicorn 默认值

fastapi_extra

类型:Dist[str, Any]
默认值:{}
说明:传递给 FastAPI 的其他参数

Quart

类型:ReverseDriver

Quart is an asyncio reimplementation of the popular Flask microframework API.

Quart 是一个类 Flask 的异步版本,拥有与 Flask 非常相似的接口和使用方法。

DRIVER=~quart

Quart 配置项

quart_reload

:::warning 警告 不推荐开启该配置项,在 Windows 平台上开启该功能有可能会造成预料之外的影响!替代方案:使用 nb-cli 命令行工具以及参数 --reload 启动 NoneBot。

nb run --reload

:::

类型:bool
默认值:False
说明:是否开启 uvicornreload 功能,需要在机器人入口文件提供 ASGI 应用路径。

app = nonebot.get_asgi()
nonebot.run(app="bot:app")
quart_reload_dirs

类型:List[str] | None
默认值:None
说明:重载监控文件夹列表,默认为 uvicorn 默认值

quart_reload_delay

类型:float | None
默认值:None
说明:重载延迟,默认为 uvicorn 默认值

quart_reload_includes

类型:List[str] | None
默认值:None
说明:要监听的文件列表,支持 glob pattern默认为 uvicorn 默认值

quart_reload_excludes

类型:List[str] | None
默认值:None
说明:不要监听的文件列表,支持 glob pattern默认为 uvicorn 默认值

quart_extra

类型:Dist[str, Any]
默认值:{}
说明:传递给 Quart 的其他参数

HTTPX

类型:ForwardDriver

:::warning 注意 本驱动器仅支持 HTTP 请求,不支持 WebSocket 连接请求。 :::

HTTPX is a fully featured HTTP client for Python 3, which provides sync and async APIs, and support for both HTTP/1.1 and HTTP/2.

DRIVER=~httpx

websockets

类型:ForwardDriver

:::warning 注意 本驱动器仅支持 WebSocket 连接请求,不支持 HTTP 请求。 :::

websockets is a library for building WebSocket servers and clients in Python with a focus on correctness, simplicity, robustness, and performance.

DRIVER=~websockets

AIOHTTP

类型:ForwardDriver

AIOHTTP: Asynchronous HTTP Client/Server for asyncio and Python.

DRIVER=~aiohttp