aiogram 删除机器人命令列表 deleteMyCommands：作用域与语言参数的完整实战指南

• 后端
• 即时通讯
• API设计

deleteMyCommands是 Telegram Bot API 中用于删除机器人已注册命令列表的标准方法，在 aiogram 中对应DeleteMyCommands方法对象与Bot.delete_my_commands()便捷调用。本文以 aiogram 官方 API 文档页 delete_my_commands.rst 为骨架，结合仓库内方法源码、Bot 客户端实现、作用域类型定义与单元测试，系统讲解该方法的作用、两个核心参数、四种调用形态、底层调用链以及它与setMyCommands的配合场景。读完本文，你将能够在 aiogram 中准确、安全地按作用域与语言代码删除机器人命令，并理解命令"回退到更高层级作用域"的实际含义。

方法概述：deleteMyCommands 的作用与返回值

deleteMyCommands用于删除给定作用域（scope）和用户语言（language code）下机器人的命令列表。删除之后，被删除命令所影响的用户将看到"更高级别（higher level）"的命令——这正是 Telegram 命令作用域分层机制的体现：当某个具体作用域的命令被删除，Telegram 会自动回退显示上一层级（例如全局默认）作用域中仍然存在的命令。

在 aiogram 中，该方法被建模为泛型方法对象：

class DeleteMyCommands(TelegramMethod[bool]): __returning__ = bool __api_method__ = "deleteMyCommands"

• __returning__ = bool表示调用成功后返回布尔值；
• __api_method__ = "deleteMyCommands"是发送给 Telegram Bot API 的实际方法名（小驼峰格式），源码见 aiogram/methods/delete_my_commands.py；
• 成功时返回True，这是 API 文档 delete_my_commands.rst 中明确声明的返回类型。

参数详解：scope 与 language_code

DeleteMyCommands方法对象只包含两个业务参数，均为可选，源码注释给出了精确语义：

scope：命令适用的用户作用域

scope: BotCommandScopeUnion | None = None

• 类型为BotCommandScopeUnion，即 7 种BotCommandScope子类的联合类型；
• 默认值为None，此时 Telegram 按BotCommandScopeDefault（默认作用域）处理，即作用于所有用户，且不会出现更窄作用域的替代命令；
• 该参数在 Telegram API 层面是 JSON 序列化对象，aiogram 中则直接传入对应的作用域对象，由底层序列化后发送。

language_code：语言代码

language_code: str | None = None

• 类型为字符串，取值为两位 ISO 639-1 语言代码（如en、ru、zh）；
• 为空（None）时，删除操作将应用于指定作用域下"没有专属命令语言"的全部用户，即作为该作用域的兜底语言版本；
• 提供了具体语言代码时，只删除该语言专属的命令列表。

提示：作用域 + 语言代码共同定位"某一批命令"。例如你可以为中文用户单独注册命令菜单，再单独删除它而不影响英文用户的命令。

四种调用方式（继承自官方文档的完整用法）

官方 API 文档页 给出了四种等价用法，下面逐一展开并补充完整可运行示例。

方式一：作为 Bot 方法直接调用

这是最常用的形式，通过Bot实例的快捷方法：

result: bool = await bot.delete_my_commands(...)

其中...位置可传入scope与language_code两个命名参数。例如：

result: bool = await bot.delete_my_commands() # 等价于删除默认作用域下所有语言的命令

方式二：作为方法对象使用（两种导入路径）

DeleteMyCommands支持两种导入方式：

from aiogram.methods.delete_my_commands import DeleteMyCommands # 或使用包级别名： from aiogram.methods import DeleteMyCommands

第二种写法之所以可行，是因为 aiogram/methods/init.py 中导出了DeleteMyCommands（仓库中同一目录还导出了配套的SetMyCommands）。

方式三：绑定到指定 Bot 实例执行

方法对象可显式传给bot(...)调用：

result: bool = await bot(DeleteMyCommands(...))

方式四：在 Webhook 处理器中作为返回值

在基于 Webhook 的分发架构中，可以直接从 update 处理器返回方法对象，aiogram 会将其作为 reply 发送：

return DeleteMyCommands(...)

结合 aiogram/methods/base.py 的实现可知，该形式得以成立的原因：TelegramMethod实现了__await__，当方法对象通过as_(bot)挂载到 Bot 实例后，await method会经由emit(bot)转调bot(method)完成实际请求。

源码级原理：从快捷方法到网络请求的调用链

Bot.delete_my_commands 的实现

aiogram/client/bot.py 中定义了快捷方法，其逻辑是构造DeleteMyCommands方法对象并转交统一的调用入口：

async def delete_my_commands( self, scope: BotCommandScopeUnion | None = None, language_code: str | None = None, request_timeout: int | None = None, ) -> bool: call = DeleteMyCommands( scope=scope, language_code=language_code, ) return await self(call, request_timeout=request_timeout)

