NestJS GraphQL 結構
NestJS GraphQL（code-first）應用程式中每個檔案的位置與運作方式。此技能是一份放置與結構指南：它回答了「這個檔案應該放在哪個資料夾？」、「這個檔案負責什麼？」以及「模組如何連接以解析欄位和關聯？」。它涵蓋了基礎結構地圖以及每個檔案的規則，包括模組、服務、解析器（查詢、變異、訂閱和欄位）、輸入和引數、分頁、實體（共用類型的 Mongoose 綱要最佳實踐）、僅限儲存庫的模型注入、模型/映射器、儲存庫、Mongoose 區分器、衍生欄位、提供器、載入器、事件、背景工作、驗證、例外、自訂標量、配置、通用建構區塊、基礎設施設定，以及命名/測試/lint 慣例。
此技能特意與 nestjs-best-practices 技能分開。該技能涵蓋框架行為（依賴注入深度、安全性、效能、錯誤處理、微服務、DevOps）；此技能涵蓋結構和模組組合。當兩者重疊時（功能模組、循環依賴），此技能會從放置的角度進行探討，並交叉參照另一技能以獲得行為深度。
此技能涵蓋結構規則（檔案存放位置）和模組解析規則（模組在執行時期如何連接——例如循環依賴解決）。模組解析規則位於第 2 和第 3 節。
應用時機
在以下情況參考這些指南：
- 決定新檔案應歸屬 NestJS GraphQL 程式碼庫何處時
- 設計或審查功能優先的目錄佈局時
- 建立新功能模組及其檔案時
- 決定如何建模多型文件（Mongoose 區分器）並自動發布其 GraphQL 型別時
- 決定何處可以注入 Mongoose 模型——並將資料庫存取控制在儲存庫之後時
- 決定某個值應存入資料庫還是在讀取時衍生時
- 找出模組如何解析位於另一個模組中的欄位或關聯時
- 解決模組之間的連接問題時（循環依賴、缺少匯出）
按優先順序排列的規則類別
| 優先級 | 類別 | 影響 | 前綴 |
|---|---|---|---|
| 1 | 應用程式結構 | 關鍵 | struct- |
| 2 | 模組與啟動 | 關鍵 | module- |
| 3 | 關聯與跨模組 | 關鍵 | relations- |
| 4 | 服務 | 高 | service- |
| 5 | GraphQL 解析器 | 高 | resolver- |
| 6 | GraphQL 型別與輸入 | 高 | type- |
| 7 | 資料存取 | 中高 | data- |
| 8 | 配置、通用與基礎設施 | 中 | infra- |
| 9 | 慣例與測試 | 中 | conventions- |
快速參考
1. 應用程式結構（關鍵）
struct-auth-feature- 將驗證保留在專屬功能模組中struct-canonical-layout- 標準應用程式結構struct-feature-decomposition- 功能成長時將其拆分為子模組struct-file-placement-table- 檔案放置表struct-module-kinds- 區分領域功能與應用層級模組struct-schema-artifact- 定位並制定產生的綱要成品政策
2. 模組與啟動（關鍵）
module-bootstrap- 保持 main.ts 與 app.module.ts 精簡module-export-policy- 僅匯出功能的公開 API（其服務）module-feature-module- 功能模組檔案
3. 關聯與跨模組（關鍵）
relations-avoid-circular- 解決循環模組依賴relations-dataloader- 使用每個請求的 DataLoader 批量處理關聯relations-events- 使用事件解耦模組relations-field-resolvers- 使用 @ResolveField 解析關聯relations-owning-module- 將關聯欄位放在擁有其資料的模組中
4. 服務（高）
service-background-jobs- 將佇列處理器與排程任務保留在功能中service-external-providers- 將第三方客戶端保留在 providers/ 中service-interfaces-tokens- 在 interfaces/ 中宣告服務合約與注入令牌service-single-responsibility- 每個模組可有多個專注的服務service-small-focused-methods- 保持服務方法小而專注
5. GraphQL 解析器（高）
resolver-computed-fields- 在型別上宣告欄位；在解析器中解析計算出的欄位resolver-organization- 按角色將解析器拆分至 resolvers/ 中resolver-per-type- 每個具有欄位解析器的型別一個解析器檔案resolver-subscriptions- 將訂閱解析器放在 resolvers/ 中，並將 PubSub 放在 infra/ 中
6. GraphQL 型別與輸入（高）
type-args- 在 dto/ 中定義 @Args 類別type-inputs- 在 dto/ 中定義 GraphQL 輸入type-pagination- 使用共用分頁型別分頁列表查詢type-polymorphic-discriminators- 將區分文件發布為介面或聯合類型type-unions-interfaces- 將聯合類型和介面類型放在模組的型別中
7. 資料存取（中高）
data-derived-fields- 計算衍生欄位；不要儲存它們data-discriminators- 使用區分器建模多型子類型data-entity-mongodb- 將 MongoDB 實體放在 entities/ 中data-model-injection- 僅在儲存庫中注入模型data-models-mappers- 當 API 與儲存不同時，拆分 models/ 和 mappers/data-mongoose-schema- 共用類型的 Mongoose 綱要最佳實踐data-repository- 將資料存取保留在 repositories/ 中
8. 配置、通用與基礎設施（中）
infra-common-types- 將共用類型放在 common/types/ 中infra-common- 將共用建構區塊放在 common/ 中infra-config- 將類型化配置放在 config/ 中infra-custom-scalars- 在 common/scalars/ 中實作自訂標量infra-database- 將資料庫設定與遷移放在 infra/database/ 中infra-directives- 將綱要指令放在 common/directives/ 中infra-exceptions- 將例外放在 exceptions/ 中infra-graphql- 將 GraphQL 設定放在 infra/graphql/ 中infra-seeds- 將種子腳本放在 infra/database/seeds/ 中infra-shared-module- 使用 SharedModule 處理橫切關注的服務
9. 慣例與測試（中）
conventions-barrels-aliases- 審慎使用匯出桶與路徑別名conventions-cli-generator- 使用 Nest CLI 生成器，然後調整conventions-constants-enums- 將常數與列舉保留在類別檔案之外conventions-module-boundaries- 使用 lint 強制執行模組邊界conventions-naming- 檔案與類別命名慣例conventions-test-fixtures- 將測試夾具、工廠與輔助程式放在 test/ 中conventions-testing- 測試檔案放置
如何使用
從基礎結構規則開始，然後閱讀您正在處理的特定檔案類型的規則。規則檔案位於 rules/ 下：
rules/struct-canonical-layout.md
rules/_sections.md
每個規則檔案包含：
- 目的與放置（檔案存放位置及其命名方式）
- 職責與反職責
- 一個錯誤範例及其說明
- 一個正確範例及其說明
完整編譯文件
如需所有規則展開在單一文件中的完整指南，請參閱 AGENTS.md。