11 KiB

Raw Blame History

DramaLing API 架構文檔

版本: 2.0 架構模式: Clean Architecture + Domain-Driven Design 最後更新: 2025-09-30

🏗️ 架構概覽

DramaLing API 採用 Clean Architecture 原則設計，實現高內聚、低耦合的現代化後端架構。遵循 Domain-Driven Design 理念，按業務領域組織代碼結構。

核心設計原則

依賴反轉原則 - 高層模組不依賴於低層模組
單一職責原則 - 每個類別只有一個改變的理由
開放封閉原則 - 對擴展開放，對修改封閉
介面隔離原則 - 不應該被迫依賴不使用的方法

📁 目錄架構

DramaLing.Api/
├── Controllers/           # 🎯 API 控制器層 - Web API 端點
├── Services/             # 💼 業務服務層 - 領域邏輯實現
│   ├── AI/              #   🤖 AI 相關服務 (Gemini, 圖片生成)
│   ├── Core/            #   🔧 核心業務服務 (認證)
│   ├── Infrastructure/  #   🏗️ 基礎設施服務 (快取, 監控)
│   ├── Media/           #   📁 多媒體服務 (音訊, 圖片, 儲存)
│   └── Vocabulary/      #   📚 詞彙相關服務
├── Repositories/         # 💾 資料訪問層 - 數據持久化
├── Data/                # 🗄️ EF Core 配置 - 資料庫上下文
├── Models/              # 📋 資料模型層
│   ├── Entities/        #   📊 實體模型 - 資料庫映射
│   ├── DTOs/            #   📦 數據傳輸物件 - API 交換
│   └── Configuration/   #   ⚙️ 配置類別 - 系統設定
├── Extensions/          # 🔧 擴展方法 - 依賴注入配置
├── Middleware/          # 🔗 中間件 - 請求處理管道
└── DramaLing.Api.Tests/ # 🧪 測試專案 - 完整測試覆蓋

🎯 Clean Architecture 分層

1. Presentation Layer (表示層)

Controllers/ - Web API 控制器

處理 HTTP 請求和回應
路由和參數驗證
調用 Service 層執行業務邏輯
依賴: Service Layer

關鍵特色:

遵循 RESTful API 設計原則
統一的錯誤處理和回應格式
JWT 認證和授權控制
Swagger/OpenAPI 文檔生成

2. Application/Service Layer (應用服務層)

Services/ - 業務邏輯和應用服務

2.1 領域服務組織

Services/
├── AI/                  # 🤖 AI 領域服務
│   ├── Analysis/       # 分析服務
│   ├── Gemini/         # Gemini AI 服務群組
│   └── Generation/     # 圖片生成服務群組
├── Core/               # 🔧 核心領域
├── Infrastructure/     # 🏗️ 基礎設施
├── Media/              # 📁 多媒體領域
└── Vocabulary/         # 📚 詞彙領域

2.2 服務架構模式

Facade Pattern: 每個服務群組都有統一入口

// 主要服務 - 統一入口
GeminiService (Facade)
├── SentenceAnalyzer
├── ImageDescriptionGenerator
└── GeminiClient

Composition Pattern: 複雜服務由多個小服務組合

HybridCacheService (Facade)
├── MemoryCacheProvider
├── DistributedCacheProvider
├── CacheStrategyManager
└── DatabaseCacheManager

3. Domain Layer (領域層)

Models/Entities/ - 領域實體和業務規則

User, Flashcard, AnalysisCache 等核心實體
業務邏輯和驗證規則
實體間關係定義

Models/DTOs/ - 數據傳輸物件

API 請求和回應模型
層間數據傳輸規範
序列化和驗證屬性

4. Infrastructure Layer (基礎設施層)

Repositories/ - 資料訪問抽象

Repository Pattern 實現
資料庫查詢邏輯
資料持久化操作

Data/ - 數據基礎設施

Entity Framework DbContext
資料庫連接和配置
資料庫遷移

🔄 依賴注入架構

服務註冊策略

Extensions/ServiceCollectionExtensions.cs - 模組化 DI 配置

// 依生命週期組織服務註冊
services.AddDatabaseServices(configuration);     // Scoped
services.AddRepositoryServices();               // Scoped
services.AddCachingServices();                  // Mixed
services.AddAIServices(configuration);          // Mixed
services.AddBusinessServices();                 // Scoped
services.AddAuthenticationServices();           // Singleton

生命週期管理

服務類型	生命週期	說明
Controllers	Scoped	每個請求一個實例
Services	Scoped	業務邏輯服務
Repositories	Scoped	資料訪問服務
Cache Providers	Singleton/Scoped	根據實現決定
HTTP Clients	Singleton	HTTP 連接池管理

🗄️ 資料存取架構

Repository Pattern 實現

// 泛型基礎介面
IRepository<T> : 基本 CRUD 操作

// 特化介面
IFlashcardRepository : IRepository<Flashcard>
├── GetByUserIdAsync()
├── GetByUserIdAndFlashcardIdAsync()
├── GetCountByUserIdAsync()
└── GetPagedByUserIdAsync()

Entity Framework Core 配置

Database Provider: SQLite (開發/測試), SQL Server (生產)
Code First: 資料庫遷移管理
Connection String: 環境變數優先配置
LazyLoading: 關閉，使用明確載入

