사람함께에이전트▾
사람 — 직접 정하고 책임지는 비즈니스 규칙과 흐름. 직접 읽어보세요.
함께 — 개념은 알아두고, 세부 규칙은 에이전트가 따릅니다.
에이전트 — 에이전트가 따르는 규칙과 레퍼런스. 필요할 때 찾아보세요.
모듈 규칙▾
스칼라 모듈 개요
스칼라 모듈은 애플리케이션 전반에 걸쳐 임베디드 문서, 공유 DTO 및 국제화된 데이터 구조를 위한 재사용 가능한 값 객체를 제공합니다. 스칼라를 재사용 가능한 레고 조각으로 생각해보세요 - 더 큰 모델로 조합할 수 있는 작고 집중된 데이터 구조입니다.
자체 데이터베이스 컬렉션을 가진 전체 Model과 달리, Scalar는 다른 모델 안에 내장됩니다. 다음과 같은 용도에 완벽합니다:
- 도메인 모델의 임베디드 문서 (예: 주소, 연락처 정보)
- 모듈 간 공유 DTO 및 구성 객체
- 런타임 유효성 검사가 있는 타입 안전 스키마
- 완전한 i18n 지원이 있는 국제화된 데이터 구조
핵심 원칙
🔄Reusability
모듈 간 사용을 위해 설계됨. 한 번 정의하고 어디서든 사용.
📦Stateless
비즈니스 로직 없는 순수 데이터 컨테이너. 동작이 아닌 구조에 집중.
🛡️Type-Safe
필드 옵션을 통한 런타임 유효성 검사와 완전한 TypeScript 통합.
🧩Composable
더 큰 도메인 모델 내에 임베딩 가능. 스칼라는 다른 스칼라를 포함할 수 있음.
파일 구조
스칼라 모듈은 라이브러리 내의 특수한 __scalar 디렉토리에 저장됩니다. 각 스칼라는 세 개의 핵심 파일이 있는 자체 디렉토리를 가집니다:
field설명
*.constant.ts
via() 함수를 사용하여 스칼라 스키마를 정의하고 enumOf()를 사용하여 enum을 정의합니다. 여기서 필드, 타입, 기본값 및 유효성 검사 규칙을 선언합니다.
*.dictionary.ts
scalarDictionary() 빌더 패턴을 사용하여 국제화를 제공합니다. 모델 이름, 필드 레이블, 설명 및 enum 값에 대한 번역을 정의합니다.
*.document.ts
by() 함수를 사용하여 기능을 확장하는 선택적 파일입니다. 데이터 변환 및 계산된 값을 위한 커스텀 메서드를 추가합니다.
스칼라 정의하기
Akan.js는 스칼라를 정의하는 데 함수형 접근 방식을 사용합니다. via() 함수는 타입 안전 스키마 정의를 생성하고, enumOf()는 타입이 지정된 enum 클래스를 생성합니다. 프레임워크의 실제 예시입니다:
price.constant.ts
핵심 패턴을 이해해봅시다:
field설명
enumOf(name, values)
타입이 지정된 enum 클래스를 생성합니다. 첫 번째 인수는 enum 이름(dictionary에서 사용), 두 번째는 타입 안전을 위해 "as const"가 포함된 값 배열입니다.
via((field) => ({...}))
타입이 지정된 필드를 가진 스칼라 클래스를 생성합니다. field() 함수는 타입과 기본값, 유효성 검사 등을 위한 선택적 구성을 받습니다.
Field Options
옵션에는: default (정적 또는 함수), min/max (숫자용), minlength/maxlength (문자열용), validate (커스텀 검증 함수)가 포함됩니다.
scalarDictionary()
scalarDictionary() 함수는 번역을 정의하기 위한 플루언트 빌더 패턴을 제공합니다. 타입 안전성과 모든 필드 및 enum 값의 완전한 커버리지를 보장합니다.
price.dictionary.ts
dictionary 빌더 패턴을 이해해봅시다:
field설명
scalarDictionary([languages])
지원되는 언어 배열로 초기화합니다. 순서는 번역 배열에서 어떤 인덱스가 어떤 언어에 해당하는지를 결정합니다.
.of((t) => ...)
스칼라 자체의 이름과 설명을 정의합니다. 레이블에는 t([en, ko])를, 설명에는 .desc([en, ko])를 사용합니다.
.model<Type>((t) => ({...}))
각 필드에 대한 번역을 정의합니다. 제네릭 타입은 모든 필드가 커버되도록 보장합니다. 각 필드는 레이블과 설명을 가집니다.
.enum<Type>(name, (t) => ({...}))
enum 값에 대한 번역을 정의합니다. 첫 번째 인수는 enum 이름(enumOf()와 일치), 두 번째는 각 값에 대한 번역을 정의합니다.
by()로 Document 확장하기
document 파일은 by() 함수를 사용하여 커스텀 메서드로 스칼라를 확장합니다. 이것은 선택 사항이지만 계산된 속성과 데이터 변환 메서드를 추가하는 데 유용합니다.
price.document.ts
document 확장에 대한 핵심 포인트:
field설명
by(cnst.ClassName)
상수 클래스를 감싸고 메서드 추가를 활성화합니다. 이름 충돌을 피하기 위해 상수를 cnst로 임포트합니다.
Custom Methods
계산된 속성, 유효성 검사 헬퍼, 변환 메서드를 클래스 본문에 직접 추가합니다.
Access Fields
'this'를 사용하여 상수 파일에 정의된 모든 필드에 접근합니다. TypeScript가 완전한 자동 완성을 제공합니다.
명명 규칙
일관된 명명은 유지보수성에 중요합니다. 다음 규칙을 따르세요:
field설명
Scalar Directory
camelCase (e.g., encourageInfo)
Constant File
[name].constant.ts (e.g., encourageInfo.constant.ts)
Dictionary File
[name].dictionary.ts (e.g., encourageInfo.dictionary.ts)
Document File
[name].document.ts (e.g., encourageInfo.document.ts)
Scalar Class
PascalCase (e.g., EncourageInfo)
Enum Class
PascalCase (e.g., Journey, LinkType)
Enum Values
camelCase (e.g., firstJoin, waitPay)
모범 사례
field설명
Design for Reusability
여러 모듈에서 사용할 수 있는 스칼라를 만드세요. 주소, 연락처 정보, 상태 추적과 같은 공통 데이터 패턴을 생각해보세요.
Keep Scalars Focused
각 스칼라는 단일 개념을 나타내야 합니다. 스칼라가 너무 커지면 더 작고 조합 가능한 조각으로 분리하는 것을 고려하세요.
Use Proper Defaults
선택적 필드에 합리적인 기본값을 제공하세요. 생성 시 계산되어야 하는 동적 값에는 함수 기본값 (예: () => dayjs())을 사용하세요.
Complete Dictionary Coverage
항상 모든 필드와 enum 값에 대한 번역을 제공하세요. 타입 시스템을 사용하여 누락되는 것이 없도록 하세요.
Validate at Field Level
min/max, minlength/maxlength 및 커스텀 validate 함수와 같은 필드 옵션을 사용하여 스키마 수준에서 데이터 무결성을 보장하세요.
통합 포인트
스칼라는 Akan.js 프레임워크의 다른 부분과 원활하게 통합됩니다:
field설명
Domain Models
field([ScalarClass])를 사용하여 모델에 스칼라 임베드
GraphQL
API 계약을 위한 자동 생성된 타입 및 enum
Validation
필드 옵션을 통한 런타임 타입 검사
Internationalization
scalarDictionary()를 통한 일관된 용어
UI Components
Enum 값을 선택 필드에서 직접 사용 가능
Dictionary Sharing
dictionary 간 enum 번역 재사용
🎉 배운 내용:
- ✓ via()와 enumOf() 함수를 사용하여 스칼라를 만드는 방법
- ✓ scalarDictionary()로 국제화를 정의하는 방법
- ✓ by()를 사용하여 커스텀 메서드로 스칼라를 확장하는 방법
- ✓ 스칼라의 명명 규칙과 모범 사례
- ✓ 스칼라가 모델 및 기타 프레임워크 기능과 통합되는 방법
실제 애플리케이션에서 스칼라를 생성하고 사용하는 실습 예제를 보려면 Tutorials 섹션을 확인하세요.