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

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

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

前言

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

适配器基础概念

适配器是 NoneBot2 与不同聊天平台之间的桥梁，负责将平台特有的事件和消息转换为 NoneBot2 能够理解的统一格式。一个完整的适配器通常包含以下四个核心组件：

Adapter：处理平台连接和事件转换
Bot：代表机器人实例，提供交互接口
Event：封装平台事件数据
Message：处理平台消息格式

项目结构规划

一个规范的适配器项目应该采用命名空间包的形式组织代码。推荐的项目结构如下：

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

核心组件开发详解

1. 日志处理

适配器需要独立的日志系统以便调试和问题追踪：

from nonebot.utils import logger_wrapper

# 创建带有适配器名称前缀的日志函数
log = logger_wrapper("your_adapter_name")

# 使用示例
log("DEBUG", "调试信息")
log("ERROR", "错误信息", exception)

2. 配置管理

使用 Pydantic 模型定义适配器所需的配置项：

from pydantic import BaseModel

class Config(BaseModel):
    api_key: str  # API密钥
    secret: str   # 密钥
    webhook_url: str = ""  # 可选webhook地址

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 "平台名称"

连接管理

根据平台特性选择合适的通信方式：

WebSocket 客户端示例:

async def _connect_websocket(self):
    while True:
        try:
            async with self.websocket(Request(...)) as ws:
                async for data in ws:
                    await self._handle_data(data)
        except Exception as e:
            log("ERROR", "连接异常", e)
            await asyncio.sleep(5)  # 重连间隔

HTTP Webhook 示例:

def setup(self):
    http_setup = HTTPServerSetup(
        URL("/webhook"),
        "POST",
        "Webhook",
        self._handle_webhook
    )
    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], **kwargs):
        """发送消息的核心方法"""
        platform_data = self._convert_message(message)
        await self.call_api("send_msg", **platform_data)

5. Event 实现

Event 类封装平台事件数据：

from nonebot.adapters import Event as BaseEvent

class MessageEvent(BaseEvent):
    message: Message
    user_id: str
    
    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]):
    @staticmethod
    def _construct(text: str):
        yield TextSegment({"text": text})