언어×프레임워크 조합별 실전 장애 사례집: Python·JS/TS·Go·Java + FastAPI·Django·Next.js·NestJS·Gin·Spring Boot

# bad_endpoint.py — 이 코드가 전체 서버를 멈춘다
import time
from fastapi import FastAPI

app = FastAPI()

@app.get("/slow")
async def slow_endpoint():
    # 동기 sleep이 event loop을 3초간 점유
    time.sleep(3)
    return {"status": "done"}

@app.get("/health")
async def health():
    return {"status": "ok"}

# 터미널 1: 서버 기동
uvicorn bad_endpoint:app --host 0.0.0.0 --port 8000

# 터미널 2: /slow 호출 중 /health도 3초 걸리는지 확인
curl http://localhost:8000/slow &
sleep 0.5
time curl http://localhost:8000/health
# health가 2.5초 걸리면 event loop blocking 확정

# 실시간 CPU 스택 확인
py-spy top --pid $(pgrep -f uvicorn)

# 플레임 그래프 생성
py-spy record -o flamegraph.svg --pid $(pgrep -f uvicorn) -d 30

# asyncio slow callback 임계값 조정 (0.1초 이상이면 경고)

import asyncio
loop = asyncio.get_event_loop()
loop.slow_callback_duration = 0.1  # 100ms

import asyncio
from fastapi import FastAPI
from functools import partial

app = FastAPI()

def cpu_heavy_task(data: dict) -> dict:
    """동기 함수 — CPU 바운드 작업"""
    import time
    time.sleep(3)  # 실제로는 복잡한 계산
    return {"result": "processed"}

@app.get("/slow-fixed")
async def slow_endpoint_fixed():
    # 방법 1: run_in_executor로 스레드풀에 위임
    loop = asyncio.get_event_loop()
    result = await loop.run_in_executor(None, partial(cpu_heavy_task, {}))
    return result

# 방법 2: def로 선언하면 FastAPI가 자동으로 threadpool에서 실행
@app.get("/slow-fixed-v2")
def slow_endpoint_sync():
    import time
    time.sleep(3)
    return {"status": "done"}

from pydantic import BaseModel
from fastapi import FastAPI
from typing import List

class Item(BaseModel):
    name: str
    price: float
    category: str
    tags: List[str]

class BulkRequest(BaseModel):
    items: List[Item]  # 5000개 아이템 → validation만 2초+

app = FastAPI()

@app.post("/bulk")
async def bulk_create(req: BulkRequest):
    return {"count": len(req.items)}

# 5000개 아이템 벤치마크
python -c "
import json, requests, time
items = [{'name': f'item-{i}', 'price': 9.99, 'category': 'test', 'tags': ['a','b']} for i in range(5000)]
start = time.time()
r = requests.post('http://localhost:8000/bulk', json={'items': items})
print(f'Time: {time.time()-start:.2f}s, Status: {r.status_code}')
"

py-spy record -o pydantic_profile.svg --pid $(pgrep -f uvicorn) -d 10
# pydantic.validators 관련 프레임이 대부분을 차지하면 확정

# 1) Pydantic v2 사용 (Rust 기반 core, 5~50x 빠름)
# pyproject.toml: pydantic>=2.0

# 2) 대량 입력은 스트리밍 처리
from fastapi import Request
import orjson

@app.post("/bulk-stream")
async def bulk_stream(request: Request):
    body = await request.body()
    data = orjson.loads(body)  # Pydantic 검증 건너뛰고 직접 파싱
    # 필수 필드만 수동 검증
    validated = []
    for item in data.get("items", []):
        if "name" in item and "price" in item:
            validated.append(item)
    return {"count": len(validated)}

# models.py
from django.db import models

class Customer(models.Model):
    name = models.CharField(max_length=100)

class Order(models.Model):
    customer = models.ForeignKey(Customer, on_delete=models.CASCADE)
    total = models.DecimalField(max_digits=10, decimal_places=2)
    created_at = models.DateTimeField(auto_now_add=True)

class OrderItem(models.Model):
    order = models.ForeignKey(Order, on_delete=models.CASCADE, related_name='items')
    product_name = models.CharField(max_length=200)
    quantity = models.IntegerField()

