WebDAV（Web-based Distributed Authoring and Versioning）作為一種基於HTTP的文件管理協議，為Kazumi提供了跨設備數據同步能力。本文將深入解析Kazumi中WebDAV客户端的實現細節，包括配置管理、數據同步流程及文件管理策略，並通過實際代碼與界面展示幫助開發者快速掌握相關功能模塊。

WebDAV配置界面設計與實現

Kazumi的WebDAV配置界面採用簡潔直觀的設計，主要包含服務地址、認證信息輸入區域及測試驗證功能。該界面通過lib/pages/webdav_editor/webdav_editor_page.dart實現，使用Flutter的Material組件構建響應式佈局。

核心配置表單包含三個關鍵字段：

  • URL輸入框：用於配置WebDAV服務地址，通過webDavURLController綁定用户輸入
  • 用户名輸入框：通過webDavUsernameController管理認證用户名
  • 密碼輸入框：支持顯示/隱藏切換功能，使用passwordVisible狀態控制顯示模式

保存按鈕的實現邏輯值得關注，代碼通過FloatingActionButton組件觸發配置保存流程：

floatingActionButton: FloatingActionButton(
  child: const Icon(Icons.save),
  onPressed: () async {
    // 保存配置到本地存儲
    setting.put(SettingBoxKey.webDavURL, webDavURLController.text);
    setting.put(SettingBoxKey.webDavUsername, webDavUsernameController.text);
    setting.put(SettingBoxKey.webDavPassword, webDavPasswordController.text);
    
    // 初始化WebDAV客户端並測試連接
    var webDav = WebDav();
    try {
      await webDav.init();
      await webDav.ping();
      KazumiDialog.showToast(message: '測試成功');
    } catch (e) {
      KazumiDialog.showToast(message: '配置失敗 ${e.toString()}');
      await setting.put(SettingBoxKey.webDavEnable, false);
    }
  },
)

WebDAV客户端核心實現

Kazumi的WebDAV客户端核心邏輯封裝在lib/utils/webdav.dart中，採用單例模式設計確保全局唯一實例，通過WebDav()工廠方法獲取客户端實例。

初始化流程

初始化過程包含環境準備、參數驗證和服務連接三個階段：

  1. 創建本地臨時目錄webdavLocalTempDirectory用於文件緩存
  2. 從Hive存儲lib/utils/storage.dart讀取配置參數
  3. 使用webdav_client庫創建客户端實例並驗證服務連通性

關鍵代碼實現如下：

Future<void> init() async {
  // 創建本地臨時目錄
  var directory = await getApplicationSupportDirectory();
  webDavLocalTempDirectory = Directory('${directory.path}/webdavTemp');
  if (!await webDavLocalTempDirectory.exists()) {
    await webDavLocalTempDirectory.create(recursive: true);
  }
  
  // 讀取配置參數
  Box setting = GStorage.setting;
  webDavURL = setting.get(SettingBoxKey.webDavURL, defaultValue: '');
  webDavUsername = setting.get(SettingBoxKey.webDavUsername, defaultValue: '');
  webDavPassword = setting.get(SettingBoxKey.webDavPassword, defaultValue: '');
  
  // 驗證配置並創建客户端
  client = webdav.newClient(webDavURL, user: webDavUsername, password: webDavPassword);
  await client.ping();
  await client.mkdir('/kazumiSync'); // 創建同步根目錄
  initialized = true;
}

數據同步機制

Kazumi實現了基於文件的增量同步策略，核心同步對象包括用户收藏數據和觀看歷史，通過以下方法實現數據雙向同步：

  1. 數據上傳：update(String boxName)方法負責將本地Hive數據庫文件上傳至WebDAV服務，採用臨時文件+原子重命名策略確保數據一致性
  2. 數據下載：download(String boxName)方法從服務端獲取最新數據文件
  3. 增量合併：syncCollectibles()和downloadAndPatchHistory()實現本地與遠程數據的增量合併

同步目錄結構設計如下：

/kazumiSync/
├── collectibles.tmp  # 收藏數據主文件
├── collectchanges.tmp # 收藏變更記錄
└── histories.tmp    # 觀看歷史數據

併發控制

為避免多任務衝突，客户端實現了簡單有效的併發控制機制：

// 確保同一時間只有一個歷史同步任務執行
bool isHistorySyncing = false;

Future<void> updateHistory() async {
  if (isHistorySyncing) {
    KazumiLogger().log(Level.warning, 'History is currently syncing');
    throw Exception('History is currently syncing');
  }
  isHistorySyncing = true;
  try {
    await update('histories');
  } finally {
    isHistorySyncing = false;
  }
}

數據同步策略與最佳實踐

同步對象設計

Kazumi針對不同數據類型採用差異化同步策略：

數據類型

同步方式

觸發時機

存儲路徑

觀看歷史

增量上傳

播放結束時

histories.tmp

收藏數據

全量+變更

收藏狀態變化

collectibles.tmp

收藏變更

增量記錄

收藏操作時

collectchanges.tmp

衝突解決機制

當本地與遠程數據存在衝突時，系統採用"遠程優先、本地補充"的合併策略：

  1. 下載遠程變更記錄collectchanges.tmp
  2. 應用遠程變更到本地數據庫
  3. 上傳合併後的完整數據覆蓋遠程文件

實現代碼位於syncCollectibles()方法：

Future<void> syncCollectibles() async {
  // 下載遠程數據文件
  await Future.wait([
    download('collectibles'),
    download('collectchanges')
  ]);
  
  // 讀取遠程數據
  final remoteCollectibles = await GStorage.getCollectiblesFromFile(
    '${webDavLocalTempDirectory.path}/collectibles.tmp');
  final remoteChanges = await GStorage.getCollectChangesFromFile(
    '${webDavLocalTempDirectory.path}/collectchanges.tmp');
  
  // 合併數據並上傳更新
  await GStorage.patchCollectibles(remoteCollectibles, remoteChanges);
  await updateCollectibles();
}

性能優化建議

  1. 網絡感知同步：結合網絡狀態判斷是否執行同步操作，避免移動網絡下的大文件傳輸
  2. 批量操作優化：多個小文件合併為單個歸檔文件減少HTTP請求次數
  3. 同步狀態指示：通過UI組件提示用户當前同步狀態，增強用户體驗

相關模塊與擴展閲讀

配置管理

WebDAV配置參數通過Hive存儲管理，相關實現位於lib/utils/storage.dart，定義了以下關鍵配置項：

  • webDavURL：WebDAV服務地址
  • webDavUsername：認證用户名
  • webDavPassword：認證密碼
  • webDavEnable：同步功能開關狀態

日誌與調試

同步過程中的關鍵事件通過日誌系統記錄，實現於lib/utils/logger.dart，可通過調整日誌級別獲取詳細調試信息：

KazumiLogger().log(Level.info, 'webDav backup directory create success');

界面原型

WebDAV配置界面的設計稿可參考項目中的原型資源，實際界面效果如下：

數據同步方案整理 - 旺仔沒饅頭的個人空間 -_客户端

總結

Kazumi的WebDAV客户端實現為跨設備數據同步提供了輕量級解決方案，通過簡潔的配置界面、可靠的客户端實現和靈活的同步策略，滿足了番劇觀看記錄和收藏數據的跨設備一致性需求。開發者可基於現有實現擴展更多同步對象，或優化衝突解決算法以適應更復雜的使用場景。