- Published on
프레임워크별 디버깅 실전: Spring Boot · Django/FastAPI · React/Next.js에서 브레이크포인트, 실행, 프로파일링
- Authors
- Name
프레임워크 디버깅의 핵심
언어보다 먼저 봐야 할 건 프레임워크의 실행 흐름이다.
- 요청 진입점(Controller/View/Route)
- 미들웨어/필터
- 데이터 접근 계층
- 외부 API 호출
- 렌더링/하이드레이션
디버깅은 이 흐름의 어느 단계에서 데이터가 깨지는지 찾는 작업이다.
1) Spring Boot
실행/디버그 시작
./gradlew bootRun
# 또는
./mvnw spring-boot:run
원격 디버그:
JAVA_TOOL_OPTIONS='-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005' ./gradlew bootRun
브레이크포인트 추천 위치
- Controller 진입
- Service 비즈니스 분기
- Repository 쿼리 직전
- ExceptionHandler
- Filter/Interceptor(인증/권한)
프로파일링
- Micrometer + Prometheus + Grafana: 요청/에러/지연시간 관측
- JFR/async-profiler: CPU/alloc 병목
- SQL 로그 + 실행계획: N+1/슬로우쿼리 확인
# application.yml (디버그 시)
logging.level.org.hibernate.SQL=DEBUG
logging.level.org.hibernate.orm.jdbc.bind=TRACE
2) Django
실행
python manage.py runserver
브레이크포인트
def create_order(request):
breakpoint()
...
추천 위치:
- View 진입
- Serializer 유효성 검사
- ORM 쿼리 직전/직후
- Middleware 인증/세션 처리
프로파일링
- Django Debug Toolbar: 쿼리 수, 템플릿 렌더링
- Silk/py-spy: 느린 뷰 추적
- gunicorn worker 단위 CPU 샘플링
N+1 대응:
Order.objects.select_related('user').prefetch_related('items')
3) FastAPI
실행
uvicorn app.main:app --reload
브레이크포인트 추천
- Router 함수
- Dependency injection 함수
- 외부 API 호출 함수
- 예외 핸들러
프로파일링
- py-spy로 PID 샘플링
- OpenTelemetry로 endpoint/외부 호출 trace 연결
- pydantic validation 비용(대용량 payload) 체크
py-spy top --pid <PID>
4) React
실행
npm run dev
브레이크포인트 전략
- 이벤트 핸들러(onClick/onSubmit)
- 상태 업데이트 직전(setState/useState)
- useEffect 의존성 경계
- API 응답 파싱 지점
프로파일링
- React DevTools Profiler: 불필요 렌더 탐지
- why-did-you-render: 리렌더 원인 파악
- Web Vitals(LCP/INP/CLS) 추적
체크 포인트:
- key 안정성
- memo/useMemo/useCallback 남용/누락
- context 과도한 전파
5) Next.js
실행
npm run dev
npm run build && npm run start
자주 터지는 이슈
- 서버/클라이언트 렌더 불일치(hydration mismatch)
- API route 에러 삼킴
- Edge/runtime 차이
- 이미지/캐시 정책 오해
브레이크포인트 포인트
- App Router의 server component 데이터 fetch
- route handler (
app/api/.../route.ts) - client component 이벤트 핸들러
- middleware.ts
프로파일링
- Next build output으로 번들 크기 확인
- Chrome Performance로 hydration 비용 측정
- 서버 로그 + tracing으로 API 지연 원인 분리
프레임워크 공통 디버깅 플레이북
- 요청 ID 강제: 프론트
백엔드DB까지 하나의 ID로 추적 - 경계에서 검증: 입력 DTO, 외부 응답, DB write 직전
- 환경 분리 테스트: dev만 되는 버그 제거
- 관측 우선: 로그보다 메트릭/트레이싱 먼저 붙이기
- 회귀 테스트화: 잡은 버그는 테스트로 고정
결론
프레임워크 디버깅의 승패는 “어디에 브레이크포인트를 찍을지”에서 갈린다. 흐름을 이해하고 경계 지점을 잡으면, 복잡한 장애도 빠르게 분해할 수 있다.
문제는 프레임워크가 복잡해서 생기는 게 아니라, 실행 흐름이 보이지 않아서 커진다.