# views.py — N+1 발생 코드
def order_list(request):
    orders = Order.objects.all()[:100]
    data = []
    for order in orders:
        data.append({
            'customer': order.customer.name,        # 쿼리 1번씩 (N)
            'items': [i.product_name for i in order.items.all()],  # 쿼리 1번씩 (N)
            'total': order.total,
        })
    # 총 쿼리: 1 + 100 + 100 = 201개
    return JsonResponse(data, safe=False)

# django-debug-toolbar 설치 (개발 환경)
pip install django-debug-toolbar

# settings.py
INSTALLED_APPS += ['debug_toolbar']
MIDDLEWARE.insert(0, 'debug_toolbar.middleware.DebugToolbarMiddleware')

# nplusone 라이브러리로 자동 탐지
pip install nplusone
# settings.py
INSTALLED_APPS += ['nplusone.ext.django']
MIDDLEWARE.insert(0, 'nplusone.ext.django.NPlusOneMiddleware')
NPLUSONE_RAISE = True  # N+1 발생 시 예외 발생

-- PostgreSQL에서 슬로우쿼리 확인
SELECT query, calls, mean_exec_time, total_exec_time
FROM pg_stat_statements
ORDER BY total_exec_time DESC
LIMIT 20;

# views.py — 수정 후
def order_list(request):
    orders = (
        Order.objects
        .select_related('customer')          # JOIN으로 1회
        .prefetch_related('items')           # IN 쿼리로 1회
        .all()[:100]
    )
    data = []
    for order in orders:
        data.append({
            'customer': order.customer.name,
            'items': [i.product_name for i in order.items.all()],
            'total': order.total,
        })
    # 총 쿼리: 1(orders) + 1(customers JOIN) + 1(items IN) = 2~3개
    return JsonResponse(data, safe=False)

# BAD — 트랜잭션 경계 없음
def create_payment(request):
    order = Order.objects.create(customer_id=1, total=100)
    # 여기서 예외 발생하면 order는 이미 커밋됨
    payment = Payment.objects.create(order=order, amount=100)
    send_notification(order)  # 외부 API 호출
    return JsonResponse({"order_id": order.id})

# GOOD — 명시적 트랜잭션
from django.db import transaction

def create_payment(request):
    with transaction.atomic():
        order = Order.objects.create(customer_id=1, total=100)
        payment = Payment.objects.create(order=order, amount=100)
    # 트랜잭션 밖에서 부수효과 실행
    send_notification(order)
    return JsonResponse({"order_id": order.id})

// app/dashboard/page.tsx — Hydration Mismatch 발생
export default function Dashboard() {
  // 서버: "2026-03-07T09:00:00Z", 클라이언트: "2026-03-07T09:00:03Z"
  const now = new Date().toISOString()

  // 서버에는 localStorage가 없으므로 null, 클라이언트는 "dark"
  const theme = typeof window !== 'undefined' ? localStorage.getItem('theme') : null

  return (
    <div className={theme === 'dark' ? 'dark' : 'light'}>
      <p>현재 시각: {now}</p>
      <p>테마: {theme ?? 'default'}</p>
    </div>
  )
}

# Next.js 빌드 분석
ANALYZE=true next build

# 서버 사이드 렌더링 결과 직접 확인
curl -s http://localhost:3000/dashboard | prettier --parser html > server.html
# 브라우저에서 document.documentElement.outerHTML 복사 후 비교
diff server.html client.html

'use client'

import { useState, useEffect } from 'react'

export default function Dashboard() {
  const [now, setNow] = useState<string>('')
  const [theme, setTheme] = useState<string>('default')

  // 클라이언트 전용 값은 useEffect에서 설정
  useEffect(() => {
    setNow(new Date().toISOString())
    setTheme(localStorage.getItem('theme') ?? 'default')
  }, [])

  return (
    <div className={theme === 'dark' ? 'dark' : 'light'}>
      {/* 초기에는 빈 값 → hydration 일치 → useEffect 후 갱신 */}
      <p>현재 시각: {now || '로딩 중...'}</p>
      <p>테마: {theme}</p>
    </div>
  )
}

// 대안: next/dynamic으로 클라이언트 전용 컴포넌트 분리
import dynamic from 'next/dynamic'

const ClientClock = dynamic(() => import('./ClientClock'), {
  ssr: false,
  loading: () => <p>로딩 중...</p>,
})

export default function Dashboard() {
  return (
    <div>
      <h1>대시보드</h1>
      <ClientClock />
    </div>
  )
}

