从 6 万秒超时到 3 秒闭环:pure_live 虎牙醒目留言板 HTTP 请求所有权审计与修复全解析
从 6 万秒超时到 3 秒闭环:pure_live 虎牙醒目留言板 HTTP 请求所有权审计与修复全解析
导读
本文围绕 pure_live 仓库中虎牙(Huya)醒目留言(Super Chat,下称 SC)留言板 HTTP 请求的一次专项审计展开,剖析了"默认超时单位错位、缺少发送/接收总等待边界、Dio 客户端生命周期泄漏、Future.timeout 不取消底层连接、双实现不一致"五类资源所有权缺陷,并完整还原修复设计、源码实现与验证门禁过程。读完本文,你将掌握如何为第三方平台的辅助型 HTTP 请求设计"每次请求独占客户端 + 全路径强制关闭 + 总等待上限"的资源所有权模型,并理解如何用真实 Dio 适配器与 TARS 编解码做不依赖源码字符串匹配的回归测试。
一、背景:醒目留言板在 pure_live 虎牙通道中的位置
在 pure_live 中,虎牙直播的弹幕与醒目留言由 HuyaDanmaku(lib/shared/platforms/huya/huya_danmaku.dart)统一承载。醒目留言存在两条获取通道:
- WebSocket 推送通道:弹幕服务通过
uri 2001314直接推送留言板面板(GameEventMessageBoardPanel),通过uri 1400推送弹幕区播报(形如"xxx(来自一元上头条)")。 - HTTP 留言板通道:通过虎牙 WUP(
wup.huya.com)接口以 TARS 编解码方式拉取全量留言板快照,作为推送缺失时的后台对账来源。
本文审计对象正是后者——getHuyaSuperChatMessageList 这条 HTTP 请求链路的**资源所有权(ownership)**问题:谁创建客户端、谁负责关闭、等待边界在哪里、超时后底层连接是否仍存活。
二、审计发现:五类资源所有权缺陷
本次审计冻结在本地基线 124ec716(只读上游 c6c9bd70,本轮不合并上游),对"上游既有实现"与"本分支实现"分别梳理出如下问题。
1. 默认超时单位错位:60000 被当作"秒"
上游留言板沿用通用 TARS HTTP 基类 BaseTarsHttp(lib/core/tars/base_tars_http.dart),其默认字段为:
var timeOut = 60000;
而构造函数把该值直接作为 Duration(seconds: timeOut) 注入 Dio 的 connectTimeout:
dio = Dio(
BaseOptions(
connectTimeout: Duration(seconds: timeOut),
...
),
);
也就是说,包装类把本应是毫秒语义的 60000 解释成了 60000 秒(约 16.7 小时)。留言板这类辅助请求一旦挂在弱网上,理论上可悬挂近一天。同时,该基类只设置了 connectTimeout,没有发送超时(sendTimeout)与接收超时(receiveTimeout),缺少"发送/接收总等待边界"。
2. 每次请求创建 Dio,成功/失败均不关闭
BaseTarsHttp 在构造函数中 late final Dio dio,而留言板调用方每次请求都 new 一个客户端却从不关闭。Dio 底层持有 socket 连接池,频繁的 SC 轮询/重试会持续累积未释放连接。
3. 外层 Future.timeout 只结束等待,不取消底层连接
本分支 398d182d 已把 WebSocket 处理与留言板等待分开,但外层 3 秒 Future.timeout 只让调用方停止等待,原始 Future 仍可能继续完成(这正是 Dart Future.timeout 的官方契约)。弱网重试时,多个"仍在等待/仍在传输"的旧请求会与新的重试叠加,放大资源泄漏。
4. 双实现不一致:HTTPS 与 HTTP 各一份
huya_site.dart 与 huya_utils.dart 中存在两份留言板请求/解析实现:一份 HTTPS、一份 HTTP(旧 wupUrl = "http://wup.huya.com",见 lib/shared/platforms/huya/huya_request_params.dart),且空列表处理与"最近一条"的排序逻辑不一致。重复实现会扩大修复遗漏的风险——修好一份、漏掉另一份。
审计结论边界:这属于辅助请求的资源缺陷,不作为已证明的媒体 EOF 或所有 CPU/卡顿问题的根因。它独立存在,但不应被夸大与其他播放问题混为一谈。
三、修复设计:一份实现、三向有界、全路径关闭
修复设计的原则可概括为四条:
- 共用一份 HTTPS 实现,废弃 HTTP 重复实现,消除排序与空列表行为分叉;
- 连接/发送/接收各有界,整次留言板请求最多等待 3 秒;
- 每次请求独占客户端,并在成功、HTTP 失败、解码失败、总超时四条路径上统一强制关闭;
- 保留既有正确行为:WebSocket 消息非阻塞处理、按会话隔离、现有有限重试、事件 ID 去重。
同时明确不做的边界:不更改通用 TARS 默认值、不新增长期后台任务、不更改直播取流、录制或界面代码。
四、源码级实现解读
4.1 客户端工厂:连接/发送/接收三向 2 秒有界
修复后的客户端工厂位于 lib/shared/platforms/huya/huya_utils.dart:
BaseTarsHttp createHuyaMessageBoardClient() {
// This endpoint is auxiliary to playback. Do not inherit the legacy TARS
// timeout (60000 seconds) or let one retry retain another retry's socket.
final client = BaseTarsHttp('https://wup.huya.com', 'wupui', timeOut: 2, headers: HuyaRequestParams.requestHeaders);
client.dio.options.sendTimeout = const Duration(seconds: 2);
client.dio.options.receiveTimeout = const Duration(seconds: 2);
return client;
}
关键点:
- 服务地址统一为 HTTPS
https://wup.huya.com,servant 名为wupui,走application/x-wup内容类型; timeOut: 2只覆盖基类原本的connectTimeout,配合显式sendTimeout/receiveTimeout,连接、发送、接收三段各有 2 秒上限;- 请求头来自
HuyaRequestParams.requestHeaders(lib/shared/platforms/huya/huya_request_params.dart):Origin、Referer指向https://www.huya.com,User-Agent使用固定 SDK UAHYSDK(Windows,30000002)_APP(pc_exe&7100004&official)_SDK(trans&2.40.0.6448)。
4.2 请求主流程:独占客户端 + finally 强制关闭
Future<List<LiveSuperChatMessage>> getHuyaSuperChatMessageList({
required int lPid,
bool first = false,
BaseTarsHttp Function()? clientFactory,
}) async {
final messageBoardClient = (clientFactory ?? createHuyaMessageBoardClient)();
var userId = HuyaUserId()..sHuYaUA = HuyaRequestParams.hysdkUa;
var req = GetGameEventMessageBoardReq()
..lPid = lPid
..tId = userId
..iMessageBoardScope = 0
..iPageSize = 50;
final GetGameEventMessageBoardRsp rsp;
try {
rsp = await messageBoardClient
.tupRequest('getHeadLineMessageBoard', req, GetGameEventMessageBoardRsp())
.timeout(const Duration(seconds: 3));
} finally {
// Future.timeout only stops waiting. Closing the actual transport here
// prevents outstanding HTTP requests from accumulating on repeated SCs.
messageBoardClient.dio.close(force: true);
}
...
}
该实现值得逐点拆解:
clientFactory是测试接缝:生产环境默认走createHuyaMessageBoardClient,测试可注入等价客户端而不改变超时与资源所有权语义;- 请求参数:
lPid为频道 ID(对应房间详情的topSid),iPageSize = 50,iMessageBoardScope = 0,tId携带 SDK UA。TARS 请求体定义见 lib/core/tars/get_game_event_message_board_req.dart(字段lPid/sOffset/tId/iMessageBoardScope/iPageSize,tag 0–4); finally强制关闭:dio.close(force: true)保证无论成功、HTTP 失败、WUP 解码失败还是 3 秒总超时,底层活动连接都被关闭——这是修复的核心。finally只关闭本次请求自建客户端,不会关闭其他平台/房间共享的 Dio;- 外层 3 秒
timeout仍保留:作为注入 fetcher 的独立总等待保障(在 WebSocket 刷新管线中也存在同样的 3 秒兜底)。
4.3 排序与"最近一条"语义:按时间而非价格
final messages = huyaSuperChatsFromPanel(rsp.tMessageBoardPanel);
// 最新在前(按 startTime 逆序);上游注释:虎牙按 money→level→countDown
// 排序,这里统一调整为时间序,见 dart_simple_live #157 的说明。
messages.sort((a, b) => b.startTime.compareTo(a.startTime));
if (first) {
// 首次拉起只保留最新 10 条,避免一次铺满弹幕区。
return messages.length > 10 ? messages.sublist(0, 10) : messages;
}
return messages.isEmpty ? messages : [messages.first];
- 上游排序按
money → level → countDown(金额优先),本实现统一改为按startTime时间序逆序(最新在前),避免金额排序导致 SC 展示顺序与用户直觉不符; first = true用于首次拉起/房间加载,只保留最新 10 条,防止一次铺满弹幕区;- 非首次(WebSocket 对账场景)只取最新一条,配合事件 ID 去重,实现"补拉缺失的那条 SC"而非整页重复渲染。
4.4 面板解析:字段到模型的时间窗重建
huyaSuperChatsFromPanel 将 TARS 面板(lib/core/tars/game_event_message_board_info.dart 的 GameEventMessageBoardInfo,字段 tag 0/1/2/4/5/9/12)转为统一的 LiveSuperChatMessage(lib/core/models/live_message.dart):
- 内容为空白(
sContent.trim().isEmpty)的条目直接跳过; remainSec优先取iCountDown(剩余倒计时),否则用iTotalSec,为 0 或负则跳过——倒计时已结束的留言不再展示;- 价格为
iCost;当iCost <= 0而iCostPay > 0时,按max(1, iCostPay / 100)以"分转元"兜底; - 时间窗重建:
endTime = now + remainSec,startTime = endTime - totalSeconds,由倒计时反推展示起止点; messageId为lMessageId > 0时生成huya:xxx平台事件 ID——这是去重与"同一条 SC 不重复渲染"的根基。
4.5 站点委托入口
HuyaSite(lib/shared/platforms/huya/huya_site.dart)对外暴露统一入口:
@override
Future<List<LiveSuperChatMessage>> getSuperChatMessage({required LiveRoom liveroom}) async {
final roomId = liveroom.roomId ?? '';
...
if (args.topSid != 0) {
ls = await getHuyaSuperChatMessageList(lPid: args.topSid, first: true);
}
return ls;
}
即:先拉取房间详情解析出 topSid,再以 first: true 拉取留言板;同时内部另有直接委托 getHuyaSuperChatMessageList 的转发方法(huya_site.dart 第 1178–1179 行)。生产委托路径在验证中实测 232 ms 返回合法空留言板。
五、与 WebSocket 通知管线的协同
HTTP 留言板并非孤立存在,它与弹幕 WebSocket 共用一套刷新与去重管线(lib/shared/platforms/huya/huya_danmaku.dart):
- 通知优先,HTTP 兜底:
uri 2001314消息体本身可能就是留言板面板(superChatsFromPanel尝试解析);解析失败或通知先于留言板更新到达时,走_scheduleSuperChatRefresh后台补拉,不阻塞 WebSocket 解码。弹幕区播报(来自.+?上头条)也会触发同样的补拉管线; - 有限重试:默认重试延迟表为
Duration.zero、600ms、1800ms、4000ms四次,_refreshSuperChats内对每次拉取再套 3 秒timeout; - 事件 ID 去重:
_emittedSuperChats集合按LiveSuperChatMessage的相等性去重——只要messageId非空,就按 ID 判等,上限 512 条防内存膨胀。这正是"每次轮询从倒计时重建 startTime、时间相等性会失效"场景下的正确解法(见 lib/core/models/live_message.dart 中operator ==的实现); - 会话隔离:
_generation代际号确保旧房间的补拉不会污染新房间会话。
六、测试验证与门禁结果
本次修复的验证策略是:通过真实 Dio 适配器与 TARS 编解码验证,不只匹配源代码字符串。
1. 修复前的七项回归(红)
修复前先抽出等价的客户端工厂作为测试接缝(不改变超时/资源所有权),七项回归实际失败(记录文件 20260905T044754648Z-quality-focused.json)。其中前两轮夹具构造缺少合法的 TARS 响应字段,相关夹具错误不计为产品缺陷;补全后本记录七项均失败于 HTTPS/连接释放断言,证明问题真实存在于资源所有权而非解析逻辑。
2. 修复后的 130/130 定向测试(绿)
修复后,7 项留言板测试与现有弹幕传输、播放器、签名、缓存测试合计 130/130 全部通过(20260905T045039282Z-quality-focused.json),覆盖维度包括:
- 请求方法(
getHeadLineMessageBoardWUP 调用)、主播 ID(lPid)、页大小、UA; - 空结果、排序/事件 ID、正常返回;
- HTTP 失败、WUP 解码失败、超时关闭。
面板解析的确定性夹具可见 test/shared/platforms/huya_headline_panel_test.dart:用本仓自带的 Tars 写入器拼出面板字节(不依赖上游 fixture 文件),逐字段断言 messageId、昵称、内容、价格、起止时间,并覆盖空面板(留言板已空)与非面板消息体(返回 null 触发补拉)的区分。
3. 生产委托与完整门禁
- 生产
HuyaSite委托入口公开 HTTPS/WUP 请求通过,232 ms 返回合法空留言板(20260905T045242145Z-quality-focused.json)。该房间当时没有醒目留言,故不据此声称"正在发送的付费留言已由真实 UI 接收";有内容/排序/ID 的行为由前述确定性夹具分别验证; - 最终完整门禁运行于提交
4aefaa04:868/868 单元/Widget 测试、42/42 接口探测通过,一次analyze无诊断(20260905T045902783Z-quality-full.json); - 回滚边界明确:回滚只涉及此共享助手、
HuyaSite的委托和相关测试,不回退播放器已验证的原生凭据/预取策略——修复被刻意隔离,便于独立回退。
七、关键契约备忘
Future.timeout合同(Dart API 文档):timeout只让调用方停止等待,原始 Future 仍可继续完成。因此任何"超时 = 资源已释放"的假设都是错误的,必须显式关闭底层传输——这正是finally { dio.close(force: true); }存在的原因。Dio.close(force: true)合同(Dio 文档):force: true会关闭活动连接;false则等待空闲。留言板场景选择force: true,确保弱网悬挂连接被立即回收。
结语
虎牙醒目留言板 HTTP 审计给出了一条可复用的资源所有权范式:辅助型 HTTP 请求应当"每次请求独占客户端、连接/发送/接收三向有界、总等待兜底、全路径强制关闭",并把 WebSocket 推送与 HTTP 对账做成"通知优先、后台补拉、事件 ID 去重、代际隔离"的双通道协同。源码层面,lib/shared/platforms/huya/huya_utils.dart、lib/shared/platforms/huya/huya_danmaku.dart、lib/core/tars/base_tars_http.dart 与 test/shared/platforms/huya_headline_panel_test.dart 构成了"实现—基类—测试"的完整证据链,供后续平台接入同类功能时直接参考。