NoneBot2 适配器开发指南：从零开始编写适配器-优快云博客

NoneBot2 适配器开发指南：从零开始编写适配器

nonebot2 跨平台 Python 异步聊天机器人框架 / Asynchronous multi-platform chatbot framework written in Python 项目地址: https://gitcode.com/gh_mirrors/no/nonebot2

前言

NoneBot2 作为一款优秀的 Python 异步机器人框架，其强大的适配器系统允许开发者对接各种聊天平台。本文将深入讲解如何为 NoneBot2 开发适配器，帮助开发者理解适配器的核心结构和实现原理。

适配器基础概念

适配器是 NoneBot2 与不同聊天平台之间的桥梁，负责协议转换和消息处理。一个完整的适配器通常包含以下核心组件：

Adapter：处理平台连接和事件转换
Bot：代表机器人实例，提供 API 调用能力
Event：封装平台事件数据
Message：处理消息序列化和反序列化

项目结构规划

推荐采用以下目录结构组织适配器项目：

nonebot-adapter-{平台名称}
├── nonebot
│   └── adapters
│       └── {平台名称}
│           ├── __init__.py
│           ├── adapter.py
│           ├── bot.py
│           ├── config.py
│           ├── event.py
│           └── message.py
├── pyproject.toml
└── README.md

这种结构遵循 Python 命名空间包规范，便于 NoneBot2 识别和加载适配器。

核心组件实现详解

1. 日志系统封装

适配器应当使用专用日志记录器，便于区分不同适配器的日志输出：

from nonebot.utils import logger_wrapper

log = logger_wrapper("your_adapter_name")

使用示例：

log("DEBUG", "调试信息")
log("INFO", "普通信息")
log("WARNING", "警告信息")
log("ERROR", "错误信息", exc_info=e)

2. 配置管理

使用 Pydantic 定义适配器配置模型：

from pydantic import BaseModel

class Config(BaseModel):
    platform_id: str
    platform_token: str
    webhook_url: str = ""

3. Adapter 实现

Adapter 是适配器的核心，负责平台连接和事件分发：

from nonebot.adapters import Adapter as BaseAdapter
from nonebot.drivers import Driver

class Adapter(BaseAdapter):
    def __init__(self, driver: Driver, **kwargs):
        super().__init__(driver, **kwargs)
        self.config = get_plugin_config(Config)
        self._setup_connection()

    @classmethod
    def get_name(cls) -> str:
        return "平台名称"

连接方式选择

NoneBot2 支持多种连接方式，开发者应根据平台特性选择合适的实现：

WebSocket 客户端模式：

async def _forward_ws(self):
    request = Request(
        method="GET",
        url="wss://platform.url",
        headers={"Authorization": f"Bearer {self.config.token}"}
    )
    async with self.websocket(request) as ws:
        while True:
            data = await ws.receive()
            event = self._parse_event(data)
            await self.bot.handle_event(event)

HTTP Webhook 模式：

def setup(self):
    http_setup = HTTPServerSetup(
        URL("/webhook"),
        "POST",
        "PlatformWebhook",
        self._handle_http
    )
    self.setup_http_server(http_setup)

4. Bot 实现

Bot 类代表机器人实例，提供消息发送等基础能力：

from nonebot.adapters import Bot as BaseBot

class Bot(BaseBot):
    async def send(self, event: Event, message: Union[str, Message, MessageSegment], **kwargs):
        # 实现消息发送逻辑
        platform_data = self._convert_message(message)
        await self.call_api("send_message", **platform_data)

5. Event 实现

Event 类负责封装平台事件数据：

from nonebot.adapters import Event as BaseEvent

class MessageEvent(BaseEvent):
    message_id: str
    user_id: str
    message: Message
    
    def get_type(self) -> str:
        return "message"
    
    def get_message(self) -> Message:
        return self.message

6. Message 实现

Message 系统负责消息的序列化和反序列化：

from nonebot.adapters import Message as BaseMessage

class TextSegment(MessageSegment):
    type = "text"
    
    def __str__(self):
        return self.data["text"]

class Message(BaseMessage[MessageSegment]):
    @classmethod
    def from_str(cls, msg: str) -> Iterable[MessageSegment]:
        yield TextSegment({"text": msg})