software-architecture

軟體架構開發技能

此技能提供專注於高品質的軟體開發與架構指南。它基於 Clean Architecture 與領域驅動設計原則。

程式碼風格規則

一般原則

• 提前回傳模式：盡可能使用提前回傳，而非巢狀條件，以提升可讀性
• 透過建立可重複使用的函式與模組，避免程式碼重複
• 將過長（超過 80 行程式碼）的元件與函式拆解為多個較小的元件與函式。如果無法在其他地方使用，則保留在同一檔案中。但如果檔案超過 200 行程式碼，則應拆分為多個檔案。
• 盡可能使用箭頭函式而非函式宣告

最佳實務

函式庫優先方法

• 在撰寫自訂程式碼前，務必先搜尋現有解決方案
  • 檢查 npm 上是否有現有函式庫能解決問題
  • 評估現有的服務/SaaS 解決方案
  • 考慮使用第三方 API 處理常見功能
• 使用函式庫而非自行撰寫工具或輔助程式。例如，使用 cockatiel 而非自行撰寫重試邏輯。
• 當自訂程式碼確實合理時：
  • 領域特有的特定商業邏輯
  • 有特殊需求的效能關鍵路徑
  • 當外部依賴會過度設計時
  • 需要完全掌控的安全性敏感程式碼
  • 當現有解決方案在徹底評估後仍不符合需求時

架構與設計

• Clean Architecture 與 DDD 原則：
  • 遵循領域驅動設計與通用語言
  • 將領域實體與基礎設施關注點分離
  • 保持商業邏輯獨立於框架
  • 清楚定義使用案例並保持隔離
• 命名慣例：
  • 避免通用名稱：utils、helpers、common、shared
  • 使用領域特定名稱：OrderCalculator、UserAuthenticator、InvoiceGenerator
  • 遵循限界上下文命名模式
  • 每個模組應有單一且明確的目的
• 關注點分離：
  • 不要將商業邏輯與 UI 元件混合
  • 將資料庫查詢保留在控制器之外
  • 維持上下文之間的明確邊界
  • 確保責任的適當分離

應避免的反模式

• 非我發明症候群：
  • 當 Auth0/Supabase 存在時，不要自行建立認證
  • 不要自行撰寫狀態管理，而應使用 Redux/Zustand
  • 不要自行建立表單驗證，而應使用成熟的函式庫
• 不良的架構選擇：
  • 將商業邏輯與 UI 元件混合
  • 在控制器中直接進行資料庫查詢
  • 缺乏明確的關注點分離
• 通用命名反模式：
  • utils.js 包含 50 個不相關的函式
  • helpers/misc.js 作為垃圾場
  • common/shared.js 目的不明確
• 切記：每一行自訂程式碼都是一項需要維護、測試與文件化的負債

程式碼品質

• 使用型別化的 catch 區塊進行適當的錯誤處理
• 將複雜邏輯拆解為較小、可重複使用的函式
• 避免深層巢狀（最多 3 層）
• 盡可能保持函式專注且少於 50 行
• 盡可能保持檔案專注且少於 200 行程式碼

使用時機

此技能適用於執行概述中所述的工作流程或動作。

限制

• 僅在任務明確符合上述範圍時使用此技能。
• 請勿將輸出視為環境特定驗證、測試或專家審查的替代品。
• 如果缺少必要的輸入、權限、安全邊界或成功標準，請停止並要求澄清。