356 lines
12 KiB
Markdown
356 lines
12 KiB
Markdown
# 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 服務重新分配**
|
|
```csharp
|
|
// 移動計劃
|
|
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)**
|
|
```csharp
|
|
// 拆分為多個專職服務
|
|
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)**
|
|
```csharp
|
|
// 拆分為多個專職服務
|
|
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)**
|
|
```csharp
|
|
// 拆分為多個專職服務
|
|
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 統一命名規則**
|
|
```csharp
|
|
// 介面命名規則
|
|
I{ServiceName}Service # 業務服務介面
|
|
I{ServiceName}Provider # 基礎設施提供者介面
|
|
I{ServiceName}Manager # 管理器介面
|
|
I{ServiceName}Factory # 工廠介面
|
|
|
|
// 實作命名規則
|
|
{ServiceName}Service # 業務服務實作
|
|
{ServiceName}Provider # 基礎設施提供者實作
|
|
{ServiceName}Manager # 管理器實作
|
|
{ServiceName}Factory # 工廠實作
|
|
```
|
|
|
|
#### **3.2 介面職責定義**
|
|
```csharp
|
|
// 服務層級定義
|
|
public interface IBusinessService<T> # 業務邏輯服務
|
|
public interface IDataService<T> # 資料存取服務
|
|
public interface IIntegrationService # 外部整合服務
|
|
public interface IInfrastructureService # 基礎設施服務
|
|
```
|
|
|
|
### **階段四：依賴注入優化** (1天)
|
|
|
|
#### **4.1 服務註冊重組**
|
|
```csharp
|
|
// 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 服務生命週期標準化**
|
|
```csharp
|
|
// 生命週期規則
|
|
Singleton # 無狀態配置服務、快取提供者
|
|
Scoped # 業務邏輯服務、資料存取服務
|
|
Transient # 輕量級工具服務、工廠服務
|
|
```
|
|
|
|
### **階段五：測試友好設計** (2天)
|
|
|
|
#### **5.1 介面抽象化**
|
|
- 確保所有服務都有對應介面
|
|
- 移除具體類型依賴
|
|
- 支援模擬測試
|
|
|
|
#### **5.2 單元測試覆蓋**
|
|
```csharp
|
|
// 測試結構
|
|
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%) |