模組化後端 是做什麼的?
以最小且可讀的變更來完成請求的行為。將這些慣例套用至新的後端以及現有專案中受影響的程式碼。不要將一個有範圍的修復變成整個專案的遷移。
載入相關參考資料
| 任務 | 閱讀資料 |
|---|---|
| 新模組、結構重構、DTO、依賴注入 | 架構 |
| 錯誤合約、驗證失敗、全域過濾器、i18n | 錯誤與 i18n |
| 查詢、索引、事務、Redis、快取/儲存行為 | 資料與 Redis |
| 使用者、驗證套件、session、OAuth、設備、指紋、密碼/IP 雜湊 | 身份 |
| Header 與 JWT 守衛、中介軟體、路由與參數裝飾器 | 請求邊界 |
| 啟動、設定、速率限制、日誌、健康檢查、驗證 | 操作 |
| 佇列、工作者、排程、Webhook 冪等性、資源限制 | 背景工作 |
| Dockerfile、本地 Compose、啟動/停止 Bash 腳本、API/工作者指令 | Docker |
| CI 檢查、容器、遷移、發佈、回滾 | CI/CD |
對於新的後端、基礎架構全面翻新,或修復缺失的基礎元件,請在編輯前先閱讀架構、操作、錯誤與 i18n、請求邊界、Docker 和資料與 Redis。根據任務需求閱讀其他參考資料。根據已安裝的版本和實際領域調整範例。使用可攜式 Markdown 和標準專案工具。遵循主機代理的權限模型。
在編輯前確定範圍
閱讀儲存庫說明、套件清單、啟動程式、受影響的模組與呼叫者、相關 schema、Redis 使用情況和測試。使用設定定義和範例變數名稱進行探索。
新後端。 直接套用基礎建設與架構規則。實作已連接的基礎,並針對請求的產品流程使用相關參考資料。詢問會影響行為或資料所有權的缺失產品決策。此技能已設定基礎的工程選擇。
現有後端。 從唯讀的架構評估開始。呈現目前的架構、提議的目標,以及哪些元件要保留、變更、新增或延後。**「根據 modular-backend 修訂此後端」**涵蓋整個後端。當請求指定了標準但未選擇特定變更時,用一個簡潔的問題詢問要套用哪些提議,並等待決定。如果使用者已明確要求特定變更,請先分析並分享相關的架構,然後進行該變更,並在承擔進一步的架構變更前先詢問。僅限分析的請求以評估結果結束。在使用者選擇範圍後,實作它並執行適用的驗收檢查。
對於命名功能、端點或錯誤的請求,將評估限制在該路徑及其受影響的呼叫者。使用最接近的、遵循這些規則的現有模組作為命名、檔案放置、DTO、錯誤和事務風格的模型。
新後端、基礎架構全面翻新或基礎修復
- HTTP 必須使用 AppBuilder 和 Helmet。 保持
src/main.ts精簡,並將 HTTP 建構放在src/builder/app.builder.ts中。對於沒有 Nest 的 Node.js HTTP,使用明確的 NestFastifyAdapter或直接使用fastify。在初始化或監聽之前註冊相容的@fastify/helmet。在 HTTP 整合測試中綁定真實的建構器。沒有 HTTP 的工作者使用它們自己的進入點。 - 在一個全域過濾器或 Fastify 處理程式中本地化 HTTP 錯誤。 使用模組錯誤定義,包含
code、status和messageKey、一個型別註冊表,和一個共享的異常。為新的 HTTP 合約回傳{ status, code, message }。status符合 HTTP 狀態碼,code跨語言保持穩定,message來自 i18n。對於現有的 API,在達成相容的遷移協議前,保留已發布的欄位。 - 需要 Redis 基礎建設和一個真實的 Redis 資料路徑。 新增經過驗證的連線設定、集中管理的 Redis 金鑰和 TTL 檔案、一個共享的 Redis 提供者,以及一個就緒探針。為 Redis 指派至少一個有用的資料家族,且該家族以 Redis 為唯一真實來源。透過領域儲存庫實作其實際的讀取和寫入。僅有連線、健康檢查探針或 SQL 回應快取並不能滿足此規則。使用合適的現有產品流程,例如已發布的客戶端設定、即時排名/狀態或共享的限流。在產品有客戶端設定或版本策略的地方,從 Redis 儲存和提供其已發布的文件。如果從範圍內無法選擇合法的資料家族,請找出缺失的產品決策。
- 從共享模板生成 Redis 金鑰。 將
[placeholder]模板保留在redis-keys.config.ts中,TTL 保留在redis-ttl.config.ts中,generateRedisKey/generateRedisKeys保留在src/utils/redis-key.util.ts中。讓共享的提供者套用一次設定的命名空間。在實際的讀取器、寫入器和工作中使用此路徑。除非使用者選擇了計劃中的遷移,否則在修訂期間保留現有的金鑰格式。請參閱 Redis 金鑰範例。 - Redis 擁有和準備好的讀取應留在 Redis 上。 為每個金鑰家族設定填充、更新、遺失金鑰、過期、停機和復原行為。對於真正遺失的實體使用型別化的缺失,對於停機或尚未準備好的必要投影使用型別化的不可用。請求絕不回退查詢 SQL 來扮演這些角色。僅對已同意的可拋棄快取使用明確的 cache-aside 例外。在不相關的修訂中保留現有的讀取合約。
- 為 HTTP 連接共享速率限制。 註冊強制執行守衛或鉤子,並為外部路由設定一個預設的預算。為存在的驗證、復原和昂貴的動作新增更嚴格的 Redis 支援的預算。對密碼登入使用分開的 IP 和標準化帳戶計數器。原子性地遞增和過期,以 429 和
Retry-After回應,並在必要的強制執行不可用時回傳型別化的 503。對系統路由豁免使用明確的策略。 - 對 HTTP 公開的每個會增長的集合進行分頁。 使用經過驗證的查詢 DTO、有界的限制,以及一個包含每個排序值和唯一斷開器的穩定游標鍵。在儲存庫中使用呼叫者的範圍和過濾器查詢
limit + 1。為新的列表回傳{ items, nextCursor }。僅在 API 合約需要時才計算精確總數並使用頁碼偏移。 - 連接 API 使用的守衛和裝飾器。 對行動/設備合約使用型別化的 header 守衛,對受保護的 JWT 路由使用 JWT 守衛,以及在策略需要時使用角色、訪客或特定提供者的守衛。註冊這些守衛並使用參數裝飾器消費其驗證過的上下文。對跨領域的傳輸關注點使用 Fastify 請求鉤子或現有的中介軟體。
- 提供可運行的 Docker 工作流程。 提供或重複使用 Dockerfile、用於本地依賴的 Compose,以及專案範圍的 Bash 啟動/停止指令。等待就緒並對權威資料使用持久化卷。在修訂時保留同等的既有工作流程。僅在工作負載需要時才執行工作排程和消費者。
- 只實作必要的模組/功能。驗證/使用者/設備工作流程是可重複使用的指導,不是允許向不需要它的服務添加帳戶功能的許可。
- 優先使用 Node.js 內建模組和官方的 NestJS 模組。已批准的基準包括相容的
@fastify/helmet、單一 Redis 用戶端,以及如果未安裝合適的 i18n 整合時,用於 Nest HTTP 錯誤的nestjs-i18n。新的密碼驗證流程可以使用相容的argon2進行 Argon2id;使用node:crypto進行令牌摘要和鍵控指紋。保留現有的運作中 Redis 用戶端,或對新專案預設使用redis。在匯入處直接使用fastify。其他新的第三方套件、可選的對等依賴和 Fastify 外掛需要明確的批准。請參閱操作。 - 交付已連接的啟動程式、驗證過的設定、提供者、必要的遷移、本地設定和請求的 API。不要在未連接的 scaffold 檔案處停止。
現有後端 / 修訂
- 在變更共享函數或移動檔案前,找到所有呼叫者:服務、控制器、工作、守衛、匯出、模擬、測試固件和回應消費者。
- 保留不相關的變更、公開合約、令牌/儲存行為、驗證、所有權過濾器和既定的命名。將清理限制在任務的路徑內。
- 當任務設定、替換或修復 HTTP 基礎建設時,一起將 Fastify、AppBuilder 和 Helmet 納入範圍。在不相關的功能變更期間保留配接器和啟動程式。當遷移到 Fastify 時,驗證狀態碼、中介軟體、cookies、上傳和簽署的 webhook 主體(若相關)。
- 當變更相關服務時,將查詢提取到具體的儲存庫。保留事務上下文、鎖定、錯誤處理、回傳形狀、軟刪除和租戶範圍。
- 當變更列表或限制器時,保留現有的公開游標和回應合約,並在範圍內加強驗證。將速率限制中繼資料追蹤到運作中的守衛或鉤子。在資料查詢中保留參與者和租戶範圍。明確規劃不相容的游標或限制器金鑰變更。
- 對於基礎建設設定或重構,套用相同的套件策略。除非任務變更它們,否則保留現有的整合。在新增套件前,解析請求的基礎建設所需的依賴。
- 不要默默地移除回退、切換 session 儲存、變更令牌生命週期或作為清理而使所有 session 失效。為請求的轉換規劃相容性和資料/金鑰遷移。
- 產生必要的遷移;不要刪除線上資料或意外地執行生產遷移。
架構規則
- 對
src/modules/下的每個功能使用完整佈局。 每個功能模組包含dto/、一個控制器、一個服務、一個儲存庫和<feature>.module.ts。在模組根目錄保留一個控制器、服務或儲存庫。當一個層有多個檔案時,將它們分組到controllers/、services/或repositories/中。必要時為模組特定的錯誤使用errors/。當支援提供者沒有功能 API 或資料存取時,將它們放在基礎建設下,或當工作者沒有功能 API 或資料存取時,將它們放在工作者下。在範圍內的修訂中,保留現有的路徑,除非模組佈局變更是任務的一部分。 - 控制器處理 HTTP;服務做決策;儲存庫存取資料。 控制器中沒有業務邏輯、ORM 查詢或 Redis 指令。服務擁有規則和編排。儲存庫擁有查詢和 Redis 操作,包括強制執行原子不變量的條件式寫入。
- 務實地組合。 跨模組的業務動作呼叫所屬的服務。允許直接使用匯出的儲存庫進行純資料工作或共享事務。不要為了表面功夫而建立傳遞服務方法。
- 保持事務所有權靠近工作。 服務可以使用一個傳遞的事務用戶端跨越多個儲存庫;儲存庫可以擁有一個自包含的原子操作。每個參與者都使用該用戶端。沒有通用的事務工作單元或事務框架。
- 撰寫精簡、可讀的程式碼。 重複使用輔助工具、標準 API 和已安裝的依賴。避免投機的選項、包裝器、基底類別、通用儲存庫和一次性抽象。移除冗餘的驗證和捕捉後重新拋出;保留邊界驗證、授權、並發和防止資料遺失的保護。
- 減少實際工作量。 最小化查詢、往返次數、欄位、行數和中間的分配。平行的逐項查詢仍然是 N+1。為工作負載平衡時間和空間;不要承諾兩者都達到絕對最小值,或為了速度而削弱密碼雜湊。
- 證明索引的合理性。 將每個索引連結到一個真實的查詢或完整性約束。在新增更多索引之前,檢查主鍵/唯一鍵/複合索引。不要新增投機的重複項,或僅基於 schema 外觀就移除索引。
- 為 Redis 指派一個角色。 區分主要資料、準備好的讀取模型和可拋棄的快取。定義所有權、填充/更新、TTL、遺失、停機和復原。沒有自動回退到資料庫。快取遺失和連線失敗是分開的;從資料參考中選擇策略。
- 只共享共享的程式碼。 通用輔助工具屬於 utils/common,基礎建設屬於 libs,共享設定屬於 config。保留僅限模組的輔助工具在本地。集中管理 Redis 金鑰和 TTL。
- 擁有和型別化錯誤。 在模組的
errors/目錄下定義領域錯誤。透過AppException拋出註冊的ErrorCode,並在 HTTP 邊界翻譯其messageKey。將內部的查詢、堆疊追蹤、秘密和提供者詳細資訊排除在回應之外。
完成並驗證
更新必要的呼叫者、DTO、錯誤定義、提供者/匯出、設定、schema/遷移和測試。同時實作重要的失敗情況和成功情況。
對於基礎建設工作,遵循驗收檢查。追蹤生產進入點通過建構器和一個真實的功能通過其 Redis 儲存庫。驗證 Helmet、本地化 HTTP 錯誤合約、Redis 初始化和關閉,以及遺失與停機。在真實的限制路由上驗證 429 和 503,並在每個新的列表合約上測試穩定的分頁。報告任何缺失或未驗證的基礎項目。
新的非平凡邏輯需要一個小的行為測試或基於斷言的檢查。驗證受影響的不變量:所有權、查詢計數、回滾、令牌過期/重複使用/並發、Redis 遺失與停機,或原子更新。瑣碎的移動不需要實作鏡像測試。