12 KiB
12 KiB
DramaLing 後端 Services 層架構優化計劃
版本: 1.1 日期: 2025-09-30 狀態: 🚧 實施中
🎯 優化目標
基於大規模清理後的 Services 層現況，進一步優化架構設計，提升可維護性、可測試性和擴展性。
📊 當前 Services 層分析
現有服務列表 (19個服務)
根目錄服務 (14個)
Services/
├── AnalysisService.cs # AI 分析服務 (4.9KB)
├── AudioCacheService.cs # 音訊快取服務 (4.8KB)
├── AuthService.cs # 認證服務 (3.4KB)
├── AzureSpeechService.cs # Azure 語音服務 (6.2KB)
├── GeminiService.cs # Gemini AI 服務 (23.1KB) ⚠️ 過大
├── IAnalysisService.cs # 分析服務介面 (1.8KB)
├── IImageGenerationOrchestrator.cs # 圖片生成編排介面 (359B)
├── IImageProcessingService.cs # 圖片處理服務介面 (254B)
├── IOptionsVocabularyService.cs # 選項詞彙庫服務介面 (1.6KB)
├── ImageGenerationOrchestrator.cs # 圖片生成編排服務 (17.3KB) ⚠️ 過大
├── ImageProcessingService.cs # 圖片處理服務 (3.1KB)
├── OptionsVocabularyService.cs # 選項詞彙庫服務 (6.9KB)
├── ReplicateService.cs # Replicate API 服務 (10.6KB)
└── UsageTrackingService.cs # 使用量追蹤服務 (9.4KB)
子目錄服務 (5個)
Storage/
├── IImageStorageService.cs # 圖片儲存服務介面 (597B)
└── LocalImageStorageService.cs # 本地圖片儲存服務 (4.1KB)
Monitoring/
└── OptionsVocabularyMetrics.cs # 選項詞彙庫監控服務 (5.4KB)
Caching/
├── ICacheService.cs # 快取服務介面 (2.9KB)
└── HybridCacheService.cs # 混合快取服務 (17.6KB) ⚠️ 過大
🔍 問題識別
1. 架構問題
- 缺乏分層邏輯: 根目錄混雜不同類型的服務
- 職責不清: 部分服務承擔過多責任
- 命名不一致: 介面和實作命名規則不統一
2. 檔案大小問題
- GeminiService.cs (23.1KB): 包含過多功能，違反單一職責原則
- ImageGenerationOrchestrator.cs (17.3KB): 編排邏輯過於複雜
- HybridCacheService.cs (17.6KB): 快取邏輯包含太多實作細節
3. 依賴關係問題
- 循環依賴風險: 服務間依賴關係不夠清晰
- 介面分離不足: 某些服務職責過大
- 測試困難: 大型服務難以進行單元測試
🏗️ 優化方案
階段一：服務分類重組 (1-2天)
1.1 按功能域重新組織目錄結構
Services/
├── Core/ # 核心業務服務
│ ├── Auth/ # 認證授權
│ ├── Flashcard/ # 詞卡管理
│ └── User/ # 用戶管理
├── AI/ # AI 相關服務
│ ├── Analysis/ # 分析服務
│ ├── Gemini/ # Gemini AI
│ └── Generation/ # 內容生成
├── Media/ # 多媒體服務
│ ├── Audio/ # 音訊處理
│ ├── Image/ # 圖片處理
│ └── Storage/ # 儲存服務
├── Infrastructure/ # 基礎設施服務
│ ├── Caching/ # 快取服務
│ ├── Monitoring/ # 監控服務
│ └── Messaging/ # 訊息服務
└── Vocabulary/ # 詞彙相關服務
├── Options/ # 選項生成
└── Management/ # 詞彙管理
1.2 服務重新分配
// 移動計劃
AuthService → Core/Auth/
AnalysisService → AI/Analysis/
GeminiService → AI/Gemini/ (需拆分)
ImageGenerationOrchestrator → AI/Generation/ (需拆分)
ReplicateService → AI/Generation/
AudioCacheService → Media/Audio/
AzureSpeechService → Media/Audio/
ImageProcessingService → Media/Image/
Storage/* → Media/Storage/
OptionsVocabularyService → Vocabulary/Options/
UsageTrackingService → Infrastructure/Monitoring/
Caching/* → Infrastructure/Caching/
Monitoring/* → Infrastructure/Monitoring/
階段二：大型服務拆分 (2-3天)
2.1 拆分 GeminiService (23.1KB)
// 拆分為多個專職服務
AI/Gemini/
├── IGeminiClient.cs # HTTP 客戶端介面
├── GeminiClient.cs # HTTP 客戶端實作
├── IGeminiAnalyzer.cs # 分析功能介面
├── GeminiAnalyzer.cs # 句子分析服務
├── IGeminiDescriptionGenerator.cs # 描述生成介面
├── GeminiDescriptionGenerator.cs # 圖片描述生成服務
├── Models/ # Gemini 相關 DTOs
└── Configuration/ # Gemini 配置類
2.2 拆分 ImageGenerationOrchestrator (17.3KB)
// 拆分為多個專職服務
AI/Generation/
├── IImageGenerationWorkflow.cs # 工作流程介面
├── ImageGenerationWorkflow.cs # 主要工作流程
├── IGenerationStateManager.cs # 狀態管理介面
├── GenerationStateManager.cs # 狀態管理實作
├── IGenerationValidator.cs # 驗證服務介面
├── GenerationValidator.cs # 請求驗證服務
└── Steps/ # 生成步驟
├── IDescriptionStep.cs # 描述生成步驟
├── DescriptionStep.cs
├── IImageStep.cs # 圖片生成步驟
├── ImageStep.cs
├── IStorageStep.cs # 儲存步驟
└── StorageStep.cs
2.3 拆分 HybridCacheService (17.6KB)
// 拆分為多個專職服務
Infrastructure/Caching/
├── ICacheProvider.cs # 快取提供者介面
├── MemoryCacheProvider.cs # 記憶體快取實作
├── DistributedCacheProvider.cs # 分散式快取實作
├── ICacheKeyGenerator.cs # 快取鍵生成介面
├── CacheKeyGenerator.cs # 快取鍵生成實作
├── ICacheConfiguration.cs # 快取配置介面
├── CacheConfiguration.cs # 快取配置實作
└── Strategies/ # 快取策略
├── IEvictionStrategy.cs # 清除策略介面
└── LRUEvictionStrategy.cs # LRU 清除策略
階段三：介面標準化 (1天)
3.1 統一命名規則
// 介面命名規則
I{ServiceName}Service # 業務服務介面
I{ServiceName}Provider # 基礎設施提供者介面
I{ServiceName}Manager # 管理器介面
I{ServiceName}Factory # 工廠介面
// 實作命名規則
{ServiceName}Service # 業務服務實作
{ServiceName}Provider # 基礎設施提供者實作
{ServiceName}Manager # 管理器實作
{ServiceName}Factory # 工廠實作
3.2 介面職責定義
// 服務層級定義
public interface IBusinessService<T> # 業務邏輯服務
public interface IDataService<T> # 資料存取服務
public interface IIntegrationService # 外部整合服務
public interface IInfrastructureService # 基礎設施服務
階段四：依賴注入優化 (1天)
4.1 服務註冊重組
// Extensions/ServiceCollectionExtensions.cs 重構
public static IServiceCollection AddCoreServices(this IServiceCollection services)
public static IServiceCollection AddAIServices(this IServiceCollection services)
public static IServiceCollection AddMediaServices(this IServiceCollection services)
public static IServiceCollection AddInfrastructureServices(this IServiceCollection services)
public static IServiceCollection AddVocabularyServices(this IServiceCollection services)
4.2 服務生命週期標準化
// 生命週期規則
Singleton # 無狀態配置服務、快取提供者
Scoped # 業務邏輯服務、資料存取服務
Transient # 輕量級工具服務、工廠服務
階段五：測試友好設計 (2天)
5.1 介面抽象化
- 確保所有服務都有對應介面
- 移除具體類型依賴
- 支援模擬測試
5.2 單元測試覆蓋
// 測試結構
Tests/
├── Services/
│ ├── Core/
│ ├── AI/
│ ├── Media/
│ ├── Infrastructure/
│ └── Vocabulary/
└── Integration/
├── AI/
└── Media/
📅 實施時程
第 1 週
- 第 1-2 天: 階段一 - 服務分類重組
- 第 3-5 天: 階段二 - 大型服務拆分
- 第 6-7 天: 階段三 - 介面標準化
第 2 週
- 第 1 天: 階段四 - 依賴注入優化
- 第 2-3 天: 階段五 - 測試友好設計
- 第 4-5 天: 整合測試與驗證
🎯 預期效果
程式碼品質提升
- 可維護性: 服務職責單一，易於修改
- 可測試性: 介面抽象化，支援模擬測試
- 可讀性: 目錄結構清晰，命名一致
開發效率提升
- 團隊協作: 功能域分離，減少衝突
- 新功能開發: 標準化介面，快速擴展
- 問題定位: 服務分離，快速排查
架構健康度
- 從當前 7.5/10 提升到 9.0/10
- 服務數量: 19個 → 約35個 (拆分後)
- 平均檔案大小: 減少60%
- 測試覆蓋率: 從0% → 80%+
⚠️ 風險評估
高風險項目
- GeminiService 拆分: 影響多個控制器
- 快取服務重構: 可能影響效能
降低風險措施
- 分階段實施: 避免大規模同時變更
- 充分測試: 每階段完成後進行整合測試
- 回滾計劃: 保持舊版本分支作為備份
📋 檢查清單
階段一完成標準
- 目錄結構重組完成
- 所有服務移動到對應目錄
- 編譯無錯誤
- 基本功能測試通過
階段二完成標準
- 大型服務拆分完成
- 新服務介面定義清晰
- 依賴注入配置更新
- 單元測試覆蓋重要邏輯
整體完成標準
- 所有服務檔案 < 10KB
- 介面命名規則統一
- 依賴關係清晰無循環
- 測試覆蓋率 > 80%
- 效能回歸測試通過
📈 實施進度
✅ 已完成項目 (2025-09-30)
階段一：服務分類重組 ✅ 已完成
- ✅ 新目錄結構創建: 建立 Core/AI/Media/Infrastructure/Vocabulary 功能域
- ✅ 服務重新分配: 19個服務已移動到對應功能域目錄
- ✅ 編譯驗證: 新架構編譯成功，服務正常運行
當前架構狀態
Services/ (重組後)
├── Core/Auth/ # 認證服務 (1個文件)
├── AI/
│ ├── Analysis/ # 分析服務 (2個文件)
│ ├── Gemini/ # Gemini AI (1個文件, 584行) ⚠️ 待拆分
│ └── Generation/ # 圖片生成 (3個文件)
├── Media/
│ ├── Audio/ # 音訊服務 (2個文件)
│ ├── Image/ # 圖片處理 (2個文件)
│ └── Storage/ # 儲存服務 (2個文件)
├── Infrastructure/
│ ├── Caching/ # 快取服務 (2個文件) ⚠️ 待拆分
│ └── Monitoring/ # 監控服務 (2個文件)
└── Vocabulary/
└── Options/ # 選項詞彙庫 (2個文件)
🚧 下一步實施計劃
階段二：大型服務拆分 🔄 準備中
- ⏳ GeminiService 拆分 (584行 → 多個專職服務)
- ⏳ ImageGenerationOrchestrator 拆分 (424行 → 工作流程服務)
- ⏳ HybridCacheService 拆分 (大型快取服務 → 策略模式)
階段三：介面標準化 ⏸️ 待開始
- ⏸️ 統一命名規則實施
- ⏸️ 服務層級介面定義
- ⏸️ 依賴注入標準化
文檔版本: 1.1 最後更新: 2025-09-30 17:02 負責人: Claude Code 審核狀態: 實施中 進度: 階段一完成 (33%)