TypeScript Development

本說明假設專案以 TypeScript 5.x（或更新版本）建置，並編譯為以 ES2022 為基準的 JavaScript。若執行環境需要更舊的語言目標或降級轉譯，請相應調整下列指引。

核心宗旨

尊重現有架構與程式碼規範。
偏好可讀且明確的解法，而非巧妙但難以理解的捷徑。
在發明新抽象之前，先擴充現有抽象。
優先考量可維護性與清晰度，保持方法與類別簡短，維持乾淨的程式碼。

一般守則

目標為 TypeScript 5.x / ES2022，優先使用原生功能而非 polyfill。
使用純 ES 模組；不要輸出 require、module.exports 或 CommonJS 協助程式。
儘量依賴專案現有的建置、lint 與測試腳本，除非另有指示。
當設計意圖不明顯時，註明設計上的權衡取捨。

專案組織

新增程式碼時遵循儲存庫既有的資料夾與責任分工。
使用 kebab-case 檔名（例如 user-session.ts、data-service.ts），除非另有指示。
當有助於尋找時，將測試、型別與輔助工具放置於實作附近。
在新增工具前，先重用或擴充共用工具。

命名與風格

對於類別、介面、列舉與型別別名使用 PascalCase；其他使用 camelCase。
不要使用 I 這類介面前綴；以具描述性的名稱為主。
以行為或領域意義命名，而非實作細節。

格式化與風格

在提交前執行專案的 lint/format 腳本（例如 npm run lint）。
遵循專案的縮排、引號風格與結尾逗號規則。
讓函式專注於單一職責；當邏輯分支變多時抽出輔助函式。
實務上優先使用不可變資料與純函式。

型別系統期待

避免使用 any（隱含或明確）；偏好使用 unknown 並搭配窄化處理。
對即時事件與狀態機使用區分式聯合型別（discriminated unions）。
集中管理共用契約，避免重複定義型別結構。
使用 TypeScript 的工具型別來表達意圖（例如 Readonly、Partial、Record）。

非同步、事件與錯誤處理

使用 async/await；對 await 包裝 try/catch，並使用結構化錯誤。
盡早處理邊界情況以避免過深的巢狀結構。
使用專案的日誌/遙測工具來傳送錯誤資訊。
以專案既有的通知模式顯示用戶可見的錯誤。
對受設定驅動的更新使用 debounce，並以確定性方式釋放資源。

架構與模式

遵循儲存庫既有的依賴注入或組合模式；保持模組單一職責。
在接入生命週期時，遵循現有的初始化與釋放順序。
維持傳輸層、領域層與展示層的解耦，並以清晰的介面界定。
新增服務時提供生命週期掛鉤（例如 initialize、dispose）並加入針對性的測試。

外部整合

在熱路徑之外實例化客戶端，並以注入方式提升可測試性。
切勿把秘密（secrets）硬編碼；從安全來源載入。
對網路或 I/O 呼叫加入重試、退避與取消機制。
將外部回應正規化，並將錯誤對映為領域型別。

安全實務

使用 schema 驗證器或型別守衛來驗證與清理外部輸入。
避免動態程式碼執行與渲染不受信任的模板。
在渲染 HTML 前對不受信任的內容進行編碼；使用框架提供的逃脫機制或 trusted types。
使用參數化查詢或 prepared statements 來阻擋注入攻擊。
將秘密儲存在安全儲存中、定期輪替，並申請最小必要權限。
對敏感資料偏好不可變流程與防禦性複製。
只使用經過審核的加密函式庫。
及時修補相依套件並監控安全公告。

設定與密鑰管理

透過共用的 helper 取得設定，並以 schema 或專用驗證器進行驗證。
使用專案的安全儲存來處理秘密；對 undefined 與錯誤狀態加以防護。
記錄新的設定鍵並更新相關測試。

使用者介面與體驗元件

在渲染前清理使用者或外部內容。
保持 UI 層精簡；將繁重邏輯移至服務或狀態管理器。
使用訊息或事件來解耦 UI 與業務邏輯。

測試期待

使用專案的測試框架與命名風格新增或更新單元測試。
當行為跨越多個模組或平台 API 時，擴充整合測試或端對端測試。
在提交前執行針對性的測試腳本以獲得快速回饋。
避免脆弱的時間斷言；偏好使用假時鐘或注入時鐘。

效能與可靠性

對重量級相依延遲載入，使用完畢後釋放。
將昂貴工作延後到使用者需要時再執行。
對高頻事件進行批次處理或 debounce 以降低頻繁操作影響。
追蹤資源生命週期以防洩漏。

文件與註解

在公開 API 加入 JSDoc；在有幫助時包含 @remarks 或 @example。
撰寫能傳達意圖的註解，並在重構時移除已過時的註記。
在引入重要模式時更新架構或設計文件。