Community程式設計與開發github.com

模組化後端

編寫程式技能。使用 Fastify、AppBuilder、Helmet、本地化錯誤、Redis 儲存、速率限制和游標分頁來建置、擴充、重構或修復模組化的 NestJS 和 Node.js 後端。對新的後端和現有系統套用高效的查詢、JWT 和設備驗證、請求防護、排程工作、Docker 和 CI/CD。

模組化後端 是什麼?

此技能旨在協助開發者與 AI 代理建置、擴充、重構或修復模組化的 NestJS 與 Node.js 後端。它強制採用一套全面的慣例與架構規則,以確保程式碼庫的一致性、可維護性與高品質。此技能支援多種平台,包括 Claude Code、Cursor 和 GitHub Copilot,特別適用於 Fastify、AppBuilder、Helmet 和 Redis 等技術棧。其核心功能涵蓋強制要求使用 AppBuilder 與 Helmet 的 HTTP 基礎建設、透過全域過濾器進行本地化錯誤處理、以 Redis 作為主要資料來源(不僅是快取)、共享的速率限制、基於游標的分頁、JWT 與設備驗證,以及完整的 Docker 與 CI/CD 工作流程。此技能透過「SKILL.md」檔案引導使用者建立新的後端(從基礎建設到已連接的功能),或僅對現有系統的特定路徑進行精確的、有範圍的修訂。它優先考慮最小化、可讀的變更、避免投機的抽象化,並要求進行驗收測試以驗證核心基礎元件是否正常運作。

相容平台~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/yigitcicekci/modular-backend/tree/HEAD

Installed? Explore more 程式設計與開發 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

模組化後端 是做什麼的?

以最小且可讀的變更來完成請求的行為。將這些慣例套用至新的後端以及現有專案中受影響的程式碼。不要將一個有範圍的修復變成整個專案的遷移。

載入相關參考資料

任務閱讀資料
新模組、結構重構、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,使用明確的 Nest FastifyAdapter 或直接使用 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 失效。為請求的轉換規劃相容性和資料/金鑰遷移。
  • 產生必要的遷移;不要刪除線上資料或意外地執行生產遷移。

架構規則

  1. 對 src/modules/ 下的每個功能使用完整佈局。 每個功能模組包含 dto/、一個控制器、一個服務、一個儲存庫和 <feature>.module.ts。在模組根目錄保留一個控制器、服務或儲存庫。當一個層有多個檔案時,將它們分組到 controllers/、services/ 或 repositories/ 中。必要時為模組特定的錯誤使用 errors/。當支援提供者沒有功能 API 或資料存取時,將它們放在基礎建設下,或當工作者沒有功能 API 或資料存取時,將它們放在工作者下。在範圍內的修訂中,保留現有的路徑,除非模組佈局變更是任務的一部分。
  2. 控制器處理 HTTP;服務做決策;儲存庫存取資料。 控制器中沒有業務邏輯、ORM 查詢或 Redis 指令。服務擁有規則和編排。儲存庫擁有查詢和 Redis 操作,包括強制執行原子不變量的條件式寫入。
  3. 務實地組合。 跨模組的業務動作呼叫所屬的服務。允許直接使用匯出的儲存庫進行純資料工作或共享事務。不要為了表面功夫而建立傳遞服務方法。
  4. 保持事務所有權靠近工作。 服務可以使用一個傳遞的事務用戶端跨越多個儲存庫;儲存庫可以擁有一個自包含的原子操作。每個參與者都使用該用戶端。沒有通用的事務工作單元或事務框架。
  5. 撰寫精簡、可讀的程式碼。 重複使用輔助工具、標準 API 和已安裝的依賴。避免投機的選項、包裝器、基底類別、通用儲存庫和一次性抽象。移除冗餘的驗證和捕捉後重新拋出;保留邊界驗證、授權、並發和防止資料遺失的保護。
  6. 減少實際工作量。 最小化查詢、往返次數、欄位、行數和中間的分配。平行的逐項查詢仍然是 N+1。為工作負載平衡時間和空間;不要承諾兩者都達到絕對最小值,或為了速度而削弱密碼雜湊。
  7. 證明索引的合理性。 將每個索引連結到一個真實的查詢或完整性約束。在新增更多索引之前,檢查主鍵/唯一鍵/複合索引。不要新增投機的重複項,或僅基於 schema 外觀就移除索引。
  8. 為 Redis 指派一個角色。 區分主要資料、準備好的讀取模型和可拋棄的快取。定義所有權、填充/更新、TTL、遺失、停機和復原。沒有自動回退到資料庫。快取遺失和連線失敗是分開的;從資料參考中選擇策略。
  9. 只共享共享的程式碼。 通用輔助工具屬於 utils/common,基礎建設屬於 libs,共享設定屬於 config。保留僅限模組的輔助工具在本地。集中管理 Redis 金鑰和 TTL。
  10. 擁有和型別化錯誤。 在模組的 errors/ 目錄下定義領域錯誤。透過 AppException 拋出註冊的 ErrorCode,並在 HTTP 邊界翻譯其 messageKey。將內部的查詢、堆疊追蹤、秘密和提供者詳細資訊排除在回應之外。

完成並驗證

更新必要的呼叫者、DTO、錯誤定義、提供者/匯出、設定、schema/遷移和測試。同時實作重要的失敗情況和成功情況。

對於基礎建設工作,遵循驗收檢查。追蹤生產進入點通過建構器和一個真實的功能通過其 Redis 儲存庫。驗證 Helmet、本地化 HTTP 錯誤合約、Redis 初始化和關閉,以及遺失與停機。在真實的限制路由上驗證 429 和 503,並在每個新的列表合約上測試穩定的分頁。報告任何缺失或未驗證的基礎項目。

新的非平凡邏輯需要一個小的行為測試或基於斷言的檢查。驗證受影響的不變量:所有權、查詢計數、回滾、令牌過期/重複使用/並發、Redis 遺失與停機,或原子更新。瑣碎的移動不需要實作鏡像測試。

相關技能