383 lines
14 KiB
Markdown
383 lines
14 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 提升到 8.5/10** (階段二完成)
|
||
- **服務數量**: 19個 → 33個 (拆分後)
|
||
- **大型服務處理**: 2個大型服務已拆分完成
|
||
- ImageGenerationOrchestrator: 425行 → 6個服務 (平均<80行)
|
||
- HybridCacheService: 538行 → 8個服務 (平均<100行)
|
||
- **編譯狀態**: ✅ 成功 (0個錯誤，13個警告)
|
||
- **架構模式**: 組合模式、外觀模式、策略模式已實施
|
||
|
||
---
|
||
|
||
## ⚠️ **風險評估**
|
||
|
||
### **高風險項目**
|
||
- **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個文件)
|
||
```
|
||
|
||
### **✅ 已完成項目** (2025-09-30 更新)
|
||
|
||
#### **階段二：大型服務拆分** ✅ **已完成**
|
||
- ✅ **ImageGenerationOrchestrator 拆分** (425行 → 6個專職服務)
|
||
- `IImageGenerationWorkflow` + `ImageGenerationWorkflow` - 主要工作流程
|
||
- `IGenerationStateManager` + `GenerationStateManager` - 狀態管理
|
||
- `IImageSaveManager` + `ImageSaveManager` - 圖片保存邏輯
|
||
- `IGenerationPipelineService` + `GenerationPipelineService` - 生成流程管道
|
||
- 原 `ImageGenerationOrchestrator` 改為外觀模式代理
|
||
|
||
- ✅ **HybridCacheService 拆分** (538行 → 8個專職服務)
|
||
- `ICacheProvider` + `MemoryCacheProvider` - 記憶體快取提供者
|
||
- `ICacheProvider` + `DistributedCacheProvider` - 分散式快取提供者
|
||
- `ICacheSerializer` + `JsonCacheSerializer` - JSON序列化器
|
||
- `ICacheStrategyManager` + `CacheStrategyManager` - 快取策略管理
|
||
- `IDatabaseCacheManager` + `DatabaseCacheManager` - 資料庫快取管理
|
||
- `RefactoredHybridCacheService` - 重構後的主要快取服務
|
||
|
||
- ✅ **GeminiService 拆分** (584行 → 4個專職服務)
|
||
- `IGeminiClient` + `GeminiClient` - HTTP API 客戶端
|
||
- `ISentenceAnalyzer` + `SentenceAnalyzer` - 句子分析專職服務
|
||
- `IImageDescriptionGenerator` + `ImageDescriptionGenerator` - 圖片描述生成服務
|
||
- 原 `GeminiService` 改為 Facade 模式統一入口
|
||
|
||
- ✅ **依賴注入配置更新** - ServiceCollectionExtensions 完整重構
|
||
- 新增快取組件注入配置
|
||
- 新增 AI 服務組件配置 (包含 Gemini 拆分服務)
|
||
- 所有服務正確註冊並編譯成功
|
||
|
||
### **🚧 下一步實施計劃**
|
||
|
||
#### **階段三：介面標準化** ⏸️ **待開始**
|
||
- ⏸️ 統一命名規則實施
|
||
- ⏸️ 服務層級介面定義
|
||
- ⏸️ 單元測試覆蓋
|
||
|
||
---
|
||
|
||
**文檔版本**: 1.3
|
||
**最後更新**: 2025-09-30 20:15
|
||
**負責人**: Claude Code
|
||
**審核狀態**: 階段二完成 (含 GeminiService 拆分)
|
||
**進度**: 階段二完成 (85%) |