api 下载器扩展库 (1.0.0 → 1.1.0):从 WebView 下载器到全新源系统的能力演进

原创2026-10-09 22:31:381,694 阅读
文章标签:移动开发原生移动逆向工程开发者工具

api 下载器扩展库 (1.0.0 → 1.1.0):从 WebView 下载器到全新源系统的能力演进

本篇技术指南聚焦 revanced-manager 仓库中独立发布的 api 模块(api/CHANGELOG.md),系统梳理其从 1.0.0 到 1.1.0 的版本演进脉络。读者将掌握:api 模块的定位与安全边界、下载器 DSL(Downloader / DownloaderScope / GetScope)的完整用法、runWebView 与 WebViewDownloader 编写带 WebView 界面的下载器插件的实战方法,以及 1.1.0 对“源系统(source system)”重构背后的源码级实现原理。无论你是下载器插件的作者、接入自定义下载器源的维护者,还是仅想深入理解 Manager 下载器生态的开发者,本文都可作为一份可落地、可追溯的源码级参考。

一、api 模块概述:它不是 Manager 的 API,而是下载器插件 SDK

api 是 revanced-manager 仓库中的独立 Gradle 子模块(位于 api/ 目录),拥有独立的版本号、变更记录与发布节奏,对应仓库根目录 settings.gradle.kts 中所声明的子项目。它面向的对象并非普通用户,而是下载器插件的开发者:

  • 插件以 APK 形式发布与安装:下载器 APK 像普通 Android 应用一样被安装、更新与卸载(详见 docs/2_4_managing_downloaders.md);
  • 但这类 APK 的内部实现并不是常规的独立应用,而是依赖 api 模块暴露的下载器 DSL(Domain-Specific Language),在运行时被宿主程序 ReVanced Manager 动态加载与调用。

从 api/api/api.api(Kotlin 二进制兼容性校验(binary-compatibility-validator)生成的公开 API 摘要)可以清晰看到模块对外开放的完整符号面:

  • DSL 核心:Downloader、DownloaderBuilder、DownloaderScope、GetScope、Scope、BaseDownloadScope、InputDownloadScope、OutputDownloadScope;
  • 异常体系:UserInteractionException 及其 RequestDenied / Activity.Cancelled / Activity.NotCompleted 三个子类;
  • Parcelable 数据载体:Package、DownloadUrl;
  • WebView 扩展:WebViewScope、WebViewCallbackScope、runWebView、WebViewDownloader,以及 AIDL 接口 IWebView、IWebViewEvents。

1.1 安全边界:为什么下载器“必须被标记为可信”

下载器 APK 一旦被安装,就运行在 Manager 的进程内,可执行任意代码。文档 docs/2_4_managing_downloaders.md 明确指出:“Downloaders can execute arbitrary code inside ReVanced Manager and must be marked as trusted before use”(下载器可以在 ReVanced Manager 内部执行任意代码,使用前必须将其标记为可信)。

因此 api 模块通过 @RequiresOptIn 注解划分了严格的权限边界——见 Downloader.kt:

@RequiresOptIn(
    level = RequiresOptIn.Level.ERROR,   // 默认视为编译错误,必须显式 OptIn
    message = "This API is only intended for downloader hosts, don't use it in a downloader.",
)
@Retention(AnnotationRetention.BINARY)
annotation class DownloaderHostApi

DownloaderHostApi 被标记为 Level.ERROR:下载器插件开发者一旦误用宿主 API,编译期即失败。该注解在 DownloaderBuilder.build、Downloader 的构造属性、GetScope.requestStartFragment 默认实现、runWebView 以及 IWebView/IWebViewEvents 两个 AIDL 接口(见 IWebView.aidl、IWebViewEvents.aidl 上的 @JavaPassthrough)上均有应用,确保插件只能接触为插件设计的能力面,而不能触达 Manager 的内部宿主逻辑。

与之配套,Manager 侧的信任管理位于 Settings > Downloads,并会在仪表盘(Dashboard)发现新下载器时弹出通知,用户可随时授予或收回信任。

二、1.0.0 里程碑:四个能力基石的落地

1.0.0(2026-03-14)作为首个稳定版本,把此前 dev 系列的三项实验性能力正式固化,并完成一次整体 UI 重构:

