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를 나열합니다.

커스텀 로더

into()의 4번째 인수로 특정 필드별 효율적인 배치 조회를 위한 커스텀 DataLoader를 정의할 수 있습니다.

Custom Loader Definition

method	설명	예제
byField(field)	고유 필드로 단일 문서
byArrayField(field)	필드 값으로 여러 문서
byQuery([fields])	여러 필드 조건으로 문서

byField(field)

고유 필드로 단일 문서

byArrayField(field)

필드 값으로 여러 문서

byQuery([fields])

여러 필드 조건으로 문서

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) 사용

method

설명

예제

.arg(name, Type, options?)

필수 파라미터. 관리자 패널의 UI 렌더링을 위한 { ref, renderOption } 옵션 포함.

.opt(name, Type, options?)

선택적 파라미터. 제공되지 않으면 undefined. 쿼리에서 조건부 스프레드 사용.

.query((...args) => MongoQuery)

MongoDB 쿼리 객체를 반환합니다. 인수는 .arg()와 .opt() 호출 순서와 일치합니다.

method

설명

예제

this.set(data)

여러 필드를 한 번에 설정. Object.assign(this, data)와 동일

await this.save()

변경사항을 MongoDB에 저장. 저장된 문서를 반환.

await this.refresh()

데이터베이스에서 문서를 다시 로드하고 로컬 변경사항을 삭제.

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)

검색 텍스트와 일치하는 문서 수를 셉니다.

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에 정의된 원시 쿼리 객체를 가져옵니다.

method

설명

예제

byField(field)

고유 필드로 단일 문서

byArrayField(field)

필드 값으로 여러 문서

byQuery([fields])

여러 필드 조건으로 문서