어떤 객체가 청소되나

// GC 는 "루트에서 도달할 수 없는" 객체를 지운다
//   루트 = 스택의 지역변수, static 필드, 실행 중인 스레드 …

List<byte[]> cache = new ArrayList<>();

void leak() {
    cache.add(new byte[10_000_000]);   // cache 가 살아있는 한 절대 안 지워짐
}

void ok() {
    byte[] tmp = new byte[10_000_000];
    process(tmp);
}   // 메서드 끝 -> 참조가 끊김 -> 다음 GC 때 회수 ✅

// System.gc() 는 '요청'일 뿐이고, 오히려 Full GC 를 유발합니다.
// 실무에서 호출할 이유가 없습니다.

GC 종류 — 뭘 쓸까

java -XX:+UseG1GC -jar app.jar        # 기본
java -XX:+UseZGC -jar app.jar
# ※ 세대형 ZGC 는 Java 23부터 기본이라 따로 켤 필요 없음
#   (21~22에서만 -XX:+ZGenerational 추가, 24부터는 이 플래그가 폐기됨)

켜고 보기

# 운영에서도 켜 두세요 — 오버헤드가 거의 없고, 없으면 사고 때 아무것도 못 봅니다
java -Xlog:gc*:file=/var/log/gc.log:time,uptime,level,tags:filecount=5,filesize=20M \
     -jar app.jar

# 실시간으로 훑어보기
jcmd <pid> GC.heap_info
jstat -gcutil <pid> 1000        # 1초마다 각 영역 사용률(%)

$ jstat -gcutil 1234 1000
  S0     S1     E      O      M     YGC   YGCT    FGC   FGCT
  0.00  31.25  68.42  45.10  95.2   842   12.4      3    1.85
  0.00  31.25  91.03  45.10  95.2   842   12.4      3    1.85
 28.15   0.00   7.21  45.62  95.2   843   12.4      3    1.85   ← 마이너 GC 발생

읽는 법
  E   Eden 사용률 — 차오르다 GC 후 떨어지는 톱니 모양이면 정상
  O   구세대 사용률 — ★ 계속 우상향하면 누수 의심
  YGC 마이너 횟수 · YGCT 누적 시간
  FGC 메이저(Full) 횟수 · FGCT 누적 시간 ← 여기가 늘어나면 문제

증상 → 원인 → 조치

# 무엇이 힙을 채우는지 — 이 한 줄이면 대개 범인이 보입니다
jcmd <pid> GC.class_histogram | head -20

# 정확히 보려면 덤프를 떠서 Eclipse MAT 로
jcmd <pid> GC.heap_dump /tmp/heap.hprof
#   MAT 의 "Leak Suspects" 리포트가 대개 바로 답을 줍니다

# 30분 간격으로 두 번 떠서 비교하면 "늘어난 것"이 곧 누수입니다

규약 — 둘은 항상 같이 구현

public final class Money {
    private final String currency;
    private final long amount;

    public Money(String currency, long amount) {
        this.currency = currency;
        this.amount = amount;
    }

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof Money m)) return false;      // 패턴 매칭
        return amount == m.amount && currency.equals(m.currency);
    }

    @Override
    public int hashCode() {
        return Objects.hash(currency, amount);          // 필드 조합
    }
}

// 규약
//   1) a.equals(b) 가 true 면 -> hashCode() 도 반드시 같아야 한다
//   2) hashCode 가 같다고 equals 가 true 일 필요는 없다 (해시 충돌 허용)
//   3) equals 에 쓴 필드만 hashCode 에도 쓴다

불변 객체 — 가장 값싼 안전장치

// 불변 만들기 5원칙
public final class Period {              // 1) final class — 상속 차단
    private final LocalDate start;       // 2) 모든 필드 final + private
    private final List<String> tags;

    public Period(LocalDate start, List<String> tags) {
        this.start = start;
        this.tags = List.copyOf(tags);   // 3) 방어적 복사 (들어올 때)
    }

    public List<String> getTags() {
        return tags;                     // 4) 이미 불변이라 그대로 OK
    }                                    //    가변이면 복사해서 반환

    public Period withStart(LocalDate s) {
        return new Period(s, tags);      // 5) 변경은 '새 객체'로
    }
}

// record 를 쓰면 1·2는 자동. 3만 신경 쓰면 됩니다
public record Period(LocalDate start, List<String> tags) {
    public Period {
        tags = List.copyOf(tags);        // 압축 생성자에서 복사
    }
}

불변 객체는 여러 스레드가 동시에 읽어도 안전합니다. 동시성 문제의 상당수가 “공유되는 가변 상태”에서 나오므로, 불변으로 만들 수 있으면 락 자체가 필요 없어집니다.

만들고 실행하기

// 1) 가장 단순한 방법
Thread t = new Thread(() -> System.out.println("다른 스레드"));
t.start();          // ⚠️ run() 을 직접 부르면 그냥 메서드 호출입니다
t.join();           // 끝날 때까지 기다림

// 2) 이름을 붙이면 로그·덤프에서 찾기 쉽다
Thread t2 = new Thread(task, "order-worker-1");

// 3) 데몬 스레드 — 메인이 끝나면 같이 종료
t2.setDaemon(true);

// 현재 스레드
Thread.currentThread().getName();     // "main", "http-nio-8080-exec-1" …
Thread.sleep(1000);                   // 1초 대기 (InterruptedException 처리 필요)

// 인터럽트 — '멈춰 달라'는 신호 (강제 종료가 아님)
t.interrupt();
// 받는 쪽
while (!Thread.currentThread().isInterrupted()) { ... }

스레드 상태

ExecutorService — 이것이 기본입니다

// ✗ new Thread() 를 직접 쓰는 코드는 거의 항상 잘못된 코드입니다
new Thread(() -> doWork()).start();     // 개수 제어 없음 · 예외 유실 · 종료 불가

// ✓ 풀에 맡깁니다 (try-with-resources — Java 19+)
try (var pool = Executors.newFixedThreadPool(8)) {
    List<Future<Report>> futures = ids.stream()
        .map(id -> pool.submit(() -> buildReport(id)))
        .toList();

    for (var f : futures) {
        Report r = f.get(10, TimeUnit.SECONDS);   // ★ 타임아웃을 반드시
        save(r);
    }
}   // 블록을 벗어나면 알아서 close + 완료 대기

// ✓✓ 가상 스레드 (Java 21+) — IO 대기가 많으면 이쪽
try (var pool = Executors.newVirtualThreadPerTaskExecutor()) {
    ids.forEach(id -> pool.submit(() -> callExternalApi(id)));
}   // 1만 개를 던져도 됩니다

// 주기 작업 — 앱이 사는 동안 유지해야 하므로 필드로 두고 종료 시 shutdown()
//   (try-with-resources 로 감싸면 블록을 나가는 순간 close() → 주기 작업이 취소됩니다)
private final ScheduledExecutorService sched = Executors.newScheduledThreadPool(1);
sched.scheduleAtFixedRate(this::cleanup, 0, 1, TimeUnit.HOURS);   // @PreDestroy 에서 sched.shutdown()

풀 크기를 정하는 법

// 큐가 무한이면 메모리가 터집니다 — 상한과 거절 정책을 함께
var pool = new ThreadPoolExecutor(
    8, 16,                                   // core, max
    60L, TimeUnit.SECONDS,
    new ArrayBlockingQueue<>(1000),          // ★ 큐 상한
    new ThreadFactoryBuilder()               // Guava. JDK 21+ 는 Thread.ofPlatform().name("report-", 0).factory()
        .setNameFormat("report-%d").build(), // ★ 이름 — 덤프에서 결정적입니다
    new ThreadPoolExecutor.CallerRunsPolicy());  // 넘치면 호출자가 직접 실행
    //  = 자연스러운 배압(backpressure). AbortPolicy 는 예외를 던집니다.

// 종료는 반드시 (스프링이면 @PreDestroy · @Bean(destroyMethod))
pool.shutdown();
if (!pool.awaitTermination(30, TimeUnit.SECONDS)) pool.shutdownNow();

ExecutorService — 스레드 풀

// 고정 크기 풀
try (var pool = Executors.newFixedThreadPool(10)) {   // Java 19+ AutoCloseable
    Future<Integer> f = pool.submit(() -> compute());
    Integer result = f.get();          // 결과를 기다림 (블로킹)
}   // 자동으로 shutdown + 대기

// 예전 방식 (여전히 많이 봅니다)
ExecutorService pool = Executors.newFixedThreadPool(10);
try {
    pool.submit(task);
} finally {
    pool.shutdown();                   // 새 작업 거부, 진행 중인 건 마침
    if (!pool.awaitTermination(30, TimeUnit.SECONDS))
        pool.shutdownNow();            // 시간 안에 안 끝나면 강제 종료
}

// 여러 작업을 한 번에
List<Callable<String>> tasks = List.of(t1, t2, t3);
List<Future<String>> futures = pool.invokeAll(tasks);   // 전부 끝날 때까지
String first = pool.invokeAny(tasks);                    // 가장 먼저 끝난 하나

// 주기 실행
var sched = Executors.newScheduledThreadPool(2);
sched.scheduleAtFixedRate(job, 0, 10, TimeUnit.SECONDS);

동시성 컬렉션

var map = new ConcurrentHashMap<String, Integer>();
map.merge("key", 1, Integer::sum);        // 원자적 증가 ✅
map.computeIfAbsent("k", k -> expensive());  // 한 번만 계산

// 생산자-소비자
BlockingQueue<Order> queue = new LinkedBlockingQueue<>(1000);
queue.put(order);        // 가득 차면 대기
Order o = queue.take();  // 비어 있으면 대기

// 동기화 보조 도구
var latch = new CountDownLatch(3);    // 3개가 끝날 때까지 대기
latch.countDown();  latch.await();
var sem = new Semaphore(5);           // 동시 5개만 허용
sem.acquire();  try { ... } finally { sem.release(); }

무엇이 문제였나

기존 플랫폼 스레드는 OS 스레드와 1:1입니다. 하나에 스택 메모리 약 1MB가 필요해서 수천 개가 한계이고, DB 조회·API 호출 같은 기다리는 시간 동안 그 비싼 스레드가 아무것도 안 하고 묶여 있습니다.

쓰는 법 — 놀랄 만큼 단순합니다

// 1) 하나 띄우기
Thread.startVirtualThread(() -> {
    var result = restClient.get().uri("/api/orders")
                           .retrieve().body(String.class);   // 블로킹해도 괜찮다
    log.info("{}", result);
});

// 2) 실행자 — 작업마다 새 가상 스레드 (풀이 필요 없음!)
try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
    List<Future<Order>> futures = ids.stream()
            .map(id -> executor.submit(() -> orderClient.find(id)))
            .toList();
    for (var f : futures) process(f.get());
}   // 자동으로 전부 대기 후 종료

// 3) 10,000개 동시 실행 — 예전엔 상상도 못 했던 코드
try (var ex = Executors.newVirtualThreadPerTaskExecutor()) {
    IntStream.range(0, 10_000).forEach(i ->
        ex.submit(() -> {
            Thread.sleep(1000);      // 1초 대기하는 작업 1만 개
            return i;
        }));
}   // 전체 소요 시간: 약 1초 (플랫폼 스레드였다면 메모리 부족)

구조적 동시성

// 문제: 하나가 실패해도 나머지는 계속 돌아 자원을 낭비한다
// 해결: 스코프로 묶어 생명주기를 함께 관리

// ⚠️ 아래 open()/Joiner API 는 2026-08 현재도 여전히 preview 입니다.
//    Java 25 = JEP 505(5차 preview) · Java 26 = JEP 525(6차 preview).
//    컴파일·실행에 --enable-preview 플래그가 필요합니다.
//    Java 26 에서 Joiner.onTimeout() 이 추가돼 스코프 단위 타임아웃을 걸 수 있습니다.
//    Java 21~24 의 preview API 는 형태가 다릅니다:
//    try (var scope = new StructuredTaskScope.ShutdownOnFailure()) { ... }

try (var scope = StructuredTaskScope.open()) {
    // 두 작업을 동시에 시작
    var userTask  = scope.fork(() -> userClient.find(id));
    var orderTask = scope.fork(() -> orderClient.findByUser(id));

    scope.join();                     // 둘 다 끝날 때까지 대기
                                      // 하나가 실패하면 나머지는 자동 취소 ✅
    return new Dashboard(userTask.get(), orderTask.get());
}   // 스코프를 벗어나면 남은 작업은 반드시 정리된다

// 가장 먼저 성공한 것만 쓰기 (여러 공급자 중 빠른 것)
try (var scope = StructuredTaskScope.open(
        StructuredTaskScope.Joiner.<String>anySuccessfulResultOrThrow())) {
    scope.fork(() -> providerA.fetch());
    scope.fork(() -> providerB.fetch());
    return scope.join();
}

ScopedValue — ThreadLocal 의 후계

// ThreadLocal 의 문제: 언제 지워야 할지 모르고, 가상 스레드에선 메모리 폭증
private static final ThreadLocal<User> CURRENT = new ThreadLocal<>();
CURRENT.set(user);
try { ... } finally { CURRENT.remove(); }   // 빼먹으면 누수

// ScopedValue — 범위가 끝나면 자동으로 사라진다 (불변)
private static final ScopedValue<User> CURRENT_USER = ScopedValue.newInstance();

ScopedValue.where(CURRENT_USER, loginUser)
           .run(() -> {
               service.process();          // 이 안에서는 어디서든 읽을 수 있다
           });                             // 끝나면 자동 해제 ✅

// 읽는 쪽
void deepInside() {
    User u = CURRENT_USER.get();
}

