ab-download-manager扩展插件开发：自定义Destination实现云存储对接

2026-02-05 04:18:09作者：谭伦延

在ab-download-manager中，下载文件的最终存储位置由Destination组件控制。默认实现SimpleDownloadDestination.kt仅支持本地文件系统存储，而通过自定义Destination实现，我们可以将下载内容直接对接至阿里云OSS、腾讯云COS等云存储服务。本文将详细介绍扩展开发的核心步骤与最佳实践。

核心接口解析

DownloadDestination是所有存储目的地的抽象基类，定义了文件写入、校验和清理等关键操作。其核心方法包括：

abstract class DownloadDestination(
    outputFile: File,
) {
    abstract fun getWriterFor(part: Part): DestWriter?  // 获取分块写入器
    abstract suspend fun prepareFile(onProgressUpdate: (Int?) -> Unit)  // 准备存储位置
    abstract suspend fun isDownloadedPartsIsValid(): Boolean  // 校验已下载内容
    abstract fun flush()  // 刷新缓存
}

关键组件关系

DestWriter：负责具体分块数据的写入逻辑
DownloadDestination：管理整体存储策略与状态
Part：代表下载任务的一个分块（从from到to的字节范围）

自定义Destination开发步骤

1. 创建云存储Destination类

继承DownloadDestination并实现核心方法，以下是阿里云OSS对接的框架示例：

class OssDownloadDestination(
    outputFile: File,
    private val ossClient: OSSClient,
    private val bucketName: String,
    private val objectKey: String
) : DownloadDestination(outputFile) {

    override fun getWriterFor(part: Part): DestWriter {
        return OssDestWriter(part, ossClient, bucketName, objectKey)
    }

    override suspend fun prepareFile(onProgressUpdate: (Int?) -> Unit) {
        // 创建OSS分片上传任务
        val uploadId = ossClient.initMultipartUpload(
            InitMultipartUploadRequest(bucketName, objectKey)
        ).uploadId
        // 记录uploadId用于后续分片提交
    }

    override suspend fun isDownloadedPartsIsValid(): Boolean {
        // 校验云端已上传分片的完整性
        return ossClient.listParts(
            ListPartsRequest(bucketName, objectKey, uploadId)
        ).parts.isNotEmpty()
    }

    override fun flush() {
        // 合并OSS分片
        ossClient.completeMultipartUpload(
            CompleteMultipartUploadRequest(bucketName, objectKey, uploadId, partETags)
        )
    }
}

2. 实现云存储写入器

创建DestWriter子类处理分块上传逻辑：

class OssDestWriter(
    private val part: Part,
    private val ossClient: OSSClient,
    private val bucketName: String,
    private val objectKey: String
) : DestWriter(part.from, part.current) {

    override suspend fun write(bytes: ByteArray, offset: Int, length: Int) {
        val request = UploadPartRequest().apply {
            this.bucketName = bucketName
            this.key = objectKey
            this.uploadId = uploadId
            this.partNumber = part.partNumber
            this.inputStream = ByteArrayInputStream(bytes, offset, length)
            this.partSize = length.toLong()
        }
        // 上传分片并保存ETag
        val etag = ossClient.uploadPart(request).eTag
        partETags.add(PartETag(part.partNumber, etag))
    }

    override fun close() {
        // 关闭网络连接
    }
}

3. 注册自定义Destination

通过DownloadManager配置自定义存储策略：

val ossDestination = OssDownloadDestination(
    File("temp.dat"), 
    OSSClientBuilder().build(),
    "my-bucket", 
    "downloads/file.zip"
)

val downloadManager = DownloadManager(
    destinationFactory = { file -> ossDestination }
)

高级特性实现

断点续传支持

利用云存储的分片上传机制，通过isDownloadedPartsIsValid方法实现断点续传：

override suspend fun isDownloadedPartsIsValid(): Boolean {
    val uploadedParts = ossClient.listParts(
        ListPartsRequest(bucketName, objectKey, uploadId)
    ).parts
    // 校验已上传分片与本地记录是否匹配
    return uploadedParts.all { part ->
        localParts.any { 
            it.partNumber == part.partNumber && it.etag == part.eTag 
        }
    }
}

进度回调与状态管理

重写onProgressUpdate实现云存储特有指标监控：

override fun onProgressUpdate(part: Part, bytesWritten: Long) {
    val totalUploaded = partETags.sumOf { it.size }
    val progress = (totalUploaded.toFloat() / outputSize * 100).toInt()
    listener.onCloudUploadProgress(progress, part.partNumber)
}

测试与调试

本地模拟测试

使用MockWebServer模拟云存储API：

val mockServer = MockWebServer().apply { start() }
val mockClient = OSSClient(mockServer.url("/").toString(), "ak", "sk")

// 测试分片上传逻辑
val destination = OssDownloadDestination(
    File("test"), mockClient, "test-bucket", "test-key"
)

集成测试

通过desktop/app/src/main/kotlin/com/abdownloadmanager/desktop/pages/中的下载页面UI进行端到端测试，验证云存储对接的完整性。

插件打包与分发

将自定义Destination实现打包为独立插件，放置于项目的plugins/目录下，遵循installer-plugin的打包规范。用户可通过应用内插件市场一键安装。

目录结构示例

plugins/
  oss-destination/
    src/main/kotlin/
      com/abdownloadmanager/oss/
        OssDownloadDestination.kt
        OssDestWriter.kt
    build.gradle.kts

实战案例：腾讯云COS对接

以下是腾讯云对象存储的关键实现代码：

class CosDestWriter(part: Part, cosClient: COSClient, bucket: String, key: String) : DestWriter(part.from, part.current) {
    override suspend fun write(bytes: ByteArray, offset: Int, length: Int) {
        val request = UploadPartRequest().apply {
            bucketName = bucket
            key = key
            uploadId = uploadId
            partNumber = part.partNumber
            inputStream = ByteArrayInputStream(bytes, offset, length)
        }
        val etag = cosClient.uploadPart(request).eTag
    }
}