NoneBot2 事件响应器（Matcher）完全指南：从辅助函数到响应规则

后端即时通讯【免费下载链接】nonebot2跨平台 Python 异步聊天机器人框架 / Asynchronous multi-platform chatbot framework written in Python项目地址https://gitcode.com/gh_mirrors/no/nonebot2点击查看免费下载事件响应器Matcher是 NoneBot2 中响应事件的基本单元也是插件开发的核心概念所有插件的能力都建立在一个或多个事件响应器之上。本文将基于 NoneBot2 官方教程与仓库源码系统讲解事件响应器的概念、辅助函数、创建方法与参数调优并结合 nonebot/plugin/on.py 与 nonebot/internal/matcher/matcher.py 的源码实现带你从“会写”深入到“懂原理”学完即可独立创建具备规则筛选、优先级控制与阻断能力的自定义响应器。什么是事件响应器事件响应器Matcher是对接收到的事件进行响应的基本单元所有的事件响应器都继承自Matcher基类。在 NoneBot 中事件响应器可以通过一系列特定的规则筛选出具有某种特征的事件并按照特定的流程交由预定义的事件处理依赖进行处理。例如在快速上手中我们使用了内置插件echo它定义的事件响应器能响应机器人用户发送的/echo hello world消息提取hello world信息并作为回复消息发送。从源码结构看Matcher基类位于 nonebot/internal/matcher/matcher.py它通过类属性定义了事件响应器的核心组成要素这些要素也正是我们创建和配置响应器时控制的核心维度类属性类型含义typestr事件响应器类型与event.get_type()一致时触发空字符串表示响应所有类型ruleRule事件响应器匹配规则用于筛选事件特征permissionPermission事件触发权限在类型检查通过后进行校验handlerslist[Dependent]事件响应器拥有的事件处理函数列表priorityint响应优先级越小越先被触发blockbool是否阻止事件向更低优先级传播tempbool是否为临时响应器触发一次后自动删除expire_timedatetime事件响应器过期时间点过时即被自动销毁这些属性在Matcher.new()类方法nonebot/internal/matcher/matcher.py中被集中赋值新响应器会被动态创建为一个继承Matcher的子类并按其priority追加到全局的matchers[priority]列表中等待事件分发。事件响应器辅助函数NoneBot 中所有事件响应器均继承自Matcher基类但直接使用Matcher.new()方法创建事件响应器过于繁琐且不能记录插件信息。因此NoneBot 中提供了一系列事件响应器辅助函数下称辅助函数来辅助我们用最简的方式创建带有不同规则预设的事件响应器提高代码可读性和书写效率。通常情况下我们只需要使用辅助函数即可完成事件响应器的创建。在 NoneBot 中辅助函数以on()或on_type/rule()形式出现例如on_command()调用后根据不同的参数返回一个Type[Matcher]类型的新事件响应器。目前 NoneBot 提供了多种功能各异的辅助函数、具有共同命令名称前缀的命令组以及具有共同参数的响应器组均可以从nonebot模块直接导入使用。在 nonebot/init.py 中可以看到on、on_message、on_command、CommandGroup、MatcherGroup等符号均被从nonebot.plugin子模块重新导出因此插件中直接from nonebot import on_command即可使用。更多细节可参考事件响应器进阶。辅助函数的底层实现从源码 nonebot/plugin/on.py 可以看到所有辅助函数最终都会收敛到基础的on()函数其核心签名如下def on( type: str , rule: Rule | T_RuleChecker | None None, permission: Permission | T_PermissionChecker | None None, *, handlers: list[T_Handler | Dependent[Any]] | None None, temp: bool False, expire_time: datetime | timedelta | None None, priority: int 1, block: bool False, state: T_State | None None, _depth: int 0, ) - type[Matcher]:on()内部调用Matcher.new()完成响应器的创建并通过store_matcher()将响应器记录到当前正在加载的插件中nonebot/plugin/on.py。这正是直接使用Matcher.new()不能记录插件信息这一问题的解法get_matcher_source()通过检查调用栈将响应器的插件 ID、模块名、定义行号封装为MatcherSource并挂到响应器上nonebot/plugin/on.py后续可通过matcher.plugin、matcher.plugin_name、matcher.module_name等类属性查询其来源。而on_message()、on_notice()、on_request()、on_metaevent()则是对on()的薄封装只是把type固定为message、notice、request、meta_eventnonebot/plugin/on.py。注意on_message会默认设置blockTrue而on_command则默认blockFalsenonebot/plugin/on.py这决定了非命令类消息响应器默认会阻断事件向后续优先级传播。创建事件响应器在上一节创建插件中我们创建了一个weather插件现在我们来实现它的功能。我们直接使用on_command()辅助函数来创建一个事件响应器from nonebot import on_command weather on_command(天气)这样我们就获得一个名为weather的事件响应器了这个事件响应器会对/天气开头的消息进行响应。:::tip[提示] 如果一条消息中包含机器人或以机器人的昵称开始例如bot /天气时协议适配器会将event.is_tome()判断为True同时也会自动去除bot即事件响应器收到的信息内容为/天气方便进行命令匹配。 :::on_command会基于command规则进行命令匹配命令前缀与分隔符Command Start 与 Command Separator由全局配置控制默认情况下/天气即可触发。命令解析后的结果可以通过Command、RawCommand、CommandArg、CommandStart等依赖注入获取详见事件响应器进阶。内置插件的实战参照仓库内置插件echo给出了一个最小可用的完整示例nonebot/plugins/echo.pyecho on_command(echo, to_me()) echo.handle() async def handle_echo(message: Message CommandArg()): if any((not seg.is_text()) or str(seg) for seg in message): await echo.send(messagemessage)这里可以看到事件响应器的两种典型用法on_command(echo, to_me())创建带to_me规则的命令响应器echo.handle()装饰器则向响应器添加一个事件处理函数。响应器在匹配成功后会依次执行其handlers列表中注册的处理函数nonebot/internal/matcher/matcher.py处理函数支持依赖注入例如用CommandArg()提取命令参数。为事件响应器添加参数在辅助函数中我们可以添加一些参数来对事件响应器进行更加精细的调整例如事件响应器的优先级、匹配规则等。例如from nonebot import on_command from nonebot.rule import to_me weather on_command( 天气, ruleto_me(), aliases{weather, 查天气}, priority10, blockTrue )这样我们就获得了一个可以响应天气、weather、查天气三个命令的响应规则需要私聊或bot时才会响应优先级为 10越小越优先阻断事件向后续优先级传播的事件响应器了。下面逐一拆解这些参数的作用与底层影响rule响应规则rule接受一个Rule对象或RuleChecker函数用于筛选事件特征。Rule是若干个RuleChecker的集合在 nonebot/internal/rule.py 的实现中它会通过anyio.create_task_group()并发调用所有RuleChecker只有当全部检查通过时才视为匹配成功。多个规则可以使用运算符合并例如to_me() is_enableRule会忽略合并时的None值因此(rule None) is rule恒成立。to_me()则用于匹配事件是否与机器人相关私聊或bot场景。关于自定义RuleChecker的完整用法可参考响应规则。aliases命令别名aliases接受一个集合set[str | tuple[str, ...]]为命令添加别名。在on_command的实现中nonebot/plugin/on.pycmd与所有别名会被合并为一个命令集合统一交给command规则匹配因此天气、weather、查天气均能触发同一响应器。priority响应优先级priority是一个正整数越小越先被触发优先级相同时按注册顺序触发。底层实现中Matcher.new()会将响应器按优先级追加到matchers[priority]列表nonebot/internal/matcher/matcher.py事件分发时即按该顺序依次检查、触发。block阻断事件传播block是一个布尔值为True时事件被当前响应器处理后不再向更低优先级传播。内置响应器中所有非command规则的message类型响应器默认阻断其他则不会这与on_message默认blockTrue、on_command默认blockFalse的源码设定一致。此外在处理函数中还可以通过调用 matcher 实例的stop_propagation()方法动态阻止事件传播nonebot/internal/matcher/matcher.py。更多可选参数除上述参数外on()及大多数辅助函数还支持permission事件触发权限在类型检查通过后、规则检查前校验handlers预置的事件处理函数列表temp是否为临时响应器触发一次后自动销毁expire_time响应器过期时间点可传datetime或timedelta过时自动销毁Matcher.new()内部会将timedelta转换为datetime.now() expire_time见 nonebot/internal/matcher/matcher.pystate响应器的默认状态字典触发时初始化并进入事件处理流程。:::tip[提示] 需要注意的是不同的辅助函数有不同的可选参数在使用之前可以参考事件响应器进阶 - 基本辅助函数或 API 文档。 :::辅助函数速查表从源码 nonebot/plugin/on.py 与测试 tests/test_plugin/test_on.py 可以确认当前仓库提供以下辅助函数及其对应规则辅助函数对应响应规则典型用途on(type, ...)自定义类型创建任何类型的事件响应器on_message()—创建消息事件响应器默认blockTrueon_metaevent()—创建元事件响应器on_notice()—创建通知事件响应器on_request()—创建请求事件响应器on_startswith(msg, ignorecaseFalse)startswith消息纯文本以指定内容开头时响应on_endswith(msg, ignorecaseFalse)endswith消息纯文本以指定内容结尾时响应on_fullmatch(msg, ignorecaseFalse)fullmatch消息纯文本与指定内容完全一致时响应on_keyword(keywords)keyword消息纯文本包含关键词时响应on_command(cmd, aliases..., force_whitespace...)command消息以指定命令开头时响应on_shell_command(cmd, parser...)shell_command类 shell 命令支持 argparse 参数解析on_regex(pattern, flags0)regex消息匹配正则表达式时响应on_type(types)is_type事件为指定类型时响应其中on_command的force_whitespace参数用于控制命令与参数间的空白符要求为True时要求命令后必须有任意个空白符为字符串时要求命令后必须有与该字符串一致的空白符默认False允许不加空格on_shell_command传入ArgumentParser后可自动解析类 shell 命令参数on_regex使用search而非match进行正则匹配如需从头匹配请使用r^xxx模式。各规则更详细的定义可参考事件响应器进阶。小结事件响应器是 NoneBot2 插件的核心骨架通过一行辅助函数调用即可创建具备类型、规则、权限、优先级、阻断等完整属性的响应器借助aliases、rule、priority、block等参数可以精准控制响应器的触发条件与行为边界。其底层由Matcher.new()动态构建子类、按优先级注册到全局匹配表并由Rule并发执行全部RuleChecker完成筛选理解这一调用链有助于在复杂插件中排查事件未被响应或被多个响应器抢答的问题。创建好事件响应器后下一步就是为它添加事件处理函数并使用send、finish、pause等响应器操作完成交互可继续阅读事件处理与会话控制深入实践。赞分享后端即时通讯【免费下载链接】nonebot2跨平台 Python 异步聊天机器人框架 / Asynchronous multi-platform chatbot framework written in Python项目地址https://gitcode.com/gh_mirrors/no/nonebot2点击查看免费下载相关推荐NoneBot2 事件响应器Matcher进阶指南组成机制、内置响应规则与响应器组实战NoneBot2 事件响应器Matcher进阶指南组成机制、内置响应规则与响应器组实战 本篇进阶指南聚焦 NoneBot2 事件响应器Matcher的后端即时通讯3个关键步骤让xiaomusic在Windows上流畅运行小爱音箱音乐3个关键步骤让xiaomusic在Windows上流畅运行小爱音箱音乐 xiaomusic是一个开源音乐播放项目专为小爱音箱用户设计通过yt dlp技术实后端智能硬件音视频NoneBot2 事件响应器(Matcher)使用教程NoneBot2 事件响应器 Matcher 使用教程 什么是事件响应器 在 NoneBot2 框架中事件响应器 Matcher 是处理机器人接收到的事件的核后端即时通讯上一篇Whisper语音识别模型5分钟掌握高效语音转文字技术下一篇如何用现代前端技术打造极致优雅的诗词阅读体验AsPoem开源项目深度解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考