요청 단위의 로그인 사용자·추적 ID·테넌트 정보를 넘길 때 씁니다. 메서드 파라미터로 계속 넘기지 않아도 되면서, ThreadLocal 처럼 새지 않습니다.

측정 도구

# JFR — 60초 기록
jcmd <pid> JFR.start duration=60s filename=rec.jfr
# 시작할 때부터 기록
java -XX:StartFlightRecording=duration=60s,filename=r.jfr -jar app.jar

체감이 큰 순서대로

• ① DB 쿼리 — 웹 애플리케이션 성능 문제의 8할. N+1, 인덱스 누락, 불필요한 findAll()
• ② 외부 API 호출 — 순차 호출을 병렬로, 타임아웃·커넥션 풀 설정
• ③ 객체 생성량 — 반복문 안의 문자열 +, 불필요한 DTO 변환
• ④ 잘못된 자료구조 — 반복문 안의 list.contains()
• ⑤ 락 경합 — 스레드 덤프에 BLOCKED 가 몰려 있는지
• ⑥ GC 옵션 — 여기까지 왔으면 이미 앞의 다섯을 다 본 뒤

리플렉션 — 실행 중에 클래스를 들여다보기

Class<?> clazz = order.getClass();
clazz.getSimpleName();                      // "Order"
clazz.getDeclaredFields();                  // 필드 목록
clazz.getDeclaredMethods();                 // 메서드 목록

// 애너테이션이 붙었는지 확인
if (clazz.isAnnotationPresent(Service.class)) { ... }

// 값 읽기·쓰기 (private 도 가능)
Field f = clazz.getDeclaredField("amount");
f.setAccessible(true);
int amount = (int) f.get(order);

// 메서드 호출
Method m = clazz.getMethod("pay");
m.invoke(order);

// 객체 생성
Object o = clazz.getDeclaredConstructor().newInstance();

직접 만드는 애너테이션

@Target(ElementType.METHOD)          // 어디에 붙일 수 있나
@Retention(RetentionPolicy.RUNTIME)  // 언제까지 살아있나 (리플렉션엔 RUNTIME 필수)
public @interface LogExecutionTime {
    String value() default "";
}

// 사용
@LogExecutionTime("주문 처리")
public void process(Order o) { ... }

// 읽는 쪽 (보통은 AOP 가 대신 해 줍니다)
Method m = ...;
if (m.isAnnotationPresent(LogExecutionTime.class)) {
    String label = m.getAnnotation(LogExecutionTime.class).value();
}

프록시 — 스프링 AOP 의 정체

// 원본 객체를 감싼 '대역'을 만들어 앞뒤에 코드를 끼운다
Object proxy = Proxy.newProxyInstance(
    loader, new Class[]{Notifier.class},
    (p, method, args) -> {
        long t = System.nanoTime();
        Object result = method.invoke(target, args);   // 원본 호출
        log.info("{} took {}ms", method.getName(),
                 (System.nanoTime() - t) / 1_000_000);
        return result;
    });

컨테이너에서 제일 먼저 하는 설정

# ❌ 흔한 실수 — 컨테이너 메모리를 무시하고 고정
java -Xmx2g -jar app.jar
   → 컨테이너 한도가 1GB 면 힙만으로 초과 → OOMKilled(exit 137)
   → 애플리케이션 로그에는 아무것도 안 남습니다 (커널이 죽인 것)

# ✅ 컨테이너 한도의 비율로 지정 (Java 10+ 기본으로 컨테이너를 인식)
java -XX:MaxRAMPercentage=75.0 \
     -XX:InitialRAMPercentage=75.0 \
     -jar app.jar

운영에서 늘 넣는 옵션

-XX:MaxRAMPercentage=75.0
-XX:+HeapDumpOnOutOfMemoryError          # ★ OOM 순간을 파일로 남긴다
-XX:HeapDumpPath=/dump/heap.hprof        #   (영속 볼륨이어야 재시작 후에도 남음)
-XX:+ExitOnOutOfMemoryError              # 반쯤 죽은 채 서비스하지 말고 재시작
-Xlog:gc*:file=/log/gc.log:time,uptime:filecount=5,filesize=10M
-Dfile.encoding=UTF-8
-Duser.timezone=Asia/Seoul               # ★ 컨테이너 기본은 UTC 입니다

GC 고르기 — Java 21 기준

# p99 가 GC 때문에 튄다면 (gc.log 에서 200ms+ 정지가 보임)
-XX:+UseZGC     # 세대형 ZGC 는 Java 23부터 기본 (ZGenerational 플래그는 24부터 폐기)

# G1 을 계속 쓰면서 정지 시간만 낮추고 싶다면
-XX:MaxGCPauseMillis=100     # 목표치일 뿐, 보장은 아닙니다

기동 시간 — 오토스케일에 직결됩니다

• 트래픽이 몰려 서버를 늘릴 때 부팅이 60초면 이미 늦습니다
• CDS(클래스 데이터 공유)로 기동 20~30% 단축 — -XX:ArchiveClassesAtExit Spring Boot 3.3+
• 스프링의 지연 초기화는 첫 요청이 느려지므로 운영에서는 권하지 않습니다
• 기동 직후 느린 것(JIT 워밍업)은 정상 — readiness 프로브로 트래픽 투입을 늦추세요

① 객체를 대신 만들고 연결한다 (DI)

var repo = new OrderRepository(dataSource);
var mailer = new EmailNotifier(smtpConfig);
var service = new OrderService(repo, mailer);
var controller = new OrderController(service);
// 하나 바뀌면 줄줄이 고쳐야 한다

@Service
public class OrderService {
    private final OrderRepository repo;
    private final Notifier notifier;

    // 생성자만 만들어 두면 스프링이 알아서 넣어 준다
    public OrderService(OrderRepository repo, Notifier notifier) {
        this.repo = repo;
        this.notifier = notifier;
    }
}

② 흔한 설정을 미리 해 둔다 (자동 설정)

spring-boot-starter-webmvc 하나를 넣으면 톰캣 서버 · JSON 변환기 · 에러 페이지 · 정적 리소스 처리가 전부 딸려옵니다. spring-boot-starter-data-jpa를 넣으면 DataSource · 커넥션 풀 · 트랜잭션 매니저 · EntityManager가 자동으로 준비됩니다.

③ 서버를 내장한다

@SpringBootApplication          // 이 한 줄이 아래 셋을 합친 것
// = @Configuration + @EnableAutoConfiguration + @ComponentScan
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

WAR 를 만들어 톰캣에 올리던 시절과 달리, jar 하나에 서버가 들어 있어 java -jar app.jar 로 끝납니다.

1) 프로젝트 생성

start.spring.io 에서 만들거나, IntelliJ 의 New Project → Spring Initializr. 고를 것은 넷뿐입니다.

처음 담을 의존성

• Spring Web — REST API (필수)
• Lombok — 보일러플레이트 제거
• Spring Data JPA — DB
• H2 Database — 개발용 인메모리 DB
• Validation — 요청 검증
• Spring Boot DevTools — 자동 재시작

2) 폴더 구조 — 도메인형을 권합니다

빈으로 등록하는 방법

// 1) 스테레오타입 애너테이션 — 가장 흔함
@Component      // 일반적인 빈
@Service        // 비즈니스 로직 (의미만 다름)
@Repository     // DB 접근 (예외 변환 기능이 덤으로)
@Controller     // 웹 (뷰 반환)
@RestController // 웹 (JSON 반환) = @Controller + @ResponseBody

// 2) @Configuration + @Bean — 외부 라이브러리 객체를 등록할 때
@Configuration
public class AppConfig {

    @Bean
    public RestClient restClient() {
        return RestClient.builder()
                .baseUrl("https://api.example.com")
                .build();
    }

    // Boot 4 의 기본은 Jackson 3 — ObjectMapper 가 아니라 불변 JsonMapper 입니다
    // import tools.jackson.databind.json.JsonMapper;  (groupId 도 tools.jackson)
    @Bean
    public JsonMapper jsonMapper() {
        // java.time 지원은 Jackson 3 에 내장 — JavaTimeModule 등록이 필요 없습니다
        return JsonMapper.builder()
                .disable(DateTimeFeature.WRITE_DATES_AS_TIMESTAMPS)   // 3.x 에서 옮겨진 자리 (기본값도 false)
                .build();
    }
}

주입 방법 — 생성자 주입만 쓰세요

@Service
public class OrderService {
    @Autowired private OrderRepository repo;   // ❌
}
// · 테스트에서 가짜 객체를 넣기 어렵다
// · final 을 못 써서 나중에 바뀔 수 있다
// · 순환 참조가 있어도 실행될 때까지 모른다

@Service
@RequiredArgsConstructor          // Lombok — final 필드로 생성자 자동 생성
public class OrderService {
    private final OrderRepository repo;
    private final Notifier notifier;
}
// · final 보장 (불변)
// · 테스트에서 new OrderService(mockRepo, mockNotifier)
// · 순환 참조는 시작할 때 바로 에러 ✅
// · 생성자가 하나면 @Autowired 도 생략 가능

같은 타입 빈이 여러 개일 때

public interface Notifier { void send(String to, String msg); }

@Component("email") class EmailNotifier implements Notifier { }
@Component("sms")   class SmsNotifier implements Notifier { }

// 1) 이름으로 지정
public OrderService(@Qualifier("email") Notifier notifier) { }

// 2) 기본값 지정
@Component @Primary
class EmailNotifier implements Notifier { }

// 3) 전부 받기 — 전략 패턴에서 유용
@Service
public class NotifyService {
    private final List<Notifier> all;              // 전부 주입
    private final Map<String, Notifier> byName;    // 빈 이름이 키

    public void broadcast(String msg) {
        all.forEach(n -> n.send("all", msg));
    }
}

스코프

동작 방식

// 스프링 부트 내부의 자동 설정 클래스는 대략 이렇게 생겼습니다
@AutoConfiguration
@ConditionalOnClass(DataSource.class)         // 이 클래스가 클래스패스에 있고
@ConditionalOnMissingBean(DataSource.class)   // 내가 직접 만든 게 없으면
@EnableConfigurationProperties(DataSourceProperties.class)
public class DataSourceAutoConfiguration {

    @Bean
    public DataSource dataSource(DataSourceProperties props) {
        return props.initializeDataSourceBuilder().build();
    }
}

핵심은 @ConditionalOnMissingBean 입니다 — 내가 직접 빈을 등록하면 자동 설정은 물러납니다. “설정을 바꾸고 싶으면 그냥 만들어라”가 스프링 부트의 방식입니다.

무엇이 적용됐는지 확인하기

# application.yml — 시작할 때 리포트 출력
debug: true

============================
CONDITIONS EVALUATION REPORT
============================

Positive matches:            ← 적용된 것
-----------------
   DataSourceAutoConfiguration matched:
      - @ConditionalOnClass found 'javax.sql.DataSource'

Negative matches:            ← 적용 안 된 것 + 이유 ★
-----------------
   RedisAutoConfiguration:
      Did not match:
      - @ConditionalOnClass did not find 'RedisOperations'

application.yml

spring:
  application:
    name: order-service
  datasource:
    url: jdbc:mysql://localhost:3306/mydb
    username: ${DB_USER}              # 환경변수에서 (기본값 없이)
    password: ${DB_PASSWORD}
    hikari:
      maximum-pool-size: 20
  jpa:
    hibernate:
      ddl-auto: validate              # 운영은 절대 update/create 금지
    properties:
      hibernate:
        format_sql: true
  threads:
    virtual:
      enabled: true                   # 가상 스레드 (Boot 3.2+)

server:
  port: 8080
  shutdown: graceful                  # 종료 시 처리 중인 요청 마무리

logging:
  level:
    root: INFO
    com.myapp: DEBUG

app:                                  # 내가 만든 설정
  order:
    max-amount: 1000000
    auto-cancel-minutes: 30
    admin-emails:
      - admin@example.com
      - ops@example.com

타입 안전하게 읽기 (권장)

// record + @ConfigurationProperties = 가장 깔끔한 조합
@ConfigurationProperties(prefix = "app.order")
public record OrderProperties(
        int maxAmount,
        int autoCancelMinutes,
        List<String> adminEmails
) { }

// 활성화
@SpringBootApplication
@ConfigurationPropertiesScan
public class Application { }

// 사용 — 오타가 나면 컴파일 에러 ✅
@Service
@RequiredArgsConstructor
public class OrderService {
    private final OrderProperties props;

    public void check(int amount) {
        if (amount > props.maxAmount()) throw new ...;
    }
}

// 단발성이면 @Value 도 가능 (오타는 런타임에 터짐)
@Value("${app.order.max-amount}")
private int maxAmount;

자주 쓰는 애너테이션

적용과 커스텀 검증

// 컨트롤러에서 @Valid 를 붙여야 실행됩니다 (잊기 쉬움!)
@PostMapping
public OrderRes create(@Valid @RequestBody OrderCreateReq req) { ... }

// 중첩 객체
public record OrderCreateReq(
        @NotNull Long productId,
        @Valid @NotNull AddressReq address     // ← @Valid 를 붙여야 안쪽까지
) { }

// 여러 필드를 함께 봐야 할 때 — 커스텀 애너테이션
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = DateRangeValidator.class)
public @interface ValidDateRange {
    String message() default "종료일이 시작일보다 빠릅니다";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

public class DateRangeValidator
        implements ConstraintValidator<ValidDateRange, SearchReq> {
    @Override
    public boolean isValid(SearchReq r, ConstraintValidatorContext ctx) {
        if (r.from() == null || r.to() == null) return true;
        return !r.to().isBefore(r.from());
    }
}

@ValidDateRange
public record SearchReq(LocalDate from, LocalDate to) { }

AOP — 실행 시간 로깅 예제

@Aspect
@Component
@Slf4j
public class LoggingAspect {

