/init : AI 가 자동으로 디렉터리 구조 , 설정 파일, 의존성, 기본 코드 등을 만들어주는 과정
결과
CLAUDE.md 파일을 생성했습니다.
주요 내용:
📋 프로젝트 컨텍스트
- 현재 상태: 5% 완료 (기초 구조만 존재)
- 실제 API 엔드포인트 없음 (Controller, DTO 미구현)
🛠️ 개발 명령어
- Backend: ./gradlew bootRun, ./gradlew test
- Frontend: npm run dev, npm run build
- 알려진 이슈 3가지 명시 (즉시 수정 필요)
🏗️ 아키텍처 가이드
- 백엔드 패키지 구조 (생성 필요한 패키지 표시)
- 프론트엔드 계층 구조 (현재 비어있음 명시)
- JWT 인증 플로우 상세 설명
⚙️ 중요 설정
- JWT 설정 및 보안 이슈
- CORS 설정 방법
- 파일 업로드 로컬/S3 전환
- SQLite → PostgreSQL 마이그레이션 필요
⚠️ 기술 부채 & 리스크
- Critical: 3개 (빌드 불가 이슈)
- High: 4개 (보안, API 미구현)
- Medium: 4개 (DB, 테스트 등)
- Low: 4개 (문서, CI/CD)
🎯 개발 워크플로우
- 기능 추가 순서
- 테스트 전략
- 보안 체크리스트
질문
> 지금 문서를 기반으로 프로젝트 템플릿을 생성해줘
프로젝트 템플릿 : 새 프로젝트를 만들 때 기반으로 삼는 구조와 설정
결과
프로젝트 템플릿을 생성했습니다!
✅ 완료된 작업
1. 환경 문제 해결 (Critical)
- ✅ TailwindCSS 4.x PostCSS 플러그인 설치 및 설정
- ✅ Gradle Wrapper JAR 파일 다운로드
- ✅ 프론트엔드 빌드 테스트 통과
2. 백엔드 구조 완성
생성된 파일들:
- Exception 처리: GlobalExceptionHandler, ErrorResponse, 4개 커스텀 예외
- Base Entity: BaseEntity (타임스탬프 자동 관리)
- DTO: ApiResponse (공통 응답 포맷)
- 패키지: controller, dto/request, dto/response, exception, util
3. 프론트엔드 구조 완성
생성된 파일들:
- Services: api.js (Axios + 인터셉터), authService.js
- Context: AuthContext.jsx (인증 상태 관리)
- Components: Button, Input, Loading
- Utils: tokenUtils.js
- Constants: routes.js
- 폴더: components/{common,course,auth,layout}, pages, hooks
4. 템플릿 파일 (3개)
- TEMPLATE_CONTROLLER.java - REST API 패턴
- TEMPLATE_SERVICE.java - Service Layer 패턴
- TEMPLATE_PAGE.jsx - React Query 페이지
- TEMPLATE_HOOK.js - Custom Hook 패턴
5. 환경 설정 파일
- application-local.yml - 로컬 개발용
- application-prod.yml - 프로덕션 (환경변수)
- .env.example - 프론트엔드 환경변수 예제
- .env.local - 로컬 개발용 설정
- .gitignore 업데이트
6. 문서
- SETUP.md - 템플릿 활용 가이드 및 다음 단계
📊 프로젝트 상태
총 생성된 소스 파일: 32개
- Backend: 14개 Java 파일
- Frontend: 10개 JS/JSX 파일
- Templates: 4개
- Config: 4개
진행률: 약 10% → 15% (템플릿 인프라 완성)
🚀 다음 단계
Phase 2 시작 준비 완료!
1. AuthController 및 AuthService 구현
2. 템플릿 파일 활용하여 빠른 개발 가능
3. SETUP.md 참고하여 개발 진행
2. 의존성 관리
패키지 버전 최적화
프롬프트
package.json 의 의존성을 분석하고 다음 작업을 수행해줘.
1. 보안 취약점 확인
2. 최신 안정 버전으로 업데이트 가능한 패키지 목록
3. 버전 충돌 가능성 확인
4. 불필요한 의존성 제거
package.json : 프론트엔드 프로젝트의 핵심 구성 파일
결과
프론트엔드 의존성 분석을 완료했습니다!
📊 분석 결과 요약
1. ✅ 보안 취약점: 0개 (안전)
- 모든 패키지가 알려진 보안 취약점 없음
- npm audit 통과
2. ⚠️ 업데이트 가능 패키지
Critical 이슈:
- React 19.2.0 → React 18.3.1 다운그레이드 권장
- 이유: 생태계 안정성, 프로덕션 검증됨
- React 19는 2024년 12월 출시된 신버전
Medium:
- eslint-plugin-react-hooks: 5.2.0 → 7.0.0
- React 19 사용 시 업그레이드 필요
- React 18 사용 시 현재 버전 유지
나머지 패키지: ✅ 모두 최신 안정 버전 사용 중
3. ✅ 버전 충돌: 없음
- React Query 5.90.2: React 19 호환 ✅
- React Router 7.9.4: React 19 호환 ✅
- TailwindCSS 4.1.14: 정상 작동 ✅
- 모든 peer dependencies 충족
4. ✅ 불필요한 의존성: 0개
- 모든 17개 패키지가 사용 중
- 제거 가능한 패키지 없음
🎯 최종 권장사항
Option A: React 18 다운그레이드 ⭐ 권장
- 프로덕션 안정성 보장
- 생태계 완벽 호환
- MVP 개발에 집중 가능
제공된 도구:
1. DEPENDENCY_ANALYSIS.md - 상세 분석 보고서
2. package.json.react18 - React 18 버전 설정 파일
3. DOWNGRADE_TO_REACT18.sh - 자동 다운그레이드 스크립트
실행 방법:
cd frontend
bash DOWNGRADE_TO_REACT18.sh
Option B: React 19 유지
- 최신 기능 사용 가능
- ESLint 플러그인 7.0.0 업그레이드 필요
- 호환성 테스트 철저히 수행
모노레포 의존성 관리
프롬프트
pnpm workspace를 사용한 monorepo 의존성을 설정해줘
- 공통 의존성은 루트에 설치
- 패키지 간 의존성 연결
pnpm workspace
여러 프로젝트를 한 저장소에서 관리
루트에 공통 의존성 설치 : 중복 방지
패키지 간 로컬 의존성 연결
결과
pnpm workspace 기반 monorepo 설정을 완료했습니다!
✅ 완료된 작업
1. Workspace 설정
- ✅ pnpm-workspace.yaml 생성
- ✅ .npmrc 설정 (호환성 및 자동 링크)
- ✅ Root package.json (공통 스크립트 및 의존성)
2. 공유 패키지 (3개)
@running-share/types
- TypeScript 타입 정의 (User, Course, Comment 등)
- API Request/Response 타입
- Pagination, ErrorResponse 등
- 총 100+ 타입 정의
@running-share/config
- API 엔드포인트 URL
- 라우트 경로
- Validation 규칙
- React Query 설정
- 파일 업로드 제한
@running-share/utils
- 거리 계산 (calculateDistance, calculateRouteDistance)
- 날짜 포맷팅 (formatDate, formatRelativeTime)
- Debounce/Throttle
- 총 15개 유틸리티 함수
3. Frontend 통합
- Frontend에서 공유 패키지 의존성 설정
- workspace:* 프로토콜 사용
4. 문서
- MONOREPO_GUIDE.md 생성 (사용법, 예제, 트러블슈팅)
📊 Monorepo 구조
running_share_service/
├── pnpm-workspace.yaml
├── package.json (root)
├── frontend/ (@running-share/frontend)
│ ├── package.json (workspace 의존성 포함)
│ └── src/
└── packages/
├── types/ (@running-share/types)
├── config/ (@running-share/config)
└── utils/ (@running-share/utils)
🚀 주요 명령어
# 전체 설치
pnpm install
# Frontend 개발 실행
pnpm dev
# 전체 빌드
pnpm build
# Frontend만 빌드
pnpm build:frontend
💡 사용 예시
// 타입 import
import type { CourseResponse, LoginRequest } from '@running-share/types';
// 상수 import
import { ROUTES, API_ENDPOINTS } from '@running-share/config';
// 유틸리티 import
import { formatDistance, formatRelativeTime } from '@running-share/utils';
🎯 다음 단계
1. pnpm 설치: npm install -g pnpm@9
2. 의존성 설치: cd running_share_service && pnpm install
3. 개발 시작: pnpm dev
4. 기존 코드 마이그레이션: 공유 패키지 사용으로 전환
3. 개발 환경 구성
VS Code 설정
프롬프트
> VS Code 설정 파일을 생성해줘
- 추천 익스텐션 목록
- 디버깅 설정
- 태스크 러너
- 코드 스니펫
추천 익스텐션 : 개발 생산성과 코드 품질 향상
디버깅 설정 : 프론트,백엔드 디버깅 환경 통합
태스크 러너 : 빌드/테스트/린트 자동화
코드 스니펫 : 반복 코드 자동 완성
결과
VS Code 설정 파일을 생성했습니다!
✅ 생성된 파일 (7개)
1. extensions.json - 추천 익스텐션 목록
30개 이상의 익스텐션 포함:
- ✅ ESLint, Prettier, EditorConfig (필수)
- ✅ React, TypeScript 개발 도구
- ✅ Java, Spring Boot, Gradle 지원
- ✅ TailwindCSS IntelliSense
- ✅ GitLens, Database Client, REST Client
- ✅ Markdown, YAML, Docker 지원
2. settings.json - 워크스페이스 설정
주요 기능:
- ✅ 저장 시 자동 포맷팅 (Prettier)
- ✅ ESLint 자동 수정
- ✅ Java/TypeScript 설정
- ✅ TailwindCSS 지원
- ✅ 파일 제외 규칙 (node_modules, dist, .gradle)
- ✅ 언어별 개별 설정
3. launch.json - 디버깅 설정
8개 디버그 설정:
- ✅ Frontend: Chrome/Edge/Firefox
- ✅ Backend: Spring Boot 애플리케이션
- ✅ Backend: 테스트 디버깅
- ✅ Backend: Attach (실행 중인 프로세스)
- ✅ Full Stack: 동시 디버깅 (Compounds)
4. tasks.json - 태스크 러너
25개 이상의 태스크:
- ✅ Frontend: Dev, Build, Lint, Preview
- ✅ Backend: Run, Build, Test, Clean Build
- ✅ Monorepo: Install All, Build All, Lint All
- ✅ Full Stack: 병렬 실행/빌드
- ✅ Database: Clean SQLite
- ✅ Git: Pull, Status
5. react.code-snippets - React 스니펫
20개 이상의 스니펫:
- ✅ React 컴포넌트 (rfc, rfcp)
- ✅ React Hooks (ust, uef, uctx, urf, umm, ucb)
- ✅ React Query (rquq, rqum, rqhook)
- ✅ Axios 서비스 (axsvc)
- ✅ 일반 스니펫 (imp, af, clg, tryc)
6. java.code-snippets - Java/Spring Boot 스니펫
12개 이상의 스니펫:
- ✅ Spring Boot Controller (sbctrl)
- ✅ Spring Boot Service (sbsvc)
- ✅ JPA Entity (jpae)
- ✅ JPA Repository (jpar)
- ✅ Request/Response DTO (reqd, resd)
- ✅ 테스트 (test, mockmvc)
- ✅ Lombok, Validation 어노테이션
7. VSCODE_GUIDE.md - 사용 가이드
완전한 문서:
- ✅ 익스텐션 설치 방법
- ✅ 디버깅 가이드 (Frontend/Backend/Full Stack)
- ✅ 태스크 사용법 및 단축키
- ✅ 코드 스니펫 사용 예시
- ✅ 문제 해결 (Troubleshooting)
- ✅ 팁 & 트릭
🚀 사용 시작하기
1. VS Code 열기
cd running_share_service
code .
2. 추천 익스텐션 설치
- VS Code가 자동으로 알림 표시
- "Install All Workspace Extension Recommendations" 클릭
3. 디버깅 시작
F5 → "Frontend: Chrome" 또는 "Backend: Spring Boot" 선택
4. 태스크 실행
Cmd/Ctrl + Shift + B → 빌드 태스크
Cmd/Ctrl + Shift + P → Tasks: Run Task → 원하는 태스크 선택
5. 스니펫 사용
// 'rfc' 입력 후 Tab → React 컴포넌트 생성
// 'sbctrl' 입력 후 Tab → Spring Controller 생성
💡 주요 기능 하이라이트
✨ 자동 포맷팅: 저장 시 Prettier로 자동 정리
✨ IntelliSense: TailwindCSS, TypeScript 자동완성
✨ Full Stack 디버깅: Frontend + Backend 동시 디버그
✨ 병렬 태스크: 여러 작업 동시 실행
✨ 스니펫: 반복 코드 빠르게 생성
깃 훅 설정
프롬프트
> Git hooks 를 설정해줘
- pre-commit : 린트와 포맷팅 체크
- commit-msg : 커밋 메시지 규칙 검증
- pre-push : 테스트 실행
Git hooks : Git 에서 특정 이벤트가 발생할 때 자동으로 실행되는 스크립트
pre-commit
커밋전에 실행
스타일 문제나 포맷 오류가 있는 코드가 커밋되는 것을 방지
commit-msg
커밋 메시지를 작성한 직후 실행
일관된 커밋 메시지 규칙 유지
pre-push
원격 저장소로 푸시하기 전에 실행
실패한 테스트가 포함된 코드를 푸시하지 못하게 막아 서비스 안전성 확보
결과
Git Hooks 설정이 완료되었습니다.
✅ 완료된 작업
1. Husky 및 도구 설치
- Husky 9.1.7
- lint-staged 16.2.4
- @commitlint/cli 20.1.0
- @commitlint/config-conventional 20.0.0
- Prettier 3.6.2 (frontend)
2. Git Hooks 생성
.husky/pre-commit
- 스테이징된 파일에 대해 ESLint 및 Prettier 자동 실행
- lint-staged 사용으로 효율적인 검사
.husky/commit-msg
- Conventional Commits 규칙 검증
- 유효하지 않은 커밋 메시지 차단
- 허용 타입: feat, fix, docs, style, refactor, test, chore, perf, ci, build, revert
.husky/pre-push
- Frontend 테스트 실행 (있는 경우)
- Backend Gradle 테스트 실행
- 테스트 실패 시 푸시 차단
3. 설정 파일
- .commitlintrc.js: 커밋 메시지 규칙 정의
- .prettierrc.js: 코드 포맷팅 규칙
- .prettierignore: Prettier 제외 파일
- package.json: lint-staged 설정 추가
4. 문서
- GIT_HOOKS_GUIDE.md: 종합 사용 가이드 (한국어)
📋 사용 방법
커밋 메시지 형식
<type>(<scope>): <subject>
# 예시:
git commit -m "feat(auth): add JWT authentication"
git commit -m "fix(course): resolve map rendering issue"
git commit -m "docs(readme): update installation guide"
Hook 동작
1. 커밋 시: ESLint + Prettier 자동 실행 및 수정
2. 커밋 메시지: 규칙 검증
3. 푸시 시: 테스트 자동 실행
4. 컨테이너 환경 구성
개발용 도커 설정
프롬프트
> 개발용 Docker 환경을 구성해줘
- Hot reload 지원
- 데이터베이스 연동
- 볼륨 마운트 설정
- 네크워크 설정
Hot reload
코드 변경 시 컨테이너를 재시작하지 않고 즉시 반영
개발 속도 향상, 반복 빌드 최소화
데이터베이스 연동
개발 환경에서 실제 DB와 연동해 애플리케이션 테스트
로컬 개발 DB와 컨테이너 앱 간 안정적인 연결
볼륨 마운트 설정
로컬 파일 시스템과 컨테이너 파일 시스템을 동기화
코드 수정 → 컨테이너 즉시 반영, 데이터 지속성 확보
네트워크 설정
컨테이너 간 통신 및 외부 접근 경로 지정
개발용 서비스 URL 일관성 유지, 여러 컨테이너 연결
결과
Docker 개발 환경 설정이 완료되었습니다.
✅ 완료된 작업
1. Docker Compose 설정 (docker-compose.yml)
- Frontend: Vite 개발 서버 (포트 5173)
- Backend: Spring Boot (포트 8080, 디버그 5005)
- PostgreSQL: 데이터베이스 (포트 5432)
- Adminer: 데이터베이스 관리 UI (포트 8081)
2. Dockerfile 생성
frontend/Dockerfile.dev
- Node.js 20 Alpine 이미지
- pnpm workspace 지원
- Vite HMR (Hot Module Replacement)
- 소스 코드 볼륨 마운트
backend/Dockerfile.dev
- Eclipse Temurin JDK 17
- Gradle wrapper 사용
- Spring Boot DevTools 활성화
- 원격 디버깅 포트 (5005)
- --continuous 빌드로 Hot Reload
3. 데이터베이스 설정
PostgreSQL 초기화 스크립트 (docker/postgres/init.sql)
- UUID 및 암호화 확장 활성화
- 권한 부여
Health Check 설정
- PostgreSQL 준비 상태 확인
- Backend Actuator 헬스 체크
- 서비스 간 의존성 관리
4. 볼륨 마운트
Frontend 볼륨
- ./frontend/src → 소스 코드 Hot Reload
- ./packages → 공유 패키지
- frontend_node_modules → 독립적인 의존성
Backend 볼륨
- ./backend/src → 소스 코드 Hot Reload
- backend_gradle_cache → Gradle 캐시
- backend_uploads → 파일 업로드
영구 데이터
- postgres_data → 데이터베이스 데이터
5. 네트워크 설정
- Bridge 네트워크: running-share-network
- 서브넷: 172.28.0.0/16
- 서비스 간 내부 통신 지원
6. 환경 설정 파일
.env.docker
- 데이터베이스 연결 정보
- JWT 설정
- Frontend API 엔드포인트
- Hot Reload 설정
backend/src/main/resources/application-docker.yml
- PostgreSQL 데이터베이스 설정
- Spring DevTools 활성화
- 상세 로깅 설정
- Actuator 헬스 체크
7. Gradle 의존성 추가 (build.gradle)
- PostgreSQL 드라이버
- Spring Boot DevTools
- Spring Boot Actuator
8. 문서 (DOCKER_GUIDE.md)
- 빠른 시작 가이드
- Hot Reload 사용법
- 볼륨 및 네트워크 설명
- 디버깅 방법
- 문제 해결 가이드
- 유용한 명령어 모음
🚀 사용 방법
개발 환경 시작
# 전체 환경 시작
docker-compose up
# 백그라운드 실행
docker-compose up -d
# 로그 확인
docker-compose logs -f
서비스 접속
- Frontend: http://localhost:5173
- Backend API: http://localhost:8080/api
- Adminer: http://localhost:8081
- Health Check: http://localhost:8080/actuator/health
Hot Reload 테스트
1. Frontend: frontend/src/App.jsx 수정 → 브라우저 자동 새로고침
2. Backend: backend/src/main/java/**/*.java 수정 → 자동 재컴파일 및 재시작
원격 디버깅
- Backend 디버그 포트: 5005
- VS Code에서 "Docker Backend Debug" 설정 사용
쿠버네티스 매니페스트
프롬프트
> 로컬 테스트용으로 k8s manifest 를 작성해줘
k8s manifest
Kubernetes(줄여서 k8s)는 컨테이너화된 애플리케이션을 자동화해서 배포, 스케일, 관리하는 시스템
결과
Kubernetes 로컬 테스트 환경 설정이 완료되었습니다.
✅ 완료된 작업
1. Kubernetes Manifest 구조
k8s/
├── base/ # Base manifests
│ ├── namespace.yaml # running-share namespace
│ ├── configmaps.yaml # 3개 ConfigMaps (postgres, backend, frontend)
│ ├── secrets.yaml # 2개 Secrets (postgres, backend)
│ ├── pvc.yaml # Backend 업로드용 PVC
│ ├── postgres-statefulset.yaml # PostgreSQL StatefulSet + Service
│ ├── backend-deployment.yaml # Backend Deployment + Service
│ ├── frontend-deployment.yaml # Frontend Deployment + Service
│ ├── ingress.yaml # Ingress 라우팅
│ └── kustomization.yaml
├── overlays/local/ # 로컬 환경 overlay
│ ├── kustomization.yaml # Local 설정
│ ├── replica-patch.yaml # Replica 수 조정
│ └── resource-patch.yaml # 리소스 제한 조정
└── build-images.sh # 이미지 빌드 스크립트
2. 리소스 구성
Namespace
- running-share namespace 생성
ConfigMaps (3개)
- postgres-config: 데이터베이스 이름
- postgres-init-config: 초기화 SQL 스크립트
- backend-config: Spring Boot 설정 (DB URL, JPA, JWT, 파일 업로드)
- frontend-config: Vite 환경변수 (API URL)
Secrets (2개)
- postgres-secret: PostgreSQL 사용자/비밀번호 (base64)
- backend-secret: JWT Secret (base64)
StatefulSet
- PostgreSQL 16 Alpine
- Replicas: 1
- Storage: 1Gi (VolumeClaimTemplate)
- Health checks: liveness + readiness
- Init script 마운트
Deployments (2개)
- Backend (Spring Boot)
- Image: running-share-backend:latest
- Init Container: wait-for-postgres
- Health checks: liveness + readiness (Actuator)
- Volume: backend-uploads-pvc
- Resources: 250m/500m CPU, 256Mi/512Mi Memory
- Frontend (Nginx)
- Image: running-share-frontend:latest
- Health checks: liveness + readiness
- Resources: 50m/100m CPU, 64Mi/128Mi Memory
Services
- postgres: Headless Service (ClusterIP None)
- backend: ClusterIP (8080)
- frontend: ClusterIP (80)
Ingress
- Host: running-share.local
- Routes:
- / → frontend:80
- /api → backend:8080
- /actuator → backend:8080
3. Kustomize Overlays
Local Environment
- Namespace: running-share
- Name Prefix: local-
- Labels: environment: local
- Replica 조정: 모두 1개
- Resource 제한 감소 (로컬 환경 최적화)
4. Production Dockerfiles
backend/Dockerfile.prod
- Multi-stage build (builder + runtime)
- Eclipse Temurin JDK 17 Alpine
- Non-root user (spring:spring)
- Health check (Actuator)
- JAR 빌드 및 실행
frontend/Dockerfile.prod
- Multi-stage build (builder + nginx)
- Node 20 Alpine + Nginx 1.25 Alpine
- Production build (pnpm build)
- Nginx 정적 파일 서빙
- Health check endpoint
frontend/nginx.conf
- Gzip 압력
- 보안 헤더 (X-Frame-Options, X-XSS-Protection)
- Static asset 캐싱
- React Router fallback
- Health check endpoint (/health)
5. Spring Boot K8s Profile
backend/src/main/resources/application-k8s.yml
- PostgreSQL 데이터베이스 연결
- HikariCP 연결 풀 설정
- Graceful shutdown
- Actuator probes (liveness, readiness)
- Prometheus metrics 지원
- 프로덕션 로깅 레벨
6. 빌드 스크립트
k8s/build-images.sh
- Backend 프로덕션 이미지 빌드
- Frontend 프로덕션 이미지 빌드
- 빌드 상태 출력
7. 문서 (K8S_GUIDE.md)
- 사전 요구사항 (Docker, kubectl, Minikube)
- 빠른 시작 가이드
- 디렉토리 구조 설명
- 아키텍처 다이어그램
- Kustomize 사용법
- Secrets 관리
- 스토리지 관리
- 네트워킹 설정
- 모니터링 방법
- 디버깅 가이드
- 업데이트 및 롤백
- 문제 해결 (6가지 일반적인 문제)
- 유용한 명령어 모음
🚀 사용 방법
1. Minikube 시작
minikube start --cpus=4 --memory=4096
minikube addons enable ingress
2. 이미지 빌드
eval $(minikube docker-env)
./k8s/build-images.sh
3. 배포
kubectl apply -k k8s/overlays/local/
kubectl get all -n running-share
4. 접속 설정
echo "$(minikube ip) running-share.local" | sudo tee -a /etc/hosts
5. 서비스 접속
- Frontend: http://running-share.local
- Backend API: http://running-share.local/api
- Health Check: http://running-share.local/actuator/health
5. 테스트 환경 부트스트래핑
테스트 설정
프롬프트
테스트 환경을 설정해줘
- 테스트 커버리지 설정
- Jest 설정(unit test)
- React Testing Library(component test)
- Playwright(E2E test)
Jest
함수나 컴포넌트 같은 작은 단위(Unit)를 독립적으로 테스트
비즈니스 로직이 의도대로 동작하는지 검증
React Testing Libray
React 컴포넌트를 실제 화면처럼 렌더링하고 동작 테스트
Playwright
브라우저에서 실제 사용자 시나리오를 그대로 테스트
결과
테스트 환경 설정 완료
Running Course Sharing Service 프로젝트의 포괄적인 테스트 인프라를 성공적으로 구축했습니다.
백엔드 테스팅 (JUnit + JaCoCo)
설정 내용:
- JaCoCo 테스트 커버리지 플러그인 추가 (backend/build.gradle:5)
- 커버리지 목표: 전체 70%, 클래스별 60%
- 테스트용 H2 인메모리 데이터베이스 구성
- 테스트 프로필 설정 (backend/src/test/resources/application-test.yml:1)
예제 테스트 파일:
- JwtUtilTest.java - JWT 유틸리티 단위 테스트
- UserRepositoryTest.java - @DataJpaTest를 사용한 리포지토리 테스트
- UserServiceTest.java - Mockito를 사용한 서비스 레이어 테스트
실행 명령어:
cd backend
./gradlew test # 테스트 실행
./gradlew jacocoTestReport # 커버리지 리포트 생성
./gradlew check # 테스트 + 커버리지 임계값 검증
프론트엔드 테스팅 (Vitest + React Testing Library)
설정 내용:
- Vitest와 React Testing Library 설치 완료
- 전역 mock 설정 파일 (frontend/src/test/setup.js:1)
- 커스텀 테스트 유틸리티 (frontend/src/test/test-utils.jsx:1)
- Vite 설정에 커버리지 구성 (frontend/vite.config.js:7)
- 커버리지 목표: 라인, 함수, 브랜치, 구문 각 70%
예제 테스트 파일:
- App.test.jsx - 기본 앱 테스트
- Button.test.jsx - 컴포넌트 테스트 예제
- hooks.test.js - React Query 훅 테스트 예제
실행 명령어:
cd frontend
pnpm test # Watch 모드
pnpm test:ui # 비주얼 UI
pnpm test:coverage # 커버리지 리포트 포함
E2E 테스팅 (Playwright)
설정 내용:
- Playwright와 Chromium 브라우저 설치
- 설정 파일 (playwright.config.js:1)
- 테스트 전 자동으로 개발 서버 시작
- 실패 시 스크린샷/비디오 자동 저장
테스트 파일:
- e2e/example.spec.js - 기본 E2E 테스트
- e2e/auth.spec.js - 인증 플로우 테스트 템플릿
- e2e/helpers/test-helpers.js - 재사용 가능한 테스트 유틸리티
실행 명령어:
pnpm test:e2e # 모든 E2E 테스트 실행
pnpm test:e2e:ui # 인터랙티브 모드
pnpm test:e2e:report # HTML 리포트 보기
루트 레벨 통합 명령어
프로젝트 루트에서 모든 테스트 실행 가능:
pnpm test:frontend # 프론트엔드 테스트만
pnpm test:backend # 백엔드 테스트만
pnpm test:e2e # E2E 테스트만
pnpm test:coverage # 모든 커버리지 리포트 생성
pnpm test:all # 모든 테스트 실행
문서화
전체 가이드: TESTING.md:1 - 다음 내용을 포함한 종합 테스트 문서:
- 테스트 유형별 설명
- 코드 예제
- 모범 사례
- 문제 해결 가이드
- CI/CD 통합 예제
빠른 참조: .github/TEST_QUICK_REFERENCE.md:1 - 자주 사용하는 명령어 치트시트
커버리지 리포트 위치
백엔드: backend/build/reports/jacoco/test/html/index.html
프론트엔드: frontend/coverage/index.html
다음 단계
1. 설정 확인을 위한 테스트 실행:
# 프론트엔드 테스트
cd frontend && pnpm test:run
# E2E 테스트 (개발 서버 필요)
pnpm test:e2e
2. 기능 구현 시 실제 테스트 작성:
- Controller → @WebMvcTest 패턴 사용
- Service → 예제의 Mockito 패턴 따르기
- Component → React Testing Library 예제 따르기
- User Flow → E2E 스펙에 추가
3. 개발하면서 커버리지 모니터링:
pnpm test:coverage
4. CI/CD 통합 고려 - TESTING.md에 GitHub Actions 워크플로우 예제 포함됨
모든 테스트 아티팩트(리포트, 스크린샷, 커버리지)는 이미 .gitignore:26에 추가되어 있습니다.
주요 특징
✅ 백엔드: JaCoCo 커버리지 70% 목표, H2 인메모리 DB 사용
✅ 프론트엔드: Vitest + React Testing Library, 70% 커버리지 목표
✅ E2E: Playwright, 자동 스크린샷/비디오 캡처
✅ 문서: 상세한 가이드와 빠른 참조 문서 완비
✅ 예제 테스트: 각 테스트 유형별 실전 예제 코드 포함
6. 부트스트래핑
프롬프트
> 현재까지 구상된 문서 및 설계를 바탕으로 MVP 를 구현해줘
docker-compose 를 통해 실행 가능한 형태로, 구현 내용은 playwright 를 통해 검증해줘
결과
🎉 MVP 구현 완료!
러닝 코스 공유 서비스 MVP를 성공적으로 완전히 구현했습니다!
✅ 구현된 내용
백엔드 (Spring Boot)
- 18개의 REST API 엔드포인트 (인증, 코스, 댓글, 좋아요, 북마크)
- JWT 인증 및 권한 부여
- 관계가 설정된 6개의 JPA 엔티티
- 비즈니스 로직을 가진 5개의 서비스
- 커스텀 쿼리를 포함한 6개의 리포지토리
- PostgreSQL 통합
프론트엔드 (React + Vite)
- 8개의 재사용 가능한 컴포넌트
- 라우팅이 적용된 6개의 페이지
- 서버 상태 관리를 위한 React Query
- 인증 컨텍스트 및 보호된 라우트
- 인터셉터가 적용된 Axios API 클라이언트
- TailwindCSS 반응형 디자인
Docker 구성
- 3계층 아키텍처 (PostgreSQL + 백엔드 + 프론트엔드)
- 최적화를 위한 멀티 스테이지 빌드
- Nginx 리버스 프록시
- 모든 서비스의 헬스 체크
- 영구 볼륨
- 자동화된 시작 스크립트
E2E 테스트 (Playwright)
- 52개 이상의 테스트 케이스
- 인증 플로우
- 코스 CRUD 작업
- 댓글 및 소셜 기능
- 검색 기능
- 멀티 브라우저 지원
7. 결과
****JWT 라이브러리 API 호환성 오류
문제: JwtUtil.java에서 parserBuilder() 메서드를 찾을 수 없음
해결: JwtUtil.java:28 - 새로운 API로 변경
Lombok @Builder 경고
문제: AuthResponse.java에서 초기화 표현식이 무시된다는 경고
해결: AuthResponse.java:14 - @Builder.Default 어노테이션 추가
Frontend npm workspace 프로토콜 오류
문제: Docker 빌드 시 workspace 프로토콜을 인식하지 못함
해결:
frontend/Dockerfile 전체 재작성 - npm 대신 pnpm 사용
빌드 컨텍스트를 루트로 변경하여 monorepo 전체 구조 복사
docker-compose.yml - frontend 빌드 컨텍스트를 .으로 변경
AWS S3 자동 설정 오류
문제: Spring Boot 시작 시 AWS region을 찾을 수 없음
해결: RunningShareServiceApplication.java:8 - S3 자동 설정 제외
Actuator Health 엔드포인트 403 Forbidden
문제: /actuator/health 엔드포인트 접근 시 403 오류
SecurityConfig.java:46 - permitAll() 추가
Frontend "Error loading courses" 오류 (1차)
문제: 홈페이지에서 "Error loading courses" 메시지 표시
해결: courseService.js - 모든 메서드에서 response.data.data 반환하도록 수정
Frontend "Error loading courses" 오류 (2차)
문제: 코드 수정 후에도 여전히 오류 발생
해결:
frontend/.env 및 .env.local - 상대 경로로 변경 VITE_API_BASE_URL=/api
api.js:3 - baseURL 변경 baseURL: '/api' // nginx를 통한 프록시 사용
