Architecture

架构设计,读懂每一条播放链路

一份基于客户端源码的架构说明。沿着数据与事件的流向,看 AnimeFlow 如何连接跨平台界面、可配置数据源、双播放内核、离线下载与收藏同步。

本文对应源码快照 7b4a967 · 章节顺序与源码目录一致,可对照阅读

01 / System Overview

以功能为边界,以接口连接

app 组装应用,features 承载业务,core 提供基础设施,shared 复用模型与组件。下图是客户端边界内的调用与数据访问方向,外部服务统一以接口呈现。

箭头表示主要调用或数据访问方向;网络、存储与平台能力可被多个功能共享。Flow 服务的数据库、任务队列与部署拓扑不在本仓库中,因此以外部服务节点表示。

02 / Bootstrap & Structure

先恢复运行条件,再进入界面

启动流程把必须完成的存储与平台初始化放在 runApp 之前;在线状态、内置源与 Shader 准备等工作以异步任务启动,减少根组件中的初始化责任。

01

初始化运行环境

main() 以 runZonedGuarded 捕获未处理异常;bootstrap 依次初始化 Flutter binding、错误日志、许可信息与 MediaKit。

02

恢复本地状态

初始化 Hive 与各业务 Box;iOS 重定位历史下载路径、恢复下载目录权限,接入图片缓存并初始化前台下载服务与字体。

03

准备网络与平台能力

读取包信息并初始化 DioFactory 的设备 User-Agent,异步启动 PresenceService;桌面平台初始化窗口并设置标题栏。

04

创建状态容器并启动 UI

创建 ProviderContainer,读取应用信息,异步准备 Shader 目录与内置数据源;runApp 使用 UncontrolledProviderScope 注入容器。

main.dart → bootstrap.dart → MyApp → runApp

目录职责与实现入口

源码目录职责入口
lib/app/ 应用组装:启动流程、应用根节点、类型化路由、主题与本地化。 bootstrap.dart
lib/features/ 功能模块:围绕 home、search、play、download、user、source 等业务组织,按复杂度采用 presentation、application、data、domain、infrastructure。 play_provider.dart
lib/core/ 跨功能基础设施:网络与认证、规则引擎、平台 WebView、设置、日志、图片缓存及在线状态服务。 dio_factory.dart
lib/shared/ 共享数据与组件:番剧、剧集、下载与收藏模型,以及图片、卡片、BBCode 等通用界面组件。 download_record.dart
test/ 行为验证:覆盖纯逻辑、仓库、Provider、内核适配与 Widget 交互,目录大体镜像功能结构。 playback_coordinator_test.dart

03 / Source Pipeline

规则驱动,检索与媒体解析分离

番剧元数据与播放站点资源是两类数据。数据源功能把可配置站点转成统一的搜索条目与剧集线路,再通过平台 WebView 提取最终媒体地址,播放器无需理解每个站点的页面结构。

插件 JSON 规则 → RuleEngine → 标题打分选源 → WebView 解析 → 媒体地址

01

声明式扩展与兼容性检查

搜索与章节可分别使用 XPath 或 API 规则;API 请求支持 GET/POST、变量模板与 JSONPath 提取。安装时验证 RuleApiLevel,避免把客户端无法执行的规则写入配置。

02

检索并发与标题匹配

站点搜索默认限制为 5 路并发、每站最多 5 个候选。标题与别名在 isolate 中打分,同时考虑季数、最终季、OVA 与剧场版等差异,降低错番与错季的概率。

03

解析取消与验证码恢复

站点验证由验证码 WebView 与 CookieManager 配合处理;播放解析复用共享 WebView。新请求取消旧请求,身份校验与超时约束共同阻止旧解析结果污染当前集。

04 / Playback Session

一套会话,协调内核、状态与观看进度

播放模块的分层最完整:presentation 负责界面与状态,application 负责业务协调,domain 定义播放器契约,infrastructure 接入 media_kit 与 FVP。弹幕与播放记录与会话协作,各自管理请求与持久化逻辑。

01

内核接口与快照恢复

PlayerEngine 统一打开、seek、音量、倍速、截图与 Shader 操作。切换时从 PlayerSnapshot 恢复媒体与进度,候选内核准备完成后替换事件订阅;能力差异通过 PlayerCapabilities 显式判断。

02

异步竞态与资源生命周期

PlayerOperationQueue 串行化原生操作;PlaySession 用请求 ID 检查切集结果,seek 落点确认前过滤陈旧事件。退出页面时失效请求、取消订阅、保存进度,并等待原生队列排空后释放内核。

03

进度记录与自动标记

记录按 3 秒防抖并串行写入,先落 Hive 再同步 Flow。自动标记「已看」需满足登录、设置开启、非本地播放、有效番剧与剧集信息、时长至少 2 分钟且播放达到 90%,进行中与已完成的标记请求会去重。

04

弹幕与 Anime4K

弹幕按秒分桶并在该秒内分散发送,seek 或切集立即取消待发计时器。繁简转换有独立版本检查,屏蔽来源与颜色在分发时处理。Anime4K GLSL 从 assets 复制到应用支持目录,仅对支持 Shader 的内核启用。

05 / Offline Pipeline

下载是有状态的任务系统

离线功能不只保存一个 URL。它需要解析资源、调度多个剧集、控制分片并发、处理暂停与续传、维护目录权限、持久化任务状态,并让本地文件重新进入统一播放链路。