    // 이 패키지 아래 모든 서비스 메서드
    @Around("execution(* com.myapp..*Service.*(..))")
    public Object logTime(ProceedingJoinPoint pjp) throws Throwable {
        long start = System.nanoTime();
        try {
            return pjp.proceed();                  // 원래 메서드 실행
        } finally {
            long ms = (System.nanoTime() - start) / 1_000_000;
            if (ms > 500) {
                log.warn("느린 메서드: {} {}ms", pjp.getSignature().toShortString(), ms);
            }
        }
    }

    // 특정 애너테이션이 붙은 것만
    @Around("@annotation(com.myapp.common.LogExecutionTime)")
    public Object logAnnotated(ProceedingJoinPoint pjp) throws Throwable { ... }
}

⚠️ 프록시의 한계 — 자기 호출은 안 먹는다

@Service
public class OrderService {

    public void process() {
        save();          // ← this.save() 라서 프록시를 안 거침!
    }

    @Transactional
    public void save() { ... }    // 트랜잭션 없이 실행됨 💥
}

// 1) 클래스를 분리한다 (권장)
@Service
@RequiredArgsConstructor
public class OrderService {
    private final OrderSaver saver;      // 다른 빈이므로 프록시를 거침
    public void process() { saver.save(); }
}

// 2) 호출하는 쪽 메서드에 붙인다
@Transactional
public void process() { save(); }

// 3) 자기 자신을 주입 (임시방편)
// ⚠️ @RequiredArgsConstructor 는 필드의 @Lazy 를 생성자 파라미터로
//    복사하지 않아 그냥은 순환 참조로 실패합니다. lombok.config 에
//    lombok.copyableAnnotations += org.springframework.context.annotation.Lazy
//    를 넣거나, 생성자를 직접 작성해 파라미터에 @Lazy 를 붙이세요.
@Lazy private final OrderService self;
public void process() { self.save(); }

⏰ 스케줄러

@SpringBootApplication
@EnableScheduling            // 켜기
public class Application { }

@Component
@Slf4j
public class OrderScheduler {

    // 매일 새벽 3시
    @Scheduled(cron = "0 0 3 * * *", zone = "Asia/Seoul")
    public void settle() { ... }

    // 이전 실행이 끝난 뒤 10분
    @Scheduled(fixedDelay = 600_000)
    public void cleanup() { ... }

    // 시작 시각 기준 10분마다
    @Scheduled(fixedRate = 600_000,
               initialDelay = 30_000)
    public void poll() { ... }
}

/* cron: 초 분 시 일 월 요일
   0 0 3 * * *     매일 3시
   0 0/30 * * * *  30분마다
   0 0 9 * * MON-FRI  평일 9시 */

⚡ 비동기

@SpringBootApplication
@EnableAsync
public class Application { }

@Service
public class MailService {

    @Async                       // 별도 스레드에서
    public void send(String to) {
        // 오래 걸려도 호출한 쪽은 안 기다림
    }

    @Async
    public CompletableFuture<Report> build() {
        return CompletableFuture
                .completedFuture(makeReport());
    }
}

# 가상 스레드를 쓰면 풀 설정이 불필요
spring:
  threads:
    virtual:
      enabled: true

💾 캐시

@SpringBootApplication
@EnableCaching
public class Application { }

@Service
public class ProductService {

    // 있으면 그대로, 없으면 실행 후 저장
    @Cacheable(value = "products", key = "#id")
    public Product get(Long id) {
        return repository.findById(id)
                .orElseThrow();
    }

    // 실행하고 결과로 갱신
    @CachePut(value = "products", key = "#p.id")
    public Product update(Product p) { ... }

    // 지우기
    @CacheEvict(value = "products", key = "#id")
    public void delete(Long id) { ... }