里程碑 PR / 提交主题 含义
下载器 UI 支持 Fragment Add support for writing downloader UI with fragments([#2998]) 下载器可以通过 Fragment 直接绘制界面(而非只能启动独立 Activity)
单个 APK 支持多个下载器 Allow multiple downloaders per APK([#2916]) 一个下载器 APK 可同时提供多个下载器实现
升级至 Patcher v22 Update to Patcher v22(#2939]) 与宿主端 Patcher 运行时(见 [runtime/process)保持 API 兼容
UI 焕新与 UX 改进 Revamp UI and improve UX 下载器管理界面重做

在发布时间线上:1.0.0-dev.1(2026-02-19,支持多下载器)→ 1.0.0-dev.2(2026-02-27,升级 Patcher v22)→ 1.0.0-dev.3(2026-03-12,Fragment UI 支持)→ 1.0.0-dev.4(2026-03-14,UI 焕新)→ 1.0.0(2026-03-14 正式版)。

这三项能力共同定义了 api 模块“插件容器”式的架构定位,下面对应展开。

三、核心 DSL 详解:从 Downloader 到 GetScope

3.1 Downloader:定义下载器的入口

Downloader.kt 中的 Downloader<T : Parcelable> 是最终产物,由三个元素构成:

  • get:接收 (packageName: String, version: String?),返回 GetResult<T>(即 Pair<T, Version?>);返回 null 表示无法找到该应用;
  • download:接收数据 T 与输出流 OutputStream,把应用本体写入输出流;
  • name:下载器名称的资源 ID(@StringRes)。

构建过程经由工厂函数与 DownloaderBuilder(Downloader.kt)完成:build(scopeImpl, context, resources) 在宿主进程中构造 DownloaderScope 并执行 DSL 配置块,最终产出 Downloader 实例。T 必须实现 Parcelable——这是为了后续在宿主与下载器之间跨进程/跨 ClassLoader 传递数据。

3.2 统一作用域 Scope

所有 DSL 作用域共享 Scope 接口(Downloader.kt),它向下载器暴露三项运行时上下文:

interface Scope {
    val hostPackageName: String      // ReVanced Manager 的包名
    val downloaderPackageName: String // 本下载器 APK 的包名
    val dataDir: File                // 本下载器专用数据目录
}

3.3 GetScope:查找应用与发起用户交互

GetScope(Downloader.kt)承担“get”阶段的职责,核心方法是 requestStartActivity(intent):启动一个由下载器提供的 Activity 完成用户交互(如登录、选择镜像),只有在该 Activity 以 Activity.RESULT_OK 结束时才返回其 Intent。若用户拒绝或流程中断,则抛出 UserInteractionException:

  • RequestDenied:用户决定跳过此下载器;
  • Activity.Cancelled:交互被取消;
  • Activity.NotCompleted(resultCode, intent):Activity 以未知结果码结束。

配套的扩展(Extensions.kt)让常用调用更加简洁:

suspend inline fun <reified ACTIVITY : Activity> GetScope.requestStartActivity() =
    requestStartActivity(
        Intent().apply { setClassName(downloaderPackageName, ACTIVITY::class.qualifiedName!!) }
    )

suspend inline fun <reified T : Fragment> GetScope.requestStartFragment(args: Bundle?) =
    requestStartFragment(T::class.java, args)

requestStartFragment 的默认实现(Downloader.kt)会构造 Intent,把类名与参数打包进 app.revanced.manager.DownloaderActivity——这是 1.0.0 “用 Fragment 写下载器 UI” 的基础,详见下文第四节。

3.4 数据载体:Package 与 DownloadUrl

Parcelables.kt 提供两个开箱即用的数据类型:

  • Package(name, version):仅需包名与版本即可实现下载的简单场景;
  • DownloadUrl(url, headers):携带下载地址与请求头,其 toDownloadResult() 会基于 HttpURLConnection 发起 GET 请求并返回输入流与 Content-Length 长度(连接超时 10 秒、useCaches=false、按需写入 headers),直接可转交给 download 阶段。

若这两个类型不够用,开发者可自定义任意 Parcelable 数据类作为 T。

四、1.0.0 核心能力:WebView 下载器与 Fragment UI 的实现

4.1 DownloaderActivity:下载器 Fragment 的宿主

1.0.0 新增的 Fragment UI 支持,其宿主是 DownloaderActivity.kt:它从 Intent 中解析 DOWNLOADER_NAME、FRAGMENT_CLASS_NAME、FRAGMENT_ARGS 三个 extra,把下载器的类加载器(ClassLoader)和资源(Resources)注入到 Activity 中,从而在 Manager 的 Activity 里渲染下载器 APK 自带的 Fragment 与资源(Android 11+ 通过 ResourcesLoader 加载,低版本通过 updateConfiguration 兼容,见 DownloaderRepository.kt 的 ResourceImpl 双实现)。这是“用 Fragment 写下载器 UI”得以实现的关键宿主设施。

4.2 runWebView:托管 WebView 的完整回调闭环

runWebView(API.kt)把“下载器需要访问网页”(如镜像站、验证页面)的场景封装成一套协程化的托管 WebView:

@OptIn(DownloaderHostApi::class)
suspend fun <T> GetScope.runWebView(
    title: String,                                  // ActionBar 上显示的标题
    block: suspend WebViewScope<T>.() -> InitialUrl // 定义事件处理器并返回初始 URL
) = supervisorScope {
    var result by Delegates.notNull<Container<T>>()
    val scope = WebViewScope<T>(this@supervisorScope, this@runWebView) { result = Container(it) }
    scope.initialUrl = scope.block()

    // 启动 WebViewFragment 并等待其结束
    requestStartFragment<WebViewFragment>(Bundle().apply {
        putParcelable(WebViewFragment.KEY, WebViewFragment.Parameters(title, scope.binder))
    })

    coroutineContext.cancelChildren() // 清理残余协程
    result.value                       // 返回事件处理器写入的结果
}

调用 runWebView 后,宿主通过 requestStartFragment 启动 WebViewFragment.kt(布局见 webview_fragment.xml),WebView 的交互事件通过 Binder 传递。Activity 会一直运行,直到被取消或事件处理器调用 WebViewCallbackScope.finish(result)。

4.3 WebViewScope 与 WebViewCallbackScope:可配置的事件模型

WebViewScope<T>(API.kt)允许下载器注册两类事件处理器:

  • pageLoad(block: suspend WebViewCallbackScope<T>.(url: String) -> Unit):页面加载完成时回调;
  • download(block: suspend WebViewCallbackScope<T>.(url: String, mimeType: String, userAgent: String) -> Unit):WebView 尝试下载文件到磁盘时回调。

WebViewCallbackScope<T>(API.kt)则在回调作用域内提供两个控制动作:

  • finish(result: T):写入结果并结束整个 Activity(返回 RESULT_OK);
  • load(url: String):命令 WebView 加载新页面。

其底层通过 AIDL 双接口实现进程内 Binder 通信:

  • IWebViewEvents.aidl:ready(IWebView)(WebView 就绪,宿主把控制端 Binder 交给下载器)、pageLoad(url)、download(url, mimetype, userAgent);
  • IWebView.aidl:load(url)、finish(),由下载器侧通过 Binder 回调宿主控制 WebView。

注意:IWebView 与 IWebViewEvents 上的方法均为 oneway(异步),事件分派在 Dispatchers.Default.limitedParallelism(1) 的串行调度器上执行(见 API.kt),因此回调不会被并发打断。

4.4 WebViewDownloader:一行代码写出的 WebView 下载器

API.kt 提供的 WebViewDownloader 是对 runWebView 的“自动化装配”:它内置了下载事件处理器,当 WebView 触发下载时自动把 url 与 User-Agent 打包成 DownloadUrl 并通过 finish 结束,随后在 download 阶段调用 toDownloadResult() 真正下载 APK 文件:

fun WebViewDownloader(@StringRes name: Int, block: suspend WebViewScope<DownloadUrl>.(packageName: String, version: String?) -> InitialUrl?) =
    Downloader(name) {
        get { packageName, version ->
            class ReturnNull : Exception()
            try {
                runWebView(label) {
                    download { url, _, userAgent ->
                        finish(DownloadUrl(url, mapOf("User-Agent" to userAgent)))
                    }
                    block(this@runWebView, packageName, version) ?: throw ReturnNull()
                } to version
            } catch (_: ReturnNull) {
                null   // block 返回 null 等价于在 DownloaderScope.get 中返回 null
            }
        }
        download { it.toDownloadResult() }
    }

也就是说,插件作者只需在 WebViewDownloader 的 block 里返回初始 URL,即可完成一个带完整 WebView 交互、自动处理下载事件的下载器——这是模板化开发的核心入口。

4.5 useService:按需绑定下载器 Service

当下载器需要与宿主解耦的长时后台能力(如流式下载)时,可借助 DownloaderScope.useService(intent, block)(Downloader.kt)绑定指定 Service:绑定成功后在 block 中拿到 IBinder 使用,作用域结束时自动解绑;若 10 秒内绑定超时则抛出异常。配套扩展 Extensions.kt 允许按类型简写为 useService<SERVICE> { binder -> ... }。

五、1.1.0 演进:全新源系统与连通性修复

5.1 变更内容

1.1.0 及其前置开发版 1.1.0-dev.1(2026-03-19/2026-03-20)只有一个 Feature 条目:

Improve source system and fix connectivity issues(#3137)——改进源系统并修复连接性问题。

这标志着 api 模块的生命周期并未止步于 1.0.0:它把“下载器如何被找到、下载、更新”这一底层链路(即源系统)重做,同时修复了网络连通性问题。这一变更本身不含破坏性 API 改动——api/api/api.api 中 Downloader、Scope、WebViewScope 等公开符号在 1.0.0 与 1.1.0 之间保持一致,插件开发者无需修改代码即可平滑升级。

5.2 源码级佐证:Manager 侧的“源系统”如何工作

“源系统”的主体实现位于宿主端 DownloaderRepository.kt。从源码结构可以看出,下载器源有三种来源(对应 Source.kt 的密封类):

  • Local(本地):用户通过 APK 文件导入的下载器,存储在 app.getDir("downloaders", Context.MODE_PRIVATE) 下的 uid/downloader.jar(见 DownloaderRepository.kt);
  • API(官方源):默认的 uid == 0 源,通过 ReVanced API 的 manager/downloaders 路由获取更新(ReVancedAPI.kt),并支持“预发布版”开关(useDownloaderPrerelease);
  • Remote(远程):用户手动填入 JSON 端点(UI 见 DownloadersInfoScreen.kt 的 downloader_url 设置项),端点可在界面中修改并即时触发更新。

运行时加载流程(DownloaderRepository.kt)是:

  1. 读取下载器 APK 的 array/app.revanced.manager.downloader.classes 资源,获得下载器类名列表——这是“单个 APK 支持多个下载器”的实现机制(1.0.0 里程碑之一);
  2. 用 PathClassLoader 加载下载器 APK 的类;
  3. 通过反射查找类中的 public static 无参方法,其返回类型必须是 DownloaderBuilder 子类(见 DownloaderRepository.kt 的 getDownloaderBuilder());
  4. 调用该方法得到 DownloaderBuilder,再 build(...) 成可运行的 Downloader 实例。

每个下载器源在 Room 数据库 downloaders 表(DownloaderEntity.kt)中持久化 uid / name / version(哈希) / source / auto_update / released_at,由 DownloaderDao.kt 管理增删改查与版本哈希更新。1.1.0 对该系统的改进,直接关系到下载器源在多源共存、连通性异常(如网络切换、端点失效)时的健壮性。

六、版本发布机制与插件接入约定

6.1 发布节奏与语义化版本

  • 正式版:1.0.0(2026-03-14)、1.1.0(2026-03-20);
  • 开发版:1.0.0-dev.1 ~ 1.0.0-dev.4、1.1.0-dev.1,遵循“先 dev、后正式”的迭代节奏;
  • api/package.json(package.json)配置了 multi-semantic-release、semantic-release-changelog、gradle-semantic-release-plugin 等工具,表明版本号由 Conventional Commits 语义自动推进,并与 api/gradle.properties 中的 version = 1.1.0 保持同步;二进制兼容性由 binary-compatibility-validator(见 gradle/libs.versions.toml)通过 api/api/api.api 校验。

6.2 插件接入关键约定(面向下载器作者)

结合 DSL 与宿主加载逻辑,下载器插件需要满足:

  1. 提供入口方法:在某个类中定义一个 public static 无参方法,返回 DownloaderBuilder(即调用顶层函数 Downloader(name) { ... } 的返回类型);
  2. 声明类名列表:在 APK 资源 res/values/arrays.xml 中提供名为 app.revanced.manager.downloader.classes 的 string-array,列出所有下载器入口类;
  3. 可选提供 Fragment 界面:下载器可以携带自己的 Fragment 与资源,通过 GetScope.requestStartFragment / DownloaderScope 使用,由宿主的 DownloaderActivity 加载;
  4. 遵循信任模型:插件安装后需在 Settings > Downloads 中被用户标记为可信方可执行。

七、结语:一份持续演进的“插件契约”

api 模块以独立版本号交付了一套面向下载器插件的稳定 SDK:1.0.0 确立了多下载器、Fragment UI、Patcher v22 与 WebView 托管四大能力;1.1.0 在不破坏 API 的前提下重构了源系统并修复连通性问题。对插件作者而言,api/api/api.api 是权威的公开面参考,API.kt 与 Downloader.kt 是核心实现入口;对下载器源维护者而言,DownloaderRepository.kt 完整呈现了本地 / API / 远程三类源的加载与更新链路。如果你正在编写或维护一个 ReVanced Manager 下载器,这份变更记录连同上述源码路径,就是最直接的工程参考。

登录后查看全文
revanced-manager