모듈 규칙
모듈 규칙
model.document.ts
document 파일은 모듈의 데이터베이스 작업을 정의합니다. 문서 스키마 구조(Input, Object, Light, Model)에 대한 개요는 Module Overview를 참조하세요.
이 페이지는 Document 계층에서 사용할 수 있는 상세 API 메서드와 속성에 중점을 둡니다.
Filter 정의 - from()
Filter 클래스는 재사용 가능한 쿼리 패턴을 정의합니다. 각 쿼리는 자동 생성된 메서드 세트(list, find, count, insight 등)가 됩니다.
product.document.ts
⚡기본 제공 Query & Sort
모든 Filter에 자동으로 포함됩니다:
Using Built-in Methods
필터 빌더 메서드 이해하기:
| method | 설명 | 예제 |
|---|---|---|
| .arg(name, Type, options?) | 필수 파라미터. 관리자 패널의 UI 렌더링을 위한 { ref, renderOption } 옵션 포함. | |
| .opt(name, Type, options?) | 선택적 파라미터. 제공되지 않으면 undefined. 쿼리에서 조건부 스프레드 사용. | |
| .query((...args) => MongoQuery) | MongoDB 쿼리 객체를 반환합니다. 인수는 .arg()와 .opt() 호출 순서와 일치합니다. | |
.arg(name, Type, options?)
필수 파라미터. 관리자 패널의 UI 렌더링을 위한 { ref, renderOption } 옵션 포함.
.opt(name, Type, options?)
선택적 파라미터. 제공되지 않으면 undefined. 쿼리에서 조건부 스프레드 사용.
.query((...args) => MongoQuery)
MongoDB 쿼리 객체를 반환합니다. 인수는 .arg()와 .opt() 호출 순서와 일치합니다.
필터에서 자동 생성되는 메서드:
Auto-generated Query Methods
Document 클래스 - by()
Document 클래스는 개별 문서에서 작동하는 인스턴스 메서드를 정의합니다. 메서드는 'this'를 수정하고 메서드 체이닝을 위해 'this'를 반환해야 합니다.
product.document.ts
내장된 문서 메서드:
| method | 설명 | 예제 |
|---|---|---|
| this.set(data) | 여러 필드를 한 번에 설정. Object.assign(this, data)와 동일 | |
| await this.save() | 변경사항을 MongoDB에 저장. 저장된 문서를 반환. | |
| await this.refresh() | 데이터베이스에서 문서를 다시 로드하고 로컬 변경사항을 삭제. | |
this.set(data)
여러 필드를 한 번에 설정. Object.assign(this, data)와 동일
await this.save()
변경사항을 MongoDB에 저장. 저장된 문서를 반환.
await this.refresh()
데이터베이스에서 문서를 다시 로드하고 로컬 변경사항을 삭제.
💡 모범 사례: Document 메서드는 순수한 상태 변이여야 합니다. 비즈니스 로직(알림, 서비스 간 유효성 검사)은 Service 계층에 속합니다.
Model 클래스 - into()
Model 클래스는 Document와 Filter를 결합하여 컬렉션 레벨 작업을 추가합니다. CRUD 메서드, 쿼리 메서드, 로더를 자동 생성합니다.
into() Signature
자동 생성 CRUD 메서드
Model 클래스는 모델 이름을 기반으로 다음 CRUD 메서드를 자동 생성합니다:
| method | 설명 | 예제 |
|---|---|---|
| getProduct(id: string) | ID로 문서를 불러옵니다. 없으면 에러를 반환합니다. | |
| loadProduct(id?: string) | ID로 문서를 불러옵니다. 없으면 null을 반환합니다. | |
| loadProductMany(ids: string[]) | ID 배열로 문서를 일괄 로드합니다. 문서 또는 null 배열을 반환합니다. | |
| createProduct(data: db.ProductInput) | 입력 데이터로 새 문서를 생성합니다. | |
| updateProduct(id: string, data: Partial<db.Product>) | ID로 문서를 업데이트합니다. 업데이트된 문서를 반환합니다. | |
| removeProduct(id: string) | ID로 문서를 소프트 삭제합니다. 상태를 'archived'로 설정합니다. | |
| searchProduct(searchText: string, queryOption?: ListQueryOption) | 텍스트로 문서를 검색합니다. 문서 목록과 개수를 반환합니다. | |
| searchDocsProduct(searchText: string, queryOption?: ListQueryOption) | 텍스트로 문서를 검색합니다. 문서 목록만 반환합니다. | |
| searchCountProduct(searchText: string) | 검색 텍스트와 일치하는 문서 수를 셉니다. | |
getProduct(id: string)
ID로 문서를 불러옵니다. 없으면 에러를 반환합니다.
loadProduct(id?: string)
ID로 문서를 불러옵니다. 없으면 null을 반환합니다.
loadProductMany(ids: string[])
ID 배열로 문서를 일괄 로드합니다. 문서 또는 null 배열을 반환합니다.
createProduct(data: db.ProductInput)
입력 데이터로 새 문서를 생성합니다.
updateProduct(id: string, data: Partial<db.Product>)
ID로 문서를 업데이트합니다. 업데이트된 문서를 반환합니다.
removeProduct(id: string)
ID로 문서를 소프트 삭제합니다. 상태를 'archived'로 설정합니다.
searchProduct(searchText: string, queryOption?: ListQueryOption)
텍스트로 문서를 검색합니다. 문서 목록과 개수를 반환합니다.
searchDocsProduct(searchText: string, queryOption?: ListQueryOption)
텍스트로 문서를 검색합니다. 문서 목록만 반환합니다.
searchCountProduct(searchText: string)
검색 텍스트와 일치하는 문서 수를 셉니다.
Additional Access
자동 생성 쿼리 메서드
Filter에 정의된 각 쿼리에 대해 10개의 유틸리티 메서드가 자동 생성됩니다:
| method | 설명 | 예제 |
|---|---|---|
| list<Query>(...args, option?) | 정의된 쿼리와 일치하는 문서를 나열합니다. | |
| listIds<Query>(...args, option?) | 정의된 쿼리와 일치하는 문서 ID를 나열합니다. | |
| find<Query>(...args, option?) | 정의된 쿼리와 일치하는 단일 문서를 찾습니다. | |
| findId<Query>(...args, option?) | 정의된 쿼리와 일치하는 단일 문서 ID를 찾습니다. | |
| pick<Query>(...args, option?) | 정의된 쿼리와 일치하는 단일 문서를 찾습니다. 없으면 에러를 던집니다. | |
| pickId<Query>(...args, option?) | 정의된 쿼리와 일치하는 단일 문서 ID를 찾습니다. 없으면 에러를 던집니다. | |
| exists<Query>(...args) | 정의된 쿼리와 일치하는 문서가 존재하는지 확인합니다. ID 또는 null을 반환합니다. | |
| count<Query>(...args) | 정의된 쿼리와 일치하는 만서 수를 셉니다. | |
| insight<Query>(...args) | 정의된 쿼리와 일치하는 집계 통계를 가져옵니다. | |
| query<Query>(...args) | Filter에 정의된 원시 쿼리 객체를 가져옵니다. | |
list<Query>(...args, option?)
정의된 쿼리와 일치하는 문서를 나열합니다.
listIds<Query>(...args, option?)
정의된 쿼리와 일치하는 문서 ID를 나열합니다.
find<Query>(...args, option?)
정의된 쿼리와 일치하는 단일 문서를 찾습니다.
findId<Query>(...args, option?)
정의된 쿼리와 일치하는 단일 문서 ID를 찾습니다.
pick<Query>(...args, option?)
정의된 쿼리와 일치하는 단일 문서를 찾습니다. 없으면 에러를 던집니다.
pickId<Query>(...args, option?)
정의된 쿼리와 일치하는 단일 문서 ID를 찾습니다. 없으면 에러를 던집니다.
exists<Query>(...args)
정의된 쿼리와 일치하는 문서가 존재하는지 확인합니다. ID 또는 null을 반환합니다.
count<Query>(...args)
정의된 쿼리와 일치하는 만서 수를 셉니다.
insight<Query>(...args)
정의된 쿼리와 일치하는 집계 통계를 가져옵니다.
query<Query>(...args)
Filter에 정의된 원시 쿼리 객체를 가져옵니다.
💡 쿼리 이름은 메서드 이름에서 PascalCase가 됩니다: 'inCategory' → 'listInCategory', 'findInCategory'
커스텀 로더
into()의 4번째 인수로 특정 필드별 효율적인 배치 조회를 위한 커스텀 DataLoader를 정의할 수 있습니다.
Custom Loader Definition
| method | 설명 | 예제 |
|---|---|---|
| byField(field) | 고유 필드로 단일 문서 | |
| byArrayField(field) | 필드 값으로 여러 문서 | |
| byQuery([fields]) | 여러 필드 조건으로 문서 | |
byField(field)
고유 필드로 단일 문서
byArrayField(field)
필드 값으로 여러 문서
byQuery([fields])
여러 필드 조건으로 문서
💡 DataLoader는 여러 .load() 호출을 자동으로 단일 DB 쿼리로 배치하여 GraphQL 리졸버와 루프에서 성능을 향상시킵니다.
Middleware 클래스
Middleware 클래스는 인덱스와 훅을 추가하기 위해 Mongoose 스키마에 접근을 제공합니다. onSchema 메서드는 구성을 위해 스키마를 받습니다.
product.document.ts
Service의 Document
product.service.ts
모범 사례
1️⃣
Document 메서드는 체이닝을 위해 'this' 반환: product.sell(5).save()
2️⃣
Document 메서드는 순수하게 - 외부 호출은 Service에서
3️⃣
타입 안전한 자동 생성 메서드를 위해 Filter에서 쿼리 정의
4️⃣
필터에서 사용되는 필드에 Middleware에서 인덱스 추가
5️⃣
N+1 방지를 위해 커스텀 로더 (byField/byArrayField) 사용