// cache.service.ts — 메모리 누수 패턴
import { Injectable } from '@nestjs/common'

@Injectable()
export class CacheService {
  // 싱글턴이므로 앱 생애주기 동안 계속 커짐
  private cache = new Map<string, any>()

  set(key: string, value: any) {
    this.cache.set(key, value) // 삭제/만료 로직 없음
  }

  get(key: string) {
    return this.cache.get(key)
  }
}

# Node.js 인스펙터 모드로 시작
node --inspect dist/main.js

# 또는 NestJS CLI
nest start --debug

# clinic.js로 자동 분석
npx clinic doctor -- node dist/main.js
npx clinic heap -- node dist/main.js

// cache.service.ts — 수정
import { Injectable } from '@nestjs/common'

interface CacheEntry {
  value: any
  expireAt: number
}

@Injectable()
export class CacheService {
  private cache = new Map<string, CacheEntry>()
  private readonly MAX_SIZE = 10000
  private readonly DEFAULT_TTL = 5 * 60 * 1000 // 5분

  set(key: string, value: any, ttl = this.DEFAULT_TTL) {
    // 크기 제한 초과 시 가장 오래된 항목 제거
    if (this.cache.size >= this.MAX_SIZE) {
      const firstKey = this.cache.keys().next().value
      if (firstKey) this.cache.delete(firstKey)
    }
    this.cache.set(key, { value, expireAt: Date.now() + ttl })
  }

  get(key: string) {
    const entry = this.cache.get(key)
    if (!entry) return null
    if (Date.now() > entry.expireAt) {
      this.cache.delete(key)
      return null
    }
    return entry.value
  }
}

// BAD — Promise rejection이 삼켜진다
@Post('/process')
async processData(@Body() data: any) {
  // fire-and-forget: 에러가 발생해도 아무 로그 없음
  this.heavyService.processInBackground(data);
  return { status: 'accepted' };
}

// GOOD — 에러 처리 보장
@Post('/process')
async processData(@Body() data: any) {
  // 방법 1: await로 에러 전파
  try {
    await this.heavyService.processInBackground(data);
  } catch (error) {
    this.logger.error('Background processing failed', error);
    throw new InternalServerErrorException('Processing failed');
  }
  return { status: 'accepted' };

  // 방법 2: fire-and-forget이 필요하면 .catch() 필수
  this.heavyService.processInBackground(data)
    .catch(err => this.logger.error('Background task failed', err));
  return { status: 'accepted' };
}

// main.ts — 전역 unhandled rejection 감시
process.on('unhandledRejection', (reason, promise) => {
  console.error('Unhandled Rejection at:', promise, 'reason:', reason)
  // Sentry 등에 보고
})

// BAD — goroutine leak
func (h *Handler) FetchData(c *gin.Context) {
    results := make(chan string, 3)

    for _, url := range []string{urlA, urlB, urlC} {
        go func(u string) {
            // context 없이 호출 → 클라이언트가 끊어도 goroutine은 살아있음
            resp, err := http.Get(u)
            if err != nil {
                return // 채널에 안 보내고 리턴 → 수신자는 영원히 대기
            }
            defer resp.Body.Close()
            body, _ := io.ReadAll(resp.Body)
            results <- string(body)
        }(url)
    }

    // 3개 모두 올 때까지 대기 — 하나라도 실패하면 영원히 블로킹
    var data []string
    for i := 0; i < 3; i++ {
        data = append(data, <-results)
    }

    c.JSON(200, gin.H{"data": data})
}

# Delve로 실행 중인 프로세스에 attach
dlv attach $(pgrep myservice)
(dlv) goroutines
(dlv) goroutine <id> bt  # 특정 goroutine 스택 확인

// main.go에 pprof 엔드포인트 추가
import _ "net/http/pprof"

func main() {
    go func() {
        log.Println(http.ListenAndServe(":6060", nil))
    }()
    // ...
}

# goroutine 프로파일
go tool pprof http://localhost:6060/debug/pprof/goroutine

# 10초간 CPU 프로파일
go tool pprof http://localhost:6060/debug/pprof/profile?seconds=10

# 히프 프로파일
go tool pprof http://localhost:6060/debug/pprof/heap

// GOOD — context 전파 + 타임아웃 + errgroup
import (
    "context"
    "golang.org/x/sync/errgroup"
    "net/http"
    "time"
)

