企业官网建设流程全解析

• 音视频
• 直播
• 移动开发

花椒（huajiao.com）在 Pure Live 的多站点扩展计划中属于"参考平台"之一。由于旧版 PC 直播页已重定向为宣传/下载页，真正可用的公开直播信息只能从花椒官方 H5 移动主页与 H5 广播页的内联脚本中静态取证。本文以 Pure Live 仓库中的底层阶段审计文档为主线，完整还原花椒 H5 公开 API 的合同拆解、8 组现网差异与实现决策、红测修订（含 Dio 流式响应的取消语义问题）、34 项定向测试与生产 API 探针的验证闭环，并结合当前仓库源码（目录游标分页控制器、站点注册与配置迁移）说明这些 API 决策如何落地为可复用的工程合同。

审计范围与证据来源

底层 API 审计阶段的基线提交0879e57c838b46cacbea33b6d79f57bd9a2eae52中，Pure Live 尚无花椒应用适配器。本批是用户要求的参考平台扩展，不是已发布 Pure Live 花椒功能的回归修复；审计过程没有同步上游、升级依赖、修改版本、打包或操作手机。实现提交为9106e379c831e1f810c9b0856ab8f9dd8721ecae，源码与证据哈希清单保存在local-artifacts/huajiao-public-20260908/validation-source.json。

证据来源分为四类，全部采取只读静态取证方式：

1. 参考项目冻结快照：以 bililive-go 的 huajiao 实现作为冻结参考，其依赖的是旧User/getUserInfo、User/getUserFeeds、直播页作者 span 与live/substream接口。参考文件保留原始 SHA-256 哈希以锁定版本。
2. 花椒官网：现为宣传/下载页，旧/l/直播页样本会重定向至首页，说明旧接口路径已不可依赖。
3. 官方移动主页 H5：h.huajiao.com下的用户主页及其应用脚本提供当前用户状态和公开目录合同；供应商脚本包含当前 H5 广播入口。
4. 官方 H5 广播页内联脚本：广播页内联脚本使用/api/getFeedInfo接口，是媒体串号（feed/live）与作者 UID 匹配的关键来源。

原始证据统一存放在local-artifacts/huajiao-public-20260908/，记录请求时间、状态与响应哈希；提交的四份夹具仅保留必要结构，并替换了身份、图片、串号和签名地址。取证工具链遵循严格约束：reverse-api-engineer 0.13.0 只做 CLI 预检与 dry-run，不运行自主代理、不生成 HAR 或客户端；实际取证是显式匿名 GET，dry-run 结果不被记为浏览器抓包通过。

花椒 H5 公开 API 合同拆解

从官方 H5 页面取证可以得到四组核心接口，它们各自承担不同的职责：

这套合同拆解的核心结论是：主播 UID 才是持久身份，广播 ID 是瞬时状态。每次播放都必须重新读取当前广播，再匹配作者、广播与串号后才返回媒体地址。这一点在后续应用接入审计中被固化为应用合同：卡片、序列化和录制输入保持 UID，媒体地址仅存放在本次详情中，不写入收藏。

现网差异与实现决策（核心决策表）

审计文档最实质的部分是一张"证据 → 决策"对照表，它记录了现网观测到的 8 组反直觉行为，以及每个行为对应的实现取舍：

这张表体现的方法论值得单独强调：每一个"看起来像 bug"的现网行为，都必须先归类、再决策。例如"空历史列表""point-only feed""空标题"分别被识别为不同的语义（不证明下播、明确缺媒体哨兵、使用主播名兜底），而不是笼统地当作异常或下播处理；"目录条数不等于原生步长"则直接催生了后续独立目录游标合同的引入。

容器与编码证据：不按文件名推断格式

H5 的main与pull_m3u8有界 GET 都返回 HLS 列表；旧substream的 main 得到 32 KiB FLV 前缀，其视频标签头为0x17（AVC 标识），与 h265 元数据不一致——这说明元数据声明的编码与实际容器包头存在出入，审计以容器/包头证据为准，不把字段名当作编码事实。

历史文件flv-prefix.body实际内容为 HLS，对应元数据已标注修正；真正 FLV 前缀保存在substream-flv-prefix.body。审计明确要求不按文件名推断格式，只依据内容验证。同时，这些证据只是容器/包头层面的证明，不是全流解码或设备播放验收，边界被严格声明。

红测与修订：Dio 流式响应取消语义

首轮红测共 32 项：28 项通过、4 项失败，失败记录保存在red.log与local-artifacts/build-records/20260908T130607032Z-huajiao-api-Red.json。四个失败项分别是：

1. 真实地理 point 对象被草稿过滤，导致目录漏行；
2. 真实空标题被草稿拒绝，完整媒体结果也报 schema 错误；
3. point-only 缺广播哨兵被当成普通 feed，错误分类不准确；
4. 真实 Dio 适配器夹具中，取消包装流订阅没有触发上游取消。

前三项按当前响应修订（point 不再过滤、空标题使用主播名、point-only 识别为缺媒体哨兵）；第四项则深入到依赖层。核对锁定 Dio 5.11.1 的handleResponseStream行为：包装控制器不会将订阅取消转发至响应源，而请求的 CancelToken 会同时停止源与接收定时器。

据此，花椒请求采用独立 CancelToken：请求自己持有令牌，调用方取消时转发给该令牌，在finally中解除转发并结束本请求；不取消调用方令牌、不共享 Dio、不升级或补丁修改依赖。这个修订既保证了取消能真正切断上游流，又避免污染调用方与其他请求的共享状态。

