后端即时通讯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 中RevenueWithdrawalStateFailed类型docs/api/types/revenue_withdrawal_state_failed.rst为核心系统讲解 Telegram Stars 收益提现中「失败」状态的类型设计、判别字段、在getStarTransactions返回值中的出现位置以及配套的退款与状态轮询实战用法。读完本文你将掌握在 aiogram 中如何识别、解析提现失败状态并写出能够正确处理失败退款场景的 Stars 账本处理代码。一、RevenueWithdrawalStateFailed 在 aiogram 中的位置RevenueWithdrawalStateFailed是 Telegram Bot APIRevenueWithdrawalState对象的三种具体实现之一专门用于描述「提现失败且交易已被退款」的状态。在 aiogram 中它的完整模块路径为aiogram.types.revenue_withdrawal_state_failed由 aiogram/types/revenue_withdrawal_state_failed.py 定义并通过 aiogram/types/init.py 中的导出RevenueWithdrawalStateFailed、RevenueWithdrawalState、RevenueWithdrawalStatePending、RevenueWithdrawalStateSucceeded、RevenueWithdrawalStateUnion对外公开使用。从继承关系看它与RevenueWithdrawalStatePending提现进行中、RevenueWithdrawalStateSucceeded提现成功共同构成一个多态类型族其父类 RevenueWithdrawalState 的文档中明确列出了这三种可能形态RevenueWithdrawalStatePending—— 提现正在进行RevenueWithdrawalStateSucceeded—— 提现已成功RevenueWithdrawalStateFailed—— 提现失败交易被退款。二、类定义与字段解析RevenueWithdrawalStateFailed的源码定义非常精简其核心如下摘自 aiogram/types/revenue_withdrawal_state_failed.pyclass RevenueWithdrawalStateFailed(RevenueWithdrawalState): The withdrawal failed and the transaction was refunded. type: Literal[RevenueWithdrawalStateType.FAILED] RevenueWithdrawalStateType.FAILED Type of the state, always failed它只有一个字段字段说明如下字段类型取值含义typeLiteral[RevenueWithdrawalStateType.FAILED]恒为failed状态判别标记用于区分三种提现状态注意type字段被声明为Literal类型且带默认值这意味着在构造该对象时无需手动传入type默认即被赋为failed由于类型被收窄为字面量failed在 IDE 中对该对象进行状态判断时可以获得精确的类型推断——只要是RevenueWithdrawalStateFailed实例type就一定等于failed。与同为子类型的 RevenueWithdrawalStateSucceeded额外携带date完成时间和url交易详情链接字段不同RevenueWithdrawalStateFailed不携带额外字段语义上仅表达「提现失败 已退款」这一结果。枚举来源type的字面量取值来自枚举RevenueWithdrawalStateType定义于 aiogram/enums/revenue_withdrawal_state_type.pyclass RevenueWithdrawalStateType(str, Enum): FAILED failed PENDING pending SUCCEEDED succeeded由于 aiogram 的TelegramObject基类见 aiogram/types/base.py配置了use_enum_valuesTrue在序列化输出到 Telegram API 时枚举会以其字符串值如failed传输与 Bot API 的 JSON 字段保持一致。三、三个状态如何被统一识别判别联合类型在真实业务中你拿到的往往不是某一个具体状态类而是三者之一。aiogram 为此提供了判别联合类型RevenueWithdrawalStateUnion定义于 aiogram/types/revenue_withdrawal_state_union.pyRevenueWithdrawalStateUnion: TypeAlias Annotated[ RevenueWithdrawalStatePending | RevenueWithdrawalStateSucceeded | RevenueWithdrawalStateFailed, Field(discriminatortype), ]这里的Field(discriminatortype)表示 Pydantic 会根据type字段的取值自动把 JSON 解析到正确的子类型pending→RevenueWithdrawalStatePendingsucceeded→RevenueWithdrawalStateSucceededfailed→RevenueWithdrawalStateFailed在哪个 API 对象中出现RevenueWithdrawalStateUnion被用于 TransactionPartnerFragment 的withdrawal_state字段class TransactionPartnerFragment(TransactionPartner): type: Literal[TransactionPartnerType.FRAGMENT] TransactionPartnerType.FRAGMENT withdrawal_state: RevenueWithdrawalStateUnion | None None Optional. State of the transaction if the transaction is outgoing也就是说当你的机器人通过 Fragment 向 Telegram Stars 发起收益提现时这笔转出交易StarTransaction的receiver为TransactionPartnerFragment会携带withdrawal_state字段其值即为三种提现状态之一。若状态为RevenueWithdrawalStateFailed则说明提现失败且该笔 Stars 已被 Fragment 退回机器人余额。从 StarTransaction 的源码注释还可以确认退款路径的闭环source字段的文档明确提到「Fragment refunding a failed withdrawal」Fragment 退款一笔失败的提现是入账交易的典型来源。因此「提现失败」在账本上通常表现为两笔记录——一笔receiver为 Fragment 的失败转出状态failed随后一笔source为 Fragment 的退款转入。四、实战读取 Stars 账本并识别失败提现调用 getStarTransactionsaiogram 中将getStarTransactions封装为 GetStarTransactions 方法通过bot.get_star_transactions(...)调用返回 StarTransactions内部是list[StarTransaction]。方法参数如下参数类型默认值说明offsetint \| NoneNone跳过的事务数量用于翻页limitint \| NoneNoneAPI 侧默认 100单次最多返回的事务条数取值范围 1–100对应的 MockedBot 测试位于 tests/test_api/test_methods/test_get_star_transactions.py它验证了bot.get_star_transactions(limit10, offset0)的调用与响应反序列化流程可作为理解方法用法的参考。识别失败状态的代码示例from aiogram import Bot from aiogram.types import ( RevenueWithdrawalStateFailed, TransactionPartnerFragment, StarTransaction, ) async def find_failed_withdrawals(bot: Bot) - list[StarTransaction]: failed: list[StarTransaction] [] offset 0 while True: page await bot.get_star_transactions(offsetoffset, limit100) if not page.transactions: break for tx in page.transactions: # 提现是转出交易receiver 为 Fragment if isinstance(tx.receiver, TransactionPartnerFragment): state tx.receiver.withdrawal_state # 利用判别联合类型状态会被自动解析为具体子类 if isinstance(state, RevenueWithdrawalStateFailed): print( f提现失败已退款: tx_id{tx.id}, amount{tx.amount}, fstate{state.type} ) failed.append(tx) offset len(page.transactions) return failed关键点说明tx.receiver.withdrawal_state的类型是RevenueWithdrawalStateUnion | NonePydantic 已按type判别字段自动完成反序列化用isinstance(state, RevenueWithdrawalStateFailed)做运行时窄化后即可放心访问该状态其type恒为failed所有枚举比较在 aiogram 中均可直接使用字符串字面量例如state.type failed因为RevenueWithdrawalStateType本身继承自str。失败后的补救refundStarPayment当一次由用户发起的 Telegram Stars 支付需要退回时例如商品缺货、取消订单可调用bot.refund_star_payment。该方法封装自 RefundStarPayment参数为参数类型说明user_idint收款用户的标识telegram_payment_charge_idstrTelegram 支付流水号对应测试位于 tests/test_api/test_methods/test_refund_star_payment.py。需要区分两个不同层面的「退款」RevenueWithdrawalStateFailed描述的退款是 Fragment 向机器人退还失败的提现 Stars发生在「机器人 → 提现」方向上由 Telegram 系统自动完成你只能读取状态不能干预refundStarPayment执行的退款是机器人向用户退还已支付的 Stars发生在「用户 → 机器人」方向上由你的业务逻辑主动触发。参考示例Stars 收款与退款闭环仓库中的 examples/stars_invoice.py 展示了完整的 Stars 收款流程通过answer_invoice(currencyXTR, ...)发送演示发票在pre_checkout_query中校验库存并确认收款收到successful_payment后调用bot.refund_star_payment(...)完成退款。它证明了 StarsXTR是 Telegram 支付体系中的正式币种可作为理解提现业务上游的实战样板。五、状态机语义小结把三个状态放入整个生命周期理解Pending提现进行中 │ ├── 成功 ──► Succeededdate url可查看交易详情 └── 失败 ──► Failed交易被退款余额退回在 aiogram 中这组状态的建模要点可以总结为判别字段驱动反序列化RevenueWithdrawalStateUnion借助Field(discriminatortype)自动将 API 响应解析为正确的子类型开发者无需手写 if-else 的字段匹配字面量类型带来静态保证RevenueWithdrawalStateFailed.type的类型是Literal[RevenueWithdrawalStateType.FAILED]这意味着一旦对象类型被确认type取值不可能为其他值条件分支可以被静态检查工具完全验证贯穿整条 Stars 交易链从 get_star_transactions 的响应 →StarTransaction的receiver/source→TransactionPartnerFragment.withdrawal_state→ 三个状态子类aiogram 用类型注解完整覆盖了 Telegram 官方 API 对收益提现状态的全部描述。六、进一步阅读状态族定义revenue_withdrawal_state.py、revenue_withdrawal_state_pending.py、revenue_withdrawal_state_succeeded.py判别联合revenue_withdrawal_state_union.py状态枚举revenue_withdrawal_state_type.py承载该状态的对象transaction_partner_fragment.py、star_transaction.py关联 APIget_star_transactions.py、refund_star_payment.py对应测试test_get_star_transactions.py、test_refund_star_payment.pyStars 支付实战examples/stars_invoice.py赞分享后端即时通讯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 StarAmount 详解Telegram Stars 余额类型与纳星精度的完整指南aiogram StarAmount 详解Telegram Stars 余额类型与纳星精度的完整指南 本文围绕 aiogram 的类型参考文档 StarAmo后端即时通讯API设计aiogram 中 InputPaidMediaType 枚举详解Telegram Stars 付费媒体类型如何驱动 sendPaidMediaaiogram 中 InputPaidMediaType 枚举详解Telegram Stars 付费媒体类型如何驱动 sendPaidMedia 本篇围绕 a后端即时通讯API设计TransactionPartnerType 枚举aiogram 中 Telegram Stars 交易伙伴类型的定义、判别与应用TransactionPartnerType 枚举aiogram 中 Telegram Stars 交易伙伴类型的定义、判别与应用 本文围绕 aiogram后端即时通讯API设计上一篇3大技术突破yuzu Android版如何征服移动平台下一篇Ant Design Blazor Checkbox 组件完全指南基础用法、CheckboxGroup 与混合模式实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考