Services 層架構索引
概述
Services 層實作業務邏輯，採用領域驅動設計 (DDD) 原則，按功能領域組織服務。所有服務都已重構為符合單一職責原則 (SRP) 和組合模式 (Composition Pattern)。
目錄結構
Services/
├── README.md # 本文檔 - Services 層總覽
├── AI/ # AI 相關服務
│ ├── Analysis/ # AI 分析服務
│ ├── Gemini/ # Gemini AI 服務
│ └── Generation/ # 圖片生成服務
├── Core/ # 核心業務服務
│ └── Auth/ # 認證服務
├── Infrastructure/ # 基礎設施服務
│ ├── Caching/ # 快取服務
│ └── Monitoring/ # 監控服務
├── Media/ # 多媒體服務
│ ├── Audio/ # 音訊處理服務
│ ├── Image/ # 圖片處理服務
│ └── Storage/ # 多媒體儲存服務
└── Vocabulary/ # 詞彙相關服務
└── Options/ # 選項詞彙服務
🤖 AI 服務 (Services/AI/)
AI 分析服務組 (AI/Analysis/)
| 服務名稱 |
功能說明 |
檔案位置 |
AnalysisService |
綜合分析服務 (帶快取) |
AnalysisService.cs |
IGeminiAnalyzer |
Gemini 分析器介面 |
IGeminiAnalyzer.cs |
Gemini 服務組 (AI/Gemini/)
主要 Facade 服務: GeminiService - 統一的 Gemini AI 功能入口
| 服務名稱 |
功能說明 |
檔案位置 |
GeminiClient |
Gemini API HTTP 通訊客戶端 |
GeminiClient.cs |
SentenceAnalyzer |
句子語意分析服務 |
SentenceAnalyzer.cs |
ImageDescriptionGenerator |
圖片描述生成服務 |
ImageDescriptionGenerator.cs |
使用範例:
// 注入主要服務
private readonly IGeminiService _geminiService;
// 分析句子
var analysis = await _geminiService.AnalyzeSentenceAsync(text, options);
// 生成圖片描述
var description = await _geminiService.GenerateImageDescriptionAsync(flashcard, options);
圖片生成服務組 (AI/Generation/)
主要 Facade 服務: ImageGenerationOrchestrator - 圖片生成工作流程協調器
| 服務名稱 |
功能說明 |
檔案位置 |
ImageGenerationWorkflow |
主要圖片生成工作流程 |
ImageGenerationWorkflow.cs |
GenerationStateManager |
生成狀態管理 |
GenerationStateManager.cs |
ImageSaveManager |
圖片儲存管理 |
ImageSaveManager.cs |
GenerationPipelineService |
生成管道服務 |
GenerationPipelineService.cs |
🔧 核心服務 (Services/Core/)
認證服務 (Core/Auth/)
| 服務名稱 |
功能說明 |
檔案位置 |
AuthService |
用戶認證和授權服務 |
AuthService.cs |
🏗️ 基礎設施服務 (Services/Infrastructure/)
快取服務組 (Infrastructure/Caching/)
主要 Facade 服務: HybridCacheService - 混合快取服務
| 服務名稱 |
功能說明 |
檔案位置 |
MemoryCacheProvider |
記憶體快取提供者 |
MemoryCacheProvider.cs |
DistributedCacheProvider |
分散式快取提供者 |
DistributedCacheProvider.cs |
JsonCacheSerializer |
JSON 快取序列化器 |
JsonCacheSerializer.cs |
CacheStrategyManager |
快取策略管理器 |
CacheStrategyManager.cs |
DatabaseCacheManager |
資料庫快取管理器 |
DatabaseCacheManager.cs |
快取架構特色:
- 混合快取: 結合記憶體和分散式快取
- 策略模式: 可動態切換快取策略
- 序列化支援: JSON 格式序列化
- 資料庫整合: 支援資料庫層快取
監控服務組 (Infrastructure/Monitoring/)
| 服務名稱 |
功能說明 |
檔案位置 |
UsageTrackingService |
使用追蹤服務 |
UsageTrackingService.cs |
OptionsVocabularyMetrics |
選項詞彙指標服務 |
OptionsVocabularyMetrics.cs |
📁 媒體服務 (Services/Media/)
音訊服務 (Media/Audio/)
| 服務名稱 |
功能說明 |
檔案位置 |
AudioCacheService |
音訊快取服務 |
AudioCacheService.cs |
AzureSpeechService |
Azure 語音服務 |
AzureSpeechService.cs |
圖片服務 (Media/Image/)
| 服務名稱 |
功能說明 |
檔案位置 |
ImageProcessingService |
圖片處理服務 |
ImageProcessingService.cs |
儲存服務 (Media/Storage/)
| 服務名稱 |
功能說明 |
檔案位置 |
LocalImageStorageService |
本地圖片儲存服務 |
LocalImageStorageService.cs |
📚 詞彙服務 (Services/Vocabulary/)
選項詞彙服務 (Vocabulary/Options/)
| 服務名稱 |
功能說明 |
檔案位置 |
OptionsVocabularyService |
選項型詞彙服務 |
OptionsVocabularyService.cs |
🌐 外部服務整合
Replicate 服務
| 服務名稱 |
功能說明 |
檔案位置 |
ReplicateService |
Replicate AI 平台整合服務 |
ReplicateService.cs |
🔄 服務註冊與依賴注入
所有服務都在 Extensions/ServiceCollectionExtensions.cs 中統一註冊：
// AI 服務
services.AddAIServices(configuration);
// 業務服務
services.AddBusinessServices();
// 快取服務
services.AddCachingServices();
// Repository 服務
services.AddRepositoryServices();
⚡ 效能優化特色
- Facade Pattern: 每個服務群組都有統一入口，簡化使用
- 組合模式: 複雜服務由多個小型服務組合而成
- 異步優先: 所有 I/O 操作都使用異步方法
- 快取支援: 關鍵服務集成智能快取機制
- 依賴注入: 完全支援 DI 容器，便於測試和維護
🧪 重構成果
重構前 vs 重構後對比
| 服務 |
重構前行數 |
重構後服務數 |
改善程度 |
ImageGenerationOrchestrator |
425 行 |
6 個服務 |
職責明確化 |
HybridCacheService |
538 行 |
8 個服務 |
策略模式 |
GeminiService |
584 行 |
4 個服務 |
Facade 簡化 |
架構優勢
- ✅ 可測試性: 每個服務職責單一，易於單元測試
- ✅ 可維護性: 程式碼模組化，修改影響範圍小
- ✅ 可擴展性: 新功能開發更便捷
- ✅ 可讀性: 服務命名清晰，職責明確
📖 開發指南
新增服務步驟
- 選擇適當的領域目錄 (AI/Core/Infrastructure/Media 等)
- 建立介面檔案
I{ServiceName}.cs
- 建立實作檔案
{ServiceName}.cs
- 在
ServiceCollectionExtensions.cs 註冊服務
- 更新本索引文檔
命名規範
- 介面:
I{ServiceName} (例: IGeminiService)
- 實作:
{ServiceName} (例: GeminiService)
- Facade 服務: 保持原有名稱，作為主要入口點
版本: 1.1
最後更新: 2025-09-30
維護者: DramaLing 開發團隊
重構日期: 2025-09-29 ~ 2025-09-30
索引完善: 2025-09-30 (階段三完成)