    @CacheEvict(value = "products",
                allEntries = true)
    public void clearAll() { }
}

spring:
  cache:
    type: caffeine       # 로컬
    caffeine:
      spec: maximumSize=1000,expireAfterWrite=10m
# 서버 여러 대면 redis

업로드

@PostMapping(value = "/upload",
             consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
public UploadRes upload(@RequestPart("file") MultipartFile file,
                        @RequestPart("meta") @Valid MetaReq meta) {

    if (file.isEmpty()) throw new BadRequestException("파일이 비어 있습니다");

    // 확장자 검증 — 파일명만 믿지 말 것
    String name = StringUtils.cleanPath(
            Objects.requireNonNull(file.getOriginalFilename()));
    if (name.contains("..")) throw new BadRequestException("잘못된 경로");

    String ext = StringUtils.getFilenameExtension(name);
    if (ext == null                    // 확장자 없음 — List.of().contains(null) 은 NPE
            || !List.of("xlsx", "csv", "png", "jpg").contains(ext.toLowerCase())) {
        throw new BadRequestException("허용되지 않는 형식입니다");
    }

    // 저장 — 원본 이름을 그대로 쓰지 말 것 (덮어쓰기·경로 조작 방지)
    String saved = UUID.randomUUID() + "." + ext;
    Path target = uploadDir.resolve(saved);
    file.transferTo(target);

    return new UploadRes(saved, file.getSize());
}

// 여러 개
public void uploads(@RequestPart("files") List<MultipartFile> files) { }

spring:
  servlet:
    multipart:
      max-file-size: 10MB
      max-request-size: 50MB

다운로드

@GetMapping("/download/{id}")
public ResponseEntity<Resource> download(@PathVariable Long id) {
    FileMeta meta = fileService.get(id);
    Resource resource = new FileSystemResource(meta.path());

    // 한글 파일명은 반드시 인코딩 (안 하면 깨지거나 다운로드 실패)
    String encoded = UriUtils.encode(meta.originalName(), StandardCharsets.UTF_8);

    return ResponseEntity.ok()
            .contentType(MediaType.APPLICATION_OCTET_STREAM)
            .header(HttpHeaders.CONTENT_DISPOSITION,
                    "attachment; filename=\"" + encoded + "\"; " +
                    "filename*=UTF-8''" + encoded)
            .contentLength(meta.size())
            .body(resource);
}

// 메모리에 안 올리고 바로 흘려보내기 (대용량) ★
@GetMapping("/export")
public void export(HttpServletResponse res) throws IOException {
    res.setContentType(
        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet");
    res.setHeader(HttpHeaders.CONTENT_DISPOSITION,
                  "attachment; filename=\"orders.xlsx\"");

    try (var out = res.getOutputStream()) {
        excelService.writeTo(out);      // 스트리밍으로 직접 씀
    }
}

① 단위 테스트 — 가장 빠름

@ExtendWith(MockitoExtension.class)
class OrderServiceTest {

    @Mock OrderRepository repository;
    @Mock StockService stockService;
    @Mock Notifier notifier;
    @InjectMocks OrderService service;

    @Test
    @DisplayName("이미 결제된 주문은 다시 결제할 수 없다")
    void payTwice() {
        // given
        Order order = OrderFixture.paid();
        given(repository.findById(1L))
                .willReturn(Optional.of(order));

        // when & then
        assertThatThrownBy(() -> service.pay(1L))
                .isInstanceOf(AlreadyPaidException.class);

        then(notifier).shouldHaveNoInteractions();
    }
}

② 웹 계층 테스트

@WebMvcTest(OrderController.class)
class OrderControllerTest {

    @Autowired MockMvc mvc;
    @MockitoBean OrderService service;   // Boot 3.4+

    @Test
    void 수량이_0이면_400() throws Exception {
        mvc.perform(post("/api/orders")
                .contentType(APPLICATION_JSON)
                .content("""
                    {"productId":1,"quantity":0,"address":"서울"}
                    """))
           .andExpect(status().isBadRequest())
           .andExpect(jsonPath("$.errors[0].field")
                   .value("quantity"));
    }
}

③ 통합 테스트

@SpringBootTest(webEnvironment =
        WebEnvironment.RANDOM_PORT)
@AutoConfigureTestRestTemplate     // ★ Boot 4 부터 필수
@Testcontainers                    // 진짜 DB 로 검증 ★
class OrderIntegrationTest {

    @Container
    static MySQLContainer<?> mysql =
            new MySQLContainer<>("mysql:8.4");

    @DynamicPropertySource
    static void props(DynamicPropertyRegistry r) {
        r.add("spring.datasource.url", mysql::getJdbcUrl);
        r.add("spring.datasource.username", mysql::getUsername);
        r.add("spring.datasource.password", mysql::getPassword);
    }

    @Autowired TestRestTemplate rest;

    @Test
    void 주문_생성부터_결제까지() { ... }
}

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,prometheus   # 필요한 것만!
  endpoint:
    health:
      show-details: when_authorized
      probes:
        enabled: true          # k8s liveness/readiness
  metrics:
    tags:
      application: ${spring.application.name}

직접 지표 만들기

@Service
@RequiredArgsConstructor
public class OrderService {
    private final MeterRegistry registry;

    public void pay(Long id) {
        Timer.Sample sample = Timer.start(registry);
        try {
            doPay(id);
            registry.counter("order.pay", "result", "success").increment();
        } catch (Exception e) {
            registry.counter("order.pay", "result", "fail").increment();
            throw e;
        } finally {
            sample.stop(registry.timer("order.pay.time"));
        }
    }
}

// 커스텀 헬스 체크
@Component
public class ExternalApiHealthIndicator implements HealthIndicator {
    @Override
    public Health health() {
        return client.ping()
                ? Health.up().build()
                : Health.down().withDetail("reason", "무응답").build();
    }
}

빌드하고 실행하기

# 빌드
./gradlew clean build          # build/libs/app-1.0.0.jar

# 실행
java -jar app.jar \
     --spring.profiles.active=prod \
     --server.port=8080

# 운영에서 자주 쓰는 옵션
java -XX:MaxRAMPercentage=75 \
     -XX:+HeapDumpOnOutOfMemoryError \
     -XX:HeapDumpPath=/var/log/ \
     -Duser.timezone=Asia/Seoul \
     -Dfile.encoding=UTF-8 \
     -jar app.jar

Dockerfile — 레이어를 나눠서

# 의존성과 애플리케이션 코드를 분리하면
# 코드만 바뀔 때 캐시가 살아 빌드가 훨씬 빨라집니다
FROM eclipse-temurin:25-jre AS base
WORKDIR /app

FROM base AS builder
# *.jar 로 쓰면 Gradle 의 -plain.jar 까지 잡혀 COPY 가 실패합니다 — 정확한 이름으로
COPY build/libs/app-1.0.0.jar application.jar
RUN java -Djarmode=tools -jar application.jar extract --layers --destination extracted

FROM base
COPY --from=builder /app/extracted/dependencies/ ./
COPY --from=builder /app/extracted/spring-boot-loader/ ./
COPY --from=builder /app/extracted/snapshot-dependencies/ ./
COPY --from=builder /app/extracted/application/ ./

EXPOSE 8080
# extract 는 원본 jar 이름(application.jar)을 그대로 application/ 에 남깁니다 — 그것을 -jar 로 실행
# (JarLauncher 를 직접 부르려면 -cp 가 필요해서 그대로 쓰면 ClassNotFoundException 이 납니다)
ENTRYPOINT ["java", "-XX:MaxRAMPercentage=75", "-jar", "application.jar"]

배포 전 체크리스트

• ✅ ddl-auto: validate — update·create 는 절대 금지
• ✅ 비밀번호·키가 환경 변수로 빠져 있나
• ✅ server.shutdown: graceful — 처리 중 요청 보호
• ✅ Actuator 가 외부에 열려 있지 않은지
• ✅ 로그 레벨이 운영은 INFO (DEBUG 는 디스크를 태웁니다)
• ✅ 타임존 -Duser.timezone=Asia/Seoul
• ✅ 헬스 체크 경로를 LB 에 등록
• ✅ 힙 덤프 경로 설정 (OOM 원인 분석용)
• ✅ DB 커넥션 풀 크기 ↔ 서버 대수 확인

두 가지 프로브 — 역할이 다릅니다

# application.yml — 부트가 두 엔드포인트를 만들어 줍니다
management:
  endpoint:
    health:
      probes:
        enabled: true          # /actuator/health/liveness, /readiness
  health:
    livenessstate:  { enabled: true }
    readinessstate: { enabled: true }

server:
  shutdown: graceful           # ★ 처리 중인 요청을 끝내고 종료
spring:
  lifecycle:
    timeout-per-shutdown-phase: 30s

# deployment.yaml
livenessProbe:
  httpGet: { path: /actuator/health/liveness, port: 8080 }
  initialDelaySeconds: 30
  periodSeconds: 10
  failureThreshold: 3
readinessProbe:
  httpGet: { path: /actuator/health/readiness, port: 8080 }
  initialDelaySeconds: 10
  periodSeconds: 5
resources:
  requests: { cpu: "500m", memory: "1Gi" }    # 스케줄링 기준
  limits:   { cpu: "2",    memory: "2Gi" }    # 넘으면 OOMKilled

무중단 배포 — 끊기는 진짜 이유

파드 종료 순간 실제로 일어나는 일

  1. K8s 가 파드를 "종료 중"으로 표시
  2. 서비스 엔드포인트에서 제거   ┐ 이 둘은
  3. 컨테이너에 SIGTERM 전달      ┘ 동시에 일어납니다 (순서 보장 없음)

  → 3번이 먼저 오면, 아직 라우팅되는 상태에서 앱이 종료를 시작
  → 그 사이에 들어온 요청이 502 로 떨어집니다

해결: 종료 신호를 받고 몇 초 버틴 뒤에 실제 종료를 시작

lifecycle:
  preStop:
    exec: { command: ["sh", "-c", "sleep 5"] }   # ★ 엔드포인트 제거를 기다림
terminationGracePeriodSeconds: 60                 # graceful shutdown 보다 길게

strategy:
  type: RollingUpdate
  rollingUpdate:
    maxSurge: 1          # 새 파드를 1개 더 띄우고
    maxUnavailable: 0    # ★ 기존 파드는 하나도 안 줄인다 = 무중단

오토스케일 · 설정 주입

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
spec:
  minReplicas: 3          # ★ 2 이상 — 1이면 재시작 때 서비스가 멈춥니다
  maxReplicas: 20
  metrics:
    - type: Resource
      resource: { name: cpu, target: { type: Utilization, averageUtilization: 60 } }
  behavior:
    scaleDown:
      stabilizationWindowSeconds: 300    # 급하게 줄이지 않기 (플래핑 방지)

① 먼저 확인할 환경 요구사항

// build.gradle.kts
plugins {
    java
    id("org.springframework.boot") version "4.1.0"
    id("io.spring.dependency-management") version "1.1.7"
}

java { toolchain { languageVersion = JavaLanguageVersion.of(25) } }

② 이름이 바뀐 스타터 4종

MVC — 요청 하나에 스레드 하나

요청 1 → [스레드 1] ──DB 대기 2초── 응답
요청 2 → [스레드 2] ──DB 대기 2초── 응답
   …
요청 201 → 대기 (톰캣 기본 풀 200개 소진)

스레드는 '기다리는 동안'에도 메모리를 붙잡고 있다

WebFlux — 적은 스레드가 돌려막기

요청 1~10000 → [이벤트 루프 스레드 8개]
   DB 요청을 던져 놓고 → 즉시 다른 요청 처리
   결과가 오면 → 콜백으로 이어서 처리

기다리는 동안 스레드가 놀지 않는다

셋 중 무엇을 고를까 2026 기준

둘의 차이는 개수뿐

// 만들기
Mono<String> m1 = Mono.just("값");
Mono<String> m2 = Mono.empty();                 // 값 없음
Mono<String> m3 = Mono.error(new RuntimeException());
Mono<String> m4 = Mono.fromCallable(() -> compute());   // 지연 실행
Mono<String> m5 = Mono.defer(() -> Mono.just(now()));   // 구독할 때마다 새로

Flux<Integer> f1 = Flux.just(1, 2, 3);
Flux<Integer> f2 = Flux.range(1, 100);
Flux<String> f3 = Flux.fromIterable(list);
Flux<Long> f4 = Flux.interval(Duration.ofSeconds(1));   // 1초마다 무한

// 변환
Mono<List<T>> list = flux.collectList();
Flux<T> flux2 = mono.flux();
Mono<T> first = flux.next();

⚠️ 구독하지 않으면 아무 일도 안 일어난다

public void save(Order o) {
    repository.save(o);        // Mono 를 만들기만 하고 버림
}                              // DB 에 아무것도 안 들어감 💥

public Mono<Order> save(Order o) {
    return repository.save(o);    // 컨트롤러가 반환하면 스프링이 구독
}

Mono·Flux 는 “무엇을 할지 적어 둔 설계도”일 뿐입니다. 누군가 subscribe() 해야 비로소 흐르기 시작합니다. 웹 컨트롤러에서는 반환만 하면 스프링이 대신 구독합니다 — 직접 subscribe()를 호출하는 코드는 대개 잘못된 신호입니다.

스케줄러 종류

// 어쩔 수 없이 블로킹 코드를 써야 한다면 반드시 격리
public Mono<Report> legacyReport(Long id) {
    return Mono.fromCallable(() -> legacyJdbcDao.find(id))   // 블로킹
               .subscribeOn(Schedulers.boundedElastic());     // 별도 스레드로 ★
}

// publishOn — 이 지점 '이후'의 스레드를 바꾼다
flux.publishOn(Schedulers.parallel())
    .map(this::heavyCompute);

// subscribeOn — 소스가 실행될 스레드를 바꾼다 (위치 무관, 한 번만 적용)
mono.subscribeOn(Schedulers.boundedElastic());

막힌 곳 찾기 — BlockHound

// 테스트에서 켜 두면 블로킹 호출을 즉시 예외로 잡아 준다
@BeforeAll
static void setup() {
    BlockHound.install();
}

// 이런 코드가 있으면 바로 터집니다
// reactor.blockhound.BlockingOperationError:
//   Blocking call! java.lang.Thread.sleep

애너테이션 방식 — MVC 와 거의 같습니다

@RestController
@RequestMapping("/api/orders")
@RequiredArgsConstructor
public class OrderController {

    private final OrderService service;

    @GetMapping
    public Flux<OrderRes> list() {              // List 대신 Flux
        return service.findAll();
    }

    @GetMapping("/{id}")
    public Mono<OrderRes> get(@PathVariable Long id) {   // 단건은 Mono
        return service.get(id);
    }

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public Mono<OrderRes> create(@Valid @RequestBody Mono<OrderCreateReq> req) {
        return req.flatMap(service::create);
    }

    @DeleteMapping("/{id}")
    public Mono<Void> delete(@PathVariable Long id) {
        return service.delete(id);
    }
}

반환 타입만 바뀌었을 뿐 구조는 MVC 와 동일합니다. 기존 MVC 경험을 그대로 살릴 수 있어 처음엔 이 방식을 권합니다.

함수형 방식 — 라우터

@Configuration
public class OrderRouter {

    @Bean
    public RouterFunction<ServerResponse> routes(OrderHandler handler) {
        return RouterFunctions.route()
                .path("/api/orders", builder -> builder
                        .GET("", handler::list)
                        .GET("/{id}", handler::get)
                        .POST("", handler::create)
                        .DELETE("/{id}", handler::delete))
                .filter((req, next) -> {           // 라우터 단위 필터
                    log.info("{} {}", req.method(), req.path());
                    return next.handle(req);
                })
                .build();
    }
}

@Component
@RequiredArgsConstructor
public class OrderHandler {
    private final OrderService service;

    public Mono<ServerResponse> get(ServerRequest req) {
        Long id = Long.valueOf(req.pathVariable("id"));
        return service.get(id)
                .flatMap(o -> ServerResponse.ok().bodyValue(o))
                .switchIfEmpty(ServerResponse.notFound().build());
    }

    public Mono<ServerResponse> create(ServerRequest req) {
        return req.bodyToMono(OrderCreateReq.class)
                .flatMap(service::create)
                .flatMap(o -> ServerResponse
                        .created(URI.create("/api/orders/" + o.id()))
                        .bodyValue(o));
    }
}

설정 — 타임아웃은 반드시

@Bean
public WebClient orderApiClient(WebClient.Builder builder) {
    HttpClient httpClient = HttpClient.create()
            .option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 2000)
            .responseTimeout(Duration.ofSeconds(5))
            .doOnConnected(conn -> conn
                    .addHandlerLast(new ReadTimeoutHandler(5))
                    .addHandlerLast(new WriteTimeoutHandler(5)));

    return builder
            .baseUrl("https://api.example.com")
            .clientConnector(new ReactorClientHttpConnector(httpClient))
            .defaultHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE)
            .filter(logRequest())            // 요청 로깅
            .codecs(c -> c.defaultCodecs()
                    .maxInMemorySize(5 * 1024 * 1024))   // 응답 크기 제한 (기본 256KB)
            .build();
}

private ExchangeFilterFunction logRequest() {
    return ExchangeFilterFunction.ofRequestProcessor(req -> {
        log.debug("{} {}", req.method(), req.url());
        return Mono.just(req);
    });
}

호출하기

// GET
Mono<UserRes> user = client.get()
        .uri("/users/{id}", id)
        .retrieve()
        .bodyToMono(UserRes.class);

// 쿼리 파라미터
client.get().uri(b -> b.path("/users")
        .queryParam("status", "ACTIVE")
        .queryParam("page", 0).build());

// POST
Mono<OrderRes> res = client.post()
        .uri("/orders")
        .bodyValue(new OrderCreateReq(1L, 2))
        .retrieve()
        .bodyToMono(OrderRes.class);

// 목록
Flux<UserRes> users = client.get().uri("/users")
        .retrieve()
        .bodyToFlux(UserRes.class);

// 상태 코드별 처리 ★
client.get().uri("/users/{id}", id)
    .retrieve()
    .onStatus(s -> s.value() == 404,
              r -> Mono.error(new UserNotFoundException(id)))
    .onStatus(HttpStatusCode::is5xxServerError,
              r -> r.bodyToMono(String.class)
                    .map(body -> new ExternalApiException(body)))
    .bodyToMono(UserRes.class)
    .timeout(Duration.ofSeconds(3))
    .retryWhen(Retry.backoff(3, Duration.ofMillis(200))
                    .filter(e -> e instanceof TimeoutException))
    .onErrorResume(e -> Mono.just(UserRes.fallback()));

왜 필요한가

DB 가 초당 10만 건을 뿜는데
소비자는 초당 1천 건만 처리 가능하다면?

백프레셔 없음 → 메모리에 쌓임 → OOM 💥
백프레셔 있음 → "1천 개만 주세요" → 안정 ✅

// 전략 선택 — 넷 중 하나만 골라 씁니다 (체인으로 연결하는 게 아님)
flux.onBackpressureBuffer(1000);        // ① 1000개까지 버퍼
flux.onBackpressureDrop(v -> log.warn("버림: {}", v));  // ② 넘치면 버림
flux.onBackpressureLatest();            // ③ 최신 것만 유지
flux.onBackpressureError();             // ④ 넘치면 에러

// 속도 제한
flux.limitRate(100)                     // 한 번에 100개씩 요청
    .delayElements(Duration.ofMillis(10));

// 묶어서 처리 — DB 배치 저장에 유용 ★
flux.buffer(500)                        // 500개씩 묶음
    .flatMap(batch -> repository.saveAll(batch))
    .subscribe();

// 시간 기준으로 묶기
flux.bufferTimeout(500, Duration.ofSeconds(1));

동시 실행 개수 제한

// ❌ flatMap 기본 동시성은 256 — 외부 API 를 순식간에 때립니다
Flux.fromIterable(ids)
    .flatMap(id -> apiClient.get(id))
    .subscribe();

// ✅ 동시 실행 수를 제한
Flux.fromIterable(ids)
    .flatMap(id -> apiClient.get(id), 10)   // 최대 10개 동시
    .subscribe();

// 순서까지 지키려면
    .flatMapSequential(id -> apiClient.get(id), 10)

// 완전 순차 (가장 느리지만 안전)
    .concatMap(id -> apiClient.get(id))

Server-Sent Events

// 서버 → 클라이언트 단방향 실시간 푸시
@GetMapping(value = "/stream",
            produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<OrderEvent> stream() {
    return orderEventPublisher.flux()
            .map(OrderEvent::from);
}

// 이벤트 메타데이터까지 담기
@GetMapping(value = "/sse", produces = TEXT_EVENT_STREAM_VALUE)
public Flux<ServerSentEvent<String>> sse() {
    return Flux.interval(Duration.ofSeconds(1))
            .map(i -> ServerSentEvent.<String>builder()
                    .id(String.valueOf(i))
                    .event("tick")
                    .data("현재 시각 " + LocalTime.now())
                    .retry(Duration.ofSeconds(3))   // 끊기면 재연결 간격
                    .build());
}

// 연결이 끊겼을 때 정리
.doOnCancel(() -> log.info("클라이언트 연결 종료"))
.doFinally(sig -> cleanup());

// 브라우저 쪽
const es = new EventSource('/api/orders/sse');
es.addEventListener('tick', e => console.log(e.data));
es.onerror = () => es.close();

대용량 데이터 스트리밍

// 100만 건을 메모리에 안 올리고 흘려보내기
@GetMapping(value = "/export",
            produces = MediaType.APPLICATION_NDJSON_VALUE)
public Flux<OrderRes> export() {
    return orderRepository.findAllBy()      // R2DBC 는 스트리밍이 기본
            .map(OrderRes::from);
}
// 응답: 한 줄에 하나씩 JSON (NDJSON)
// {"id":1,...}
// {"id":2,...}

// 여러 소스를 합쳐 실시간 대시보드로
Flux.merge(
        orderEvents.map(Event::of),
        paymentEvents.map(Event::of),
        Flux.interval(Duration.ofSeconds(30)).map(i -> Event.heartbeat())
).share();          // 여러 구독자가 같은 스트림을 공유

설정

spring:
  r2dbc:
    url: r2dbc:mysql://localhost:3306/mydb   # jdbc: 가 아니라 r2dbc:
    username: ${DB_USER}
    password: ${DB_PASSWORD}
    pool:
      initial-size: 10
      max-size: 30
      max-idle-time: 30m
  sql:
    init:
      mode: always          # schema.sql 실행 (개발용)

엔티티 — JPA 와 다릅니다

@Table("orders")                       // @Entity 아님
public class Order {

    @Id
    private Long id;                   // jakarta 가 아니라 spring-data 의 @Id

    @Column("customer_name")
    private String customerName;

    private int amount;

    @Column("created_at")
    private LocalDateTime createdAt;

    // ⚠️ 연관관계 매핑이 없습니다 (@OneToMany 없음)
    //    필요하면 ID 를 들고 직접 조회해서 조합합니다
    private Long userId;
}

리포지토리

public interface OrderRepository extends ReactiveCrudRepository<Order, Long> {

    // 쿼리 메서드 — JPA 와 문법이 같습니다
    Flux<Order> findByStatus(OrderStatus status);
    Mono<Order> findByOrderNo(String orderNo);
    Mono<Long> countByUserId(Long userId);
    Mono<Boolean> existsByOrderNo(String orderNo);

    // 직접 SQL — JPQL 이 아니라 '진짜 SQL' 입니다
    @Query("""
        SELECT o.* FROM orders o
         WHERE o.user_id = :userId
           AND o.created_at >= :from
         ORDER BY o.created_at DESC
        """)
    Flux<Order> findRecent(Long userId, LocalDateTime from);

    @Modifying
    @Query("UPDATE orders SET status = :status WHERE id = :id")
    Mono<Integer> updateStatus(Long id, String status);
}

// 사용
public Mono<OrderRes> get(Long id) {
    return orderRepository.findById(id)
            .switchIfEmpty(Mono.error(new OrderNotFoundException(id)))
            .map(OrderRes::from);
}

public Flux<OrderRes> list(OrderStatus status) {
    return orderRepository.findByStatus(status).map(OrderRes::from);
}

@Configuration
public class R2dbcConfig {
    @Bean
    public ReactiveTransactionManager transactionManager(ConnectionFactory cf) {
        return new R2dbcTransactionManager(cf);
    }
}

@Service
@RequiredArgsConstructor
public class OrderService {

    private final OrderRepository orderRepository;
    private final StockRepository stockRepository;

    @Transactional                       // 리액티브에서도 그대로 동작
    public Mono<Order> create(OrderCreateReq req) {
        return stockRepository.findByProductId(req.productId())
                .switchIfEmpty(Mono.error(new StockNotFoundException()))
                .flatMap(stock -> {
                    if (stock.getQuantity() < req.quantity())
                        return Mono.error(new InsufficientStockException());
                    stock.decrease(req.quantity());
                    return stockRepository.save(stock);
                })
                .then(orderRepository.save(Order.from(req)));
                // 어느 단계에서 에러가 나도 전체 롤백 ✅
    }
}

직접 제어하기

@RequiredArgsConstructor
public class OrderService {
    private final TransactionalOperator tx;

    public Mono<Order> create(OrderCreateReq req) {
        return doWork(req)
                .as(tx::transactional);      // 이 체인 전체가 한 트랜잭션
    }
}

// ❌ 이렇게는 안 잡힙니다
try {
    return service.find(id);     // Mono 를 만들 뿐, 에러는 나중에 흐름
} catch (Exception e) { }        // 절대 안 걸림

// ✅ 연산자로 처리 — 아래는 '골라 쓰는' 목록입니다
//    (전부 이으면 1) 이 모든 에러를 먼저 삼켜 2)~4) 는 영영 안 걸립니다)
service.find(id)
    // 1) 대체값
    .onErrorReturn(Order.empty())

    // 2) 특정 예외만
    .onErrorReturn(TimeoutException.class, Order.empty())

    // 3) 다른 흐름으로 (폴백)
    .onErrorResume(e -> {
        log.warn("주 저장소 실패, 캐시 조회", e);
        return cacheRepository.find(id);
    })

    // 4) 예외를 바꿔서 다시 던지기
    .onErrorMap(DataAccessException.class,
                e -> new ServiceException("DB 오류", e))

    // 5) 비어 있을 때
    .switchIfEmpty(Mono.error(new OrderNotFoundException(id)))

    // 6) 성공·실패 관계없이
    .doFinally(sig -> meter.increment(sig.name()));

재시도 — 지수 백오프

apiClient.call()
    .timeout(Duration.ofSeconds(3))
    .retryWhen(
        Retry.backoff(3, Duration.ofMillis(200))   // 200ms, 400ms, 800ms
             .maxBackoff(Duration.ofSeconds(5))
             .jitter(0.5)                          // 동시 재시도 분산
             .filter(e -> e instanceof TimeoutException
                       || e instanceof WebClientRequestException)
             .onRetryExhaustedThrow((spec, signal) ->
                     new ExternalApiException("재시도 초과", signal.failure()))
    )
    .onErrorResume(e -> Mono.just(fallbackValue()));

디버깅

// 1) log() — 모든 신호를 찍는다
flux.log("order-flow")
    .filter(...)
    .log("after-filter");
// onSubscribe / request(N) / onNext(v) / onComplete

// 2) checkpoint() — 스택 트레이스에 위치 표시
mono.checkpoint("주문 조회 단계")
    .flatMap(...)
    .checkpoint("결제 단계");

// 3) 전역 디버그 모드 (개발 환경만! 성능 비용이 큽니다)
@PostConstruct
void init() { Hooks.onOperatorDebug(); }

// 4) doOn* 으로 관찰 (흐름을 바꾸지 않음)
.doOnSubscribe(s -> log.info("시작"))
.doOnNext(v -> log.debug("값: {}", v))
.doOnError(e -> log.error("실패", e))
.doOnCancel(() -> log.warn("취소됨"))

테스트 — StepVerifier

@Test
void 주문_조회() {
    given(repository.findById(1L)).willReturn(Mono.just(order));

    StepVerifier.create(service.get(1L))
            .expectNextMatches(r -> r.id().equals(1L))
            .verifyComplete();
}

@Test
void 없으면_예외() {
    given(repository.findById(1L)).willReturn(Mono.empty());

    StepVerifier.create(service.get(1L))
            .expectError(OrderNotFoundException.class)
            .verify();
}

@Test
void 시간을_당겨서_테스트() {
    StepVerifier.withVirtualTime(() ->
            Flux.interval(Duration.ofHours(1)).take(3))
        .thenAwait(Duration.ofHours(3))     // 3시간을 즉시 통과
        .expectNextCount(3)
        .verifyComplete();
}

자주 밟는 함정

// 로그 추적 ID 를 리액티브 컨텍스트로 전달
mono.contextWrite(ctx -> ctx.put("traceId", traceId));

// 읽는 쪽
Mono.deferContextual(ctx -> {
    String traceId = ctx.get("traceId");
    return Mono.just(...);
});

Reactor 패턴 — 스레드 하나가 수천 소켓을 본다

[ 톰캣 · 블로킹 ]
소켓 1  → 스레드 1  (read() 에서 멈춰 있음)
소켓 2  → 스레드 2  (read() 에서 멈춰 있음)
소켓 N  → 스레드 N   … 스레드 = 소켓 개수

[ Netty · Reactor 패턴 ]
소켓 1 ┐
소켓 2 ├→ [ Selector / epoll ] → 이벤트 루프 스레드 1개
  …    │      "읽을 게 생긴 소켓만 알려 줘"
소켓 N ┘
      → 이벤트가 온 소켓만 골라서 처리 → 다음 소켓
      스레드는 '기다리지' 않고 '깨워질 때만' 일한다

핵심은 스레드 수를 소켓 수에서 분리한 것입니다. 연결 1만 개가 있어도 실제로 데이터가 오가는 건 그중 수백 개뿐이므로, CPU 코어 수만큼의 스레드로 전부 감당할 수 있습니다. 컨텍스트 스위칭과 스레드 스택(기본 1MB × N)이 통째로 사라지는 것이 WebFlux 가 메모리를 적게 먹는 진짜 이유입니다.

EventLoopGroup — boss와 worker

// boss   : accept() 만 담당 (연결 수락) — 보통 1개면 충분
// worker : 수락된 연결의 read/write 를 전담 — 코어 수만큼
EventLoopGroup boss   = new MultiThreadIoEventLoopGroup(1, NioIoHandler.newFactory());
EventLoopGroup worker = new MultiThreadIoEventLoopGroup(NioIoHandler.newFactory());

// ★ 한 Channel 은 평생 같은 EventLoop 에 묶인다 (스레드 어피니티)
//    → 그 채널의 핸들러 안에서는 동기화가 필요 없다
//    → 대신 그 스레드를 막으면 '그 EventLoop 에 붙은 다른 수천 연결'도 같이 멈춘다

ChannelPipeline — 요청이 지나가는 컨베이어

소켓에서 바이트 도착
   ↓  Inbound (아래 → 위)
[ SslHandler ] → [ HttpServerCodec ] → [ 집계 ] → [ 내 핸들러 ]
   ↑  Outbound (위 → 아래)
소켓으로 바이트 전송

· ChannelHandler = 컨베이어 위의 작업자 하나
· ChannelPipeline = 작업자들의 줄 (연결마다 1개)
· ChannelHandlerContext = 작업자가 앞뒤 사람에게 말 거는 창구
· 순서가 곧 로직이다 — addLast 순서를 틀리면 조용히 안 먹는다

ByteBuf — 참조 카운팅이 붙은 버퍼 ★

할당자(Allocator) — 4.2 에서 기본값이 바뀌었습니다 ★

ByteBuf buf = ctx.alloc().buffer(1024);   // refCnt = 1
buf.writeBytes(data);
buf.retain();                              // refCnt = 2 (다른 곳도 쓴다)
ReferenceCountUtil.release(buf);           // refCnt = 1
ReferenceCountUtil.release(buf);           // refCnt = 0 → 풀로 반납

// ⚠️ release 를 빠뜨리면 GC 가 안 치웁니다 = 다이렉트 메모리 누수
//    누수는 '한참 뒤 OOM' 으로만 드러나서 원인 추적이 지옥입니다

ServerBootstrap — 최소 에코 서버

public class EchoServer {

    public static void main(String[] args) throws Exception {
        EventLoopGroup boss   = new MultiThreadIoEventLoopGroup(1, NioIoHandler.newFactory());
        EventLoopGroup worker = new MultiThreadIoEventLoopGroup(NioIoHandler.newFactory());
        try {
            ServerBootstrap b = new ServerBootstrap()
                .group(boss, worker)
                .channel(NioServerSocketChannel.class)
                .option(ChannelOption.SO_BACKLOG, 1024)              // 서버 소켓용
                .childOption(ChannelOption.TCP_NODELAY, true)        // 연결마다
                .childOption(ChannelOption.SO_KEEPALIVE, true)
                .childHandler(new ChannelInitializer<SocketChannel>() {
                    @Override protected void initChannel(SocketChannel ch) {
                        ch.pipeline()
                          .addLast(new LoggingHandler(LogLevel.DEBUG))
                          .addLast(new LengthFieldBasedFrameDecoder(
                                       65536, 0, 4, 0, 4))           // 길이 헤더 4바이트
                          .addLast(new LengthFieldPrepender(4))
                          .addLast(new StringDecoder(UTF_8))
                          .addLast(new StringEncoder(UTF_8))
                          .addLast(new EchoHandler());
                    }
                });

            ChannelFuture f = b.bind(9090).sync();
            f.channel().closeFuture().sync();          // 종료까지 대기
        } finally {
            boss.shutdownGracefully();
            worker.shutdownGracefully();
        }
    }
}

커스텀 핸들러

@ChannelHandler.Sharable          // 상태가 없을 때만 붙일 것
public class EchoHandler extends SimpleChannelInboundHandler<String> {

    @Override
    protected void channelRead0(ChannelHandlerContext ctx, String msg) {
        ctx.writeAndFlush("echo: " + msg);     // 응답
    }

    @Override
    public void channelActive(ChannelHandlerContext ctx) {
        log.info("접속 {}", ctx.channel().remoteAddress());
    }

    @Override
    public void exceptionCaught(ChannelHandlerContext ctx, Throwable cause) {
        log.error("핸들러 예외", cause);
        ctx.close();                            // ★ 안 닫으면 좀비 커넥션이 쌓인다
    }
}

// SimpleChannelInboundHandler 는 처리 후 ByteBuf 를 '자동 release' 합니다.
// ChannelInboundHandlerAdapter 를 직접 쓰면 → 반드시 직접 release 하세요.
public class RawHandler extends ChannelInboundHandlerAdapter {
    @Override public void channelRead(ChannelHandlerContext ctx, Object msg) {
        ByteBuf in = (ByteBuf) msg;
        try { /* 처리 */ } finally { ReferenceCountUtil.release(in); }   // 필수
    }
}

TCP 경계 문제 — 하프 패킷 · 스티키 패킷 ★

보낸 쪽:   [ 주문A ][ 주문B ][ 주문C ]

받는 쪽에 실제로 도착하는 모습(둘 다 정상):
  ① 스티키   [ 주문A주문B주문 ][ C ]     ← 뭉쳐서 옴
  ② 하프     [ 주문 ][ A주문B ][ 주문C ] ← 잘려서 옴

TCP 는 '바이트 스트림'이라 메시지 경계를 보장하지 않는다.
경계는 '내가' 만들어야 한다.

// 프레임 형식:  [ 길이(4바이트) ][ 본문 ]
new LengthFieldBasedFrameDecoder(
        1024 * 1024,  // maxFrameLength — 넘으면 TooLongFrameException (DoS 방어)
        0,            // lengthFieldOffset  : 길이 필드 시작 위치
        4,            // lengthFieldLength  : 길이 필드 크기
        0,            // lengthAdjustment   : 길이값 보정
        4);           // initialBytesToStrip: 앞 4바이트(헤더)는 버리고 넘김

// ⚠️ 디코더는 상태를 가집니다 → @Sharable 금지, 연결마다 새로 만들 것

ChannelOption — 자주 만지는 것만

무엇이 블로킹인가

// ❌ 이벤트 루프에서 그대로 실행됨
@GetMapping("/stat")
public Mono<Stat> stat() {
    Stat s = jdbcDao.heavyQuery();      // 300ms 동안 루프 정지 💥
    return Mono.just(s);
}

// ✅ 별도 스레드로 격리
@GetMapping("/stat")
public Mono<Stat> stat() {
    return Mono.fromCallable(() -> jdbcDao.heavyQuery())
               .subscribeOn(Schedulers.boundedElastic());   // ★
}

// ✅ CPU 바운드는 parallel 로
flux.publishOn(Schedulers.parallel())
    .map(this::resizeImage);

// boundedElastic 기본 상한: 10 × CPU 코어 수, 큐 10만
// → 이것도 무한이 아닙니다. 넘치면 RejectedExecutionException
Schedulers.newBoundedElastic(50, 1000, "legacy-jdbc");

BlockHound — 블로킹을 컴파일하듯 잡는다 ★

// 테스트 부트스트랩에서 한 번만
@BeforeAll
static void installBlockHound() {
    BlockHound.builder()
        // 우리가 '의도적으로' 허용하는 곳은 화이트리스트로
        .allowBlockingCallsInside(
            "com.example.legacy.LegacyJdbcDao", "heavyQuery")
        .allowBlockingCallsInside(
            "java.util.UUID", "randomUUID")        // 엔트로피 대기
        .blockingMethodCallback(m -> {
            log.error("🚫 블로킹 감지: {}", m);
            throw new BlockingOperationError(m);
        })
        .install();
}

// 잡히면 이렇게 나옵니다
// reactor.blockhound.BlockingOperationError:
//   Blocking call! java.net.SocketInputStream#socketRead0
//     at com.example.OrderService.stat(OrderService.java:42)
//   ← 몇 번째 줄인지까지 정확히 찍힙니다

핸들러 안의 무거운 작업 — EventExecutorGroup

// Netty 를 직접 쓸 때, 특정 핸들러만 별도 스레드 풀에서 돌린다
private static final EventExecutorGroup BIZ =
        new DefaultEventExecutorGroup(16);

ch.pipeline()
  .addLast(new HttpServerCodec())          // 루프 스레드에서
  .addLast(BIZ, new BusinessHandler());    // ★ 이 핸들러만 BIZ 스레드에서

// 주의 ① 스레드가 바뀌므로 ByteBuf 를 그대로 넘기면 수명 관리가 어려워집니다
//        → 되도록 POJO 로 디코딩한 '뒤' 지점에 붙이세요
// 주의 ② 같은 채널의 순서는 유지되지만, 채널 간 순서는 보장되지 않습니다

ConnectionProvider — 풀 설정 전부

ConnectionProvider provider = ConnectionProvider.builder("order-api")
    .maxConnections(200)                            // 호스트당 최대 커넥션 ★
    .pendingAcquireMaxCount(1000)                   // 대기 큐 (기본: max × 2)
    .pendingAcquireTimeout(Duration.ofSeconds(3))   // 대기 한계 (기본 45초 — 너무 김) ★
    .maxIdleTime(Duration.ofSeconds(20))            // 놀고 있는 커넥션 폐기 ★★
    .maxLifeTime(Duration.ofMinutes(5))             // 오래된 커넥션 강제 교체
    .evictInBackground(Duration.ofSeconds(30))      // 유휴 커넥션 청소 주기
    .lifo()                                         // 최근 쓴 것부터 재사용 (기본은 fifo)
    .metrics(true)                                  // ★ 마이크로미터 연동
    .build();

HttpClient httpClient = HttpClient.create(provider)
    .option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 2000)
    .responseTimeout(Duration.ofSeconds(5))         // 응답 읽기 사이 최대 공백 (요청 단위) ★
    .doOnConnected(c -> c
        .addHandlerLast(new ReadTimeoutHandler(5))  // 5초간 수신 없음
        .addHandlerLast(new WriteTimeoutHandler(5)))
    .compress(true)
    .keepAlive(true)
    .metrics(true, Function.identity());            // URI 태그 (카디널리티 주의)

@Bean
WebClient orderClient(WebClient.Builder b) {
    return b.baseUrl("https://order.internal")
            .clientConnector(new ReactorClientHttpConnector(httpClient))
            .build();
}

가장 흔한 사고 — keep-alive 타임아웃 불일치 ★★

우리 쪽 풀:   maxIdleTime = 무한 (기본값)
상대 서버:    keepAliveTimeout = 5초  (Node.js 기본 · nginx 는 75초)

t=0    요청 → 커넥션 A 사용 → 풀에 반납
t=5s   상대 서버가 A 를 조용히 닫음 (FIN)
       우리 풀은 아직 "A 는 살아 있다"고 믿는다
t=6s   요청 → 풀에서 A 를 꺼내 전송
       → 이미 닫힌 소켓 → 즉시 실패

증상: PrematureCloseException / Connection prematurely closed
      "BEFORE response" · 재현이 안 됨 · 트래픽 적은 새벽에 더 잦음 💥

타임아웃 3종 — 역할이 다릅니다

네이티브 트랜스포트 — epoll · io_uring

// 넣기만 하면 Reactor Netty 가 자동으로 감지해 씁니다
// 확인
log.info("native = {}", reactor.netty.resources.LoopResources.hasNativeSupport());

// 강제로 끄기 (문제 격리용)
System.setProperty("reactor.netty.native", "false");

// Netty 를 직접 쓸 때는 채널 클래스를 직접 골라야 합니다
Class<? extends ServerChannel> ch = Epoll.isAvailable()
        ? EpollServerSocketChannel.class
        : NioServerSocketChannel.class;

파일 디스크립터 — 조용한 상한선

# 소켓 하나 = FD 하나. 1만 연결 = FD 1만 개.
ulimit -n                      # 기본 1024 → 절대 부족
ulimit -n 65536

# 컨테이너 (docker-compose)
ulimits: { nofile: { soft: 65536, hard: 65536 } }

# 지금 몇 개 쓰는지
ls /proc/<pid>/fd | wc -l
cat /proc/<pid>/limits | grep files

# 넘치면: java.io.IOException: Too many open files
#         → accept 가 조용히 실패하고 신규 연결만 안 됩니다 (기존은 정상)
#         → "일부 사용자만 접속이 안 돼요" 로 보고됩니다 ★

다이렉트 메모리 — 힙 밖의 OOM ★

# Netty 는 다이렉트 버퍼를 기본으로 씁니다 → 힙이 아닙니다
-XX:MaxDirectMemorySize=512m       # 미지정 시 = -Xmx 와 같은 크기
-Dio.netty.maxDirectMemory=536870912   # Netty 자체 상한 (별도 계산)

# 컨테이너 메모리 = 힙 + 다이렉트 + 메타스페이스 + 스레드스택 + 네이티브
# 예) limits.memory 2Gi 라면
#     -XX:MaxRAMPercentage=50  (힙 1Gi)
#     -XX:MaxDirectMemorySize=512m
#     나머지 500Mi 를 여유로 남긴다  ← 이걸 안 남기면 OOMKilled

ByteBuf 누수 추적 실전

# 1) 부하 테스트 환경에서 PARANOID 로 켠다
-Dio.netty.leakDetection.level=PARANOID
-Dio.netty.leakDetection.targetRecords=64

# 2) 로그에서 이 문자열을 찾는다
#    LEAK: ByteBuf.release() was not called before it's garbage-collected
#    Recent access records:
#      #1: io.netty.buffer.AdvancedLeakAwareByteBuf.readBytes(...)
#          at com.example.ProxyHandler.channelRead(ProxyHandler.java:57)  ← 범인

# 3) 힙 밖 사용량을 JVM 에게 직접 물어본다
jcmd <pid> VM.native_memory summary        # -XX:NativeMemoryTracking=summary 필요
jcmd <pid> GC.heap_info

# 4) 할당자를 바꿔 원인을 가른다
-Dio.netty.allocator.type=unpooled   # 재사용을 꺼서 '누수인지 파편화인지' 가른다
                                     #   unpooled 로도 계속 늘면 → 진짜 누수(release 누락)
                                     #   unpooled 에서 멎으면  → 풀 파편화·풀 크기 문제
-Dio.netty.allocator.type=pooled     # 4.1 시절 기본값으로 되돌려 비교 (4.2 기본은 adaptive)

① 순수 WebSocket — 프로토콜 그대로

// build.gradle: spring-boot-starter-websocket
@Configuration @EnableWebSocket
class WsConfig implements WebSocketConfigurer {
    public void registerWebSocketHandlers(WebSocketHandlerRegistry reg) {
        reg.addHandler(new ChatHandler(), "/ws/chat")
           .setAllowedOrigins("https://app.example.com");   // ★ CORS 별도!
    }
}

class ChatHandler extends TextWebSocketHandler {
    // 세션 목록은 반드시 동시성 컬렉션으로
    private final Set<WebSocketSession> sessions = ConcurrentHashMap.newKeySet();

