NoneBot2 适配器开发完全指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_01156/article/details/148487049

NoneBot2 适配器开发完全指南

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

前言

NoneBot2 是一个强大的 Python 异步机器人框架，其核心设计理念之一就是通过适配器机制实现对不同聊天平台的支持。本文将深入讲解如何为 NoneBot2 开发适配器，帮助开发者理解适配器的工作原理并掌握开发技巧。

适配器基础概念

适配器是 NoneBot2 与各种聊天平台之间的桥梁，主要负责以下功能：

与平台建立连接和通信
将平台消息转换为 NoneBot2 事件
提供调用平台 API 的能力
处理消息的发送和接收

一个完整的适配器通常由四个核心组件构成：

Adapter：处理平台连接和协议转换
Bot：代表单个机器人实例
Event：平台事件的抽象表示
Message：平台消息的封装

项目结构与初始化

快速创建项目

NoneBot2 提供了便捷的脚手架工具，可以快速生成适配器项目骨架：

nb adapter create

按照提示输入适配器名称和路径即可完成初始化。

核心组件开发详解

日志处理

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

from nonebot.utils import logger_wrapper

# 创建带前缀的日志记录器
log = logger_wrapper("your_adapter_name")

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

配置管理

适配器通常需要平台特定的配置项，可以通过 Pydantic 模型定义：

from pydantic import BaseModel

class Config(BaseModel):
    app_id: str  # 应用ID
    token: str   # 认证令牌
    secret: str  # 密钥

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 客户端
- HTTP 轮询
服务端模式：接收平台推送
- WebHook
- WebSocket 服务端

# WebSocket 客户端示例
async def _forward_ws(self):
    while True:
        try:
            async with self.websocket(request) as ws:
                async for data in ws:
                    await self.process_data(data)
        except Exception as e:
            log("ERROR", "连接异常", e)
            await asyncio.sleep(3)

事件处理流程

接收平台原始数据
转换为 NoneBot2 事件对象
交给机器人处理

def payload_to_event(self, payload: dict) -> Event:
    try:
        return Event.parse_obj(payload)
    except Exception as e:
        log("WARNING", "事件解析失败", e)
        return UnknownEvent(payload)

async def process_data(self, data):
    event = self.payload_to_event(data)
    await bot.handle_event(event)

Bot 实现

Bot 类代表单个机器人实例：

from nonebot.adapters import Bot as BaseBot

class Bot(BaseBot):
    def __init__(self, adapter, self_id):
        super().__init__(adapter, self_id)
        self.platform_info = {}  # 平台特有信息

    async def send(self, event, message, **kwargs):
        # 实现消息发送逻辑
        pass

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

Message 实现

消息系统需要实现消息段和消息链：

from nonebot.adapters import Message as BaseMessage
from nonebot.adapters import MessageSegment as BaseMessageSegment

class MessageSegment(BaseMessageSegment):
    @classmethod
    def get_message_class(cls):
        return Message

    def is_text(self):
        return self.type == "text"

class Message(BaseMessage):
    @classmethod
    def get_segment_class(cls):
        return MessageSegment