后端即时通讯API设计【免费下载链接】aiogramaiogram is a modern and fully asynchronous framework for Telegram Bot API written in Python using asyncio项目地址https://gitcode.com/gh_mirrors/ai/aiogram点击查看免费下载RichTextEmailAddress 是 aiogram 中用于表示带有邮箱地址的富文本的核心类型节点它隶属于 Telegram Bot API 的 Rich Text富文本消息体系服务于sendRichMessage等新一代富消息发送接口。本文以 RichTextEmailAddress API 文档 为主线结合 类型源码、判别联合实现 与 回归测试讲解该节点的字段语义、在RichTextUnion中的反序列化机制以及如何在实际 bot 中构造并发送包含邮箱地址的富文本消息。一、文档与源码定位一个 autodoc 驱动的类型页docs/api/types/rich_text_email_address.rst是 aiogram 文档站中该类型的唯一入口其内容非常精简仅包含标题与一段 Sphinxautomodule指令#################### RichTextEmailAddress #################### .. automodule:: aiogram.types.rich_text_email_address :members: :member-order: bysource :undoc-members: True :exclude-members: model_config,model_fields这说明该文档页是完全由源码 docstring 与类型注解自动生成的automodule从 aiogram/types/rich_text_email_address.py 拉取类定义、字段与构造函数签名member-order: bysource按源码顺序排列成员undoc-members: True保证未写 docstring 的成员也会被收录而model_config、model_fields两个 Pydantic 内部属性被排除在文档之外。因此要完整理解该类型必须直接阅读其源码实现——这正是本文展开的核心依据。二、类定义与字段语义RichTextEmailAddress定义在 aiogram/types/rich_text_email_address.py继承自RichText即 aiogram/types/rich_text.py 中的RichText基类本质是一个基于 PydanticBaseModel的 Telegram API 对象模型。其官方语义为A text with an email address.一段带邮箱地址的文本。类中共有三个字段字段类型必填语义typeLiteral[RichTextType.EMAIL_ADDRESS]否有默认值富文本类型固定为email_address由 RichTextType 枚举 中的EMAIL_ADDRESS email_address提供textRichTextUnion是该节点承载的文本内容email_addressstr是关联的邮箱地址字符串其中type被声明为Literal[RichTextType.EMAIL_ADDRESS] RichTextType.EMAIL_ADDRESS即它是一个常量标签字段构造时无需也不应手动指定。text的类型是RichTextUnion这是一个非常关键的联合类型下文单独展开。源码在TYPE_CHECKING块中还提供了由butcher工具自动生成的__init__签名它不参与运行时逻辑仅用于让 IDE 与静态类型检查器在没有 Pydantic 插件的情况下也能获得完整的构造提示def __init__( __pydantic__self__, *, type: Literal[RichTextType.EMAIL_ADDRESS] RichTextType.EMAIL_ADDRESS, text: RichTextUnion, email_address: str, **__pydantic_kwargs: Any, ) - None: super().__init__(typetype, texttext, email_addressemail_address, **__pydantic_kwargs)2.1 基类链路TelegramObject → RichText类型继承链为RichTextEmailAddress→RichText→TelegramObject。RichText本身只承载一段说明性 docstring列举了当前全部 25 种富文本子类型Bold、Italic、Underline、Strikethrough、Spoiler、DateTime、TextMention、Subscript、Superscript、Marked、Code、CustomEmoji、MathematicalExpression、Url、EmailAddress、PhoneNumber、BankCardNumber、Mention、Hashtag、Cashtag、BotCommand、Button、Anchor、AnchorLink、Reference、ReferenceLink见 aiogram/types/rich_text.py。真正提供数据能力的是TelegramObjectaiogram/types/base.py它配置了 Pydantic 的关键行为use_enum_valuesTrue枚举字段包括type在序列化时直接使用枚举的字符串值因此发送给 Telegram 时type就是email_addressfrozenTrue模型不可变实例构造后字段只读extraallow允许额外字段对 Telegram 侧新增字段保持向前兼容validate_assignmentTrue赋值时同样触发校验defer_buildTrue延迟构建模型配合递归联合类型如RichTextUnion使用。三、text字段与 RichTextUnion 判别联合RichTextUnion定义在 aiogram/types/rich_text_union.py它是 aiogram 富文本体系中最重要的类型之一其类型别名可归纳为三类合法取值纯字符串如helloexample.com表示普通文本字符串/节点的数组如[a, RichTextBold(textb)]表示一组依次渲染的子片段任意一种RichText*模型包括RichTextBold、RichTextItalic、RichTextSpoiler、RichTextUrl、RichTextEmailAddress等 25 个具体子类。由于联合成员既包含str、list这样的 Python 原生类型又包含以type字段区分的 Pydantic 模型它不能像普通 Telegram 联合类型那样直接使用Field(discriminatortype)。aiogram 的解决方案是自定义一个运行时判别函数_rich_text_union_tagdef _rich_text_union_tag(value: Any) - Any: if isinstance(value, str): return str if isinstance(value, (list, tuple)): return list if isinstance(value, dict): return value.get(type) return getattr(value, type, None)即字符串按其 Python 类型打str标签数组打list标签字典与模型实例则读取其type字段如email_address作为标签。最终通过TypeAliasType与Annotated/Tag/Discriminator组合成一个以type为判别键的判别联合。3.1 为什么需要判别联合回归测试 #1925CHANGES/1925.bugfix.rst 记录了一次重要修复此前RichTextUnion是一个普通的智能联合Pydantic 会在每一层嵌套上逐个尝试所有成员导致加粗套斜体套剧透这类多层嵌套富文本的校验呈指数级变慢甚至冻结事件循环。修复后改为按type判别的联合回归测试 中用一个 5 层嵌套的更新负载验证了每个节点都能正确解析为具体类型并用 POSIX 的SIGALRM计时器断言30 层嵌套的RichTextUnion校验耗时小于 1 秒超过 5 秒即判定回归。这对使用者的实际意义是RichTextEmailAddress作为RichTextUnion的成员之一可以放心地与RichTextBold、RichTextItalic等节点无限嵌套组合而不会遭遇解析性能陷阱。四、从节点到消息构造带邮箱地址的富文本RichTextEmailAddress不会独立出现它总是被嵌套在富消息Rich Message结构中。发送富消息使用SendRichMessage方法aiogram/methods/send_rich_message.py其 API 方法名为sendRichMessage核心参数为chat_id与rich_message类型为InputRichMessage。InputRichMessageaiogram/types/input_rich_message.py提供三种互斥的内容描述方式html、markdown或blocks。其中blocks是结构化方式——一个InputRichBlockUnion列表每个块可以是段落InputRichBlockParagraph、标题、引用、表格等完整清单见 aiogram/types/input_rich_block.py。而段落块的text字段正是RichTextUnion邮箱地址节点就挂在这里。以下示例构造一条正文 可点击邮箱地址的富消息并通过send_rich_message发送from aiogram import Bot from aiogram.types import ( InputRichBlockParagraph, InputRichMessage, RichText, RichTextEmailAddress, ) bot Bot(TOKEN) await bot.send_rich_message( chat_idchat_id, rich_messageInputRichMessage( blocks[ InputRichBlockParagraph( textRichText( [ 欢迎来信, RichTextEmailAddress( textcontactexample.com, email_addresscontactexample.com, ), ] ) ) ] ), )关键点说明RichText与RichTextEmailAddress同为RichTextUnion的合法成员可直接混用text字段是用户看到的渲染文本email_address是被识别并关联的邮箱地址两者既可以相同如上例也可以不同例如显示联系我们而关联真实邮箱type字段无需传参默认即为email_address若消息同时包含媒体块bot 需具备对应媒体的发送权限见SendRichMessagedocstring。InputRichMessage还支持is_rtl从右到左渲染与skip_entity_detection跳过 URL、邮箱、用户名、话题标签等实体的自动识别后者对显式构造的富文本节点没有影响。五、与相近类型的对比Url、PhoneNumber、BankCardNumberRichTextEmailAddress在结构上与其姐妹节点高度相似它们共享完全相同的字段布局一个固定的type常量 一个text: RichTextUnion 一个专用承载字段。以 RichTextUrl 与 RichTextPhoneNumber 为例类型type 常量承载字段字段语义RichTextUrlurlurl: str链接地址RichTextEmailAddressemail_addressemail_address: str邮箱地址RichTextPhoneNumberphone_numberphone_number: str电话号码同样模式的还有RichTextBankCardNumber银行卡号、RichTextHashtag、RichTextCashtag、RichTextBotCommand、RichTextMention等。理解这一点后掌握其中一个节点即可触类旁通地使用整个实体型富文本家族。六、使用建议与注意事项序列化形态由于use_enum_valuesTrueRichTextEmailAddress序列化后为{type: email_address, text: ..., email_address: ...}与 Telegram Bot API 的RichTextEmailAddress定义https://core.telegram.org/bots/api#richtextemailaddress保持一致嵌套自由text可以继续嵌套其他富文本节点例如让邮箱地址局部加粗RichTextEmailAddress(text[RichTextBold(textmeexample.com)], email_addressmeexample.com)性能已由判别联合机制保证只读模型TelegramObject默认frozenTrue构造后不能修改字段需要变更时请重新构造实例文档查阅方式本类型的正式 API 文档由 docs/api/types/rich_text_email_address.rst 提供它是整个 docs/api/types 目录下 638 个 API 页面之一体系中的其他富文本节点文档位于同目录例如 rich_text.rst、rich_text_url.rst、input_rich_message.rst发送方法见 send_rich_message.rst。七、小结RichTextEmailAddress是 aiogram 富文本消息体系中的一个小而专的实体节点三个字段、一个固定类型常量、一套统一基类。它的真正复杂性体现在两点——其text字段所指向的RichTextUnion判别联合及其防指数级退化的回归测试以及它作为InputRichMessage.blocks结构化内容的一环如何参与sendRichMessage的实际发送。理解这两个层面即可在 aiogram 中熟练构造带邮箱地址、链接、电话等实体的下一代富文本消息。赞分享后端即时通讯API设计【免费下载链接】aiogramaiogram is a modern and fully asynchronous framework for Telegram Bot API written in Python using asyncio项目地址https://gitcode.com/gh_mirrors/ai/aiogram点击查看免费下载相关推荐aiogram 富文本类型详解RichTextCashtag 的字段、联合类型判别与实战用法aiogram 富文本类型详解RichTextCashtag 的字段、联合类型判别与实战用法 导读 本文围绕 aiogram 对 Telegram Bot A后端即时通讯API设计aiogram 中 RichTextStrikethrough 详解富文本消息里删除线节点的构造、联合类型分发与发送实战aiogram 中 RichTextStrikethrough 详解富文本消息里删除线节点的构造、联合类型分发与发送实战 本文以 aiogram 官方 API后端即时通讯API设计aiogram 中 RichTextReference 深度解析Telegram 富文本引用节点的字段模型、联合类型判别与实战用法aiogram 中 RichTextReference 深度解析Telegram 富文本引用节点的字段模型、联合类型判别与实战用法 本文围绕 RichText后端即时通讯API设计创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考