    public void afterConnectionEstablished(WebSocketSession s) {
        sessions.add(s);
    }
    protected void handleTextMessage(WebSocketSession s, TextMessage m)
            throws IOException {
        for (WebSocketSession peer : sessions)          // 브로드캐스트
            if (peer.isOpen()) peer.sendMessage(m);
    }
    public void afterConnectionClosed(WebSocketSession s, CloseStatus st) {
        sessions.remove(s);                             // ★ 정리 안 하면 누수
    }
}

② STOMP — 구독·발행으로 올라서기

// 채팅방·알림처럼 "채널" 개념이 생기면 STOMP 가 코드를 줄여 줍니다
@Configuration @EnableWebSocketMessageBroker
class StompConfig implements WebSocketMessageBrokerConfigurer {
    public void registerStompEndpoints(StompEndpointRegistry r) {
        r.addEndpoint("/ws").setAllowedOriginPatterns("https://*.example.com");
    }
    public void configureMessageBroker(MessageBrokerRegistry r) {
        r.enableSimpleBroker("/topic", "/queue");   // 구독 채널
        r.setApplicationDestinationPrefixes("/app"); // 클라 → 서버 접두사
    }
}

@Controller
class ChatController {
    @MessageMapping("/chat/{room}")          // 클라가 /app/chat/1 로 발행
    @SendTo("/topic/chat/{room}")            // 구독자 전원에게
    ChatMsg relay(@DestinationVariable long room, ChatMsg msg) {
        return msg;
    }
}

// 서버가 먼저 말 걸기 — 어디서든 주입해서
messagingTemplate.convertAndSend("/topic/notice", payload);
messagingTemplate.convertAndSendToUser(userId, "/queue/dm", dm);  // 1:1

// 브라우저 쪽 (@stomp/stompjs)
const c = new StompJs.Client({ brokerURL: "wss://api.example.com/ws" });
c.onConnect = () => {
  c.subscribe("/topic/chat/1", m => render(JSON.parse(m.body)));
  c.publish({ destination: "/app/chat/1",
              body: JSON.stringify({ text: "안녕하세요" }) });
};
c.activate();   // 재접속·하트비트 내장

spring:
  datasource:
    # ⚠️ URL 은 한 줄로 — YAML 은 줄바꿈을 공백으로 접어서 파라미터가 깨집니다
    url: jdbc:mysql://localhost:3306/mydb?useSSL=false&serverTimezone=Asia/Seoul&characterEncoding=UTF-8&rewriteBatchedStatements=true
    username: ${DB_USER}
    password: ${DB_PASSWORD}
    hikari:
      maximum-pool-size: 20        # 핵심 설정 ★
      minimum-idle: 10
      connection-timeout: 3000     # 커넥션을 못 얻으면 3초 후 실패
      idle-timeout: 600000         # 10분
      max-lifetime: 1740000        # 29분 (DB wait_timeout 보다 짧게!)
      leak-detection-threshold: 60000   # 60초 넘게 안 돌려주면 경고
      pool-name: HikariPool-main

풀 크기는 몇으로?

직관과 반대로 크게 잡을수록 느려집니다. DB 의 CPU·디스크가 병목이라 커넥션이 많으면 경합만 늘어납니다.

권장 공식 (HikariCP 문서)
   pool_size = (코어 수 × 2) + 유효 디스크 수

예) 4코어 + SSD 1개 → 약 10
    대부분의 웹 서비스는 10~30 사이면 충분

