✍️ 필사 모드: 프레임워크별 디버깅 실전: Spring Boot · Django/FastAPI · React/Next.js에서 브레이크포인트, 실행, 프로파일링

# Gradle
./gradlew bootRun

# Maven
./mvnw spring-boot:run

# 특정 프로파일로 실행
./gradlew bootRun --args='--spring.profiles.active=dev'

JAVA_TOOL_OPTIONS='-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005' ./gradlew bootRun

// HandlerInterceptor로 요청 흐름 추적
@Component
public class RequestTracingInterceptor implements HandlerInterceptor {

    @Override
    public boolean preHandle(HttpServletRequest request,
                             HttpServletResponse response,
                             Object handler) {
        // 여기에 브레이크포인트 — 모든 요청의 첫 진입점
        String requestId = request.getHeader("X-Request-Id");
        MDC.put("requestId", requestId);
        log.info("Incoming: {} {} requestId={}", request.getMethod(),
                 request.getRequestURI(), requestId);
        return true;
    }

    @Override
    public void afterCompletion(HttpServletRequest request,
                                HttpServletResponse response,
                                Object handler, Exception ex) {
        // 여기에 브레이크포인트 — 응답 직전에 예외 확인
        if (ex != null) {
            log.error("Request failed: requestId={}", MDC.get("requestId"), ex);
        }
        MDC.clear();
    }
}

# application.yml — 개발/디버그 시 SQL 로깅 설정
spring:
  jpa:
    show-sql: true
    properties:
      hibernate:
        format_sql: true
        # 실행되는 SQL 파라미터까지 확인
        generate_statistics: true

logging:
  level:
    org.hibernate.SQL: DEBUG
    org.hibernate.orm.jdbc.bind: TRACE # 바인딩 파라미터 출력
    org.hibernate.stat: DEBUG # 쿼리 통계
    org.springframework.transaction: TRACE # 트랜잭션 경계 확인

// N+1 감지: 쿼리 카운트 검증 테스트
@Test
void shouldNotCauseNPlusOne() {
    // given
    long queryCountBefore = getQueryCount();

    // when
    List<Order> orders = orderService.findAllWithItems();

    // then
    long queryCountAfter = getQueryCount();
    assertThat(queryCountAfter - queryCountBefore)
        .as("N+1 쿼리 발생 확인")
        .isLessThanOrEqualTo(2); // SELECT orders + SELECT items
}

python manage.py runserver

# 특정 포트로 실행
python manage.py runserver 0.0.0.0:8080

# shell_plus로 인터랙티브 디버깅
python manage.py shell_plus --print-sql

def create_order(request):
    breakpoint()  # View 진입점에서 요청 객체 확인
    serializer = OrderSerializer(data=request.data)
    serializer.is_valid(raise_exception=True)
    # ...

# 커스텀 미들웨어로 요청/응답 추적
class RequestDebugMiddleware:
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        # 요청 진입 — 여기에 브레이크포인트
        import time
        start = time.time()

        response = self.get_response(request)

        # 응답 직전 — 느린 요청 감지
        duration = time.time() - start
        if duration > 1.0:  # 1초 초과 시 경고
            import logging
            logger = logging.getLogger(__name__)
            logger.warning(
                f"Slow request: {request.method} {request.path} "
                f"took {duration:.2f}s"
            )

        return response

# settings.py — SQL 로깅 설정
LOGGING = {
    'version': 1,
    'handlers': {
        'console': {
            'class': 'logging.StreamHandler',
        },
    },
    'loggers': {
        'django.db.backends': {
            'level': 'DEBUG',      # 모든 SQL 쿼리 출력
            'handlers': ['console'],
        },
    },
}

# 테스트에서 쿼리 수 검증 — N+1 방지
from django.test.utils import override_settings

class OrderQueryTest(TestCase):
    def test_no_n_plus_one(self):
        # 10개 주문 생성
        create_test_orders(10)

        # 쿼리 수 제한 검증
        with self.assertNumQueries(2):  # orders + items 2개 쿼리만 허용
            orders = Order.objects.select_related('user') \
                                  .prefetch_related('items').all()
            # 결과를 평가해야 쿼리가 실행됨
            list(orders)

# 나쁜 예: N+1 발생
orders = Order.objects.all()
for order in orders:
    print(order.user.name)       # 주문마다 user 쿼리 발생
    print(order.items.count())   # 주문마다 items 쿼리 발생

# 좋은 예: 2개 쿼리로 해결
orders = Order.objects.select_related('user').prefetch_related('items').all()
for order in orders:
    print(order.user.name)       # 캐시에서 조회
    print(order.items.count())   # 캐시에서 조회

# 개발 모드 (자동 리로드)
uvicorn app.main:app --reload --log-level debug

# 프로덕션 모드
uvicorn app.main:app --workers 4 --host 0.0.0.0 --port 8000

from starlette.middleware.base import BaseHTTPMiddleware
import time
import logging

logger = logging.getLogger(__name__)

class TimingMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request, call_next):
        # 여기에 브레이크포인트 — 요청 진입점
        start = time.time()
        request_id = request.headers.get("X-Request-Id", "unknown")

        try:
            response = await call_next(request)
        except Exception as exc:
            # 미들웨어에서 잡히지 않는 예외 추적
            logger.error(f"Unhandled error: {request_id} {exc}", exc_info=True)
            raise

        duration = time.time() - start
        response.headers["X-Response-Time"] = f"{duration:.3f}s"

        if duration > 1.0:
            logger.warning(
                f"Slow: {request.method} {request.url.path} "
                f"{duration:.2f}s requestId={request_id}"
            )

        return response