修订后最终34/34 定向测试通过，三文件analyze无问题，记录于local-artifacts/build-records/20260908T131312192Z-huajiao-api-Final.json。测试覆盖：实际脱敏结构、身份、游标/空页、访问限制、错误分类、URL 原样保留与域名边界、UTF-8 字节上限、绝对读取期限，以及真实 Dio 包装后的错误/溢出/取消收尾；新增两项回归专门证明"上游关闭"与"调用方令牌保留"。失败记录和输入哈希均被保留，未覆写。

生产 API 探针：1/1 通过

除本地夹具测试外，审计还运行了针对生产 API 的探针，2026-09-08 13:15:19 UTC1/1 通过：

• 默认每次请求num=30；
• 两页分别返回 3/1 个公开房间，原生 offset 为 30/60，more均为 true；
• 两次房间读取均匹配主播和当前广播，解析到 HLS/FLV 两种格式；
• 未观察到两次读取之间切换广播，因此不把刷新调用当作跨开播验收。

探针使用生产 API 默认请求方法和直接 Dio，没有下载媒体、测试应用代理或进行原生操作。结果保存在production-probe.json，资源记录在local-artifacts/build-records/20260908T131523153Z-huajiao-production-probe.json。这里体现了验证体系的分层：夹具测试证明合同，生产探针证明公开状态下的链路可达性，两者都不越权宣称"原生播放/录制通过"。

从 API 到游标分页：仓库中的落地实现

底层 API 审计之后，应用接入审计引入了可选LiveSiteCursorDirectoryPager合同和LiveDirectoryPage.nextCursor。这部分契约在当前仓库源码lib/domains/live/presentation/pagination/live_directory_controller.dart中仍有完整实现，是理解"目录条数不等于原生步长"这一决策如何落地的关键：

• 控制器对实现了LiveSiteCursorDirectoryPager的站点调用getDirectoryPageAtCursor(page, cursor, category, cancel)，否则退回旧式getDirectoryPage(page, ...)兼容路径；
• 游标校验明确拒绝空、过长（>1024 字符）或立即重复的继续游标，并抛出Directory cursor did not advance；花椒 API 还额外要求数值 offset 严格前进；
• 每个已提交/刷新缓冲区持有独立游标，不在共享站点对象中存页号映射；迟发的旧刷新不会污染新目录；
• 单次加载保留请求预算（maxRequestsPerLoad = 20）与总缓冲容量（maxBufferedItems = 20000）；容量失败时整页不提交（"Never partially consume a native page"），保留已提交卡片供重试；
• 旧式无游标接口的兼容路径最多重放 20 页前缀并设总计 20 秒期限；实际 Android/Windows 目录工厂使用新游标控制器，不走前缀重放，也不宣称旧接口支持无界随机跳页。

与此同时，响应生命周期审计对同级适配器完成了复现、修订与定向回归，花椒复用其公共请求作用域，取消语义的修订被沉淀为可共享的工程基础设施。

当前仓库状态：花椒已退役但证据仍可追溯

需要特别说明的是，本审计属于 2026-09-08 的底层阶段快照。当前仓库主源码中，花椒已随 3.2.8 版本进入退役名单：

• 站点注册表中retiredSiteIds包含'huajiao'，_retiredHosts包含'huajiao.com'，退役链接会被isRetiredLink识别并应答为"retired"而非未知文本；
• 收藏数据迁移在 favorite_room_controller.dart 的_catalogAdditions中保留'huajiao', // v9 (retired in 3.2.8; keeps later versions aligned)，说明配置迁移 8→9 曾追加花椒，退役后仍保留版本对齐，用户已保存的收藏与历史可读、可显示退役徽标；
• assets/images/huajiao.png 仍作为徽标资源保留，退役平台统一使用中性徽标渲染。

因此，本文所述的 API 合同、差异决策与验证方法论，在今天主要作为参考平台扩展与取证工程的存档存在：它证明 Pure Live 如何对一个没有稳定 Web 直播页、只靠 H5 内联脚本取证的平台完成"合同级"接入，并为后续任何同类型平台扩展（依赖 H5 页面、原生游标、缺媒体哨兵）提供可复用的验证模板。

仍待完成与交付边界

按审计文档的原始记录，底层 API 阶段的交付边界明确：

• 只完成底层 API；花椒当时尚未注册到导航、设置迁移、分享/搜索、收藏、播放或录制；
• 目录游标需要接入现有分页控制器，处理"空页仍有 more 的有界继续"与刷新事务，不伪装页号乘条数；
• back字段样本为空，备用媒体合同待取证；音频/特殊房间和弹幕尚未实现；
• native HLS/FLV 解码、短录、源恢复、Android/Windows 操作及布局仍待原生验收；
• 当时的源码注册表为 15 个直播站点 + IPTV，12 组参考平台未注册；宏观验收为 20 PASS / 32 RUN / 10 NR，本批无原生 PASS、安装或发布增量；
• 回滚只移除本批未注册的 API、测试、夹具和探针，不动既有用户配置/收藏或归档候选；升级安装前需做一致性数据库备份和签名核对。

这些边界记录本身就是审计文档的价值所在：每一行"尚未完成"都对应明确的后续动作与验证前置条件，避免把底层 API 通过误写成平台原生验收通过。

延伸阅读：本主题在仓库中还有两份关联文档可继续追溯——花椒应用接入审计（UID 身份、目录游标所有权、应用合同与 287 项定向测试）与花椒累计 Android 候选（2418 项完整测试与 arm64 Debug 构建核验），两者共同构成花椒平台从 API 取证到应用接线的完整链条。

• 音视频
• 直播
• 移动开发