⚠️ 서버 5대 × 풀 30 = DB 커넥션 150개
   DB 의 max_connections 를 넘으면 전체 장애

public interface OrderRepository extends JpaRepository<Order, Long> {
    // 이것만 선언하면 아래가 전부 생깁니다
    //   save, saveAll, findById, findAll, delete, count, existsById …
}

// 계층
//   Repository
//    ├ CrudRepository → ListCrudRepository                       기본 CRUD (List 반환)
//    └ PagingAndSortingRepository → ListPagingAndSortingRepository 페이징·정렬
//         (Spring Data 3.0 부터 PagingAndSorting 은 CrudRepository 를 상속하지 않습니다)
//   JpaRepository = ListCrud + ListPagingAndSorting + QueryByExample
//                   + JPA 전용 (flush, saveAndFlush …)

쿼리 메서드 — 이름이 곧 쿼리

List<Order> findByStatus(OrderStatus status);
List<Order> findByStatusAndAmountGreaterThan(OrderStatus s, int amount);
List<Order> findByCustomerNameContaining(String keyword);     // LIKE %kw%
List<Order> findByCreatedAtBetween(LocalDateTime a, LocalDateTime b);
List<Order> findByStatusOrderByCreatedAtDesc(OrderStatus s);
List<Order> findTop10ByOrderByAmountDesc();
Optional<Order> findByOrderNo(String no);
boolean existsByOrderNo(String no);
long countByStatus(OrderStatus s);
void deleteByStatus(OrderStatus s);

키워드 표

N:1 — 가장 많이 씁니다

@Entity
public class Order {
    @Id @GeneratedValue
    private Long id;

    @ManyToOne(fetch = FetchType.LAZY)       // ★ 반드시 LAZY
    @JoinColumn(name = "user_id", nullable = false,
                foreignKey = @ForeignKey(name = "fk_order_user"))
    private User user;                        // orders 테이블에 user_id 컬럼
}

// 반대편(1:N)은 필요할 때만 추가
@Entity
public class User {
    @OneToMany(mappedBy = "user")             // mappedBy = 주인이 아님을 표시
    private List<Order> orders = new ArrayList<>();
}

1:N — 부모가 자식을 관리할 때

@Entity
public class Order {
    @OneToMany(mappedBy = "order",
               cascade = CascadeType.ALL,     // 부모 저장 시 자식도
               orphanRemoval = true)          // 목록에서 빼면 삭제
    private List<OrderItem> items = new ArrayList<>();