🚀 快取架構

混合快取策略

HybridCacheService 實現多層快取:

L1: Memory Cache (熱點數據)
    ↓ (Miss)
L2: Distributed Cache (跨實例共享)
    ↓ (Miss)
L3: Database Cache (持久化快取)
    ↓ (Miss)
Original Data Source

快取策略管理

智能過期: 根據數據類型動態設定 TTL
快取預熱: 應用啟動時預載熱點數據
快取更新: Write-Through 和 Write-Behind 策略
快取統計: 命中率和效能監控

🤖 AI 服務架構

Gemini AI 整合

GeminiService (Facade Pattern):

├── SentenceAnalyzer      # 句子語意分析
├── ImageDescriptionGenerator # 圖片描述生成
└── GeminiClient         # HTTP API 通訊

圖片生成工作流

ImageGenerationOrchestrator:

├── ImageGenerationWorkflow   # 主要生成流程
├── GenerationStateManager    # 狀態追蹤
├── ImageSaveManager         # 圖片儲存
└── GenerationPipelineService # 管道協調

🔐 認證與安全架構

JWT 認證流程

Supabase 整合: 用戶註冊和登入
Token 驗證: JWT 中間件驗證
授權控制: 基於 Claims 的授權
CORS 配置: 跨域請求安全控制

安全最佳實務

敏感資訊環境變數管理
API Key 安全儲存
輸入驗證和 SQL 注入防護
HTTPS 強制和安全標頭

🧪 測試架構

測試金字塔實現

E2E Tests (Integration)
    ↑
Unit Tests (Services, Repositories)
    ↑
Infrastructure Tests (Database, Cache)

測試基礎設施

TestBase: 統一測試環境設定
TestDataFactory: 測試數據建立工具
InMemory Database: 快速單元測試
Mock Services: 外部依賴模擬

📊 監控與日誌

結構化日誌

// 分級日誌記錄
Logger.LogInformation("Business operation completed: {Operation}", operation);
Logger.LogWarning("Performance threshold exceeded: {ResponseTime}ms", time);
Logger.LogError(ex, "Error processing request: {RequestId}", requestId);

效能監控

API 回應時間: 端點效能追蹤
資料庫查詢: EF Core 查詢分析
快取效能: 命中率和延遲監控
記憶體使用: GC 和記憶體洩漏檢測

🔧 開發工作流

新功能開發流程

領域分析: 確定功能所屬領域
介面設計: 定義 Service 介面
實現邏輯: 實作業務邏輯
資料訪問: 建立或更新 Repository
API 端點: 建立 Controller 方法
單元測試: 撰寫測試覆蓋
整合測試: API 端點測試
文檔更新: 更新相關文檔

程式碼品質保證

靜態分析: SonarQube/CodeQL 掃描
程式碼風格: EditorConfig 統一格式
Git Hook: Pre-commit 品質檢查
CI/CD: 自動化構建和部署

📈 效能優化策略

1. 資料庫最佳化

索引優化: 常用查詢欄位索引
查詢優化: N+1 問題避免
連接池: 資料庫連接管理
分頁查詢: 大數據集分頁載入

2. 快取最佳化

快取分層: 多層快取命中優化
快取預熱: 應用啟動預載
過期策略: 智能 TTL 管理
快取穿透: 空值快取防護

3. 並發處理

異步操作: async/await 模式
並行執行: Task.WhenAll 批量處理
資源池: HTTP Client 連接池
限流控制: API 頻率限制

🚀 部署架構

環境配置

Development → Testing → Staging → Production
     ↓           ↓        ↓         ↓
   SQLite → SQL Server → Azure SQL → Azure SQL
   Memory → Redis Cache → Azure Cache → Azure Cache

容器化部署

# 多階段構建
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
# ... 構建邏輯
FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS runtime
# ... 運行時配置

📋 架構決策記錄 (ADR)

ADR-001: 選擇 Clean Architecture

日期: 2025-09-29
狀態: 已採用
決策: 採用 Clean Architecture 架構模式
原因: 提高可測試性、可維護性和可擴展性

ADR-002: Repository Pattern 實現

日期: 2025-09-30
狀態: 已採用
決策: 實現 Repository Pattern 進行資料訪問抽象
原因: 分離業務邏輯和資料訪問，提升可測試性

ADR-003: Facade Pattern 在服務層

日期: 2025-09-30
狀態: 已採用
決策: 使用 Facade Pattern 簡化複雜服務調用
原因: 降低客戶端複雜度，提供統一服務入口

🔮 未來架構演進

短期優化 (1-3個月)

微服務拆分: 大型服務領域拆分
消息隊列: 異步處理長時間任務
API 版本控制: 向下兼容的版本管理
健康檢查: 完整的應用健康監控

長期規劃 (3-12個月)

Event Sourcing: 事件驅動架構演進
CQRS: 讀寫分離模式實現
Kubernetes: 容器編排和自動擴展
監控觀測: APM 和分散式追蹤

文檔維護者: DramaLing 開發團隊 架構版本: Clean Architecture 2.0 最後審核: 2025-09-30 下次審核: 2025-12-30

11 KiB Raw Blame History