사람함께에이전트▾
사람 — 직접 정하고 책임지는 비즈니스 규칙과 흐름. 직접 읽어보세요.
함께 — 개념은 알아두고, 세부 규칙은 에이전트가 따릅니다.
에이전트 — 에이전트가 따르는 규칙과 레퍼런스. 필요할 때 찾아보세요.
모듈 규칙▾
model.service.ts
service 파일은 비즈니스 로직의 핵심입니다. 복잡한 작업을 처리하고, 서로 다른 모듈 간을 조정하며, 원자적 데이터 일관성을 보장합니다.
🧠비즈니스 로직
유효성 검사, 계산, 의사 결정 로직이 데이터 정의와 분리되어 이곳에 존재합니다.
Service 클래스 구조
서비스는 serve() 함수를 사용하여 정의되며, 이 함수는 데이터베이스 모델을 바인딩하고 콜백을 통해 의존성 주입을 허용합니다.
product.service.ts
메서드 및 변수
serve() 함수는 클래스에 CRUD 메서드와 기본 모델에 대한 접근 권한을 자동으로 장착합니다.
1.1. Predefined Variables
field설명
<MODEL_NAME>Model
model.document.ts에서 선언된 데이터베이스 모델 인스턴스
logger
stdout 로깅을 위한 내장 로거 모듈
1.2. Predefined Methods (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)
검색 텍스트와 일치하는 문서 수를 셉니다.
1.3. Query Based Methods
model.document.ts의 'Filter' 정의에서 생성된 메서드들입니다.
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설명
_preCreate(data)
생성 전에 호출되는 훅입니다. 수정된 데이터를 반환하세요.
_postCreate(doc)
생성 후에 호출되는 훅입니다. 수정된 문서를 반환하세요.
_preUpdate(id, data)
업데이트 전에 호출되는 훅입니다.
_postUpdate(doc)
업데이트 후에 호출되는 훅입니다.
_preRemove(id)
삭제 전에 호출되는 훅입니다.
_postRemove(doc)
삭제 후에 호출되는 훅입니다.
listenPre(type, listener)
동적 pre-hook 리스너를 등록합니다.
listenPost(type, listener)
동적 post-hook 리스너를 등록합니다.
Example: _preCreate
의존성 주입
의존성은 serve()의 콜백 함수를 통해 주입됩니다. 이는 타입 안전성을 보장하고 순환 의존성 문제를 방지합니다.
3.1. Supported Injections
method설명
service<T>()
다른 서비스를 주입합니다.
use<T>()
외부 클래스나 변수를 주입합니다.
env<T>(key, factory?)
환경 변수를 주입합니다. 없으면 에러를 발생시킵니다.
envOptional<T>(key, factory?)
환경 변수를 안전하게 주입합니다. 없으면 undefined를 반환합니다.
generate<T>(factory)
환경에 따라 값을 동적으로 생성합니다.
signal<T>()
시그널(웹소켓/큐) 모듈을 주입합니다.
3.2. Examples
Injecting Services & Envs
⚠️주입 설정
전역 주입은 lib/option.ts 파일에서 useGlobals()를 사용하여 등록해야 합니다.
lib/option.ts
Service 모범 사례
1️⃣Document는 순수하게
단순한 상태 변경은 Document 메서드에 둡니다. 다른 서비스가 포함된 복잡한 로직은 Service 메서드에 둡니다.
2️⃣자동 생성 메서드 활용
원시 DB 쿼리보다 자동 생성된 list/find 메서드를 선호하세요. 일관성과 타입 안전성을 유지합니다.