func (h *Handler) FetchData(c *gin.Context) {
    // 요청 context에 타임아웃 추가
    ctx, cancel := context.WithTimeout(c.Request.Context(), 5*time.Second)
    defer cancel()

    g, ctx := errgroup.WithContext(ctx)
    urls := []string{urlA, urlB, urlC}
    results := make([]string, len(urls))

    for i, url := range urls {
        i, url := i, url
        g.Go(func() error {
            req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
            if err != nil {
                return err
            }
            resp, err := http.DefaultClient.Do(req)
            if err != nil {
                return err
            }
            defer resp.Body.Close()
            body, err := io.ReadAll(resp.Body)
            if err != nil {
                return err
            }
            results[i] = string(body)
            return nil
        })
    }

    if err := g.Wait(); err != nil {
        c.JSON(500, gin.H{"error": err.Error()})
        return
    }

    c.JSON(200, gin.H{"data": results})
}

// goroutine leak 테스트
import "go.uber.org/goleak"

func TestMain(m *testing.M) {
    goleak.VerifyTestMain(m)
}

# application.yml — 문제를 유발하는 기본 설정
spring:
  datasource:
    hikari:
      maximum-pool-size: 10 # 기본값
      connection-timeout: 30000 # 30초 대기 후 예외
server:
  tomcat:
    threads:
      max: 200 # 기본값

# 부하 테스트로 재현
wrk -t12 -c200 -d30s http://localhost:8080/api/orders

# 또는 간단히
ab -n 5000 -c 200 http://localhost:8080/api/orders

# 스레드 덤프
jstack $(pgrep -f 'spring-boot') > thread_dump.txt
# "WAITING on com.zaxxer.hikari" 패턴 검색

# JFR(Java Flight Recorder) 기록
jcmd $(pgrep -f 'spring-boot') JFR.start duration=60s filename=recording.jfr

# async-profiler
./asprof -d 30 -f profile.html $(pgrep -f 'spring-boot')

# HikariCP 메트릭 로깅 활성화
logging.level.com.zaxxer.hikari=DEBUG
logging.level.com.zaxxer.hikari.HikariConfig=DEBUG

curl http://localhost:8080/actuator/metrics/hikaricp.connections.active
curl http://localhost:8080/actuator/metrics/hikaricp.connections.pending

# application.yml — 수정
spring:
  datasource:
    hikari:
      maximum-pool-size: 30 # 서버 코어 수 * 2 + 스핀들 수
      minimum-idle: 10
      connection-timeout: 5000 # 5초로 단축 (빠른 실패)
      leak-detection-threshold: 10000 # 10초 이상 반환 안 하면 경고
      metrics:
        enabled: true
server:
  tomcat:
    threads:
      max: 50 # 커넥션 풀에 맞춰 축소
    accept-count: 100

// 비동기 처리로 스레드 점유 최소화
@RestController
public class OrderController {

    @GetMapping("/api/orders")
    public CompletableFuture<List<Order>> getOrders() {
        return CompletableFuture.supplyAsync(() -> {
            return orderService.findAll();
        }, taskExecutor);  // 별도 스레드풀 사용
    }
}

@Entity
public class Team {
    @Id @GeneratedValue
    private Long id;
    private String name;

    @OneToMany(mappedBy = "team", fetch = FetchType.LAZY)
    private List<Member> members;
}

@Entity
public class Member {
    @Id @GeneratedValue
    private Long id;
    private String name;

    @ManyToOne(fetch = FetchType.LAZY)
    private Team team;
}

// N+1 발생
@GetMapping("/teams")
public List<TeamDto> getTeams() {
    List<Team> teams = teamRepository.findAll(); // 쿼리 1개
    return teams.stream().map(team -> new TeamDto(
        team.getName(),
        team.getMembers().size()  // team마다 쿼리 1개씩 추가 (N개)
    )).toList();
}

# application.yml
logging:
  level:
    org.hibernate.SQL: DEBUG
    org.hibernate.orm.jdbc.bind: TRACE
spring:
  jpa:
    properties:
      hibernate:
        generate_statistics: true

# p6spy로 실제 바인딩 파라미터 포함 SQL 확인
# build.gradle
# implementation 'com.github.gavlyukovskiy:p6spy-spring-boot-starter:1.9.0'

// 방법 1: JPQL fetch join
@Query("SELECT t FROM Team t JOIN FETCH t.members")
List<Team> findAllWithMembers();

