249 lines
6.5 KiB
Markdown
249 lines
6.5 KiB
Markdown
# 🛡️ 架構防護檢查清單
|
||
|
||
## 📋 **每次開發前必讀**
|
||
|
||
### 🎯 **功能開發前的架構決策**
|
||
|
||
```
|
||
❓ 我要開發的功能屬於哪個領域？
|
||
📚 Learning (詞卡、學習、複習)
|
||
🤖 Analysis (AI分析、詞彙分析)
|
||
👤 User (用戶管理、認證、設定)
|
||
🔧 Infrastructure (快取、外部服務)
|
||
|
||
❓ 是否需要新的服務？
|
||
✅ 新業務領域 → 創建新服務
|
||
✅ 現有服務職責過重 → 拆分服務
|
||
❌ 只是小修改 → 擴展現有服務
|
||
|
||
❓ 服務應該放在哪一層？
|
||
🏢 Domain/: 核心業務邏輯
|
||
🔧 Infrastructure/: 技術實現
|
||
🤝 Shared/: 跨領域工具
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ **代碼提交前檢查清單**
|
||
|
||
### **🏗️ 架構規則檢查**
|
||
|
||
#### **服務設計**
|
||
- [ ] **服務職責單一**: 只做一件事，做好它
|
||
- [ ] **有介面定義**: 每個服務都有對應的 I*Service 介面
|
||
- [ ] **命名清晰**: 服務名稱表達業務意圖
|
||
- [ ] **大小適中**: 服務文件 < 300 行（建議 < 200 行）
|
||
|
||
#### **依賴關係**
|
||
- [ ] **向上依賴**: Domain → Infrastructure → Shared
|
||
- [ ] **無循環依賴**: 服務間不相互依賴
|
||
- [ ] **介面隔離**: 只依賴需要的介面方法
|
||
- [ ] **控制器分離**: Controller 不直接調用 Repository
|
||
|
||
#### **代碼品質**
|
||
- [ ] **異常處理**: 適當的 try-catch 和日誌記錄
|
||
- [ ] **參數驗證**: 公共方法驗證參數
|
||
- [ ] **資源管理**: using 語句管理 IDisposable
|
||
- [ ] **命名規範**: 變數和方法名有意義
|
||
|
||
---
|
||
|
||
## 🚨 **危險信號警報**
|
||
|
||
### **❌ 立即停止的架構違規**
|
||
|
||
```
|
||
🚨 Controller 直接使用 DbContext
|
||
→ 應該通過 Service 層
|
||
|
||
🚨 Domain Service 依賴 Infrastructure Service
|
||
→ 依賴方向錯誤
|
||
|
||
🚨 服務文件超過 500 行
|
||
→ 立即拆分
|
||
|
||
🚨 發現 "Manager"、"Helper"、"Utils" 類別
|
||
→ 重新設計為 Service
|
||
|
||
🚨 業務邏輯在 Controller 中
|
||
→ 移到對應的 Domain Service
|
||
```
|
||
|
||
### **⚠️ 需要注意的架構問題**
|
||
|
||
```
|
||
⚠️ 方法超過 20 行
|
||
→ 考慮拆分為更小的方法
|
||
|
||
⚠️ 類別超過 10 個公共方法
|
||
→ 考慮是否職責過多
|
||
|
||
⚠️ 構造函數參數超過 5 個
|
||
→ 可能依賴過多，考慮重構
|
||
|
||
⚠️ 重複的錯誤處理代碼
|
||
→ 考慮建立統一的錯誤處理機制
|
||
```
|
||
|
||
---
|
||
|
||
## 🎯 **快速自檢方法**
|
||
|
||
### **1. 服務職責檢查**
|
||
```
|
||
問自己：
|
||
1. 這個服務的職責能用一句話說清楚嗎？
|
||
2. 如果要給新人解釋這個服務，需要多長時間？
|
||
3. 這個服務是否混合了多個業務領域的邏輯？
|
||
|
||
✅ 好的例子：
|
||
"FlashcardService 負責詞卡的創建、更新和學習推薦"
|
||
|
||
❌ 壞的例子：
|
||
"UserFlashcardAnalysisService 負責用戶管理、詞卡操作、AI分析和快取管理"
|
||
```
|
||
|
||
### **2. 依賴關係檢查**
|
||
```
|
||
快速檢查：
|
||
1. 打開服務文件，看 using 語句
|
||
2. 檢查構造函數參數
|
||
3. 確認沒有向下依賴
|
||
|
||
✅ 正確依賴：
|
||
FlashcardService 依賴 IFlashcardRepository
|
||
AnalysisService 依賴 ICacheService
|
||
|
||
❌ 錯誤依賴：
|
||
CacheService 依賴 FlashcardService
|
||
Repository 依賴 AnalysisService
|
||
```
|
||
|
||
### **3. 測試友好度檢查**
|
||
```
|
||
問自己：
|
||
1. 這個服務容易寫單元測試嗎？
|
||
2. 所有依賴都是可以模擬的介面嗎？
|
||
3. 方法的輸入輸出是否清晰明確？
|
||
|
||
✅ 測試友好：
|
||
public async Task<FlashcardDto> CreateFlashcardAsync(CreateFlashcardRequest request)
|
||
|
||
❌ 測試困難：
|
||
public async Task DoComplexFlashcardOperation(object data, bool flag1, bool flag2)
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 **架構品質指標**
|
||
|
||
### **🎯 目標指標**
|
||
```
|
||
服務數量: 目標 8-15 個核心服務
|
||
平均服務大小: < 200 行
|
||
介面覆蓋率: > 90%
|
||
依賴深度: < 4 層
|
||
快取命中率: > 80%
|
||
```
|
||
|
||
### **📈 追蹤方式**
|
||
```bash
|
||
# 快速檢查命令
|
||
echo "服務數量: $(find backend/DramaLing.Api/Services -name "*Service.cs" | wc -l)"
|
||
echo "介面數量: $(find backend/DramaLing.Api/Services -name "I*Service.cs" | wc -l)"
|
||
echo "平均文件大小: $(find backend/DramaLing.Api/Services -name "*.cs" -exec wc -l {} + | awk '{sum+=$1; count++} END {print int(sum/count)}')"
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 **實用工具**
|
||
|
||
### **架構決策模板**
|
||
```markdown
|
||
# 新功能架構決策
|
||
|
||
## 功能描述
|
||
簡述要實現的功能
|
||
|
||
## 架構選擇
|
||
- [ ] 使用現有服務
|
||
- [ ] 擴展現有服務
|
||
- [ ] 創建新服務
|
||
|
||
## 服務歸屬
|
||
- [ ] Domain/Learning
|
||
- [ ] Domain/Analysis
|
||
- [ ] Domain/User
|
||
- [ ] Infrastructure/*
|
||
|
||
## 依賴分析
|
||
列出需要依賴的其他服務，確認依賴方向正確
|
||
|
||
## 測試計劃
|
||
描述如何測試新功能
|
||
```
|
||
|
||
### **重構安全清單**
|
||
```markdown
|
||
# 重構前準備
|
||
- [ ] 現有功能有足夠測試覆蓋
|
||
- [ ] 識別所有受影響的代碼
|
||
- [ ] 準備回滾方案
|
||
|
||
# 重構中執行
|
||
- [ ] 小步驟，頻繁提交
|
||
- [ ] 每步都保持測試通過
|
||
- [ ] 保持 API 兼容性
|
||
|
||
# 重構後驗證
|
||
- [ ] 功能完全正常
|
||
- [ ] 性能沒有退化
|
||
- [ ] 文檔已更新
|
||
```
|
||
|
||
---
|
||
|
||
## 🎓 **最佳實踐總結**
|
||
|
||
### **👍 推薦做法**
|
||
1. **先設計介面，後實作**: 確保 API 設計合理
|
||
2. **小服務優於大服務**: 職責單一，更容易維護
|
||
3. **依賴注入**: 所有依賴通過構造函數注入
|
||
4. **異步優先**: 所有 I/O 操作使用 async/await
|
||
5. **日誌記錄**: 關鍵操作要有適當日誌
|
||
|
||
### **👎 避免做法**
|
||
1. **靜態依賴**: 避免 static 類別和方法
|
||
2. **直接數據訪問**: Controller 不直接操作數據庫
|
||
3. **過度抽象**: 不要為了抽象而抽象
|
||
4. **忽略異常**: 不要吞掉異常
|
||
5. **魔法數字**: 避免硬編碼的數值和字串
|
||
|
||
---
|
||
|
||
## 📞 **獲得幫助**
|
||
|
||
### **遇到架構問題時**
|
||
1. **查閱文檔**: 先查看 ARCHITECTURE_GOVERNANCE.md
|
||
2. **檢查現有模式**: 看看類似功能是如何實現的
|
||
3. **架構審查**: 與團隊討論架構決策
|
||
4. **逐步實施**: 不確定時先小範圍實驗
|
||
|
||
### **常見問題 FAQ**
|
||
```
|
||
Q: 我的服務變得很大，該怎麼辦？
|
||
A: 按職責拆分，一個服務只負責一個業務領域
|
||
|
||
Q: 我需要在服務間共享代碼，該怎麼辦？
|
||
A: 考慮建立 Shared 服務或抽取到基類
|
||
|
||
Q: 我的 Controller 邏輯很複雜，該怎麼辦？
|
||
A: 將業務邏輯移到對應的 Domain Service
|
||
|
||
Q: 我需要跨多個服務的操作，該怎麼辦？
|
||
A: 考慮建立協調服務或使用事件驅動模式
|
||
```
|
||
|
||
---
|
||
|
||
**記住**: 好的架構是團隊的共同責任，每個人都要參與維護！ |