# 나쁜 예: async 함수에서 동기 I/O 호출 → 이벤트 루프 블로킹
@app.get("/users/{user_id}")
async def get_user(user_id: int):
    # requests.get은 동기 호출 → 전체 서버 블로킹
    response = requests.get(f"http://external-api/users/{user_id}")
    return response.json()

# 좋은 예 1: httpx 비동기 클라이언트 사용
@app.get("/users/{user_id}")
async def get_user(user_id: int):
    async with httpx.AsyncClient() as client:
        response = await client.get(f"http://external-api/users/{user_id}")
    return response.json()

# 좋은 예 2: 동기 코드를 run_in_executor로 감싸기
import asyncio

@app.get("/report")
async def generate_report():
    loop = asyncio.get_event_loop()
    # CPU-bound 작업을 스레드풀에서 실행
    result = await loop.run_in_executor(None, heavy_computation)
    return {"result": result}

# SQLAlchemy SQL 로깅 활성화
import logging
logging.getLogger('sqlalchemy.engine').setLevel(logging.DEBUG)

# 또는 create_engine에서 직접 설정
from sqlalchemy import create_engine
engine = create_engine(DATABASE_URL, echo=True)  # echo=True → SQL 출력

# py-spy로 PID 샘플링
py-spy top --pid <PID>

# flamegraph 생성
py-spy record -o profile.svg --pid <PID>

npm run dev
# 또는
npx vite   # Vite 프로젝트

// why-did-you-render로 불필요 리렌더 감지
// wdyr.ts (앱 진입점 전에 import)
import React from 'react'

if (process.env.NODE_ENV === 'development') {
  const whyDidYouRender = require('@welldone-software/why-did-you-render')
  whyDidYouRender(React, {
    trackAllPureComponents: true,
    logOnDifferentValues: true,
  })
}

// 감시할 컴포넌트에 표시
const OrderList: React.FC<Props> = ({ orders }) => {
  return (
    <ul>
      {orders.map((order) => (
        <OrderItem key={order.id} order={order} />
      ))}
    </ul>
  )
}
OrderList.whyDidYouRender = true

// useEffect 무한 루프 디버깅
function UserProfile({ userId }: { userId: string }) {
  const [user, setUser] = useState(null)

  // 나쁜 예: 매 렌더마다 새 객체가 의존성에 들어감
  // const options = { include: ['orders'] }  // 렌더마다 새 참조
  // useEffect(() => { fetchUser(userId, options) }, [userId, options])

  // 좋은 예: useMemo로 참조 안정화
  const options = useMemo(() => ({ include: ['orders'] }), [])
  useEffect(() => {
    fetchUser(userId, options).then(setUser)
  }, [userId, options]) // options가 안정적이므로 무한 루프 방지
}

# 개발 모드
npm run dev

# 프로덕션 빌드 + 실행
npm run build && npm run start

# Turbopack으로 빠른 개발 서버
npx next dev --turbopack

// Server Component 디버깅 — console.log가 서버 터미널에 출력됨
// app/orders/page.tsx
export default async function OrdersPage() {
  // 서버에서만 실행 — 브라우저 콘솔에 안 보임
  console.log('[SERVER] Fetching orders...')

  const orders = await db.order.findMany({
    include: { user: true, items: true },
  })

  console.log(`[SERVER] Found ${orders.length} orders`)

  return <OrderList orders={orders} />
}

// 'use client'를 빼먹으면 에러 — 서버 컴포넌트에서 훅 사용 불가
// "useState is not a function" 에러의 원인
'use client' // 반드시 파일 최상단에 선언

import { useState } from 'react'

export function Counter() {
  const [count, setCount] = useState(0)
  return <button onClick={() => setCount((c) => c + 1)}>{count}</button>
}

// Route Handler (app/api/orders/route.ts)
import { NextResponse } from 'next/server'

export async function GET(request: Request) {
  try {
    const { searchParams } = new URL(request.url)
    const status = searchParams.get('status')

    console.log('[API] GET /api/orders status=', status)

    const orders = await db.order.findMany({
      where: status ? { status } : undefined,
    })

    return NextResponse.json(orders)
  } catch (error) {
    // 에러 삼킴 방지 — 반드시 로그 남기기
    console.error('[API] GET /api/orders failed:', error)
    return NextResponse.json({ error: 'Internal Server Error' }, { status: 500 })
  }
}

// 흔한 원인 1: 서버/클라이언트에서 다른 값 렌더
// 나쁜 예
function Greeting() {
  // Date.now()는 서버와 클라이언트에서 다른 값
  return <p>Timestamp: {Date.now()}</p>
}

// 좋은 예: suppressHydrationWarning 또는 useEffect로 처리
function Greeting() {
  const [timestamp, setTimestamp] = useState<number | null>(null)

  useEffect(() => {
    setTimestamp(Date.now())
  }, [])

  return <p>Timestamp: {timestamp ?? 'Loading...'}</p>
}

# 번들 크기 분석
ANALYZE=true npm run build
# next.config.js에 @next/bundle-analyzer 설정 필요

# Spring Boot — SQL 로깅 + 메트릭 (build.gradle에 추가)
# implementation 'io.micrometer:micrometer-registry-prometheus'
# implementation 'com.github.gavlyukovskiy:p6spy-spring-boot-starter:1.9.0'

# Django — 디버그 도구 일괄 설치
pip install django-debug-toolbar django-silk nplusone

# FastAPI — 프로파일링 + 트레이싱
pip install py-spy opentelemetry-api opentelemetry-sdk opentelemetry-instrumentation-fastapi

# React — 리렌더 분석
npm install -D @welldone-software/why-did-you-render

# Next.js — 번들 분석
npm install -D @next/bundle-analyzer