剧集选择 → 资源解析 → 分片队列 → 本地 m3u8 重建 → 离线播放

01

分层并发与可取消任务

VideoSourceResolverPool 负责解析 worker,DownloadManager 负责剧集队列,信号量限制每集分片传输。管理器默认 2 集、每集 3 分片并发,实际配置可由设置调整;Android 另接入前台服务维护下载通知与后台任务。

02

HLS 的本地重建

解析主列表、相对地址、嵌套列表、密钥、初始化段与字节范围,下载后重写本地 m3u8;嵌套解析深度默认最多 3 层。流程明确拒绝直播与独立音轨,避免生成不完整的离线内容。

03

续传、状态与离线复用

已完成的 HLS 分片可复用,直链文件按 Range 续传,传输失败按 1/3/9 秒退避。进度缓存在内存、状态改变时写 Hive;已完成记录构建离线剧集列表,本地媒体与弹幕复用原有播放器会话。

06 / Collection Sync

以任务版本为准,让实时同步保持有序

收藏同步由客户端触发 Flow 服务的任务,再以 SSE 订阅进度与冲突状态。账号变化、页面订阅与应用前后台都会影响连接生命周期;客户端只接受当前会话的有效更新。

HTTP 触发任务 → SSE 回传状态 → 版本号过滤 → 刷新收藏 / 冲突待选

01

状态发现与任务触发分离

登录并完成 Bangumi 绑定后读取同步状态。CollectionSyncLifecycle 负责启动与前台恢复时发现状态,启动本身不会发起同步;用户操作经仓库提交带请求 ID 的触发请求。

02

增量解码与过期状态过滤

SSE 解析处理跨块 UTF-8、多行 data、注释心跳与空行分帧,单事件文本限制 64 KiB。任务 ID 与 statusVersion 保证新状态不会被旧状态覆盖,generation 隔离已结束的连接与登录会话。

03

订阅范围、重连与冲突

前台且存在页面订阅者时才保持连接;60 秒无事件触发断线处理,重连按指数退避、上限 30 秒。有效同步变化刷新收藏并递增 revision;收藏冲突通过对话框读出差异,由用户选择后单独提交。

07 / Shared Infrastructure

完整体验,来自共同的基础设施

账号、网络、缓存、平台与更新贯穿多个功能。把这些能力放在独立入口中,让业务页面保持清晰,也让异常恢复有一致的处理位置。

账号认证与会话保护

邮箱登录由 LoginService 写入 FlowTokenStorage,令牌保存在 FlutterSecureStorage。刷新拦截器仅在明确的 access_token_expired 情况下处理,多个请求共享刷新 Future,每个原请求最多重试一次;退出登录使旧刷新代次失效,临时网络或存储失败不会直接清空有效会话。

网络隔离与图片缓存

DioFactory 为 API、Flow、GitHub、插件与下载分配客户端并统一配置。图片加载使用自定义 FileService 与缓存管理器;开启 ECH 且域名命中配置时才走 EchImageService,其余图片走普通 HTTP。缓存清理同时处理磁盘文件与 Flutter 内存图像缓存。

跨平台能力与界面适配

Flutter 共享页面与业务状态;视频 WebView、验证码 WebView、下载目录与安装更新提供各平台实现。主题、字体与语言由独立 Provider 管理,桌面窗口、全屏、系统音量及移动端手势通过相应能力接入。

发现、识番与应用更新

首页、排行、日历、搜索、人物与番剧详情以各自 Provider 加载业务数据;截图识番将图片文件或 URL 交给 trace.moe。更新检查经 FlowApi.getLatestRelease 获取发布信息,再由平台更新控制器处理下载后的安装或跳转。

08 / Design & Verification

把复杂性留在明确的边界里

功能内聚、接口隔离、异步失效检查与持久化策略贯穿这些实现。现有测试覆盖规则解析、内核切换、弹幕调度、下载恢复与收藏同步等行为,可从各章节的测试入口继续阅读。

01

按功能组织,按复杂度分层

功能目录形成业务边界,播放等复杂模块再细分领域与适配层。较轻的模块直接以页面与 Provider 组织;这种渐进分层让结构与功能复杂度相匹配,减少简单业务中的层级负担。

02

接口隔离原生与外部依赖

PlayerEngine、IVideoSourceProvider、IDownloadManager 与 IDownloadRepository 为替换内核、注入测试实现与平台适配提供边界。数据源规则把站点差异从播放器控制逻辑中移出。

03

为异步结果定义有效期

播放请求 ID、弹幕 generation/epoch、收藏任务版本与认证刷新代次处理各自的竞态;串行队列管理不能并发的原生操作,取消令牌管理可终止的网络请求。

04

分清实时状态与持久状态

UI 与高频下载进度保留在响应式状态或内存缓存中;Hive 保存恢复所需记录,媒体保存在文件系统,认证凭证进入安全存储。播放记录先本地保存,再尝试同步。

说明范围:客户端源码及其外部接口。Flow 服务的数据库、任务队列与部署拓扑未包含在此仓库中。若发现文档与源码不一致,以仓库当前代码为准,欢迎在 Issues 中指出。

想自己读一遍源码?

仓库公开,Issue 与 PR 都欢迎;也可以先下载客户端体验完整链路