// 방법 2: @EntityGraph
@EntityGraph(attributePaths = {"members"})
List<Team> findAll();

// 방법 3: Projection DTO (가장 효율적)
@Query("""
    SELECT new com.example.dto.TeamDto(t.name, SIZE(t.members))
    FROM Team t
    """)
List<TeamDto> findAllTeamSummaries();

// BAD — flush 전에 native query 실행
@Transactional
public void processOrder(Long orderId) {
    Order order = orderRepository.findById(orderId).orElseThrow();
    order.setStatus("PROCESSED");
    orderRepository.save(order);  // 아직 DB에 flush 안 됨

    // native query는 영속성 컨텍스트를 모름 → 이전 상태 조회
    int count = em.createNativeQuery("SELECT count(*) FROM orders WHERE status = 'PROCESSED'")
                  .getSingleResult();
}

// GOOD — 명시적 flush
@Transactional
public void processOrder(Long orderId) {
    Order order = orderRepository.findById(orderId).orElseThrow();
    order.setStatus("PROCESSED");
    orderRepository.saveAndFlush(order);  // 즉시 DB에 반영

    int count = em.createNativeQuery("SELECT count(*) FROM orders WHERE status = 'PROCESSED'")
                  .getSingleResult();
}

// BAD — race condition 발생
function SearchResults() {
  const [query, setQuery] = useState('')
  const [results, setResults] = useState([])

  useEffect(() => {
    if (!query) return

    // 이전 요청을 취소하지 않으므로,
    // 느린 응답이 빠른 응답을 덮어쓸 수 있다
    fetch(`/api/search?q=${query}`)
      .then((res) => res.json())
      .then((data) => setResults(data))
  }, [query])

  return (
    <div>
      <input value={query} onChange={(e) => setQuery(e.target.value)} placeholder="검색어 입력" />
      <ul>
        {results.map((r) => (
          <li key={r.id}>{r.title}</li>
        ))}
      </ul>
    </div>
  )
}

// 디버깅용: 요청/응답 순서 로깅
useEffect(() => {
  if (!query) return
  const requestId = Date.now()
  console.log(`[REQ ${requestId}] query="${query}"`)

  fetch(`/api/search?q=${query}`)
    .then((res) => res.json())
    .then((data) => {
      console.log(`[RES ${requestId}] query="${query}" results=${data.length}`)
      setResults(data)
    })
}, [query])

// 출력 예시:
// [REQ 1001] query="r"
// [REQ 1002] query="re"
// [REQ 1003] query="rea"
// [RES 1003] query="rea" results=15    ← 먼저 도착
// [RES 1001] query="r" results=100     ← 나중에 도착, "rea" 결과를 덮어씀!
// [RES 1002] query="re" results=50

// GOOD — AbortController로 이전 요청 취소
function SearchResults() {
  const [query, setQuery] = useState('')
  const [results, setResults] = useState([])

  useEffect(() => {
    if (!query) return

    const controller = new AbortController()

    fetch(`/api/search?q=${query}`, { signal: controller.signal })
      .then((res) => res.json())
      .then((data) => setResults(data))
      .catch((err) => {
        if (err.name !== 'AbortError') {
          console.error('Search failed:', err)
        }
      })

    // cleanup: 다음 query 변경 시 이전 요청 취소
    return () => controller.abort()
  }, [query])

  return (
    <div>
      <input value={query} onChange={(e) => setQuery(e.target.value)} placeholder="검색어 입력" />
      <ul>
        {results.map((r) => (
          <li key={r.id}>{r.title}</li>
        ))}
      </ul>
    </div>
  )
}

// 대안: React Query (TanStack Query) 사용 — 자동으로 처리됨
import { useQuery } from '@tanstack/react-query'

function SearchResults() {
  const [query, setQuery] = useState('')

  const { data: results = [] } = useQuery({
    queryKey: ['search', query],
    queryFn: ({ signal }) => fetch(`/api/search?q=${query}`, { signal }).then((r) => r.json()),
    enabled: !!query,
  })

  return (
    <div>
      <input value={query} onChange={(e) => setQuery(e.target.value)} placeholder="검색어 입력" />
      <ul>
        {results.map((r: any) => (
          <li key={r.id}>{r.title}</li>
        ))}
      </ul>
    </div>
  )
}