Version: Next

选择驱动器

注意

驱动器的选择通常与你所使用的协议适配器相关，如果你不知道该选择哪个驱动器，可以先阅读你想要使用的协议适配器文档说明。

提示

如何安装驱动器请参考安装驱动器。

如何使用驱动器请参考配置。

驱动器的类型

驱动器的类型有两种：

  • ForwardDriver：即客户端类型驱动器，多用于使用 HTTP 轮询，WebSocket 连接服务器的情形。
  • ReverseDriver：即服务端类型驱动器，多用于使用 WebHook 情形。

其中 ReverseDriver 可以配合 ForwardDriver 一起使用，即可以同时使用客户端功能和服务端功能。

驱动器的功能

在 NoneBot 中，驱动器主要负责数据的收发，不对数据进行处理。通常，驱动器会实现以下功能：

ForwardDriver

  1. 异步发送 HTTP 请求，自定义 HTTP Method、URL、Header、Body、Cookie、Proxy、Timeout 等。
  2. 异步建立 WebSocket 连接上下文，自定义 WebSocket URL、Header、Cookie、Proxy、Timeout 等。

ReverseDriver

  1. 协议适配器自定义 HTTP 上报地址以及对上报数据处理的回调函数。
  2. 协议适配器自定义 WebSocket 连接请求地址以及对 WebSocket 请求处理的回调函数。
  3. 用户可以将 Driver 作为服务端使用，自行添加任何服务端相关功能。

内置驱动器

FastAPI（默认）

类型：ReverseDriver

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

FastAPI 是一个易上手、高性能的异步 Web 框架，具有极佳的编写体验，可以挂载其他 ASGI、WSGI 应用。

FastAPI：文档、仓库

驱动器：API、源码

DRIVER=~fastapi

FastAPI 配置项

fastapi_openapi_url

类型：Optional[str]
默认值：None
说明：FastAPI 提供的 OpenAPI JSON 定义地址，如果为 None，则不提供 OpenAPI JSON 定义。

fastapi_docs_url

类型：Optional[str]
默认值：None
说明：FastAPI 提供的 Swagger 文档地址，如果为 None，则不提供 Swagger 文档。

fastapi_redoc_url

类型：Optional[str]
默认值：None
说明：FastAPI 提供的 ReDoc 文档地址，如果为 None，则不提供 ReDoc 文档。

fastapi_include_adapter_schema

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

fastapi_reload

类型：bool
默认值：False
说明：是否开启 uvicorn 的 reload 功能，需要提供 asgi 应用路径。

bot.py
app = nonebot.get_asgi()
nonebot.run(app="bot:app")
警告

在 Windows 平台上开启该功能有可能会造成预料之外的影响！

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

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

后者（SelectorEventLoop）在 Windows 平台的可使用性不如前者（ProactorEventLoop），包括但不限于

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

具体信息参考 Python 文档

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

  1. playwright

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

fastapi_reload_dirs

类型：Optional[List[str]]
默认值：None
说明：重载监控文件夹列表，默认为 uvicorn 默认值

fastapi_reload_delay

类型：Optional[float]
默认值：None
说明：重载延迟，默认为 uvicorn 默认值

fastapi_reload_includes

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

fastapi_reload_excludes

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

Quart

类型：ReverseDriver

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

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

Quart：文档、仓库

驱动器：API、源码

DRIVER=~quart

Quart 配置项

quart_reload

类型：bool
默认值：False
说明：是否开启 uvicorn 的 reload 功能，需要提供 asgi 应用路径。

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

类型：Optional[List[str]]
默认值：None
说明：重载监控文件夹列表，默认为 uvicorn 默认值

quart_reload_delay

类型：Optional[float]
默认值：None
说明：重载延迟，默认为 uvicorn 默认值

quart_reload_includes

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

quart_reload_excludes

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

HTTPX

类型：ForwardDriver

注意

本驱动器仅支持 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.

HTTPX：文档、仓库

驱动器：API、源码

DRIVER=~httpx
注意

本驱动器支持 Mixin

websockets

类型：ForwardDriver

注意

本驱动器仅支持 WebSocket 请求，不支持 HTTP 请求。

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

websockets：文档、仓库

驱动器：API、源码

DRIVER=~websockets
注意

本驱动器支持 Mixin

AIOHTTP

类型：ForwardDriver

Asynchronous HTTP Client/Server for asyncio and Python.

AIOHTTP：文档、仓库

驱动器：API、源码

DRIVER=~aiohttp
注意

本驱动器支持 Mixin