Zoha/agent-skills

NestJS GraphQL 구조

NestJS GraphQL(코드 우선) 애플리케이션에서 모든 파일이 속할 위치와 각 파일이 작동하는 방식입니다. 이 기술은 배치 및 구조 가이드입니다. "이 파일은 어느 폴더에 들어가나요?", "이 파일의 책임은 무엇인가요?", "모듈이 어떻게 연결되어 필드와 관계를 해석하나요?"에 대한 답을 제공합니다. 기본 구조 맵과 더불어 모듈, 서비스, 리졸버(쿼리, 뮤테이션, 서브스크립션, 필드), 입력 및 인자, 페이지네이션, 엔티티(공유 타입을 위한 Mongoose 스키마 모범 사례), 리포지토리 전용 모델 주입, 모델/매퍼, 리포지토리, Mongoose 판별자, 파생 필드, 프로바이더, 로더, 이벤트, 백그라운드 작업, 인증, 예외, 사용자 정의 스칼라, 설정, 공통 빌딩 블록, 인프라 설정, 그리고 명명/테스트/린트 규칙을 다룹니다.

이 기술은 의도적으로 nestjs-best-practices 기술과 분리되어 있습니다. 해당 기술은 프레임워크 동작(의존성 주입 깊이, 보안, 성능, 오류 처리, 마이크로서비스, DevOps)을 다루고, 이 기술은 구조와 모듈 구성을 다룹니다. 중복되는 부분(기능 모듈, 순환 의존성)에 대해서는 이 기술이 배치 관점에서 바라보고 동작적 깊이는 다른 기술을 참조합니다.

이 기술은 구조 규칙(파일이 어디에 위치하는지)과 모듈 해결 규칙(모듈이 런타임에 어떻게 연결되는지 — 예: 순환 의존성 해결)을 모두 다룹니다. 모듈 해결 규칙은 2장과 3장에 있습니다.

적용 시점

다음과 같은 경우 이 지침을 참조하세요:

• NestJS GraphQL 코드베이스에서 새 파일이 어디에 속할지 결정할 때
• 기능 우선 디렉터리 레이아웃을 설계하거나 검토할 때
• 새 기능 모듈과 그 파일들을 스캐폴딩할 때
• 다형성 문서(Mongoose 판별자)를 모델링하고 GraphQL 타입을 자동으로 게시하는 방법을 결정할 때
• Mongoose 모델이 주입될 수 있는 위치와 데이터베이스 접근을 리포지토리 뒤에 유지해야 하는지 결정할 때
• 값이 데이터베이스에 저장되어야 하는지, 아니면 읽을 때 파생되어야 하는지 결정할 때
• 모듈이 다른 모듈에 있는 필드나 관계를 해결하는 방법을 알아낼 때
• 모듈 간 연결 문제(순환 의존성, 누락된 내보내기)를 해결할 때

우선 순위별 규칙 범주

우선 순위	범주	영향	접두사
1	애플리케이션 구조	치명적(CRITICAL)	struct-
2	모듈 및 부트스트랩	치명적(CRITICAL)	module-
3	관계 및 교차 모듈	치명적(CRITICAL)	relations-
4	서비스	높음(HIGH)	service-
5	GraphQL 리졸버	높음(HIGH)	resolver-
6	GraphQL 타입 및 입력	높음(HIGH)	type-
7	데이터 접근	중간-높음(MEDIUM-HIGH)	data-
8	설정, 공통 및 인프라	중간(MEDIUM)	infra-
9	규칙 및 테스트	중간(MEDIUM)	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 - @Args 클래스를 dto/에 정의하기
• type-inputs - GraphQL 입력을 dto/에 정의하기
• 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 - 린트로 모듈 경계 강제하기
• conventions-naming - 파일 및 클래스 명명 규칙
• conventions-test-fixtures - 테스트 픽스처, 팩토리, 헬퍼를 test/에 배치하기
• conventions-testing - 테스트 파일 배치

사용 방법

기본 구조 규칙으로 시작한 다음, 작업 중인 특정 파일 종류에 대한 규칙을 읽으세요. 규칙 파일은 rules/ 디렉터리에 있습니다:

rules/struct-canonical-layout.md
rules/_sections.md

각 규칙 파일에는 다음이 포함됩니다:

• 목적 및 배치(파일이 위치하는 곳과 이름 지정 방법)
• 책임 및 책임이 아닌 것
• 설명이 포함된 잘못된 예시
• 설명이 포함된 올바른 예시

전체 컴파일된 문서

모든 규칙이 하나의 문서로 확장된 완전한 가이드를 보려면 AGENTS.md를 참조하세요.