개발 사이클 개요
Sonamu의 개발은 다음과 같은 사이클로 진행됩니다:1
1. 엔티티 설계 및 정의
Sonamu UI에서 엔티티 구조를 정의합니다.
2
2. 마이그레이션
데이터베이스에 테이블을 생성하거나 수정합니다.
3
3. 스캐폴딩
Model 파일과 테스트 파일을 자동 생성합니다.
4
4. 비즈니스 로직 구현
생성된 Model 파일에 비즈니스 로직을 추가합니다.
5
5. 동기화 (Sync)
변경사항을 프론트엔드와 동기화합니다.
6
6. 테스트
작성한 코드를 테스트합니다.
7
7. 프론트엔드 통합
자동 생성된 Service를 사용하여 UI를 구현합니다.
🎬 필요: 전체 개발 워크플로우 순서도 (위 7단계를 시각화)
1단계: 엔티티 설계 및 정의
Sonamu UI에서 엔티티 생성
개발은 항상 Sonamu UI에서 엔티티를 정의하는 것으로 시작합니다.- Entity 탭에서 새 엔티티 추가
- 필드 정의 - 타입, 제약조건, 기본값 설정
- Subset 정의 - API 응답 형태 정의
- Enum 정의 - 정렬/검색 옵션 정의
- Relation 정의 - 다른 엔티티와의 관계 설정
📸 필요: Sonamu UI에서 엔티티 정의하는 화면
CLI로 엔티티 생성 (선택사항)
CLI를 사용하여 빈 엔티티를 생성할 수도 있습니다:더 알아보기
- 엔티티 정의하기 - 엔티티 구조와 설정 옵션
- Sonamu UI 사용하기 - UI에서 엔티티 관리
- 필드 타입 - 사용 가능한 모든 필드 타입
- Relation 정의 - 엔티티 간 관계 설정
- Enum 정의 - 열거형 타입 관리
- Entity Management - Sonamu UI Entity 탭 가이드
2단계: 마이그레이션
엔티티 정의를 데이터베이스에 반영합니다.Sonamu UI에서 마이그레이션
- Migration 탭 클릭
- Generate Migration - SQL 자동 생성
- 생성된 SQL 검토
- Run Migration - 데이터베이스에 적용
📸 필요: Migration 탭에서 마이그레이션 실행하는 화면
CLI로 마이그레이션 (선택사항)
더 알아보기
- 마이그레이션 작동 원리 - 마이그레이션 시스템 이해
- 마이그레이션 생성하기 - SQL 자동 생성 메커니즘
- 마이그레이션 실행하기 - 안전한 마이그레이션 실행
- Migration 탭 - Sonamu UI에서 마이그레이션 관리
- migrate CLI - CLI로 마이그레이션 제어
3단계: 스캐폴딩
마이그레이션 후 Model 파일과 테스트 파일을 자동 생성합니다.Sonamu UI에서 스캐폴딩
- Scaffolding 탭 클릭
- 엔티티 선택
- 생성할 템플릿 선택:
- Model - 비즈니스 로직 및 API 엔드포인트
- Model Test - 테스트 파일
- Preview (선택사항) - 생성될 코드 미리보기
- Generate - 파일 생성
📸 필요: Scaffolding 탭에서 Model 파일 생성하는 화면
CLI로 스캐폴딩 (선택사항)
생성되는 파일
{entity}.model.ts- 기본 CRUD API 포함{entity}.model.test.ts- 테스트 템플릿
더 알아보기
- Scaffolding 탭 - UI에서 코드 생성하기
- scaffold CLI - CLI로 파일 스캐폴딩
- 테스트 스캐폴딩 - 테스트 파일 자동 생성
4단계: 비즈니스 로직 구현
생성된 Model 파일에 비즈니스 로직을 추가합니다.Model 파일 구조
user.model.ts
API 데코레이터
@api 데코레이터는 메서드를 REST API 엔드포인트로 자동 등록합니다:
HMR (Hot Module Replacement)Model 파일을 수정하면 API 서버가 자동으로 재시작됩니다. 별도의 서버 재시작이 필요 없습니다!
더 알아보기
- Model이란? - Model의 역할과 구조
- @api 데코레이터 - API 엔드포인트 자동 생성
- 비즈니스 로직 작성 - Model에서 로직 구현하기
- BaseModel 메서드 - 내장 CRUD 메서드
- API 만들기 - 상세한 API 개발 가이드
- Puri 쿼리 빌더 - 타입 안전한 쿼리 작성
- 트랜잭션 - 안전한 데이터 처리
5단계: 동기화 (Sync)
변경사항을 프론트엔드와 동기화합니다.자동 동기화 (HMR)
pnpm dev로 개발 서버를 실행하면 파일 변경 시 자동으로 동기화됩니다:
- ✅ Model 파일 변경 → Service 파일 자동 재생성
- ✅ Types 파일 변경 → Web 프로젝트로 자동 복사
- ✅ Entity 정의 변경 → 스키마 자동 재생성
📸 필요: 터미널에서 HMR이 동작하는 로그 화면
수동 동기화
필요한 경우 수동으로 동기화할 수 있습니다:pnpm sync는 다음 작업을 수행합니다:
- sonamu.shared.ts 복사 - 공통 타입 및 유틸리티를 Web으로 복사
- 변경 파일 감지 - Checksum 기반으로 변경된 파일 확인
- 타입 동기화 -
*.types.ts,*.generated.ts파일을 Web으로 복사 - Service 생성 - Model의 API를 기반으로 프론트엔드 Service 생성
- Config 동기화 -
.sonamu.env파일 업데이트
Sync 명령어가 필요한 경우
- 개발 서버를 종료한 상태에서 여러 파일을 수정한 경우
- Git에서 다른 브랜치로 전환한 경우
- 동기화 상태가 꼬였다고 생각될 경우
더 알아보기
- Syncer 이해하기 - 동기화 메커니즘 상세
- 자동 생성되는 것들 - 어떤 파일이 생성되는지
- HMR 작동 원리 - Hot Module Replacement 이해
6단계: 테스트
작성한 비즈니스 로직을 테스트합니다.테스트 파일 작성
스캐폴딩으로 생성된 테스트 파일에 테스트 케이스를 추가합니다:user.model.test.ts
테스트 실행
📸 필요: 터미널에서 테스트 실행 결과 화면
더 알아보기
- 테스트 작성하기 - Vitest 기반 테스트 구조
- 테스트 스캐폴딩 - 테스트 템플릿 활용
- Fixture 만들기 - 테스트 데이터 관리
- Naite란? - 테스트 로깅 시스템
7단계: 프론트엔드 통합
자동 생성된 Service를 사용하여 UI를 구현합니다.생성된 Service 파일
Model에 정의된 API는 자동으로 프론트엔드 Service로 생성됩니다:web/src/services/UserService.ts (자동 생성)
React 컴포넌트에서 사용
web/src/pages/UserProfile.tsx
타입 안전성Service와 타입이 백엔드와 자동 동기화되므로, 타입 불일치 오류를 컴파일 타임에 발견할 수 있습니다!
더 알아보기
- Service 작동 원리 - 자동 생성 메커니즘
- Service 사용하기 - 실전 활용 가이드
- 공유 타입 - 백엔드-프론트엔드 타입 동기화
전체 워크플로우 예시
실제 기능을 추가하는 전체 과정을 예시로 살펴봅시다.시나리오: “좋아요” 기능 추가
1
1. 엔티티 수정
Post 엔티티에
like_count 필드 추가2
2. 마이그레이션
3
3. Model에 비즈니스 로직 추가
4
4. 자동 동기화
HMR이 자동으로:
post.types.ts→ Web으로 복사PostService.ts에addLike메서드 추가
5
5. 프론트엔드 구현
6
6. 테스트
🎬 필요: 위 6단계를 실제로 시연하는 영상 (좋아요 기능 추가 전체 과정)
개발 팁
1. Entity First 원칙
모든 개발은 엔티티 정의에서 시작합니다. 데이터 구조가 명확해야 API와 UI도 명확해집니다.2. Subset 활용
다양한 Subset을 미리 정의해두면 API 응답 크기를 최적화할 수 있습니다:- A (All): 모든 필드 (상세 페이지)
- C (Compact): 주요 필드만 (목록 페이지)
- S (Summary): 최소 필드 (미리보기)
3. 관계(Relation) 설계
엔티티 간 관계를 명확히 정의하면 JOIN 쿼리가 자동으로 생성됩니다.4. 테스트 우선 작성
복잡한 비즈니스 로직은 테스트를 먼저 작성하면 안전하게 개발할 수 있습니다.5. HMR 활용
개발 중에는pnpm dev를 계속 실행해두고, 파일만 수정하면 자동으로 동기화됩니다.
6. 문제 발생 시
동기화 상태가 이상하면:- 개발 서버 재시작
pnpm sync수동 실행rm sonamu.lock후 재시작