    // 양방향은 편의 메서드로 양쪽을 함께 세팅
    public void addItem(OrderItem item) {
        items.add(item);
        item.setOrder(this);      // ★ 이걸 빠뜨리면 FK 가 null 로 저장됨
    }
}

1:1 과 N:M

// 1:1 — FK 를 가진 쪽이 주인
@Entity
public class User {
    @OneToOne(fetch = FetchType.LAZY, cascade = CascadeType.ALL)
    @JoinColumn(name = "profile_id")
    private Profile profile;
}

// ⚠️ 1:1 의 '반대편'은 LAZY 가 안 먹습니다 (프록시를 못 만듦)
//    → 조회 시 항상 추가 쿼리가 나갑니다. 단방향으로 두는 게 안전합니다.

// N:M — @ManyToMany 는 쓰지 마세요 ★
// ❌ 중간 테이블에 컬럼을 못 넣고, 쿼리가 예측 불가
@ManyToMany
private List<Tag> tags;

// ✅ 중간 엔티티를 직접 만듭니다
@Entity
public class PostTag {
    @Id @GeneratedValue private Long id;

    @ManyToOne(fetch = LAZY) @JoinColumn(name = "post_id")
    private Post post;

    @ManyToOne(fetch = LAZY) @JoinColumn(name = "tag_id")
    private Tag tag;

    private LocalDateTime taggedAt;      // 추가 정보를 넣을 수 있다 ✅
}

public interface OrderRepository extends JpaRepository<Order, Long> {

    // JPQL — 엔티티 이름과 필드명을 씁니다 (테이블/컬럼 아님)
    @Query("""
        SELECT o FROM Order o
         WHERE o.status = :status
           AND o.amount >= :minAmount
         ORDER BY o.createdAt DESC
        """)
    List<Order> search(@Param("status") OrderStatus status,
                       @Param("minAmount") int minAmount);

    // DTO 로 바로 받기 (필요한 컬럼만 SELECT — 성능에 유리) ★
    @Query("""
        SELECT new com.myapp.order.dto.OrderSummary(o.id, o.orderNo, u.name, o.amount)
          FROM Order o JOIN o.user u
         WHERE o.createdAt >= :from
        """)
    List<OrderSummary> findSummaries(LocalDateTime from);

    // 네이티브 SQL — DB 고유 기능이 필요할 때
    @Query(value = """
        SELECT * FROM orders
         WHERE MATCH(memo) AGAINST(:kw IN BOOLEAN MODE)
        """, nativeQuery = true)
    List<Order> fullTextSearch(String kw);

    // 벌크 연산 — 한 번에 UPDATE/DELETE
    @Modifying(clearAutomatically = true, flushAutomatically = true)
    @Query("UPDATE Order o SET o.status = :to WHERE o.status = :from")
    int bulkUpdateStatus(OrderStatus from, OrderStatus to);
}

프로젝션 — 필요한 것만 가져오기

// 1) 인터페이스 프로젝션 — 가장 간편
public interface OrderView {
    Long getId();
    String getOrderNo();
    int getAmount();
    UserInfo getUser();            // 중첩 프로젝션 — o.user.name
    interface UserInfo { String getName(); }
    // (String getUserName() 처럼 쓰면 Order 에 userName 속성이 없어 실패)
}
List<OrderView> findByStatus(OrderStatus status);

// 2) record 프로젝션 — 명시적
public record OrderSummary(Long id, String orderNo, String userName, int amount) { }

// 3) 동적 프로젝션 — 한 메서드로 여러 형태
<T> List<T> findByStatus(OrderStatus status, Class<T> type);
// 호출
repo.findByStatus(PAID, OrderView.class);
repo.findByStatus(PAID, Order.class);

Gradle 설정 (Spring Boot 4.x · jakarta)

dependencies {
    implementation("com.querydsl:querydsl-jpa:5.1.0:jakarta")
    annotationProcessor("com.querydsl:querydsl-apt:5.1.0:jakarta")
    annotationProcessor("jakarta.annotation:jakarta.annotation-api")
    annotationProcessor("jakarta.persistence:jakarta.persistence-api")
}

// 생성된 Q타입을 빌드 폴더에 두기 (clean 하면 같이 지워짐)
tasks.withType<JavaCompile> {
    options.generatedSourceOutputDirectory
           .set(file("build/generated/querydsl"))
}

./gradlew clean compileJava
# build/generated/querydsl 아래 QOrder.java 등이 생성됩니다
# IDE 에서 안 잡히면: Gradle 새로고침 또는 build 폴더를 소스로 표시

JPAQueryFactory 빈 등록

@Configuration
public class QuerydslConfig {

    @PersistenceContext
    private EntityManager em;

    @Bean
    public JPAQueryFactory jpaQueryFactory() {
        return new JPAQueryFactory(em);
    }
}

커스텀 리포지토리 붙이기

// 1) 인터페이스
public interface OrderRepositoryCustom {
    Page<OrderSummary> search(OrderSearchCond cond, Pageable pageable);
}

// 2) 구현체 — 이름은 반드시 "인터페이스명 + Impl"
@Repository
@RequiredArgsConstructor
public class OrderRepositoryImpl implements OrderRepositoryCustom {
    private final JPAQueryFactory query;
    // ... 다음 섹션에서 구현
}

// 3) 기존 리포지토리에 상속
public interface OrderRepository
        extends JpaRepository<Order, Long>, OrderRepositoryCustom { }

// 이제 한 리포지토리에서 둘 다 씁니다
orderRepository.findById(1L);              // Spring Data
orderRepository.search(cond, pageable);    // QueryDSL ✅

자주 쓰는 문법

// 비교
order.amount.eq(1000)      .ne(1000)
order.amount.goe(1000)     // >=      .gt() >
order.amount.loe(1000)     // <=      .lt() <
order.amount.between(1, 100)
order.status.in(PAID, DONE)
order.deletedAt.isNull()   .isNotNull()

// 문자열
user.name.eq("김현우")
user.name.contains("현")      // LIKE %현%
user.name.startsWith("김")    // LIKE 김%
user.name.containsIgnoreCase("kim")

// 조합
statusEq(s).and(amountGoe(1000)).or(isVip())
order.status.eq(PAID).not()

// 집계
query.select(order.amount.sum(), order.count(),
             order.amount.avg(), order.amount.max())
     .from(order).fetchOne();

// 그룹핑
query.select(user.name, order.amount.sum())
     .from(order).join(order.user, user)
     .groupBy(user.name)
     .having(order.amount.sum().gt(10000))
     .fetch();

페치 조인 · 서브쿼리 · CASE

// 페치 조인 (엔티티를 가져올 때)
query.selectFrom(order)
     .join(order.user, user).fetchJoin()
     .where(order.id.eq(id))
     .fetchOne();

// 서브쿼리
import static com.querydsl.jpa.JPAExpressions.select;

query.selectFrom(order)
     .where(order.amount.gt(
             select(order2.amount.avg()).from(order2)))   // 평균보다 큰
     .fetch();

// CASE WHEN
query.select(new CaseBuilder()
        .when(order.amount.gt(100000)).then("VIP")
        .when(order.amount.gt(10000)).then("일반")
        .otherwise("신규"))
     .from(order).fetch();

// 벌크 연산
long updated = query.update(order)
        .set(order.status, OrderStatus.CANCELLED)
        .where(order.createdAt.lt(deadline))
        .execute();
em.clear();      // ★ 영속성 컨텍스트 초기화 필수 (보류 중인 변경은 execute() '전에' em.flush())

// 결과 가져오기
.fetch()          // List
.fetchOne()       // 하나 (2개 이상이면 예외)
.fetchFirst()     // 첫 번째
.stream()         // 스트림

기본 페이징

// 컨트롤러 — Pageable 을 그대로 받으면 됩니다
@GetMapping
public Page<OrderRes> list(
        @PageableDefault(size = 20, sort = "createdAt",
                         direction = Sort.Direction.DESC) Pageable pageable) {
    return orderService.list(pageable);
}
// 요청: /api/orders?page=0&size=20&sort=createdAt,desc

// 리포지토리 — 반환 타입만 다르고 시그니처가 같으므로 둘 중 하나만 선언
Page<Order> findByStatus(OrderStatus status, Pageable pageable);
// Slice<Order> findByStatus(OrderStatus status, Pageable pageable);  // 카운트 없음

// Page 가 주는 정보
page.getContent();        page.getTotalElements();
page.getTotalPages();     page.hasNext();
page.map(OrderRes::from); // 내용만 변환 (메타는 유지) ★

깊은 페이지가 느린 이유와 해결

-- 100만 번째 페이지
SELECT * FROM orders ORDER BY id DESC LIMIT 20 OFFSET 1000000;
-- DB 가 100만 20건을 읽고 100만 건을 버립니다 💥

// ✅ 커서(무한 스크롤) 방식 — 마지막 본 ID 부터
@Query("""
    SELECT o FROM Order o
     WHERE (:lastId IS NULL OR o.id < :lastId)
     ORDER BY o.id DESC
    """)
List<Order> findNext(Long lastId, Pageable pageable);
// 항상 인덱스로 바로 찾아가므로 페이지가 깊어져도 일정한 속도 ✅

// QueryDSL 로도
query.selectFrom(order)
     .where(lastId != null ? order.id.lt(lastId) : null)
     .orderBy(order.id.desc())
     .limit(size)
     .fetch();

설정

mybatis:
  mapper-locations: classpath:mapper/**/*.xml
  type-aliases-package: com.myapp.order.dto
  configuration:
    map-underscore-to-camel-case: true    # user_name -> userName ★
    default-fetch-size: 100
    jdbc-type-for-null: NULL

logging:
  level:
    com.myapp.order.mapper: DEBUG          # SQL 로그

매퍼 인터페이스

@Mapper                                     // 또는 @MapperScan 을 설정에
public interface OrderMapper {

    // 애너테이션 방식 — 짧은 쿼리에
    @Select("SELECT * FROM orders WHERE id = #{id}")
    OrderDto findById(Long id);

    @Insert("""
        INSERT INTO orders (order_no, amount, status, created_at)
        VALUES (#{orderNo}, #{amount}, #{status}, NOW())
        """)
    @Options(useGeneratedKeys = true, keyProperty = "id")
    int insert(OrderDto dto);

    // XML 방식 — 복잡한 쿼리는 이쪽
    List<OrderSummary> search(OrderSearchCond cond);
}

XML 매퍼

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
        "https://mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="com.myapp.order.mapper.OrderMapper">

  <select id="search" resultType="OrderSummary">
    SELECT o.id,
           o.order_no   AS orderNo,
           u.name       AS userName,
           o.amount,
           o.created_at AS createdAt
      FROM orders o
      JOIN users u ON u.id = o.user_id
     WHERE o.deleted_at IS NULL
     ORDER BY o.created_at DESC
     LIMIT #{size} OFFSET #{offset}
  </select>

</mapper>

동적 SQL

