当前位置：首页 > news >正文

bili-sync开发者指南：扩展自定义适配器与API接口开发

news 2026/5/28 1:32:07

bili-sync开发者指南：扩展自定义适配器与API接口开发

【免费下载链接】bili-sync由 Rust & Tokio 驱动的哔哩哔哩同步工具项目地址: https://gitcode.com/gh_mirrors/bi/bili-sync

想要为bili-sync哔哩哔哩同步工具开发自定义适配器吗？本文将为你提供完整的开发指南，帮助你理解bili-sync的插件架构并掌握API接口扩展技巧。bili-sync是一个由Rust和Tokio驱动的高性能哔哩哔哩视频同步工具，支持自动下载收藏夹、合集、投稿等多种视频来源。

📋 项目架构概览

bili-sync采用模块化设计，核心架构分为适配器层和API层，这种设计让扩展变得异常简单。通过理解这两个核心模块，你可以轻松地为bili-sync添加新的视频来源或自定义API功能。

bili-sync整体架构设计，展示了适配器与API的协作关系

核心目录结构

crates/bili_sync/src/ ├── adapter/ # 适配器模块 │ ├── collection.rs # 合集适配器 │ ├── favorite.rs # 收藏夹适配器 │ ├── submission.rs # 投稿适配器 │ ├── watch_later.rs # 稍后再看适配器 │ └── mod.rs # 适配器接口定义 ├── api/ # API接口模块 │ ├── routes/ # 路由定义 │ │ ├── config/ # 配置相关API │ │ ├── video_sources/ # 视频源管理API │ │ ├── videos/ # 视频管理API │ │ └── ... # 其他API模块 │ └── mod.rs # API主模块 └── bilibili/ # 哔哩哔哩客户端

🎯 适配器开发指南

理解VideoSource Trait

bili-sync通过VideoSourcetrait定义了所有视频源的统一接口。要创建自定义适配器，你需要实现这个trait的关键方法：

pub trait VideoSource { // 获取视频源显示名称 fn display_name(&self) -> Cow<'static, str>; // 获取数据库筛选条件 fn filter_expr(&self) -> SimpleExpr; // 设置视频关联ID fn set_relation_id(&self, video_model: &mut video::ActiveModel); // 获取存储路径 fn path(&self) -> &Path; // 刷新视频源数据 async fn refresh<'a>( self, bili_client: &'a BiliClient, credential: &'a Credential, connection: &'a DatabaseConnection, ) -> Result<(VideoSourceEnum, Pin<Box<dyn Stream<Item = Result<VideoInfo>> + Send + 'a>>)>; }

适配器实现示例

以收藏夹适配器为例，查看crates/bili_sync/src/adapter/favorite.rs的实现：

结构定义：每个适配器对应一个数据库实体模型
trait实现：实现VideoSource的所有必需方法
数据流处理：通过Stream异步获取视频数据

收藏夹适配器在Web界面中的展示效果

创建自定义适配器的步骤

定义数据结构：在bili_sync_entity中定义数据库模型
实现VideoSource trait：创建新的适配器文件
注册适配器：在adapter/mod.rs中添加到VideoSourceEnum
添加数据库迁移：创建对应的数据表
实现API接口：提供管理界面支持

🔌 API接口开发指南

API路由架构

bili-sync使用Axum框架构建RESTful API，采用分层设计：

路由层：定义HTTP端点路径
处理器层：处理具体业务逻辑
数据访问层：与数据库交互
响应包装层：统一API响应格式

视频源管理API示例

查看crates/bili_sync/src/api/routes/video_sources/mod.rs，这里定义了完整的视频源管理API：

// 获取所有视频源 GET /api/video-sources // 获取视频源详情 GET /api/video-sources/details // 更新视频源配置 PUT /api/video-sources/{type}/{id} // 删除视频源 DELETE /api/video-sources/{type}/{id} // 添加收藏夹 POST /api/video-sources/favorites // 添加合集 POST /api/video-sources/collections // 添加投稿 POST /api/video-sources/submissions

Web界面中的API配置管理页面