資料存取層 (DAL)
優先級:P1 (高)
集中管理所有資料存取(資料庫與外部 API),確保一致的安全性、授權與快取機制。
實作指南
- 架構:在
services/或lib/data.ts檔案中建立一個資料存取層 (DAL)。使用import 'server-only'以防止後端邏輯洩漏至客戶端套件組合。 - DTO:在將原始資料庫/API 資料返回給元件之前,務必將其轉換為資料傳輸物件 (DTO)。這可以防止洩漏敏感欄位(例如
passwordHash)。 - 安全性:使用
experimental_taintAPI 中的taintObjectReference或taintUniqueValue,確保敏感資料絕不會意外傳遞至客戶端元件。 - 授權:將授權檢查置於每個 DAL 函數內部。不要依賴 UI 層來強制執行安全性。使用
await auth()驗證使用者。 - 快取:使用 React 的
cache()包裝 DAL 函數,以在單一渲染週期內對請求進行去重,防止重複的資料庫/API 呼叫。 - 錯誤處理:拋出標準化錯誤(例如
NotFoundError、UnauthorizedError),以便被 Next.jserror.tsx或notFound()捕獲。
限制
- 客戶端元件:無法匯入 DAL 檔案。必須使用 Server Actions 或 Route Handlers 作為橋樑。
反模式
- 不在 DAL 外部進行授權檢查:驗證邏輯必須內建於 DAL 函數中。
- 不返回原始 ORM 實例:返回前須轉換為純 DTO 物件。
- 不在伺服器元件中使用
fetch('localhost/api'):應直接呼叫 DAL 函數。 - 不在客戶端元件中匯入 DAL:應使用 Server Actions 或 Route Handlers 作為橋樑。