<select id="search" resultType="OrderSummary">
  SELECT o.*, u.name AS userName
    FROM orders o
    JOIN users u ON u.id = o.user_id
  <where>                          <!-- 조건이 하나도 없으면 WHERE 자체를 안 붙임 -->
    <if test="status != null">
      AND o.status = #{status}
    </if>
    <if test="userName != null and userName != ''">
      AND u.name LIKE CONCAT('%', #{userName}, '%')
    </if>
    <if test="from != null and to != null">
      AND o.created_at BETWEEN #{from} AND #{to}
    </if>
    <if test="statuses != null and statuses.size() > 0">
      AND o.status IN
      <foreach collection="statuses" item="s" open="(" separator="," close=")">
        #{s}
      </foreach>
    </if>
  </where>
  <choose>
    <when test="sort == 'amount'">ORDER BY o.amount DESC</when>
    <otherwise>ORDER BY o.created_at DESC</otherwise>
  </choose>
</select>

<!-- UPDATE 에는 set -->
<update id="update">
  UPDATE orders
  <set>                            <!-- 마지막 콤마를 알아서 제거 -->
    <if test="status != null">status = #{status},</if>
    <if test="memo != null">memo = #{memo},</if>
    updated_at = NOW()
  </set>
  WHERE id = #{id}
</update>

결과 매핑 · 대량 처리

<!-- 1:N 을 한 번에 매핑 -->
<resultMap id="orderDetail" type="OrderDetail">
  <id property="id" column="o_id"/>
  <result property="orderNo" column="order_no"/>
  <association property="user" javaType="UserDto">
    <id property="id" column="u_id"/>
    <result property="name" column="u_name"/>
  </association>
  <collection property="items" ofType="ItemDto">
    <id property="id" column="i_id"/>
    <result property="name" column="i_name"/>
  </collection>
</resultMap>

<!-- 대량 INSERT — 한 번의 쿼리로 ★ -->
<insert id="insertAll">
  INSERT INTO orders (order_no, amount, status) VALUES
  <foreach collection="list" item="o" separator=",">
    (#{o.orderNo}, #{o.amount}, #{o.status})
  </foreach>
</insert>

// 수십만 건 조회를 메모리에 안 올리고 처리
@Select("SELECT * FROM orders")
@Options(fetchSize = 1000, resultSetType = ResultSetType.FORWARD_ONLY)
Cursor<OrderDto> scanAll();

// ⚠️ 트랜잭션(@Transactional) 안에서 열어야 합니다 — 밖이면 세션이 바로 닫혀 Cursor 도 닫힙니다
//    MySQL 은 URL 에 useCursorFetch=true 가 있어야 fetchSize 가 먹습니다 (없으면 통째로 적재)
try (Cursor<OrderDto> cursor = mapper.scanAll()) {
    for (OrderDto o : cursor) { process(o); }
}

기본 사용

@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)        // 클래스 기본값 = 읽기 전용
public class OrderService {

    @Transactional                      // 쓰기 메서드만 재정의
    public Order create(OrderCreateReq req) { ... }

    // 옵션
    @Transactional(
        timeout = 5,                              // 5초 넘으면 롤백
        isolation = Isolation.READ_COMMITTED,     // 격리 수준
        propagation = Propagation.REQUIRED,       // 전파 방식
        rollbackFor = Exception.class             // ★ 체크 예외도 롤백
    )
    public void process() { ... }
}

전파(Propagation)

// 실전 예: 주문이 실패해도 로그는 반드시 남긴다
@Transactional(propagation = Propagation.REQUIRES_NEW)
public void writeAuditLog(String message) {
    auditRepository.save(new AuditLog(message));
}

동시성 — 락

// 낙관적 락 — 충돌이 드물 때 (권장)
@Entity
public class Product {
    @Version
    private Long version;      // 수정할 때마다 +1
}
// 다른 트랜잭션이 먼저 고쳤으면
// -> OptimisticLockingFailureException

// 비관적 락 — 재고 차감처럼 충돌이 잦을 때
@Lock(LockModeType.PESSIMISTIC_WRITE)
@Query("SELECT p FROM Product p WHERE p.id = :id")
Optional<Product> findByIdForUpdate(Long id);
// SELECT ... FOR UPDATE

// 재시도로 감싸기
@Retryable(retryFor = OptimisticLockingFailureException.class,
           maxAttempts = 3, backoff = @Backoff(delay = 100))
@Transactional
public void decrease(Long id, int qty) { ... }

트랜잭션 설계 원칙

• 짧게 유지하세요 — 트랜잭션이 길면 커넥션을 오래 붙잡아 풀이 고갈됩니다
• 외부 API 호출을 트랜잭션 안에 넣지 마세요 — 상대가 느려지면 우리 DB 커넥션이 전부 묶입니다
• 커밋 후 처리는 이벤트로

// 커밋된 뒤에만 알림 보내기 ★
@TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
public void onOrderPaid(OrderPaidEvent event) {
    notifier.send(event.email(), "결제 완료");
    // 트랜잭션이 롤백되면 이 코드는 아예 실행되지 않습니다 ✅
}

// 발행하는 쪽
@Transactional
public void pay(Long id) {
    Order o = ...;
    o.pay();
    eventPublisher.publishEvent(new OrderPaidEvent(o.getId(), o.getEmail()));
}

spring:
  jpa:
    hibernate:
      ddl-auto: validate       # ★ 엔티티와 스키마가 맞는지 검증만
  flyway:
    enabled: true
    baseline-on-migrate: true  # 기존 DB 에 처음 적용할 때
    locations: classpath:db/migration

-- V1__create_orders.sql
CREATE TABLE orders (
    id          BIGINT AUTO_INCREMENT PRIMARY KEY,
    order_no    VARCHAR(30)  NOT NULL,
    user_id     BIGINT       NOT NULL,
    amount      INT          NOT NULL,
    status      VARCHAR(20)  NOT NULL,
    memo        TEXT,
    created_at  DATETIME     NOT NULL,
    updated_at  DATETIME,
    version     BIGINT       NOT NULL DEFAULT 0,   -- @Version (validate 가 컬럼을 확인합니다)
    UNIQUE KEY uk_order_no (order_no),
    KEY idx_user_status (user_id, status)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

규칙

• 파일 이름은 V{번호}__{설명}.sql — 밑줄 2개입니다
• 적용된 파일은 절대 수정하지 마세요 — 체크섬이 달라져 실행이 막힙니다. 새 버전을 추가하세요
• flyway_schema_history 테이블에 이력이 남습니다
• 운영 DB 변경은 무중단을 고려해서 — 컬럼 추가는 안전, 삭제·이름 변경은 2단계로 나눠서

-- 안전한 컬럼 삭제 (2단계 배포)
-- 1단계: 코드에서 컬럼 사용을 제거하고 배포
-- 2단계: 다음 배포에서 실제 DROP
ALTER TABLE orders DROP COLUMN old_field;

직접 짜면 반드시 부딪히는 것들

@Scheduled 로 만든 자체 배치의 최후

  · 500만 건을 findAll() → 즉시 OOM
  · 3시간 돌다가 240만 건에서 실패 → 처음부터 다시
  · 어디까지 처리했는지 아무도 모름
  · 서버가 2대라 같은 배치가 동시에 두 번 돎
  · 실패했는데 아무도 몰랐고, 다음 날 정산이 틀림

Spring Batch 가 기본으로 해결해 주는 것
  ✓ 청크 단위 처리 (메모리 일정하게 유지)
  ✓ 실패 지점부터 재시작
  ✓ 실행 이력을 메타 테이블에 기록
  ✓ 같은 파라미터의 Job 중복 실행 차단
  ✓ 건너뛰기(skip)·재시도(retry) 정책

청크 처리 — 핵심 개념 하나

read → read → … → read  (chunk size 만큼 = 1,000건)
                    ↓
                 process  (한 건씩 변환·필터)
                    ↓
                  write   (1,000건을 한 번에 저장 · 커밋)
                    ↓
              메모리 비우고 다음 청크로

→ 500만 건이어도 메모리에는 항상 1,000건만 있습니다
→ 커밋도 1,000건마다 — 롤백 범위가 작습니다

실전 Job — Spring Boot 4 기준

@Configuration
@RequiredArgsConstructor
public class SettlementJobConfig {

    private final JobRepository jobRepository;
    private final PlatformTransactionManager txManager;
    private final DataSource dataSource;

    @Bean
    public Job settlementJob(Step settlementStep) {
        return new JobBuilder("settlementJob", jobRepository)
                .start(settlementStep)
                .build();
    }

    @Bean
    public Step settlementStep(ItemReader<Order> reader,
                               ItemProcessor<Order, Settlement> processor,
                               ItemWriter<Settlement> writer) {
        return new StepBuilder("settlementStep", jobRepository)
                .<Order, Settlement>chunk(1000, txManager)   // ★ 청크 크기
                .reader(reader)
                .processor(processor)
                .writer(writer)
                .faultTolerant()
                .skip(InvalidDataException.class).skipLimit(100)  // 100건까지는 건너뜀
                .retry(DeadlockLoserDataAccessException.class).retryLimit(3)
                .build();
    }

    // ★ 커서 방식 — 500만 건이어도 메모리는 일정
    @Bean
    @StepScope                                  // 실행 시점 파라미터를 받으려면 필수
    public JdbcCursorItemReader<Order> reader(
            @Value("#{jobParameters['targetDate']}") String targetDate) {
        return new JdbcCursorItemReaderBuilder<Order>()
                .name("orderReader")
                .dataSource(dataSource)
                .sql("select id, user_id, amount from orders where order_date = ?")
                .queryArguments(targetDate)
                .rowMapper(new DataClassRowMapper<>(Order.class))
                .fetchSize(1000)
                .build();
    }

    @Bean
    public JdbcBatchItemWriter<Settlement> writer() {
        return new JdbcBatchItemWriterBuilder<Settlement>()
                .dataSource(dataSource)
                .sql("insert into settlement (order_id, amount, fee) " +
                     "values (:orderId, :amount, :fee)")
                .beanMapped()
                .build();                       // 내부적으로 JDBC 배치 = 가장 빠름
    }
}

SINGLE_TABLE · JOINED 코드

@Entity
@Inheritance(strategy = InheritanceType.SINGLE_TABLE)
@DiscriminatorColumn(name = "payment_type")     // 기본 컬럼명은 DTYPE
public abstract class Payment {
    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private Long amount;
    @Enumerated(EnumType.STRING)
    private PaymentStatus status;
}

@Entity
@DiscriminatorValue("CARD")
public class CardPayment extends Payment {
    private String cardNo;          // ⚠️ NOT NULL 을 걸 수 없다 (다른 타입 행은 null)
    private int installment;
}

@Entity
@DiscriminatorValue("BANK")
public class BankTransfer extends Payment {
    private String bankCode;
    private String accountNo;
}

// JOINED 로 바꾸려면 애너테이션 한 줄
@Inheritance(strategy = InheritanceType.JOINED)
@DiscriminatorColumn(name = "payment_type")     // JOINED 에서는 선택 (있으면 조회가 빨라진다)

@MappedSuperclass — 상속이 아니라 '재사용'

// 테이블 상속이 아니라 '필드만 물려주는' 용도
@MappedSuperclass
@EntityListeners(AuditingEntityListener.class)
public abstract class BaseEntity {
    @CreatedDate
    @Column(updatable = false)
    private LocalDateTime createdAt;

    @LastModifiedDate
    private LocalDateTime updatedAt;

    @CreatedBy
    @Column(updatable = false)
    private String createdBy;
}

@Entity
public class Order extends BaseEntity { ... }    // 컬럼만 물려받는다

// 차이
// · @Inheritance   : 부모도 엔티티. 부모 타입으로 조회 가능 (다형 쿼리)
// · @MappedSuperclass : 부모는 엔티티가 아니다. 조회 불가. 순수 재사용
//
// 감사 필드·공통 id 는 대부분 @MappedSuperclass 가 정답이다

둘 중 무엇을 쓰나

식별 관계 vs 비식별 관계

// 식별 관계 — 부모 키가 자식 기본키의 일부 (위 예시)
// · 키가 계속 늘어난다 (손자 세대는 3개 컬럼)
// · 조인이 늘고 인덱스가 커진다

// 비식별 관계 — 자식은 자기 대리키를 가진다 (권장)
@Entity
public class OrderItem {
    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;                        // 대리키

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "order_id", nullable = false)
    private Order order;                    // 그냥 외래키

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "product_id", nullable = false)
    private Product product;

    // 논리적 유일성은 유니크 제약으로
    // @Table(uniqueConstraints = @UniqueConstraint(columnNames = {"order_id","product_id"}))
}

값 타입은 공유하면 안 된다

// ❌ 위험 — 같은 인스턴스를 두 엔티티가 참조
Address addr = new Address("12345", "서울", "1층");
memberA.setHomeAddress(addr);
memberB.setHomeAddress(addr);      // 같은 객체!

addr.setAddress1("부산");           // A, B 둘 다 바뀐다 (부작용)

// ✅ 값 타입은 '불변'으로 만든다 — 세터를 두지 않는다
// 바꿔야 하면 새 인스턴스로 통째 교체
memberA.changeAddress(new Address("54321", "부산", "2층"));

// 복사가 필요하면 명시적으로
Address copy = new Address(addr.getZipCode(), addr.getAddress1(), addr.getAddress2());

값 타입 컬렉션 — 쓰지 않는 편이 낫다

@ElementCollection
@CollectionTable(name = "member_tags",
    joinColumns = @JoinColumn(name = "member_id"))
@Column(name = "tag")
private Set<String> tags = new HashSet<>();

// 문제
// · List(bag) 로 두면 원소 하나만 바꿔도 전체 DELETE 후 전체 INSERT
//   (Set 은 행 단위로 지우지만, 그래도 원소를 값으로만 식별한다)
// · 원소에 기본키가 없어 추적이 안 된다
// · 지연 로딩·페이징이 어렵다

// ✅ 대안 — 엔티티로 승격
@Entity
public class MemberTag {
    @Id @GeneratedValue private Long id;
    @ManyToOne(fetch = FetchType.LAZY) private Member member;
    private String tag;
}
// 원소가 몇 개 안 되고 통째로 갈아끼우는 경우에만 @ElementCollection 을 쓰세요

AttributeConverter 기본

// enum 을 코드값으로 저장 (ORDINAL 도 STRING 도 싫을 때)
@Converter(autoApply = true)      // 이 타입 전체에 자동 적용
public class OrderStatusConverter implements AttributeConverter<OrderStatus, String> {

    @Override
    public String convertToDatabaseColumn(OrderStatus attr) {
        return attr == null ? null : attr.getCode();      // "01", "02" …
    }

    @Override
    public OrderStatus convertToEntityAttribute(String dbData) {
        return dbData == null ? null : OrderStatus.fromCode(dbData);
    }
}

// 암호화 컬럼 — 주민번호·계좌번호
@Converter
public class CryptoConverter implements AttributeConverter<String, String> {
    @Override public String convertToDatabaseColumn(String plain) {
        return plain == null ? null : AesUtil.encrypt(plain);
    }
    @Override public String convertToEntityAttribute(String cipher) {
        return cipher == null ? null : AesUtil.decrypt(cipher);
    }
}

@Entity
public class Member {
    @Convert(converter = CryptoConverter.class)
    private String ssn;               // DB 에는 암호문으로 저장된다
}

JSON 컬럼 다루기

// Hibernate 6 는 JSON 을 기본 지원한다
@Entity
public class Product {
    @Id @GeneratedValue private Long id;

    @JdbcTypeCode(SqlTypes.JSON)
    @Column(columnDefinition = "jsonb")        // PostgreSQL
    private ProductOptions options;            // 그냥 객체로 매핑된다

    @JdbcTypeCode(SqlTypes.JSON)
    private List<String> keywords;
}

public record ProductOptions(
    String color, String size, Map<String, String> extra) {}

// 컨버터로 직접 만들 수도 있다 (MySQL 등)
@Converter
public class JsonConverter implements AttributeConverter<ProductOptions, String> {
    private static final ObjectMapper MAPPER = new ObjectMapper();

    @Override public String convertToDatabaseColumn(ProductOptions attr) {
        try { return MAPPER.writeValueAsString(attr); }
        catch (JsonProcessingException e) { throw new IllegalStateException(e); }
    }
    @Override public ProductOptions convertToEntityAttribute(String db) {
        try { return db == null ? null : MAPPER.readValue(db, ProductOptions.class); }
        catch (JsonProcessingException e) { throw new IllegalStateException(e); }
    }
}