注意：快捷方法额外暴露了request_timeout参数，允许为本次请求单独指定超时时间，这是方法对象本身不直接暴露的运行时参数。

统一的请求分发入口

Bot.__call__是所有 Telegram 方法对象的最终分发点（aiogram/client/bot.py）：

async def __call__(self, method: TelegramMethod[T], request_timeout: int | None = None) -> T: return await self.session(self, method, timeout=request_timeout)

因此无论是bot.delete_my_commands(...)还是bot(DeleteMyCommands(...))，最终都汇聚到 session 层发出 HTTP 请求，只是封装层次不同。

TelegramMethod 基类的约束

DeleteMyCommands继承自TelegramMethod[bool]（aiogram/methods/base.py），这是一个基于 pydantic 的抽象基类：

• 要求子类声明__returning__（返回类型）与__api_method__（API 方法名）；
• 使用extra="allow"、populate_by_name=True等配置，保证与 Bot API 字段命名对齐；
• 提供remove_unset校验器，在字段校验前剔除UNSET哨兵值——这也是scope、language_code传None时不会产生多余请求字段的底层保障。

深入 scope：七种命令作用域全解析

scope参数的类型BotCommandScopeUnion在 aiogram/types/bot_command_scope_union.py 中定义为 7 种作用域类的联合，并借助Field(discriminator="type")按type字段自动反序列化。七种作用域定义于 aiogram/types/bot_command_scope.py，对应枚举值见 aiogram/enums/bot_command_scope_type.py：

需要附加字段的三种作用域对chat_id的支持见各类型源码（如 bot_command_scope_chat.py）：支持数字 ID 或@username形式的超级群用户名，但不支持频道直聊会话与频道会话。user_id为目标用户的唯一标识符（见 bot_command_scope_chat_member.py）。

删除命令时的典型用法，例如只删除指定超级群中的命令而不影响其他会话：

from aiogram.types import BotCommandScopeChat result = await bot.delete_my_commands(scope=BotCommandScopeChat(chat_id=-1001234567890))

与 setMyCommands 的配套使用

删除命令与注册命令是一对操作：setMyCommands用于设置命令列表，deleteMyCommands用于清除。二者参数签名几乎完全对齐（都接受scope与language_code），便于按同一作用域"注册 / 注销"。

• setMyCommands要求必传commands: list[BotCommand]，最多 100 条，每条命令名须为 1–32 个字符的小写英文字母、数字与下划线，描述为 1–256 字符（见 aiogram/methods/set_my_commands.py）；
• 其 Bot 快捷方法同样位于 aiogram/client/bot.py。

典型场景：当某个功能下线时，用同样的scope与language_code调用delete_my_commands，即可将该功能的命令菜单整体移除，且不影响其他层级命令的显示（按"更高层级命令回退"规则）。

测试验证：如何确认调用行为

仓库中提供了针对该方法的单元测试 tests/test_api/test_methods/test_delete_my_commands.py：

from aiogram.methods import DeleteMyCommands from tests.mocked_bot import MockedBot class TestKickChatMember: async def test_bot_method(self, bot: MockedBot): prepare_result = bot.add_result_for(DeleteMyCommands, ok=True, result=True) response: bool = await bot.delete_my_commands() bot.get_request() assert response == prepare_result.result

测试要点：

• 使用MockedBot预先注册返回结果为True的桩响应；
• 调用bot.delete_my_commands()后，通过bot.get_request()校验请求确实被发出；
• 断言返回值为True，与__returning__ = bool的类型声明一致。

这表明在不依赖真实 Telegram 网络的情况下，可以通过 MockedBot 完整验证delete_my_commands的请求构造与返回解析。

实战注意事项

1. 作用域回退是"删除后自动发生"的：删除窄作用域命令后，受影响用户会看到更高层级（如BotCommandScopeDefault）仍保留的命令，因此无需手动"恢复"默认命令；
2. 语言代码要成对管理：设置命令与删除命令时尽量保持相同的language_code，避免留下"空壳语言版本"；
3. 默认值语义：不传scope与language_code时，删除的是默认作用域下所有语言用户的命令，属于"全局清空"操作，生产环境中应谨慎使用；
4. 超时控制：需要更严格请求超时时，使用 Bot 快捷方法并显式传request_timeout，而不是直接构造方法对象；
5. 返回判断：方法返回True才代表删除成功，可通过该布尔值驱动后续业务逻辑（如前端菜单刷新提示）。

借助 aiogram 的类型化方法对象与七种作用域封装，deleteMyCommands的调用全程拥有静态类型检查与 IDE 补全支持，既可以在普通会话中按 bot 方法一行调用，也可以在 Webhook 分发中直接作为 handler 返回值，是管理机器人命令菜单生命周期中不可缺少的一环。

• 后端
• 即时通讯
• API设计