DooDoo IT Blog

데이터베이스 트랜잭션과 격리 수준

doodoo3804@gmail.com (DoYoon Kim) — Mon, 06 Apr 2026 00:00:00 +0900

들어가며

트랜잭션은 데이터베이스의 가장 근본적인 개념이다. “데이터 정합성”이라는 단어를 들어봤다면, 그 정합성을 보장하는 메커니즘이 바로 트랜잭션이다.

하지만 트랜잭션을 단순히 “커밋 아니면 롤백”으로만 이해하면 실무에서 동시성 문제에 부딪힌다. 이 글에서는 ACID 특성부터 격리 수준, 데드락, 락 전략까지 트랜잭션의 전체 그림을 정리한다.

트랜잭션 ACID 특성

트랜잭션은 네 가지 특성을 보장해야 한다.

Atomicity (원자성)

트랜잭션의 모든 연산은 전부 성공하거나 전부 실패한다. 중간 상태는 없다.

BEGIN;
UPDATE accounts SET balance = balance - 10000 WHERE id = 1;  -- 출금
UPDATE accounts SET balance = balance + 10000 WHERE id = 2;  -- 입금
COMMIT;
-- 둘 중 하나라도 실패하면 ROLLBACK → 둘 다 취소

Consistency (일관성)

트랜잭션 전후로 데이터베이스는 항상 일관된 상태를 유지한다. 제약 조건(NOT NULL, UNIQUE, FK 등)이 깨지지 않는다.

Isolation (격리성)

동시에 실행되는 트랜잭션들이 서로 간섭하지 않아야 한다. 격리 수준에 따라 간섭의 정도가 달라진다.

Durability (지속성)

커밋된 트랜잭션의 결과는 영구적으로 보존된다. 시스템 장애가 발생해도 커밋된 데이터는 유지된다 (WAL, redo log 등을 통해).

동시성 문제

격리성이 완벽하지 않을 때 발생하는 세 가지 대표적인 문제:

Dirty Read (더티 리드)

다른 트랜잭션이 커밋하지 않은 데이터를 읽는 것.

TX1: UPDATE accounts SET balance = 0 WHERE id = 1;  -- 아직 커밋 안 함
TX2: SELECT balance FROM accounts WHERE id = 1;      -- 0을 읽음 (Dirty Read)
TX1: ROLLBACK;                                        -- 원래 값으로 되돌아감
-- TX2는 존재하지 않는 데이터를 읽은 셈

Non-Repeatable Read (반복 불가능 읽기)

같은 쿼리를 두 번 실행했을 때 결과가 다른 것. 다른 트랜잭션이 커밋한 UPDATE 때문에 발생.

TX1: SELECT balance FROM accounts WHERE id = 1;  -- 10000
TX2: UPDATE accounts SET balance = 5000 WHERE id = 1; COMMIT;
TX1: SELECT balance FROM accounts WHERE id = 1;  -- 5000 (값이 바뀜!)

Phantom Read (팬텀 리드)

같은 조건으로 조회했을 때 행의 수가 달라지는 것. 다른 트랜잭션이 커밋한 INSERT/DELETE 때문에 발생.

TX1: SELECT COUNT(*) FROM orders WHERE status = 'PENDING';  -- 5건
TX2: INSERT INTO orders (status) VALUES ('PENDING'); COMMIT;
TX1: SELECT COUNT(*) FROM orders WHERE status = 'PENDING';  -- 6건 (유령 행!)

격리 수준 4단계

SQL 표준은 네 가지 격리 수준을 정의한다. 아래로 갈수록 격리성이 높고, 동시성(성능)은 떨어진다.

READ UNCOMMITTED

가장 낮은 격리 수준. 커밋되지 않은 데이터를 읽을 수 있다.

SET TRANSACTION ISOLATION LEVEL READ UNCOMMITTED;

Dirty Read: 발생
Non-Repeatable Read: 발생
Phantom Read: 발생

실무에서 거의 사용하지 않는다.

READ COMMITTED

대부분의 RDBMS 기본 격리 수준 (PostgreSQL, Oracle, SQL Server 포함). 커밋된 데이터만 읽는다.

SET TRANSACTION ISOLATION LEVEL READ COMMITTED;

Dirty Read: 방지
Non-Repeatable Read: 발생
Phantom Read: 발생

REPEATABLE READ

트랜잭션 시작 시점의 스냅샷을 기준으로 읽는다. MySQL InnoDB의 기본 격리 수준이다.

SET TRANSACTION ISOLATION LEVEL REPEATABLE READ;

Dirty Read: 방지
Non-Repeatable Read: 방지
Phantom Read: 발생 (MySQL InnoDB는 Gap Lock으로 대부분 방지)

SERIALIZABLE

가장 높은 격리 수준. 트랜잭션을 직렬로 실행한 것과 동일한 결과를 보장한다.

SET TRANSACTION ISOLATION LEVEL SERIALIZABLE;

Dirty Read: 방지
Non-Repeatable Read: 방지
Phantom Read: 방지

성능 오버헤드가 크므로 꼭 필요한 경우에만 사용한다.

격리 수준 비교표

격리 수준	Dirty Read	Non-Repeatable Read	Phantom Read
READ UNCOMMITTED	O	O	O
READ COMMITTED	X	O	O
REPEATABLE READ	X	X	O
SERIALIZABLE	X	X	X

PostgreSQL 격리 수준 실제 동작

PostgreSQL은 내부적으로 MVCC(Multi-Version Concurrency Control) 를 사용한다. PostgreSQL의 쿼리 성능 최적화가 필요하다면 PostgreSQL 인덱스 제대로 이해하기도 함께 참고하자. 각 트랜잭션에 스냅샷을 할당하여 락 없이도 격리성을 제공한다.

PostgreSQL의 특이점

PostgreSQL은 실제로 3단계 격리 수준만 구현한다:

설정값	실제 동작
READ UNCOMMITTED	READ COMMITTED로 동작 (Dirty Read 허용 안 함)
READ COMMITTED	READ COMMITTED
REPEATABLE READ	Snapshot Isolation (REPEATABLE READ)
SERIALIZABLE	Serializable Snapshot Isolation (SSI)

PostgreSQL은 어떤 격리 수준에서도 Dirty Read를 허용하지 않는다.

READ COMMITTED에서의 동작

-- TX1
BEGIN;
SELECT balance FROM accounts WHERE id = 1;  -- 10000

-- TX2
BEGIN;
UPDATE accounts SET balance = 5000 WHERE id = 1;
COMMIT;

-- TX1 (계속)
SELECT balance FROM accounts WHERE id = 1;  -- 5000 (TX2의 커밋 반영)
COMMIT;

각 SQL문 실행 시점에 새로운 스냅샷을 가져온다. 같은 트랜잭션 내에서도 다른 트랜잭션의 커밋이 보인다.

REPEATABLE READ에서의 동작

-- TX1
BEGIN TRANSACTION ISOLATION LEVEL REPEATABLE READ;
SELECT balance FROM accounts WHERE id = 1;  -- 10000

-- TX2
BEGIN;
UPDATE accounts SET balance = 5000 WHERE id = 1;
COMMIT;

-- TX1 (계속)
SELECT balance FROM accounts WHERE id = 1;  -- 10000 (스냅샷 유지!)
COMMIT;

트랜잭션 시작 시점의 스냅샷을 계속 사용한다. 다른 트랜잭션의 커밋을 볼 수 없다.

REPEATABLE READ에서의 충돌 감지

-- TX1
BEGIN TRANSACTION ISOLATION LEVEL REPEATABLE READ;
UPDATE accounts SET balance = balance - 1000 WHERE id = 1;

-- TX2
BEGIN TRANSACTION ISOLATION LEVEL REPEATABLE READ;
UPDATE accounts SET balance = balance - 2000 WHERE id = 1;
-- TX2는 TX1이 커밋할 때까지 대기

-- TX1
COMMIT;

-- TX2
-- ERROR: could not serialize access due to concurrent update
ROLLBACK;

같은 행을 동시에 수정하면 먼저 커밋한 쪽이 승리하고, 나중 트랜잭션은 에러가 발생한다. 애플리케이션에서 재시도 로직이 필요하다.

SERIALIZABLE (SSI)

PostgreSQL의 SERIALIZABLE은 Serializable Snapshot Isolation(SSI) 알고리즘을 사용한다. 전통적인 락 기반이 아닌, 스냅샷 격리에 직렬화 충돌 감지를 추가한 방식이다.

-- TX1
BEGIN TRANSACTION ISOLATION LEVEL SERIALIZABLE;
SELECT SUM(balance) FROM accounts WHERE branch = 'A';  -- 결과를 기반으로 작업
INSERT INTO audit_log (total) VALUES (50000);

-- TX2
BEGIN TRANSACTION ISOLATION LEVEL SERIALIZABLE;
SELECT SUM(balance) FROM accounts WHERE branch = 'A';  -- 같은 데이터를 읽음
UPDATE accounts SET balance = balance + 1000 WHERE id = 1;

-- 둘 다 커밋 시도 → 직렬화 불가능하면 한쪽이 실패

읽기-쓰기 의존성(rw-dependency)을 추적하여 직렬화 불가능한 패턴을 감지하면 한쪽 트랜잭션을 롤백한다.

Spring @Transactional 옵션

propagation (전파 속성)

트랜잭션이 이미 존재할 때 새 트랜잭션을 어떻게 처리할지 결정한다:

@Transactional(propagation = Propagation.REQUIRED)  // 기본값
public void methodA() {
    // 기존 트랜잭션이 있으면 참여, 없으면 새로 생성
}

@Transactional(propagation = Propagation.REQUIRES_NEW)
public void methodB() {
    // 항상 새 트랜잭션 생성 (기존 트랜잭션은 일시 중단)
}

@Transactional(propagation = Propagation.MANDATORY)
public void methodC() {
    // 기존 트랜잭션이 반드시 있어야 함 (없으면 예외)
}

전파 속성	기존 TX 있음	기존 TX 없음
REQUIRED (기본)	참여	새로 생성
REQUIRES_NEW	새로 생성 (기존 중단)	새로 생성
MANDATORY	참여	예외 발생
SUPPORTS	참여	TX 없이 실행
NOT_SUPPORTED	TX 없이 실행 (기존 중단)	TX 없이 실행
NEVER	예외 발생	TX 없이 실행
NESTED	중첩 TX (세이브포인트)	새로 생성

isolation (격리 수준)

@Transactional(isolation = Isolation.READ_COMMITTED)
public void readData() {
    // READ COMMITTED 격리 수준으로 실행
}

@Transactional(isolation = Isolation.REPEATABLE_READ)
public void consistentRead() {
    // REPEATABLE READ 격리 수준으로 실행
}

@Transactional(isolation = Isolation.SERIALIZABLE)
public void criticalOperation() {
    // SERIALIZABLE 격리 수준으로 실행 (가장 엄격)
}

readOnly

@Transactional(readOnly = true)
public List<Order> findOrders() {
    // Hibernate: 더티 체킹 비활성화 → 성능 향상
    // DB: 읽기 전용 힌트 전달 → 일부 DB에서 최적화
    return orderRepository.findAll();
}

읽기 전용 메서드에는 readOnly = true를 반드시 설정하자. Hibernate의 더티 체킹 비용을 절약하고, DB 레플리카로 라우팅할 수도 있다.

timeout과 rollbackFor

@Transactional(
    timeout = 5,                          // 5초 초과 시 롤백
    rollbackFor = BusinessException.class  // Checked 예외에도 롤백
)
public void processOrder(Long orderId) {
    // ...
}

기본적으로 @Transactional은 Unchecked 예외(RuntimeException)에만 롤백한다. Checked 예외에도 롤백하려면 rollbackFor를 지정해야 한다.

주의: 프록시 기반 동작

Spring의 @Transactional은 AOP 프록시를 통해 동작한다. 같은 클래스 내부에서 호출하면 프록시를 거치지 않아 트랜잭션이 적용되지 않는다:

@Service
public class OrderService {

    public void outer() {
        // 같은 클래스의 inner() 호출 → 프록시를 안 거침
        // inner()의 @Transactional이 동작하지 않음!
        this.inner();
    }

    @Transactional
    public void inner() {
        // ...
    }
}

해결 방법:

inner()를 별도 클래스로 분리
self-injection 사용 (@Lazy 등)
TransactionTemplate 프로그래밍 방식 사용

데드락 발생 원인과 해결

데드락이란

두 개 이상의 트랜잭션이 서로가 보유한 락을 기다리며 무한 대기 상태에 빠지는 것.

TX1: Lock(A) → Lock(B) 시도 → 대기 (TX2가 B를 보유)
TX2: Lock(B) → Lock(A) 시도 → 대기 (TX1이 A를 보유)
→ 교착 상태!

SQL 예시

-- TX1
BEGIN;
UPDATE accounts SET balance = balance - 100 WHERE id = 1;  -- id=1 락
-- (잠시 후)
UPDATE accounts SET balance = balance + 100 WHERE id = 2;  -- id=2 락 대기

-- TX2
BEGIN;
UPDATE accounts SET balance = balance - 200 WHERE id = 2;  -- id=2 락
-- (잠시 후)
UPDATE accounts SET balance = balance + 200 WHERE id = 1;  -- id=1 락 대기

-- 데드락! DB가 한쪽을 강제 롤백

데드락 감지

PostgreSQL은 deadlock_timeout(기본 1초) 후 데드락을 감지하고, 비용이 적은 트랜잭션을 롤백한다:

ERROR: deadlock detected
DETAIL: Process 12345 waits for ShareLock on transaction 67890;
        blocked by process 67891.
        Process 67891 waits for ShareLock on transaction 12345;
        blocked by process 12345.

데드락 예방 전략

1. 락 순서 통일

가장 효과적인 방법. 모든 트랜잭션이 동일한 순서로 리소스에 접근하면 데드락이 발생하지 않는다:

public void transfer(Long fromId, Long toId, int amount) {
    // 항상 작은 ID 먼저 락
    Long firstId = Math.min(fromId, toId);
    Long secondId = Math.max(fromId, toId);

    Account first = accountRepository.findByIdWithLock(firstId);
    Account second = accountRepository.findByIdWithLock(secondId);

    // 이체 로직
}

2. 트랜잭션 범위 최소화

// Bad: 외부 API 호출까지 트랜잭션에 포함
@Transactional
public void processOrder(Long orderId) {
    Order order = orderRepository.findById(orderId).orElseThrow();
    paymentGateway.charge(order.getAmount());  // 외부 API (수 초 소요)
    order.complete();
}

// Good: 트랜잭션 범위를 DB 작업만으로 제한
public void processOrder(Long orderId) {
    Order order = orderRepository.findById(orderId).orElseThrow();
    paymentGateway.charge(order.getAmount());  // 트랜잭션 밖

    completeOrder(orderId);  // 별도 트랜잭션
}

@Transactional
public void completeOrder(Long orderId) {
    Order order = orderRepository.findById(orderId).orElseThrow();
    order.complete();
}

3. 타임아웃 설정

@Transactional(timeout = 5)
public void criticalUpdate() {
    // 5초 내에 완료되지 않으면 롤백
}

낙관적 락 vs 비관적 락

동시성 제어를 위한 두 가지 전략이다.

비관적 락 (Pessimistic Lock)

“충돌이 자주 발생할 것”이라고 가정하고, 데이터를 읽는 시점에 락을 건다.

public interface AccountRepository extends JpaRepository<Account, Long> {

    // SELECT ... FOR UPDATE
    @Lock(LockModeType.PESSIMISTIC_WRITE)
    @Query("SELECT a FROM Account a WHERE a.id = :id")
    Account findByIdWithLock(@Param("id") Long id);
}

실행되는 SQL:

SELECT * FROM accounts WHERE id = 1 FOR UPDATE;
-- 이 행에 대해 다른 트랜잭션의 UPDATE/DELETE를 블로킹

사용 시점:

충돌이 빈번한 경우 (재고 차감, 선착순 이벤트)
데이터 정합성이 반드시 보장되어야 하는 경우
트랜잭션이 짧은 경우

주의사항:

락 대기로 인한 성능 저하
데드락 가능성
타임아웃 설정 필수

@Lock(LockModeType.PESSIMISTIC_WRITE)
@QueryHints({@QueryHint(name = "jakarta.persistence.lock.timeout", value = "3000")})
@Query("SELECT a FROM Account a WHERE a.id = :id")
Account findByIdWithLock(@Param("id") Long id);

낙관적 락 (Optimistic Lock)

“충돌이 드물 것”이라고 가정하고, 실제 업데이트 시점에 충돌을 감지한다.

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

    private String name;
    private int stock;

    @Version
    private Long version;  // 버전 필드
}

동작 방식:

-- 조회 시: version = 1
SELECT * FROM products WHERE id = 1;

-- 업데이트 시: WHERE에 version 조건 추가
UPDATE products
SET stock = 99, version = 2
WHERE id = 1 AND version = 1;

-- 영향받은 행이 0이면 → 다른 트랜잭션이 먼저 수정한 것
-- → ObjectOptimisticLockingFailureException 발생

서비스 계층에서 재시도 처리:

@Service
@RequiredArgsConstructor
public class ProductService {

    private final ProductRepository productRepository;

    @Retryable(
        retryFor = ObjectOptimisticLockingFailureException.class,
        maxAttempts = 3,
        backoff = @Backoff(delay = 100)
    )
    @Transactional
    public void decreaseStock(Long productId, int quantity) {
        Product product = productRepository.findById(productId)
            .orElseThrow(() -> new EntityNotFoundException("상품이 없습니다"));

        product.decreaseStock(quantity);
    }
}

@Retryable을 사용하려면 spring-retry 의존성과 @EnableRetry 설정이 필요하다.

사용 시점:

충돌이 드문 경우 (일반적인 게시글 수정 등)
락으로 인한 성능 저하를 피하고 싶은 경우
읽기가 많고 쓰기가 적은 경우

비교 정리

항목	비관적 락	낙관적 락
전략	충돌 예방 (락 선점)	충돌 감지 (버전 체크)
구현	`SELECT FOR UPDATE`	`@Version` 필드
성능	락 대기 오버헤드	충돌 시 재시도 오버헤드
데드락	가능	불가능
적합한 상황	충돌 빈번, 짧은 TX	충돌 드묾, 읽기 위주
실패 시	대기 후 실행	예외 발생 → 재시도

실무 의사결정 가이드

동시 수정이 발생하는가?
├── 거의 없음 → 낙관적 락 (@Version)
└── 빈번함
    ├── 정합성이 절대적 → 비관적 락 (SELECT FOR UPDATE)
    └── 약간의 지연 허용 → 낙관적 락 + 재시도

마무리

트랜잭션은 단순히 @Transactional을 붙이는 것으로 끝나지 않는다.

ACID를 이해하고, 특히 Isolation이 성능과 트레이드오프 관계임을 인지하자.
격리 수준은 기본값(READ COMMITTED)을 유지하되, 특정 비즈니스 로직에서 REPEATABLE READ가 필요한지 검토하자.
데드락은 락 순서 통일과 트랜잭션 범위 최소화로 예방하자.
낙관적 락 vs 비관적 락은 충돌 빈도에 따라 선택하자. 대부분의 경우 낙관적 락으로 시작하는 것이 좋다.
Spring의 @Transactional은 프록시 기반임을 잊지 말고, 내부 호출 시 트랜잭션이 적용되지 않는 함정을 주의하자.

항상 spring.jpa.show-sql=true와 로그 레벨 설정을 통해 실제 실행되는 SQL과 트랜잭션 경계를 확인하는 습관을 들이자.

Spring Security 아키텍처 완전 이해

doodoo3804@gmail.com (DoYoon Kim) — Sun, 05 Apr 2026 00:00:00 +0900

들어가며

Spring Security는 Spring 기반 애플리케이션의 인증(Authentication)과 인가(Authorization)를 담당하는 프레임워크다. 강력하지만 그만큼 내부 구조가 복잡하다.

설정을 복사해서 붙여넣기만 하면 “왜 이렇게 동작하는지” 이해하지 못한 채로 개발하게 된다. 이 글에서는 Spring Security 6.x(Spring Boot 3.x) 기준으로 아키텍처를 밑바닥부터 정리한다.

Spring Security 필터 체인 구조

서블릿 필터 기반

Spring Security는 서블릿 필터(Servlet Filter) 기반으로 동작한다. 클라이언트의 HTTP 요청이 DispatcherServlet에 도달하기 전에 보안 필터 체인을 거친다.

Client → [Filter₁] → [Filter₂] → ... → [FilterN] → DispatcherServlet → Controller

DelegatingFilterProxy와 FilterChainProxy

Spring Security는 서블릿 컨테이너와 Spring 컨테이너를 연결하기 위해 두 가지 핵심 컴포넌트를 사용한다:

서블릿 컨테이너
└── DelegatingFilterProxy (서블릿 필터)
    └── FilterChainProxy (Spring Bean)
        └── SecurityFilterChain
            ├── DisableEncodeUrlFilter
            ├── SecurityContextHolderFilter
            ├── CsrfFilter
            ├── LogoutFilter
            ├── UsernamePasswordAuthenticationFilter
            ├── BearerTokenAuthenticationFilter
            ├── AuthorizationFilter
            └── ...

DelegatingFilterProxy: 서블릿 필터로 등록되지만, 실제 처리를 Spring Bean인 FilterChainProxy에 위임한다.
FilterChainProxy: 여러 SecurityFilterChain을 관리하며, 요청 URL에 맞는 체인을 선택하여 실행한다.

SecurityFilterChain 설정

Spring Security 6.x에서는 SecurityFilterChain을 Bean으로 등록하여 설정한다:

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .csrf(csrf -> csrf.disable())
            .sessionManagement(session ->
                session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/auth/**").permitAll()
                .requestMatchers("/api/admin/**").hasRole("ADMIN")
                .anyRequest().authenticated()
            );

        return http.build();
    }
}

다중 SecurityFilterChain

URL 패턴에 따라 서로 다른 보안 설정을 적용할 수 있다:

@Bean
@Order(1)
public SecurityFilterChain apiFilterChain(HttpSecurity http) throws Exception {
    http
        .securityMatcher("/api/**")
        .authorizeHttpRequests(auth -> auth.anyRequest().authenticated())
        .addFilterBefore(jwtAuthFilter, UsernamePasswordAuthenticationFilter.class);
    return http.build();
}

@Bean
@Order(2)
public SecurityFilterChain webFilterChain(HttpSecurity http) throws Exception {
    http
        .securityMatcher("/**")
        .authorizeHttpRequests(auth -> auth.anyRequest().permitAll());
    return http.build();
}

@Order가 작을수록 먼저 매칭을 시도한다. /api/users 요청은 apiFilterChain에, /home 요청은 webFilterChain에 매칭된다.

Authentication vs Authorization

Spring Security의 두 핵심 개념을 명확히 구분해야 한다.

Authentication (인증)

“너는 누구냐?” — 사용자의 신원을 확인하는 과정.

로그인 (ID/PW 확인)
JWT 토큰 검증
OAuth2 소셜 로그인

Authorization (인가)

“너는 이걸 할 수 있느냐?” — 인증된 사용자가 특정 리소스에 접근할 권한이 있는지 확인하는 과정.

ROLE_USER는 /api/users에 접근 가능
ROLE_ADMIN만 /api/admin에 접근 가능

처리 순서

요청 → [인증 필터] → SecurityContext에 Authentication 저장 → [인가 필터] → Controller

인증이 먼저 수행되고, 그 결과(Authentication 객체)를 바탕으로 인가가 수행된다.

SecurityContextHolder와 SecurityContext

구조

SecurityContextHolder
└── SecurityContext
    └── Authentication
        ├── Principal (사용자 정보)
        ├── Credentials (비밀번호 등)
        └── Authorities (권한 목록)

SecurityContextHolder

SecurityContext를 보관하는 저장소다. 기본적으로 ThreadLocal을 사용하여 스레드별로 SecurityContext를 관리한다.

// 현재 인증된 사용자 정보 가져오기
SecurityContext context = SecurityContextHolder.getContext();
Authentication authentication = context.getAuthentication();

String username = authentication.getName();
Collection extends GrantedAuthority> authorities = authentication.getAuthorities();

Authentication 인터페이스

public interface Authentication extends Principal, Serializable {
    // 권한 목록 (ROLE_USER, ROLE_ADMIN 등)
    Collection extends GrantedAuthority> getAuthorities();

    // 비밀번호 (인증 후 보안을 위해 null로 지워짐)
    Object getCredentials();

    // 사용자 상세 정보
    Object getDetails();

    // UserDetails 또는 사용자 식별자
    Object getPrincipal();

    // 인증 완료 여부
    boolean isAuthenticated();
}

컨트롤러에서 인증 정보 접근

@RestController
@RequestMapping("/api")
public class UserController {

    // 방법 1: @AuthenticationPrincipal
    @GetMapping("/me")
    public UserResponse getMyInfo(@AuthenticationPrincipal UserDetails userDetails) {
        return userService.findByUsername(userDetails.getUsername());
    }

    // 방법 2: SecurityContextHolder 직접 접근
    @GetMapping("/me2")
    public UserResponse getMyInfo2() {
        Authentication auth = SecurityContextHolder.getContext().getAuthentication();
        String username = auth.getName();
        return userService.findByUsername(username);
    }
}

UserDetailsService와 UserDetails 구현

UserDetails 인터페이스

Spring Security가 이해하는 사용자 정보 형태다:

public interface UserDetails extends Serializable {
    Collection extends GrantedAuthority> getAuthorities();
    String getPassword();
    String getUsername();
    boolean isAccountNonExpired();
    boolean isAccountNonLocked();
    boolean isCredentialsNonExpired();
    boolean isEnabled();
}

커스텀 UserDetails 구현

@Getter
@RequiredArgsConstructor
public class CustomUserDetails implements UserDetails {

    private final User user;  // 우리 도메인의 User 엔티티

    @Override
    public Collection extends GrantedAuthority> getAuthorities() {
        return List.of(new SimpleGrantedAuthority("ROLE_" + user.getRole().name()));
    }

    @Override
    public String getPassword() {
        return user.getPassword();
    }

    @Override
    public String getUsername() {
        return user.getEmail();
    }

    @Override
    public boolean isAccountNonExpired() { return true; }

    @Override
    public boolean isAccountNonLocked() { return true; }

    @Override
    public boolean isCredentialsNonExpired() { return true; }

    @Override
    public boolean isEnabled() { return user.isActive(); }
}

UserDetailsService 구현

DB에서 사용자 정보를 조회하여 UserDetails로 변환하는 역할:

@Service
@RequiredArgsConstructor
public class CustomUserDetailsService implements UserDetailsService {

    private final UserRepository userRepository;

    @Override
    public UserDetails loadUserByUsername(String email) throws UsernameNotFoundException {
        User user = userRepository.findByEmail(email)
            .orElseThrow(() ->
                new UsernameNotFoundException("사용자를 찾을 수 없습니다: " + email));

        return new CustomUserDetails(user);
    }
}

AuthenticationProvider와의 관계

AuthenticationFilter
  → AuthenticationManager
    → AuthenticationProvider
      → UserDetailsService.loadUserByUsername()
      → PasswordEncoder.matches()
    → Authentication 객체 반환
  → SecurityContextHolder에 저장

AuthenticationProvider는 UserDetailsService로 사용자를 조회하고, PasswordEncoder로 비밀번호를 검증한 뒤 Authentication 객체를 만들어 반환한다.

JWT 기반 인증 구현

실제 JWT 인증의 전체 구현 코드와 Refresh Token 전략은 Spring Security 6 + JWT 인증 구현에서 다룬다.

JWT 유틸리티 클래스

@Component
public class JwtTokenProvider {

    @Value("${jwt.secret}")
    private String secretKey;

    @Value("${jwt.access-token-validity}")
    private long accessTokenValidity;  // 예: 30분

    @Value("${jwt.refresh-token-validity}")
    private long refreshTokenValidity;  // 예: 7일

    private SecretKey getSigningKey() {
        byte[] keyBytes = Decoders.BASE64.decode(secretKey);
        return Keys.hmacShaKeyFor(keyBytes);
    }

    public String generateAccessToken(Authentication authentication) {
        CustomUserDetails userDetails = (CustomUserDetails) authentication.getPrincipal();
        Date now = new Date();
        Date expiry = new Date(now.getTime() + accessTokenValidity);

        return Jwts.builder()
            .subject(userDetails.getUsername())
            .claim("role", userDetails.getUser().getRole().name())
            .issuedAt(now)
            .expiration(expiry)
            .signWith(getSigningKey())
            .compact();
    }

    public String getUsernameFromToken(String token) {
        return Jwts.parser()
            .verifyWith(getSigningKey())
            .build()
            .parseSignedClaims(token)
            .getPayload()
            .getSubject();
    }

    public boolean validateToken(String token) {
        try {
            Jwts.parser()
                .verifyWith(getSigningKey())
                .build()
                .parseSignedClaims(token);
            return true;
        } catch (JwtException | IllegalArgumentException e) {
            return false;
        }
    }
}

JwtAuthenticationFilter

모든 요청에서 JWT를 검증하고 SecurityContext에 인증 정보를 저장하는 필터:

@Component
@RequiredArgsConstructor
public class JwtAuthenticationFilter extends OncePerRequestFilter {

    private final JwtTokenProvider jwtTokenProvider;
    private final CustomUserDetailsService userDetailsService;

    @Override
    protected void doFilterInternal(
            HttpServletRequest request,
            HttpServletResponse response,
            FilterChain filterChain) throws ServletException, IOException {

        // 1. 헤더에서 JWT 추출
        String token = resolveToken(request);

        // 2. 토큰 검증
        if (token != null && jwtTokenProvider.validateToken(token)) {
            // 3. 토큰에서 사용자 정보 추출
            String username = jwtTokenProvider.getUsernameFromToken(token);

            // 4. UserDetailsService로 사용자 조회
            UserDetails userDetails = userDetailsService.loadUserByUsername(username);

            // 5. Authentication 객체 생성 및 SecurityContext에 저장
            UsernamePasswordAuthenticationToken authentication =
                new UsernamePasswordAuthenticationToken(
                    userDetails, null, userDetails.getAuthorities());

            authentication.setDetails(
                new WebAuthenticationDetailsSource().buildDetails(request));

            SecurityContextHolder.getContext().setAuthentication(authentication);
        }

        filterChain.doFilter(request, response);
    }

    private String resolveToken(HttpServletRequest request) {
        String bearerToken = request.getHeader("Authorization");
        if (bearerToken != null && bearerToken.startsWith("Bearer ")) {
            return bearerToken.substring(7);
        }
        return null;
    }
}

SecurityConfig에 필터 등록

@Configuration
@EnableWebSecurity
@RequiredArgsConstructor
public class SecurityConfig {

    private final JwtAuthenticationFilter jwtAuthFilter;

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .csrf(csrf -> csrf.disable())
            .sessionManagement(session ->
                session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/auth/**").permitAll()
                .requestMatchers("/api/admin/**").hasRole("ADMIN")
                .anyRequest().authenticated()
            )
            .addFilterBefore(jwtAuthFilter,
                UsernamePasswordAuthenticationFilter.class);

        return http.build();
    }

    @Bean
    public AuthenticationManager authenticationManager(
            AuthenticationConfiguration config) throws Exception {
        return config.getAuthenticationManager();
    }

    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder();
    }
}

로그인 / 토큰 발급 API

@RestController
@RequestMapping("/api/auth")
@RequiredArgsConstructor
public class AuthController {

    private final AuthenticationManager authenticationManager;
    private final JwtTokenProvider jwtTokenProvider;

    @PostMapping("/login")
    public TokenResponse login(@RequestBody @Valid LoginRequest request) {
        // AuthenticationManager가 UserDetailsService + PasswordEncoder로 검증
        Authentication authentication = authenticationManager.authenticate(
            new UsernamePasswordAuthenticationToken(
                request.getEmail(), request.getPassword()));

        // 인증 성공 시 토큰 발급
        String accessToken = jwtTokenProvider.generateAccessToken(authentication);

        return new TokenResponse(accessToken);
    }
}

전체 인증 흐름 정리

POST /api/auth/login (email, password)
AuthenticationManager → UserDetailsService → DB 조회
PasswordEncoder.matches()로 비밀번호 검증
검증 성공 → JWT 토큰 발급 → 클라이언트에 반환

GET /api/users (Authorization: Bearer xxx)
JwtAuthenticationFilter → 토큰 파싱 → 유효성 검증
UserDetailsService → DB에서 사용자 조회
SecurityContext에 Authentication 저장
AuthorizationFilter → 권한 확인
Controller 도달

Method Security

URL 패턴 기반 인가 외에, 메서드 레벨에서도 권한을 제어할 수 있다.

활성화

@Configuration
@EnableMethodSecurity  // Spring Security 6.x
public class MethodSecurityConfig {
}

@PreAuthorize

메서드 실행 전에 권한을 검사한다. SpEL(Spring Expression Language)을 사용하여 유연한 조건을 표현할 수 있다:

@Service
@RequiredArgsConstructor
public class PostService {

    // ADMIN 역할만 삭제 가능
    @PreAuthorize("hasRole('ADMIN')")
    public void deletePost(Long postId) {
        postRepository.deleteById(postId);
    }

    // 본인 게시글만 수정 가능
    @PreAuthorize("#userId == authentication.principal.user.id")
    public PostResponse updatePost(Long userId, Long postId, PostUpdateRequest request) {
        // ...
    }

    // ADMIN이거나 본인인 경우
    @PreAuthorize("hasRole('ADMIN') or #userId == authentication.principal.user.id")
    public UserResponse getUserProfile(Long userId) {
        // ...
    }
}

@PostAuthorize

메서드 실행 후에 반환값을 기반으로 권한을 검사한다:

// 반환된 게시글의 작성자만 볼 수 있음
@PostAuthorize("returnObject.authorId == authentication.principal.user.id")
public PostDetailResponse getSecretPost(Long postId) {
    return postRepository.findById(postId)
        .map(PostDetailResponse::from)
        .orElseThrow();
}

@Secured

간단한 역할 기반 인가에 사용한다. SpEL은 지원하지 않는다:

@Secured("ROLE_ADMIN")
public void adminOnly() {
    // ...
}

@Secured({"ROLE_ADMIN", "ROLE_MANAGER"})
public void adminOrManager() {
    // ...
}

@PreAuthorize vs @Secured 비교

항목	@PreAuthorize	@Secured
SpEL 지원	O	X
복잡한 조건	`hasRole() and #id == ...`	역할 이름만 가능
파라미터 접근	`#paramName`으로 접근 가능	불가
권장 여부	권장	단순한 경우만

CSRF 설정

CSRF란

Cross-Site Request Forgery — 사용자가 의도하지 않은 요청을 보내도록 유도하는 공격이다. 세션 쿠키 기반 인증에서 위험하다.

REST API에서의 CSRF

JWT 기반의 stateless API는 쿠키를 사용하지 않으므로 CSRF 공격에 취약하지 않다. 따라서 비활성화하는 것이 일반적이다:

http.csrf(csrf -> csrf.disable());

CSRF를 활성화해야 하는 경우

서버 렌더링(Thymeleaf 등) + 세션 기반 인증을 사용하는 경우 CSRF 보호를 유지해야 한다:

http.csrf(csrf -> csrf
    .csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse())
    .csrfTokenRequestHandler(new CsrfTokenRequestAttributeHandler())
);

 th:action="@{/api/posts}" method="post">
     type="text" name="title" />
     type="submit">작성

CORS 설정

CORS란

Cross-Origin Resource Sharing — 브라우저가 다른 출처(Origin)의 리소스에 접근할 수 있도록 허용하는 메커니즘이다.

프론트엔드(localhost:3000)와 백엔드(localhost:8080)가 다른 포트에서 실행되면 CORS 에러가 발생한다.

Spring Security에서 CORS 설정

@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    http
        .cors(cors -> cors.configurationSource(corsConfigurationSource()))
        // ... 나머지 설정
    ;
    return http.build();
}

@Bean
public CorsConfigurationSource corsConfigurationSource() {
    CorsConfiguration config = new CorsConfiguration();

    config.setAllowedOrigins(List.of(
        "http://localhost:3000",
        "https://myapp.com"
    ));
    config.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE", "PATCH"));
    config.setAllowedHeaders(List.of("*"));
    config.setExposedHeaders(List.of("Authorization"));
    config.setAllowCredentials(true);
    config.setMaxAge(3600L);

    UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
    source.registerCorsConfiguration("/api/**", config);
    return source;
}

주요 설정 항목

항목	설명
`allowedOrigins`	허용할 출처 목록 (`*` 사용 시 credentials 불가)
`allowedMethods`	허용할 HTTP 메서드
`allowedHeaders`	허용할 요청 헤더
`exposedHeaders`	클라이언트에서 읽을 수 있는 응답 헤더
`allowCredentials`	쿠키/인증 헤더 포함 여부
`maxAge`	Preflight 요청 캐싱 시간(초)

마무리

Spring Security의 핵심 아키텍처를 정리하면:

필터 체인: 요청이 Controller에 도달하기 전에 보안 필터를 순서대로 통과한다.
인증(Authentication): 사용자가 누구인지 확인하고 SecurityContext에 저장한다.
인가(Authorization): SecurityContext의 권한 정보를 바탕으로 접근을 허용/거부한다.
JWT 인증: 커스텀 필터에서 토큰을 검증하고 SecurityContext에 수동으로 인증 정보를 설정한다.
Method Security: URL 패턴뿐 아니라 메서드 레벨에서도 세밀한 권한 제어가 가능하다.

이 구조를 이해하면 Spring Security의 어떤 기능을 쓰더라도 “왜 이렇게 동작하는지” 설명할 수 있다. 복사-붙여넣기 설정에서 벗어나 자신만의 보안 설계를 할 수 있게 된다.

JPA N+1 문제 완전 정복

doodoo3804@gmail.com (DoYoon Kim) — Sat, 04 Apr 2026 00:00:00 +0900

들어가며

Spring Boot + JPA 기초에서 기본적인 CRUD API를 구현했다면, 실무에서 반드시 만나게 되는 문제가 있다. 바로 N+1 문제다. 엔티티 하나를 조회했을 뿐인데 연관된 엔티티를 가져오기 위해 추가 쿼리가 N번 더 나가는 현상이다.

개발 단계에서는 데이터가 적어 문제를 인지하지 못하다가, 운영 환경에서 데이터가 쌓이면 성능이 급격히 떨어진다. 이 글에서는 N+1 문제의 원인을 정확히 이해하고, 상황에 맞는 해결 전략을 코드와 함께 정리한다.

N+1 문제란 무엇인가

개념

N+1 문제란 1번의 쿼리로 N개의 엔티티를 조회한 뒤, 각 엔티티의 연관 관계를 조회하기 위해 N번의 추가 쿼리가 발생하는 현상이다.

예를 들어 Team과 Member가 1:N 관계일 때:

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

    @OneToMany(mappedBy = "team")
    private List<Member> members = new ArrayList<>();
}

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

    @ManyToOne
    @JoinColumn(name = "team_id")
    private Team team;
}

팀 목록을 조회하고 각 팀의 멤버를 출력하면:

List<Team> teams = teamRepository.findAll(); // 쿼리 1번

for (Team team : teams) {
    System.out.println(team.getMembers().size()); // 팀마다 쿼리 1번씩
}

팀이 10개면 1(팀 전체 조회) + 10(각 팀의 멤버 조회) = 11번의 쿼리가 실행된다. 팀이 1000개면 1001번이다.

발생 원인

N+1 문제는 JPA가 연관 엔티티를 프록시 객체로 감싸고, 실제 접근 시점에 쿼리를 실행하는 지연 로딩(Lazy Loading) 메커니즘 때문에 발생한다.

JPQL이나 Spring Data JPA의 findAll()은 엔티티 자체만 조회하는 SQL을 생성한다. 연관 관계는 별도로 조회하지 않으며, 이후 해당 필드에 접근할 때 개별 쿼리가 나간다.

지연 로딩 vs 즉시 로딩

즉시 로딩 (EAGER)

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

엔티티 조회 시 연관 엔티티도 즉시 함께 가져온다. 하지만 이것이 N+1을 해결하지는 않는다.

JPQL을 사용하면 즉시 로딩이어도 N+1이 발생한다. JPQL은 SQL로 번역될 때 연관 관계를 고려하지 않고, 조회 후 즉시 로딩 설정을 보고 추가 쿼리를 실행하기 때문이다.

// EAGER로 설정해도 JPQL 사용 시 N+1 발생
@Query("SELECT t FROM Team t")
List<Team> findAllTeams();

지연 로딩 (LAZY)

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

연관 엔티티에 실제로 접근할 때 쿼리가 나간다. 접근하지 않으면 쿼리가 나가지 않는다는 장점이 있다.

결론: 기본 전략은 LAZY

모든 연관 관계는 FetchType.LAZY로 설정하는 것이 원칙이다. @ManyToOne, @OneToOne은 기본값이 EAGER이므로 명시적으로 LAZY를 지정해야 한다.

@ManyToOne(fetch = FetchType.LAZY)
@JoinColumn(name = "team_id")
private Team team;

지연 로딩으로 설정한 뒤, 필요한 시점에 적절한 방법으로 연관 엔티티를 함께 가져오는 것이 N+1 문제 해결의 핵심이다.

해결 전략 1: Fetch Join

가장 많이 사용하는 해결 방법이다. JPQL에서 JOIN FETCH를 사용하면 연관 엔티티를 한 번의 쿼리로 함께 조회한다.

기본 사용법

public interface TeamRepository extends JpaRepository<Team, Long> {

    @Query("SELECT t FROM Team t JOIN FETCH t.members")
    List<Team> findAllWithMembers();
}

실행되는 SQL:

SELECT t.*, m.*
FROM team t
INNER JOIN member m ON t.id = m.team_id

쿼리 1번으로 팀과 멤버를 모두 가져온다.

중복 제거: DISTINCT

일대다 Fetch Join은 카테시안 곱 때문에 결과가 중복될 수 있다. 팀 1개에 멤버 3명이면 팀이 3번 반복된다.

@Query("SELECT DISTINCT t FROM Team t JOIN FETCH t.members")
List<Team> findAllWithMembers();

Hibernate 6(Spring Boot 3.x)부터는 일대다 Fetch Join 시 자동으로 중복을 제거해주지만, 명시적으로 DISTINCT를 쓰는 것이 안전하다.

주의사항: 페이징 불가

일대다(1:N) Fetch Join에서는 페이징을 사용할 수 없다.

// 위험! 메모리에서 페이징 처리됨
@Query("SELECT t FROM Team t JOIN FETCH t.members")
Page<Team> findAllWithMembers(Pageable pageable);

Hibernate는 경고 로그를 남기면서 전체 데이터를 메모리에 올린 뒤 애플리케이션 레벨에서 페이징한다. 데이터가 많으면 OutOfMemoryError가 발생한다.

HHH90003004: firstResult/maxResults specified with collection fetch; applying in memory

다대일(N:1) Fetch Join은 페이징에 문제가 없다. 결과 row 수가 변하지 않기 때문이다.

// 안전! 다대일 Fetch Join + 페이징
@Query("SELECT m FROM Member m JOIN FETCH m.team")
Page<Member> findAllWithTeam(Pageable pageable);

주의사항: 둘 이상의 컬렉션 Fetch Join 불가

// MultipleBagFetchException 발생!
@Query("SELECT t FROM Team t JOIN FETCH t.members JOIN FETCH t.projects")
List<Team> findAllWithMembersAndProjects();

둘 이상의 @OneToMany 컬렉션을 동시에 Fetch Join하면 카테시안 곱이 기하급수적으로 증가한다. Hibernate는 이를 MultipleBagFetchException으로 차단한다.

해결 전략 2: @EntityGraph

@EntityGraph는 JPQL 없이도 Fetch Join과 동일한 효과를 낼 수 있다.

기본 사용법

public interface TeamRepository extends JpaRepository<Team, Long> {

    @EntityGraph(attributePaths = {"members"})
    @Query("SELECT t FROM Team t")
    List<Team> findAllWithMembers();
}

Spring Data JPA 메서드 이름 쿼리와 함께 사용

@EntityGraph(attributePaths = {"members"})
List<Team> findByName(String name);

JPQL을 직접 작성하지 않아도 되므로 간단한 경우에 유용하다.

중첩 연관 관계 로딩

@EntityGraph(attributePaths = {"members", "members.address"})
List<Team> findAllWithMembersAndAddress();

점(.)으로 중첩 경로를 지정할 수 있다.

Named EntityGraph

엔티티 클래스에 미리 정의하고 재사용할 수 있다:

@Entity
@NamedEntityGraph(
    name = "Team.withMembers",
    attributeNodes = @NamedAttributeNode("members")
)
public class Team {
    // ...
}

@EntityGraph(value = "Team.withMembers")
List<Team> findAll();

Fetch Join vs @EntityGraph

항목	Fetch Join	@EntityGraph
사용법	JPQL에 `JOIN FETCH` 작성	어노테이션으로 지정
JOIN 방식	INNER JOIN	LEFT OUTER JOIN
유연성	WHERE 조건 등 자유롭게 조합	단순 연관 로딩에 적합
가독성	JPQL이 길어질 수 있음	깔끔하고 선언적

@EntityGraph는 LEFT OUTER JOIN을 사용하므로, 연관 엔티티가 없는 경우에도 부모 엔티티가 조회된다. Fetch Join의 INNER JOIN과 동작이 다르니 주의하자.

해결 전략 3: Batch Size

페이징이 필요한 일대다 관계에서 가장 실용적인 해결책이다.

동작 원리

@BatchSize를 설정하면 지연 로딩 시 개별 쿼리 대신 IN 절로 묶어서 한 번에 조회한다.

@Entity
public class Team {
    @OneToMany(mappedBy = "team")
    @BatchSize(size = 100)
    private List<Member> members;
}

팀 10개를 조회하고 각 팀의 멤버에 접근하면:

-- Batch Size 없이: 쿼리 10번
SELECT * FROM member WHERE team_id = 1;
SELECT * FROM member WHERE team_id = 2;
...
SELECT * FROM member WHERE team_id = 10;

-- Batch Size = 100: 쿼리 1번
SELECT * FROM member WHERE team_id IN (1, 2, 3, ..., 10);

글로벌 설정

개별 엔티티마다 @BatchSize를 붙이는 대신, application.yml에서 글로벌로 설정할 수 있다:

spring:
  jpa:
    properties:
      hibernate:
        default_batch_fetch_size: 100

실무에서는 글로벌 설정을 100~1000 사이로 잡는 것을 권장한다. 김영한님의 JPA 강의에서도 이 방식을 강조한다.

Batch Size + 페이징 조합

Fetch Join으로 페이징이 불가능한 일대다 관계에서의 해결 패턴:

// 1. 부모 엔티티만 페이징 조회
@Query("SELECT t FROM Team t")
Page<Team> findAllPaged(Pageable pageable);

// 2. Batch Size 설정으로 자식 엔티티를 IN절로 조회
// application.yml에 default_batch_fetch_size: 100 설정

Page<Team> teams = teamRepository.findAllPaged(PageRequest.of(0, 10));

for (Team team : teams) {
    // Batch Size 덕분에 IN절 쿼리 1번으로 10개 팀의 멤버를 모두 조회
    System.out.println(team.getMembers().size());
}

총 쿼리: 2번 (팀 페이징 1번 + 멤버 IN절 1번). N+1이 1+1로 최적화된다.

해결 전략 4: QueryDSL

복잡한 조건이 필요하거나 동적 쿼리가 필요한 경우 QueryDSL이 강력하다.

기본 Fetch Join

@Repository
@RequiredArgsConstructor
public class TeamQueryRepository {

    private final JPAQueryFactory queryFactory;

    public List<Team> findAllWithMembers() {
        return queryFactory
            .selectFrom(team)
            .leftJoin(team.members, member).fetchJoin()
            .distinct()
            .fetch();
    }
}

동적 조건 + Fetch Join

public List<Team> searchTeams(TeamSearchCondition condition) {
    return queryFactory
        .selectFrom(team)
        .leftJoin(team.members, member).fetchJoin()
        .where(
            teamNameContains(condition.getTeamName()),
            memberCountGoe(condition.getMinMemberCount())
        )
        .distinct()
        .fetch();
}

private BooleanExpression teamNameContains(String teamName) {
    return hasText(teamName) ? team.name.contains(teamName) : null;
}

private BooleanExpression memberCountGoe(Integer minCount) {
    return minCount != null ? team.members.size().goe(minCount) : null;
}

DTO 직접 조회로 N+1 원천 차단

연관 엔티티의 특정 필드만 필요하다면, DTO로 직접 조회하여 N+1 자체를 없앨 수 있다:

public List<TeamMemberDto> findTeamMemberDtos() {
    return queryFactory
        .select(Projections.constructor(TeamMemberDto.class,
            team.name,
            member.username,
            member.age
        ))
        .from(team)
        .leftJoin(team.members, member)
        .fetch();
}

이 경우 엔티티가 아닌 순수 DTO를 반환하므로 지연 로딩 자체가 발생하지 않는다.

실무 가이드: 언제 무엇을 쓸까

의사결정 흐름

연관 엔티티를 함께 조회해야 하는가?
├── NO → Lazy Loading 유지 (쿼리 추가 없음)
└── YES
    ├── 페이징이 필요한가?
    │   ├── 다대일(N:1) → Fetch Join + 페이징 ✅
    │   └── 일대다(1:N) → Batch Size + 페이징 ✅
    ├── 단순 연관 로딩인가?
    │   ├── YES → @EntityGraph (간결)
    │   └── NO → Fetch Join (유연)
    ├── 동적 조건이 필요한가?
    │   └── YES → QueryDSL + Fetch Join
    └── 특정 컬럼만 필요한가?
        └── YES → DTO 직접 조회 (QueryDSL Projection)

실무 권장 설정

# application.yml
spring:
  jpa:
    properties:
      hibernate:
        default_batch_fetch_size: 100  # 글로벌 Batch Size
    open-in-view: false                # OSIV 끄기 (권장)

logging:
  level:
    org.hibernate.SQL: debug                              # SQL 로그
    org.hibernate.orm.jdbc.bind: trace                    # 바인딩 파라미터

정리

방법	장점	단점	사용 시점
Fetch Join	쿼리 1번, 가장 직관적	페이징 제한, 컬렉션 2개 이상 불가	기본 해결책
@EntityGraph	선언적, JPQL 불필요	LEFT JOIN 고정, 복잡한 조건 어려움	단순 연관 로딩
Batch Size	페이징 가능, 설정 간단	쿼리가 1+1번 (완전한 1번은 아님)	페이징 + 일대다
QueryDSL	동적 쿼리, 타입 안전	설정 복잡, 러닝 커브	복잡한 조건, 동적 쿼리
DTO 조회	N+1 원천 차단, 성능 최적	엔티티가 아닌 DTO 반환	조회 전용 API

마무리

N+1 문제는 JPA를 쓰는 한 피할 수 없다. 중요한 것은 문제를 인지하고, 상황에 맞는 해결책을 선택하는 것이다.

기본 전략: 모든 연관 관계를 LAZY로 설정하고, default_batch_fetch_size를 글로벌로 잡아둔다.
필요한 곳에서: Fetch Join 또는 @EntityGraph로 한 방 쿼리를 만든다.
페이징이 필요하면: Batch Size를 활용한다.
복잡한 조건이면: QueryDSL로 해결한다.

항상 hibernate.SQL 로그를 켜두고, 개발 단계에서 쿼리 수를 확인하는 습관을 들이자. 운영에서 터지기 전에 잡을 수 있다.

Apache Kafka 입문부터 실전까지

doodoo3804@gmail.com (DoYoon Kim) — Fri, 03 Apr 2026 00:00:00 +0900

Apache Kafka는 분산 이벤트 스트리밍 플랫폼이다. 단순한 메시지 큐를 넘어서 실시간 데이터 파이프라인과 이벤트 기반 아키텍처의 중심에 있다. 이 글에서는 핵심 개념부터 실전 패턴까지 정리한다.

1. Kafka 핵심 개념

1.1 아키텍처 개요

Producer ──→ [Broker Cluster] ──→ Consumer Group
                  │
            ┌─────┴─────┐
            │  Topic A   │
            │ ┌─────────┐│
            │ │Partition0││
            │ │Partition1││
            │ │Partition2││
            │ └─────────┘│
            └────────────┘

1.2 핵심 용어 정리

개념	설명
Topic	메시지를 분류하는 논리적 채널. 하나의 주제(예: `order-events`)
Partition	Topic을 물리적으로 나눈 단위. 각 파티션 내부는 순서 보장
Broker	Kafka 서버 인스턴스. 클러스터는 여러 브로커로 구성
Consumer Group	동일 그룹의 컨슈머가 파티션을 분담하여 병렬 소비
Offset	파티션 내 메시지의 고유 순번(0, 1, 2, …)
Producer	메시지를 Topic에 발행하는 클라이언트
Consumer	메시지를 Topic에서 읽는 클라이언트

1.3 Partition과 순서 보장

Topic: order-events (3 partitions)

Partition 0: [주문A 생성] → [주문A 결제] → [주문A 배송]
Partition 1: [주문B 생성] → [주문B 결제]
Partition 2: [주문C 생성] → [주문C 취소]

파티션 내부: 순서 보장 (같은 주문은 같은 파티션으로)
파티션 간: 순서 보장 안 됨

// 같은 키(orderId)를 가진 메시지는 동일 파티션으로
producer.send(new ProducerRecord<>("order-events", orderId, event));

1.4 Consumer Group 동작 방식

Topic: order-events (3 partitions)

Consumer Group "order-service":
  Consumer A ← Partition 0, 1
  Consumer B ← Partition 2

Consumer Group "analytics":
  Consumer C ← Partition 0, 1, 2  (독립적으로 전체 소비)

같은 그룹: 파티션을 분담 → 메시지를 한 번만 처리
다른 그룹: 독립적으로 전체 메시지를 소비

2. Producer/Consumer 동작 원리

2.1 Producer 동작

Properties props = new Properties();
props.put(ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, "localhost:9092");
props.put(ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG,
        StringSerializer.class.getName());
props.put(ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG,
        StringSerializer.class.getName());

// acks 설정
props.put(ProducerConfig.ACKS_CONFIG, "all"); // 모든 레플리카 확인

KafkaProducer<String, String> producer = new KafkaProducer<>(props);

// 비동기 전송
producer.send(new ProducerRecord<>("order-events", orderId, orderJson),
    (metadata, exception) -> {
        if (exception != null) {
            log.error("전송 실패: {}", exception.getMessage());
        } else {
            log.info("전송 성공: topic={}, partition={}, offset={}",
                    metadata.topic(), metadata.partition(), metadata.offset());
        }
    });

acks 설정별 동작:

acks	동작	성능	안정성
`0`	전송 후 확인 안 함	최고	최저
`1`	리더 브로커 기록 확인	중간	중간
`all` (`-1`)	모든 ISR 레플리카 기록 확인	최저	최고

2.2 Consumer 동작

Properties props = new Properties();
props.put(ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, "localhost:9092");
props.put(ConsumerConfig.GROUP_ID_CONFIG, "order-service");
props.put(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG,
        StringDeserializer.class.getName());
props.put(ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG,
        StringDeserializer.class.getName());
props.put(ConsumerConfig.ENABLE_AUTO_COMMIT_CONFIG, false); // 수동 커밋

KafkaConsumer<String, String> consumer = new KafkaConsumer<>(props);
consumer.subscribe(List.of("order-events"));

while (true) {
    ConsumerRecords<String, String> records =
            consumer.poll(Duration.ofMillis(1000));

    for (ConsumerRecord<String, String> record : records) {
        processOrder(record.value());
    }

    // 처리 완료 후 오프셋 커밋
    consumer.commitSync();
}

2.3 Commit 방식

방식	설정	특징
Auto Commit	`enable.auto.commit=true`	주기적 자동 커밋, 중복/유실 가능
Sync Commit	`commitSync()`	커밋 완료까지 블로킹, 안전
Async Commit	`commitAsync()`	논블로킹, 실패 시 재시도 어려움

// 레코드 단위 커밋 (가장 정밀)
for (ConsumerRecord<String, String> record : records) {
    processOrder(record.value());

    consumer.commitSync(Map.of(
            new TopicPartition(record.topic(), record.partition()),
            new OffsetAndMetadata(record.offset() + 1)
    ));
}

3. 메시지 보장 수준 비교

3.1 At-least-once, At-most-once, Exactly-once

보장 수준	설명	중복	유실	설정
At-most-once	최대 한 번 전달	✗	✓	처리 전 커밋
At-least-once	최소 한 번 전달	✓	✗	처리 후 커밋
Exactly-once	정확히 한 번 전달	✗	✗	트랜잭션 + 멱등성

3.2 At-most-once 구현

// 먼저 커밋 → 처리 중 실패하면 메시지 유실
ConsumerRecords<String, String> records = consumer.poll(Duration.ofMillis(1000));
consumer.commitSync(); // 먼저 커밋!
for (ConsumerRecord<String, String> record : records) {
    processOrder(record.value()); // 여기서 실패하면 유실
}

3.3 At-least-once 구현

// 처리 후 커밋 → 커밋 전 실패하면 재처리(중복)
ConsumerRecords<String, String> records = consumer.poll(Duration.ofMillis(1000));
for (ConsumerRecord<String, String> record : records) {
    processOrder(record.value()); // 먼저 처리!
}
consumer.commitSync(); // 처리 완료 후 커밋
// 여기서 실패하면 → 다음 poll에서 같은 메시지 다시 수신

멱등성(Idempotency) 으로 중복 처리 방어:

public void processOrder(OrderEvent event) {
    // 이미 처리한 이벤트인지 확인
    if (processedEventRepository.existsById(event.getEventId())) {
        log.info("이미 처리된 이벤트: {}", event.getEventId());
        return;
    }
    orderService.createOrder(event);
    processedEventRepository.save(new ProcessedEvent(event.getEventId()));
}

3.4 Exactly-once (Kafka Transactions)

// Producer: 트랜잭션 설정
props.put(ProducerConfig.ENABLE_IDEMPOTENCE_CONFIG, true);
props.put(ProducerConfig.TRANSACTIONAL_ID_CONFIG, "order-tx-1");

KafkaProducer<String, String> producer = new KafkaProducer<>(props);
producer.initTransactions();

try {
    producer.beginTransaction();
    producer.send(new ProducerRecord<>("order-events", key, value));
    producer.send(new ProducerRecord<>("payment-events", key, paymentValue));
    producer.commitTransaction(); // 두 메시지 모두 성공 또는 모두 실패
} catch (Exception e) {
    producer.abortTransaction();
    throw e;
}

// Consumer: read_committed로 커밋된 메시지만 소비
props.put(ConsumerConfig.ISOLATION_LEVEL_CONFIG, "read_committed");

4. Spring Boot Kafka 연동

4.1 의존성 및 설정

// build.gradle
dependencies {
    implementation 'org.springframework.kafka:spring-kafka'
}

# application.yml
spring:
  kafka:
    bootstrap-servers: localhost:9092
    producer:
      key-serializer: org.apache.kafka.common.serialization.StringSerializer
      value-serializer: org.springframework.kafka.support.serializer.JsonSerializer
      acks: all
      retries: 3
    consumer:
      group-id: order-service
      key-deserializer: org.apache.kafka.common.serialization.StringDeserializer
      value-deserializer: org.springframework.kafka.support.serializer.JsonDeserializer
      auto-offset-reset: earliest
      enable-auto-commit: false
      properties:
        spring.json.trusted.packages: "com.example.event"
    listener:
      ack-mode: manual

4.2 KafkaTemplate — 메시지 발행

@Service
@RequiredArgsConstructor
public class OrderEventProducer {

    private final KafkaTemplate<String, OrderEvent> kafkaTemplate;

    public void publishOrderCreated(Order order) {
        OrderEvent event = new OrderEvent(
                UUID.randomUUID().toString(),
                order.getId(),
                "ORDER_CREATED",
                order
        );

        CompletableFuture<SendResult<String, OrderEvent>> future =
                kafkaTemplate.send("order-events", order.getId(), event);

        future.whenComplete((result, ex) -> {
            if (ex != null) {
                log.error("메시지 전송 실패: {}", ex.getMessage());
            } else {
                log.info("메시지 전송 성공: topic={}, partition={}, offset={}",
                        result.getRecordMetadata().topic(),
                        result.getRecordMetadata().partition(),
                        result.getRecordMetadata().offset());
            }
        });
    }
}

4.3 @KafkaListener — 메시지 소비

@Service
@RequiredArgsConstructor
public class OrderEventConsumer {

    private final OrderService orderService;

    @KafkaListener(
            topics = "order-events",
            groupId = "order-service",
            containerFactory = "kafkaListenerContainerFactory"
    )
    public void handleOrderEvent(
            @Payload OrderEvent event,
            @Header(KafkaHeaders.RECEIVED_PARTITION) int partition,
            @Header(KafkaHeaders.OFFSET) long offset,
            Acknowledgment ack) {

        log.info("수신: event={}, partition={}, offset={}",
                event.getType(), partition, offset);

        try {
            switch (event.getType()) {
                case "ORDER_CREATED" -> orderService.handleCreated(event);
                case "ORDER_PAID" -> orderService.handlePaid(event);
                case "ORDER_CANCELLED" -> orderService.handleCancelled(event);
                default -> log.warn("알 수 없는 이벤트: {}", event.getType());
            }
            ack.acknowledge(); // 수동 커밋
        } catch (Exception e) {
            log.error("이벤트 처리 실패: {}", e.getMessage());
            // ack 하지 않음 → 재시도 또는 DLQ로 이동
        }
    }
}

4.4 Listener Container Factory 설정

@Configuration
public class KafkaConfig {

    @Autowired
    private KafkaTemplate<String, OrderEvent> kafkaTemplate;

    @Bean
    public ConcurrentKafkaListenerContainerFactory<String, OrderEvent>
            kafkaListenerContainerFactory(
                    ConsumerFactory<String, OrderEvent> consumerFactory) {

        ConcurrentKafkaListenerContainerFactory<String, OrderEvent> factory =
                new ConcurrentKafkaListenerContainerFactory<>();
        factory.setConsumerFactory(consumerFactory);
        factory.setConcurrency(3); // 3개 스레드로 병렬 소비
        factory.getContainerProperties()
                .setAckMode(ContainerProperties.AckMode.MANUAL);

        // 에러 핸들러 + DLQ
        factory.setCommonErrorHandler(
                new DefaultErrorHandler(
                        new DeadLetterPublishingRecoverer(kafkaTemplate),
                        new FixedBackOff(1000L, 3) // 1초 간격, 3번 재시도
                ));

        return factory;
    }
}

5. Consumer Group Rebalancing

5.1 Rebalancing이 발생하는 시점

컨슈머가 그룹에 새로 참가하거나 이탈할 때
컨슈머가 heartbeat 타임아웃 (세션 만료)
토픽의 파티션 수가 변경될 때

Before Rebalancing:
  Consumer A ← P0, P1
  Consumer B ← P2

Consumer C 참가 → Rebalancing 발생

After Rebalancing:
  Consumer A ← P0
  Consumer B ← P1
  Consumer C ← P2

5.2 Rebalancing 전략

전략	동작	장점	단점
Eager (Range/RoundRobin)	모든 파티션 해제 → 재할당	구현 단순	전체 중단(Stop-the-World)
Cooperative (Incremental)	이동이 필요한 파티션만 재할당	중단 최소화	여러 라운드 필요

# Cooperative Rebalancing 활성화
spring:
  kafka:
    consumer:
      properties:
        partition.assignment.strategy: org.apache.kafka.clients.consumer.CooperativeStickyAssignor

5.3 Rebalancing 최적화

spring:
  kafka:
    consumer:
      properties:
        # Heartbeat 간격 (기본 3초)
        heartbeat.interval.ms: 3000
        # 세션 타임아웃 (기본 45초)
        session.timeout.ms: 45000
        # poll 최대 간격 — 이 시간 내 poll() 호출 필수
        max.poll.interval.ms: 300000
        # 한 번에 가져오는 레코드 수
        max.poll.records: 500

Tip: max.poll.records를 줄이면 처리 시간이 max.poll.interval.ms를 넘기는 것을 방지할 수 있다.

6. 실전 패턴: Dead Letter Queue & Retry 전략

6.1 Dead Letter Queue (DLQ)

처리에 반복적으로 실패한 메시지를 별도 토픽으로 이동시켜 메인 처리 흐름을 보호한다.

order-events → Consumer (처리 시도)
    ├── 성공 → ack
    └── 3회 실패 → order-events.DLT (Dead Letter Topic)
                      └── DLQ 모니터링 & 수동 처리

@Configuration
public class KafkaConfig {

    @Bean
    public DefaultErrorHandler errorHandler(KafkaTemplate<String, Object> template) {
        // DLQ로 보내는 Recoverer
        DeadLetterPublishingRecoverer recoverer =
                new DeadLetterPublishingRecoverer(template,
                        (record, ex) -> new TopicPartition(
                                record.topic() + ".DLT", record.partition()));

        // 1초, 2초, 4초 간격으로 3번 재시도 후 DLQ
        ExponentialBackOff backOff = new ExponentialBackOff(1000L, 2.0);
        backOff.setMaxElapsedTime(10000L);

        DefaultErrorHandler handler = new DefaultErrorHandler(recoverer, backOff);

        // 특정 예외는 재시도 없이 바로 DLQ로
        handler.addNotRetryableExceptions(
                InvalidMessageException.class,
                DeserializationException.class
        );

        return handler;
    }
}

6.2 DLQ 메시지 모니터링 & 재처리

@KafkaListener(topics = "order-events.DLT", groupId = "dlq-handler")
public void handleDlq(
        ConsumerRecord<String, OrderEvent> record,
        @Header(KafkaHeaders.DLT_EXCEPTION_MESSAGE) String errorMessage,
        @Header(KafkaHeaders.DLT_ORIGINAL_TOPIC) String originalTopic) {

    log.error("DLQ 수신: key={}, error={}, originalTopic={}",
            record.key(), errorMessage, originalTopic);

    // 알림 발송 (Slack, PagerDuty 등)
    alertService.sendDlqAlert(record, errorMessage);

    // 필요 시 수동 재처리 큐에 저장
    dlqRepository.save(new DlqRecord(record, errorMessage, originalTopic));
}

6.3 Retry Topic 패턴

DLQ 대신 단계별 재시도 토픽을 사용하는 고급 패턴:

order-events → 실패 → order-events-retry-1 (1분 후)
                         → 실패 → order-events-retry-2 (10분 후)
                                    → 실패 → order-events-DLT

@RetryableTopic(
        attempts = "4",
        backoff = @Backoff(delay = 60000, multiplier = 10, maxDelay = 600000),
        dltStrategy = DltStrategy.FAIL_ON_ERROR,
        topicSuffixingStrategy = TopicSuffixingStrategy.SUFFIX_WITH_INDEX_VALUE
)
@KafkaListener(topics = "order-events", groupId = "order-service")
public void handleOrderEvent(OrderEvent event, Acknowledgment ack) {
    orderService.process(event);
    ack.acknowledge();
}

@DltHandler
public void handleDlt(OrderEvent event) {
    log.error("최종 실패 — DLT 도착: {}", event);
    alertService.sendCriticalAlert(event);
}

7. 이벤트 소싱, CQRS와의 조합

7.1 이벤트 소싱 (Event Sourcing)

상태를 직접 저장하는 대신 상태 변경 이벤트를 순차적으로 저장하고, 이벤트를 재생하여 현재 상태를 도출한다.

주문 #123의 이벤트 로그:
  1. OrderCreated  {items: [...], total: 50000}
  2. PaymentCompleted {paymentId: "pay-1"}
  3. ItemAdded {item: "keyboard", amount: 30000}
  4. OrderShipped {trackingNo: "T-456"}

현재 상태 = 이벤트 1~4를 순차 적용한 결과

// Kafka를 이벤트 저장소로 활용
@Service
public class OrderEventStore {

    private final KafkaTemplate<String, OrderEvent> kafkaTemplate;

    public void append(String orderId, OrderEvent event) {
        // 주문 ID를 키로 → 같은 파티션에 순서대로 저장
        kafkaTemplate.send("order-event-store", orderId, event);
    }
}

7.2 CQRS (Command Query Responsibility Segregation)

쓰기 모델과 읽기 모델을 분리하여 각각 최적화한다.

[Command Side]                    [Query Side]
  Order Command ──→ Event Store   Event Store ──→ Kafka ──→ Read Model
  (정규화 DB)      (Kafka)                                  (비정규화, Elasticsearch 등)

// Command: 주문 생성
@Service
public class OrderCommandService {
    public void createOrder(CreateOrderCommand command) {
        Order order = Order.create(command);
        orderRepository.save(order);

        // 이벤트 발행
        kafkaTemplate.send("order-events", order.getId(),
                new OrderCreatedEvent(order));
    }
}

// Query: 읽기 모델 업데이트
@Service
public class OrderQueryProjector {

    @KafkaListener(topics = "order-events", groupId = "order-query")
    public void project(OrderEvent event) {
        switch (event) {
            case OrderCreatedEvent e -> {
                OrderView view = new OrderView(
                        e.getOrderId(), e.getCustomerName(),
                        e.getItems(), e.getTotal(), "CREATED"
                );
                orderViewRepository.save(view); // Elasticsearch, MongoDB 등
            }
            case OrderShippedEvent e -> {
                orderViewRepository.updateStatus(
                        e.getOrderId(), "SHIPPED", e.getTrackingNo());
            }
            // ...
        }
    }
}

// Query: 읽기 전용 API
@RestController
public class OrderQueryController {

    @GetMapping("/orders/{orderId}")
    public OrderView getOrder(@PathVariable String orderId) {
        return orderViewRepository.findById(orderId).orElseThrow();
    }

    @GetMapping("/orders/search")
    public List<OrderView> searchOrders(@RequestParam String keyword) {
        return orderViewRepository.searchByKeyword(keyword);
    }
}

7.3 조합의 장단점

장점	단점
이벤트 이력 완전 보존	시스템 복잡도 증가
읽기/쓰기 독립 확장	최종 일관성(Eventual Consistency)
다양한 읽기 모델 구축 가능	이벤트 스키마 버전 관리 필요
감사 로그 자동 확보	이벤트 재생 시간

정리

개념	핵심
Topic / Partition	논리적 채널과 물리적 분산 단위
Consumer Group	파티션 분담으로 병렬 처리
Offset Commit	메시지 처리 위치 관리, 보장 수준 결정
acks	Producer의 안정성-성능 트레이드오프
At-least-once + 멱등성	실전에서 가장 많이 사용되는 보장 전략
@KafkaListener	Spring Boot의 선언적 메시지 소비
Dead Letter Queue	실패 메시지 격리로 안정성 확보
Event Sourcing + CQRS	Kafka를 중심으로 한 이벤트 기반 아키텍처

Kafka는 단순한 메시지 전달이 아니라, 이벤트 기반 시스템의 근간이다. 메시지 보장 수준과 장애 처리 전략을 올바르게 설계하는 것이 안정적인 시스템의 핵심이다. Kafka와 함께 자주 논의되는 시스템 안정성 주제로 API Rate Limiting도 참고하자.

References

Redis 캐싱 전략 완전 정복

doodoo3804@gmail.com (DoYoon Kim) — Thu, 02 Apr 2026 00:00:00 +0900

캐싱은 백엔드 성능 최적화의 핵심이다. 캐싱 전략 기초에서 Cache-Aside, Write-Through, Write-Behind 패턴의 개념을 다뤘다면, 이 글에서는 Redis를 활용한 구체적인 구현과 실전에서 마주치는 문제, 해결책을 정리한다.

1. 캐시 전략 비교

1.1 전략 비교 표

전략	읽기 흐름	쓰기 흐름	장점	단점	적합한 상황
Cache-Aside	캐시 조회 → miss 시 DB 조회 → 캐시 저장	DB 직접 쓰기 → 캐시 무효화	구현 단순, 필요한 데이터만 캐싱	첫 요청 항상 miss, 일관성 위험	읽기 비중 높은 일반 서비스
Read-Through	캐시에 위임 → miss 시 캐시가 DB 조회	DB 직접 쓰기	애플리케이션 코드 단순	캐시 라이브러리 의존	캐시 미들웨어 사용 시
Write-Through	캐시 조회	캐시 쓰기 → 캐시가 DB에 동기 쓰기	캐시-DB 항상 일관	쓰기 지연 증가	데이터 일관성이 중요할 때
Write-Behind	캐시 조회	캐시 쓰기 → 비동기로 DB에 쓰기	쓰기 성능 극대화	데이터 유실 위험	쓰기 빈도 높고 유실 허용 시

1.2 Cache-Aside (Lazy Loading)

가장 널리 사용되는 전략이다. 애플리케이션이 캐시를 직접 관리한다.

public User getUser(String userId) {
    // 1. 캐시 조회
    String cacheKey = "user:" + userId;
    User cached = (User) redisTemplate.opsForValue().get(cacheKey);
    if (cached != null) {
        return cached; // Cache Hit
    }

    // 2. Cache Miss → DB 조회
    User user = userRepository.findById(userId)
            .orElseThrow(() -> new UserNotFoundException(userId));

    // 3. 캐시에 저장
    redisTemplate.opsForValue().set(cacheKey, user, Duration.ofMinutes(30));
    return user;
}

쓰기 시 캐시 무효화:

public User updateUser(String userId, UserUpdateRequest request) {
    User user = userRepository.save(toEntity(userId, request));

    // 캐시 삭제 (다음 읽기에서 최신 데이터로 갱신)
    redisTemplate.delete("user:" + userId);
    return user;
}

1.3 Write-Through

public User updateUser(String userId, UserUpdateRequest request) {
    User user = userRepository.save(toEntity(userId, request));

    // DB 저장 직후 캐시도 동기적으로 업데이트
    String cacheKey = "user:" + userId;
    redisTemplate.opsForValue().set(cacheKey, user, Duration.ofMinutes(30));
    return user;
}

1.4 Write-Behind (Write-Back)

public void updateUserAsync(String userId, UserUpdateRequest request) {
    String cacheKey = "user:" + userId;
    User user = toEntity(userId, request);

    // 1. 캐시에 즉시 반영
    redisTemplate.opsForValue().set(cacheKey, user);

    // 2. 변경 사항을 큐에 등록 → 비동기로 DB에 쓰기
    redisTemplate.opsForList().rightPush("write-behind:queue",
            new WriteTask(cacheKey, user));
}

// 별도 스케줄러가 큐를 소비하여 DB에 배치 저장
@Scheduled(fixedDelay = 5000)
public void flushWriteBehindQueue() {
    List<WriteTask> tasks = new ArrayList<>();
    WriteTask task;
    while ((task = redisTemplate.opsForList()
            .leftPop("write-behind:queue")) != null) {
        tasks.add(task);
    }
    if (!tasks.isEmpty()) {
        userRepository.batchUpdate(tasks);
    }
}

2. TTL 설계 전략 및 만료 패턴

2.1 TTL 설계 가이드라인

데이터 유형	권장 TTL	이유
세션 정보	30분 ~ 2시간	사용자 세션 라이프사이클
사용자 프로필	10분 ~ 1시간	변경 빈도 낮음
상품 목록	5분 ~ 15분	가격/재고 변동 반영
인기 검색어 / 랭킹	1분 ~ 5분	실시간성 중요
설정 / 코드 테이블	1시간 ~ 24시간	거의 변경되지 않음
API Rate Limit 카운터	1분 (sliding window)	정확한 윈도우 필요

2.2 TTL 안티패턴

// ❌ Bad: 모든 캐시에 동일한 TTL → 동시 만료 (Stampede 유발)
redisTemplate.opsForValue().set(key, value, Duration.ofMinutes(30));

// ✅ Good: TTL에 지터(jitter) 추가
long baseTtl = 30 * 60; // 30분
long jitter = ThreadLocalRandom.current().nextLong(0, 5 * 60); // 0~5분
redisTemplate.opsForValue().set(key, value, Duration.ofSeconds(baseTtl + jitter));

2.3 만료 패턴

Passive Expiration: 키에 접근할 때 만료 확인 → 삭제 Active Expiration: Redis가 주기적으로 만료된 키 샘플링 → 삭제

// Sliding TTL — 접근할 때마다 TTL 갱신
public User getUser(String userId) {
    String cacheKey = "user:" + userId;
    User cached = (User) redisTemplate.opsForValue().get(cacheKey);
    if (cached != null) {
        // 접근 시 TTL 리셋
        redisTemplate.expire(cacheKey, Duration.ofMinutes(30));
        return cached;
    }
    // ... DB 조회 및 캐시 저장
}

3. Cache Stampede / Thundering Herd 문제와 해결책

3.1 문제 정의

Cache Stampede: 인기 키가 만료되는 순간, 수백 개의 요청이 동시에 DB를 조회하는 현상

시간 T: 인기 상품 캐시 만료
→ 요청 1: cache miss → DB 조회
→ 요청 2: cache miss → DB 조회
→ 요청 3: cache miss → DB 조회
→ ... 수백 요청이 동시에 DB hit
→ DB 과부하 / 장애

3.2 해결책 1: Mutex Lock (분산 락)

오직 하나의 요청만 DB를 조회하고, 나머지는 대기한다.

public User getUserWithLock(String userId) {
    String cacheKey = "user:" + userId;
    String lockKey = "lock:" + cacheKey;

    User cached = (User) redisTemplate.opsForValue().get(cacheKey);
    if (cached != null) {
        return cached;
    }

    // 분산 락 획득 시도 (SETNX + TTL)
    Boolean acquired = redisTemplate.opsForValue()
            .setIfAbsent(lockKey, "1", Duration.ofSeconds(10));

    if (Boolean.TRUE.equals(acquired)) {
        try {
            // 락 획득 성공 → DB 조회 후 캐시 갱신
            User user = userRepository.findById(userId).orElseThrow();
            redisTemplate.opsForValue().set(cacheKey, user, Duration.ofMinutes(30));
            return user;
        } finally {
            redisTemplate.delete(lockKey);
        }
    } else {
        // 락 획득 실패 → 짧은 대기 후 재시도
        Thread.sleep(50);
        return getUserWithLock(userId);
    }
}

3.3 해결책 2: Probabilistic Early Expiration

캐시 만료 전에 확률적으로 미리 갱신한다.

public User getUserWithEarlyExpire(String userId) {
    String cacheKey = "user:" + userId;
    CacheEntry<User> entry = (CacheEntry<User>) redisTemplate.opsForValue().get(cacheKey);

    if (entry != null) {
        long ttlRemaining = redisTemplate.getExpire(cacheKey, TimeUnit.SECONDS);
        long delta = entry.getComputeTime(); // 원래 계산 소요 시간(초)
        double beta = 1.0;

        // 남은 TTL이 짧을수록 갱신 확률 증가
        boolean shouldRefresh = (delta * beta * Math.log(Math.random())) * -1
                >= ttlRemaining;

        if (!shouldRefresh) {
            return entry.getData();
        }
        // 확률적으로 선택된 요청만 갱신 수행 (아래로 계속)
    }

    // Cache miss 또는 갱신 대상 → DB 조회
    long start = System.currentTimeMillis();
    User user = userRepository.findById(userId).orElseThrow();
    long computeTime = (System.currentTimeMillis() - start) / 1000;

    CacheEntry<User> newEntry = new CacheEntry<>(user, computeTime);
    redisTemplate.opsForValue().set(cacheKey, newEntry, Duration.ofMinutes(30));
    return user;
}

3.4 해결책 3: 백그라운드 갱신

인기 키를 TTL 만료 전에 백그라운드에서 주기적으로 갱신한다.

@Scheduled(fixedRate = 60_000) // 1분마다
public void refreshHotKeys() {
    List<String> hotKeys = List.of("product:best-seller", "ranking:daily");
    for (String key : hotKeys) {
        Object freshData = loadFromDB(key);
        redisTemplate.opsForValue().set(key, freshData, Duration.ofMinutes(5));
    }
}

4. Redis 자료구조 활용

4.1 언제 뭘 쓸지

자료구조	용도	예시
String	단순 K-V, 카운터, 세션	`user:123 → JSON`, `counter:page → 42`
Hash	객체 필드별 접근	`user:123 → {name, email, age}`
List	큐, 최근 기록	최근 본 상품, 메시지 큐
Set	고유 집합, 태그	좋아요 사용자 목록, 태그 필터
Sorted Set	랭킹, 스코어 기반 정렬	리더보드, 인기 검색어

4.2 String — 세션 & 카운터

# 세션 저장
SET session:abc123 '{"userId":"u1","role":"admin"}' EX 1800

# 페이지 조회수 카운터
INCR page:views:home
INCRBY page:views:home 5

// Spring Boot
redisTemplate.opsForValue().set("session:" + sessionId, sessionData,
        Duration.ofMinutes(30));

Long views = redisTemplate.opsForValue().increment("page:views:" + pageId);

4.3 Hash — 객체 필드별 접근

전체 객체 대신 필요한 필드만 읽고 수정할 수 있다.

HSET user:123 name "홍길동" email "hong@example.com" age 28
HGET user:123 name          # "홍길동"
HINCRBY user:123 age 1      # 나이 1 증가
HGETALL user:123             # 전체 필드

HashOperations<String, String, String> hashOps = redisTemplate.opsForHash();
hashOps.put("user:123", "name", "홍길동");
hashOps.put("user:123", "email", "hong@example.com");

String name = hashOps.get("user:123", "name");
Map<String, String> user = hashOps.entries("user:123");

4.4 Set — 좋아요, 태그

SADD post:456:likes user:1 user:2 user:3
SISMEMBER post:456:likes user:1    # 좋아요 여부: 1 (true)
SCARD post:456:likes               # 좋아요 수: 3
SINTER post:456:likes post:789:likes  # 두 게시물 모두 좋아요한 사용자

SetOperations<String, String> setOps = redisTemplate.opsForSet();
setOps.add("post:456:likes", "user:1", "user:2");

Boolean isLiked = setOps.isMember("post:456:likes", "user:1");
Long likeCount = setOps.size("post:456:likes");

4.5 Sorted Set — 리더보드

ZADD leaderboard 1500 "player:A" 2300 "player:B" 1800 "player:C"
ZREVRANGE leaderboard 0 2 WITHSCORES   # 상위 3명 (높은 점수순)
ZRANK leaderboard "player:A"            # 순위 조회
ZINCRBY leaderboard 200 "player:A"      # 점수 증가

ZSetOperations<String, String> zSetOps = redisTemplate.opsForZSet();
zSetOps.add("leaderboard", "player:A", 1500);
zSetOps.add("leaderboard", "player:B", 2300);

// 상위 10명
Set<ZSetOperations.TypedTuple<String>> top10 =
        zSetOps.reverseRangeWithScores("leaderboard", 0, 9);

// 점수 증가
zSetOps.incrementScore("leaderboard", "player:A", 200);

5. Spring Boot + Redis 연동

5.1 의존성 및 설정

// build.gradle
dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-data-redis'
}

# application.yml
spring:
  data:
    redis:
      host: localhost
      port: 6379
      password: mypassword
      lettuce:
        pool:
          max-active: 8
          max-idle: 8
          min-idle: 2

5.2 RedisTemplate 설정

@Configuration
public class RedisConfig {

    @Bean
    public RedisTemplate<String, Object> redisTemplate(
            RedisConnectionFactory connectionFactory) {
        RedisTemplate<String, Object> template = new RedisTemplate<>();
        template.setConnectionFactory(connectionFactory);

        // Key: String, Value: JSON 직렬화
        template.setKeySerializer(new StringRedisSerializer());
        template.setValueSerializer(
                new GenericJackson2JsonRedisSerializer());

        template.setHashKeySerializer(new StringRedisSerializer());
        template.setHashValueSerializer(
                new GenericJackson2JsonRedisSerializer());

        return template;
    }
}

5.3 @Cacheable 기반 선언적 캐싱

@Configuration
@EnableCaching
public class CacheConfig {

    @Bean
    public RedisCacheManager cacheManager(
            RedisConnectionFactory connectionFactory) {
        RedisCacheConfiguration config = RedisCacheConfiguration
                .defaultCacheConfig()
                .entryTtl(Duration.ofMinutes(30))
                .serializeKeysWith(
                        SerializationPair.fromSerializer(
                                new StringRedisSerializer()))
                .serializeValuesWith(
                        SerializationPair.fromSerializer(
                                new GenericJackson2JsonRedisSerializer()))
                .disableCachingNullValues();

        // 캐시별 TTL 커스터마이징
        Map<String, RedisCacheConfiguration> perCacheConfig = Map.of(
                "users", config.entryTtl(Duration.ofMinutes(60)),
                "products", config.entryTtl(Duration.ofMinutes(10)),
                "rankings", config.entryTtl(Duration.ofMinutes(1))
        );

        return RedisCacheManager.builder(connectionFactory)
                .cacheDefaults(config)
                .withInitialCacheConfigurations(perCacheConfig)
                .build();
    }
}

@Service
public class UserService {

    @Cacheable(value = "users", key = "#userId")
    public User getUser(String userId) {
        // Cache miss 시에만 실행
        return userRepository.findById(userId).orElseThrow();
    }

    @CachePut(value = "users", key = "#userId")
    public User updateUser(String userId, UserUpdateRequest request) {
        // 항상 실행, 결과를 캐시에 저장
        return userRepository.save(toEntity(userId, request));
    }

    @CacheEvict(value = "users", key = "#userId")
    public void deleteUser(String userId) {
        // 실행 후 캐시에서 삭제
        userRepository.deleteById(userId);
    }

    @CacheEvict(value = "users", allEntries = true)
    public void clearAllUserCache() {
        // 모든 users 캐시 삭제
    }
}

6. 캐시 일관성 문제 (Cache Invalidation 전략)

“There are only two hard things in Computer Science: cache invalidation and naming things.” — Phil Karlton

6.1 일관성 문제 시나리오

Thread A: DB 업데이트 (v2) → 캐시 삭제 예정
Thread B:                      캐시 miss → DB 조회 (v2) → 캐시 저장 (v2)
Thread A:                                                    캐시 삭제!
→ 캐시 비어 있음 → 다음 요청에서 다시 DB 조회 (괜찮음)

그러나 타이밍이 꼬이면:
Thread A: DB 업데이트 (v2)
Thread B:                   캐시 miss → DB 조회 (v1, 아직 커밋 안 됨)
Thread A: 캐시 삭제
Thread B:                   캐시 저장 (v1) ← 오래된 데이터!

6.2 전략 1: Delete After Write (기본)

public void updateUser(String userId, UserUpdateRequest request) {
    userRepository.save(toEntity(userId, request));
    redisTemplate.delete("user:" + userId); // 쓰기 후 삭제
}

단순하지만 위 경합 상황에서 stale 데이터 가능성이 있다.

6.3 전략 2: 짧은 TTL + 삭제

public void updateUser(String userId, UserUpdateRequest request) {
    userRepository.save(toEntity(userId, request));
    // 즉시 삭제 대신 매우 짧은 TTL로 교체 → 경합 윈도우 최소화
    redisTemplate.expire("user:" + userId, Duration.ofSeconds(1));
}

6.4 전략 3: 버전 기반 무효화

public void updateUser(String userId, UserUpdateRequest request) {
    User user = userRepository.save(toEntity(userId, request));

    // 버전 번호로 캐시 키 분리
    String versionKey = "user:version:" + userId;
    Long newVersion = redisTemplate.opsForValue().increment(versionKey);

    String cacheKey = "user:" + userId + ":v" + newVersion;
    redisTemplate.opsForValue().set(cacheKey, user, Duration.ofMinutes(30));
}

6.5 전략 4: CDC (Change Data Capture) 기반

데이터 변경을 이벤트로 발행하여 캐시를 비동기 갱신한다.

DB 변경 → Debezium (CDC) → Kafka → Cache Updater → Redis 갱신

@KafkaListener(topics = "dbserver.public.users")
public void onUserChange(ConsumerRecord<String, String> record) {
    UserChangeEvent event = objectMapper.readValue(
            record.value(), UserChangeEvent.class);

    String cacheKey = "user:" + event.getUserId();

    if ("DELETE".equals(event.getOperation())) {
        redisTemplate.delete(cacheKey);
    } else {
        redisTemplate.opsForValue().set(cacheKey,
                event.getAfter(), Duration.ofMinutes(30));
    }
}

6.6 전략 선택 가이드

상황	권장 전략
단순 CRUD, 약간의 stale 허용	Delete After Write + 짧은 TTL
높은 일관성 필요	Write-Through 또는 버전 기반
대규모 분산 시스템	CDC 기반 비동기 무효화
읽기 극단적 부하	Cache-Aside + Mutex Lock + Jitter TTL

정리

개념	핵심
Cache-Aside	가장 범용적, 애플리케이션이 캐시 직접 관리
Write-Through / Behind	쓰기 일관성 vs 쓰기 성능 트레이드오프
TTL Jitter	동시 만료 방지의 핵심
Cache Stampede 방지	Mutex Lock 또는 확률적 조기 갱신
Redis 자료구조	데이터 특성에 맞는 자료구조 선택이 성능 좌우
@Cacheable	Spring의 선언적 캐싱으로 보일러플레이트 제거
Cache Invalidation	삭제 + 짧은 TTL이 실용적, 대규모는 CDC

캐싱은 단순히 “Redis에 저장”이 아니라, 데이터 특성에 맞는 전략을 선택하고 일관성과 성능 사이의 트레이드오프를 관리하는 것이다.

References

API Rate Limiting — 설계와 구현 전략

doodoo3804@gmail.com (DoYoon Kim) — Wed, 01 Apr 2026 00:00:00 +0900

Rate Limiting이 필요한 이유

공개 API를 운영하면 예상치 못한 트래픽 폭주를 경험하게 된다. 의도적인 DDoS 공격이 아니더라도, 클라이언트의 버그나 잘못된 재시도 로직만으로 서버가 과부하에 빠질 수 있다.

Rate Limiting은 세 가지 문제를 해결한다.

서비스 보호: 과도한 요청으로부터 서버 리소스를 보호한다.
공정한 사용: 특정 사용자가 리소스를 독점하지 못하게 한다.
비용 제어: 클라우드 환경에서 불필요한 트래픽으로 인한 비용 폭증을 방지한다.

정상 트래픽:   ████████░░░░░░░  (60% 용량)  ✓ 안정
트래픽 폭주:   ████████████████████████████  (200% 용량)  ✗ 장애
Rate Limit:   ████████████████░░░░░░░░░░░  (100% 이하 유지)  ✓ 안정

알고리즘 비교

Token Bucket

버킷에 일정 속도로 토큰이 채워진다. 요청이 들어오면 토큰을 소비한다. 토큰이 없으면 요청을 거부한다.

[버킷 용량: 10, 충전 속도: 1개/초]

t=0   토큰: 10  → 요청 5개 처리 → 토큰: 5
t=1   토큰: 6   → 요청 2개 처리 → 토큰: 4
t=2   토큰: 5   → 요청 0개      → 토큰: 5 (최대 10까지만 충전)
t=3   토큰: 6   → 요청 8개 시도 → 6개 처리, 2개 거부

특징: 버스트 트래픽을 허용한다. 버킷에 토큰이 쌓여 있으면 일시적으로 높은 트래픽을 처리할 수 있다. Amazon API Gateway, Stripe 등 많은 서비스에서 사용한다.

public class TokenBucket {
    private final int maxTokens;
    private final double refillRate;    // tokens per second
    private double currentTokens;
    private long lastRefillTime;

    public TokenBucket(int maxTokens, double refillRate) {
        this.maxTokens = maxTokens;
        this.refillRate = refillRate;
        this.currentTokens = maxTokens;
        this.lastRefillTime = System.nanoTime();
    }

    public synchronized boolean tryConsume() {
        refill();
        if (currentTokens >= 1) {
            currentTokens -= 1;
            return true;
        }
        return false;
    }

    private void refill() {
        long now = System.nanoTime();
        double elapsed = (now - lastRefillTime) / 1_000_000_000.0;
        currentTokens = Math.min(maxTokens, currentTokens + elapsed * refillRate);
        lastRefillTime = now;
    }
}

Leaky Bucket

요청이 버킷에 들어가고, 일정 속도로 빠져나간다. 버킷이 가득 차면 새 요청은 버려진다.

[버킷 용량: 10, 유출 속도: 2개/초]

요청 유입:  ████████████████  (버스트)
버킷 내부:  ██████████        (최대 10개 대기)
유출(처리): ██  ██  ██  ██    (일정 속도로 처리)

특징: 유출 속도가 일정하므로 트래픽을 평탄화(smoothing)한다. 버스트를 허용하지 않고 균일한 처리율을 보장해야 할 때 적합하다.

Fixed Window Counter

시간 윈도우(예: 1분)를 고정하고, 윈도우 내 요청 수를 카운트한다.

[1분당 100개 제한]

12:00:00 ~ 12:00:59  → 카운트: 0 ... 100 → 100 이후 거부
12:01:00 ~ 12:01:59  → 카운트: 0 (리셋)

문제점: 윈도우 경계에서 버스트가 발생할 수 있다. 12:00:55에 100개, 12:01:00에 100개가 들어오면 10초 사이에 200개가 처리된다.

Sliding Window Log

각 요청의 타임스탬프를 기록하고, 현재 시점에서 윈도우 크기만큼 뒤로 가서 요청 수를 센다.

public class SlidingWindowLog {
    private final int maxRequests;
    private final long windowSizeMs;
    private final LinkedList<Long> requestLog = new LinkedList<>();

    public SlidingWindowLog(int maxRequests, long windowSizeMs) {
        this.maxRequests = maxRequests;
        this.windowSizeMs = windowSizeMs;
    }

    public synchronized boolean tryAcquire() {
        long now = System.currentTimeMillis();
        long windowStart = now - windowSizeMs;

        // 윈도우 밖의 오래된 기록 제거
        while (!requestLog.isEmpty() && requestLog.peekFirst() <= windowStart) {
            requestLog.pollFirst();
        }

        if (requestLog.size() < maxRequests) {
            requestLog.addLast(now);
            return true;
        }
        return false;
    }
}

특징: 경계 문제가 없어 가장 정확하지만, 요청마다 타임스탬프를 저장하므로 메모리 사용량이 높다.

Sliding Window Counter

Fixed Window와 Sliding Window Log의 절충안이다. 이전 윈도우와 현재 윈도우의 카운트를 가중 평균으로 계산한다.

[1분당 100개 제한, 현재 12:00:45]

이전 윈도우(11:59:00~11:59:59) 카운트: 80
현재 윈도우(12:00:00~12:00:59) 카운트: 30

가중치 = (60 - 45) / 60 = 0.25
예상 카운트 = 80 * 0.25 + 30 = 50  → 허용

메모리 효율적이면서 경계 문제를 완화한다. 실무에서 가장 많이 채택되는 방식이다.

분산 환경에서의 Rate Limiting

서버가 여러 대인 분산 환경에서는 각 서버가 독립적으로 카운트하면 전체 제한이 깨진다. Redis를 중앙 저장소로 활용해 분산 Rate Limiting을 구현한다.

Redis 기반 Fixed Window 구현

-- rate_limit.lua
local key = KEYS[1]
local limit = tonumber(ARGV[1])
local window = tonumber(ARGV[2])

local current = redis.call('INCR', key)

if current == 1 then
    redis.call('EXPIRE', key, window)
end

if current > limit then
    return 0    -- 거부
else
    return 1    -- 허용
end

@Service
@RequiredArgsConstructor
public class RedisRateLimiter {

    private final RedisTemplate<String, String> redisTemplate;
    private final RedisScript<Long> rateLimitScript;

    public boolean isAllowed(String clientId, int limit, int windowSeconds) {
        String key = "rate_limit:" + clientId + ":" + (System.currentTimeMillis() / (windowSeconds * 1000));

        Long result = redisTemplate.execute(
            rateLimitScript,
            List.of(key),
            String.valueOf(limit),
            String.valueOf(windowSeconds)
        );

        return result != null && result == 1;
    }
}

Redis 기반 Sliding Window 구현

Sorted Set을 활용하면 Sliding Window를 구현할 수 있다.

public boolean isAllowedSlidingWindow(String clientId, int limit, int windowSeconds) {
    String key = "rate_limit:sliding:" + clientId;
    long now = System.currentTimeMillis();
    long windowStart = now - (windowSeconds * 1000L);

    redisTemplate.execute(new SessionCallback<>() {
        @Override
        public Object execute(RedisOperations operations) {
            operations.multi();
            // 윈도우 밖의 오래된 항목 제거
            operations.opsForZSet().removeRangeByScore(key, 0, windowStart);
            // 현재 요청 추가
            operations.opsForZSet().add(key, UUID.randomUUID().toString(), now);
            // 현재 윈도우 내 요청 수 조회
            operations.opsForZSet().zCard(key);
            // TTL 설정
            operations.expire(key, Duration.ofSeconds(windowSeconds));
            return operations.exec();
        }
    });

    Long count = redisTemplate.opsForZSet().zCard(key);
    return count != null && count <= limit;
}

Spring Boot + Redis Rate Limiter 구현

Bucket4j 라이브러리 활용

Bucket4j는 Token Bucket 알고리즘을 구현한 Java 라이브러리다. Redis 백엔드를 지원한다.

// build.gradle
dependencies {
    implementation 'com.bucket4j:bucket4j-core:8.7.0'
    implementation 'com.bucket4j:bucket4j-redis:8.7.0'
}

@Configuration
public class RateLimitConfig {

    @Bean
    public ProxyManager<String> proxyManager(RedisConnectionFactory factory) {
        LettuceBasedProxyManager<String> proxyManager = LettuceBasedProxyManager
            .builderFor(RedisClient.create("redis://localhost:6379"))
            .withExpirationStrategy(
                ExpirationAfterWriteStrategy.basedOnTimeForRefillingBucketUpToMax(
                    Duration.ofMinutes(1)))
            .build();
        return proxyManager;
    }
}

@Component
@RequiredArgsConstructor
public class RateLimitInterceptor implements HandlerInterceptor {

    private final ProxyManager<String> proxyManager;

    private static final BucketConfiguration BUCKET_CONFIG = BucketConfiguration.builder()
        .addLimit(Bandwidth.builder()
            .capacity(100)
            .refillGreedy(100, Duration.ofMinutes(1))
            .build())
        .build();

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response,
                             Object handler) throws Exception {
        String clientId = resolveClientId(request);
        BucketProxy bucket = proxyManager.builder()
            .build(clientId, () -> BUCKET_CONFIG);

        ConsumptionProbe probe = bucket.tryConsumeAndReturnRemaining(1);

        if (probe.isConsumed()) {
            response.setHeader("X-Rate-Limit-Remaining",
                String.valueOf(probe.getRemainingTokens()));
            return true;
        } else {
            response.setStatus(HttpStatus.TOO_MANY_REQUESTS.value());
            response.setHeader("Retry-After",
                String.valueOf(probe.getNanosToWaitForRefill() / 1_000_000_000));
            response.getWriter().write("""
                {"error": "Too Many Requests", "message": "Rate limit exceeded. Please try again later."}
                """);
            return false;
        }
    }

    private String resolveClientId(HttpServletRequest request) {
        // API Key 우선, 없으면 IP 기반
        String apiKey = request.getHeader("X-API-Key");
        if (apiKey != null && !apiKey.isEmpty()) {
            return "api_key:" + apiKey;
        }
        return "ip:" + request.getRemoteAddr();
    }
}

커스텀 어노테이션 기반 구현

더 세밀한 제어를 위해 어노테이션 기반으로 구현할 수도 있다.

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface RateLimit {
    int requests() default 100;
    int windowSeconds() default 60;
    String key() default "";    // SpEL 지원
}

@Aspect
@Component
@RequiredArgsConstructor
public class RateLimitAspect {

    private final RedisTemplate<String, String> redisTemplate;

    @Around("@annotation(rateLimit)")
    public Object enforce(ProceedingJoinPoint joinPoint, RateLimit rateLimit) throws Throwable {
        String key = resolveKey(joinPoint, rateLimit);
        int limit = rateLimit.requests();
        int window = rateLimit.windowSeconds();

        String redisKey = "rate:" + key + ":" + (System.currentTimeMillis() / (window * 1000));
        Long count = redisTemplate.opsForValue().increment(redisKey);

        if (count == 1) {
            redisTemplate.expire(redisKey, Duration.ofSeconds(window));
        }

        if (count != null && count > limit) {
            throw new RateLimitExceededException("요청 한도를 초과했습니다.");
        }

        return joinPoint.proceed();
    }

    private String resolveKey(ProceedingJoinPoint joinPoint, RateLimit rateLimit) {
        if (!rateLimit.key().isEmpty()) {
            return rateLimit.key();
        }
        return joinPoint.getSignature().toShortString();
    }
}

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

    @RateLimit(requests = 50, windowSeconds = 60)
    @PostMapping
    public ResponseEntity<OrderResponse> createOrder(@RequestBody OrderRequest request) {
        // ...
    }

    @RateLimit(requests = 200, windowSeconds = 60)
    @GetMapping("/{id}")
    public ResponseEntity<OrderResponse> getOrder(@PathVariable Long id) {
        // ...
    }
}

Rate Limit 응답 설계

표준 HTTP 응답

Rate Limit 초과 시 429 Too Many Requests를 반환한다.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 30
X-Rate-Limit-Limit: 100
X-Rate-Limit-Remaining: 0
X-Rate-Limit-Reset: 1714531200

{
    "error": "Too Many Requests",
    "message": "Rate limit exceeded. Please retry after 30 seconds.",
    "limit": 100,
    "remaining": 0,
    "retryAfter": 30
}

주요 응답 헤더:

헤더	설명
`Retry-After`	다음 요청까지 대기 시간(초)
`X-Rate-Limit-Limit`	윈도우당 최대 요청 수
`X-Rate-Limit-Remaining`	남은 요청 수
`X-Rate-Limit-Reset`	윈도우 리셋 시각(Unix timestamp)

정상 요청에도 X-Rate-Limit-Remaining 헤더를 포함시켜 클라이언트가 자체적으로 요청 속도를 조절할 수 있게 한다.

실무 고려사항

per-user vs per-IP vs per-API-key

기준	장점	단점
per-IP	구현 간단, 인증 불필요	NAT/프록시 뒤 사용자 구분 불가
per-user	정확한 사용자별 제한	인증 필수
per-API-key	서비스/클라이언트별 제한	키 관리 필요

실무에서는 계층적 Rate Limiting을 적용한다.

1차: per-IP (DDoS 방어, 인증 전 단계)  — 1000 req/min
2차: per-user (공정 사용)              — 100 req/min
3차: per-API-key (플랜별 차등)          — Free: 60, Pro: 600, Enterprise: 무제한

그 외 고려사항

Graceful Degradation: Rate Limit 저장소(Redis)에 장애가 발생하면 요청을 통과시킬지 차단할지 결정해야 한다. 보통은 통과시키는 것이 서비스 가용성 측면에서 낫다.
분산 환경 시간 동기화: 서버 간 시각이 다르면 윈도우 계산이 틀어진다. NTP로 시각을 동기화하거나, Redis 서버의 시각을 기준으로 삼는다.
API별 차등 제한: 리소스 소모가 큰 API(검색, 리포트 생성)는 더 낮은 제한을 두고, 가벼운 API(상태 조회)는 높은 제한을 둔다.

정리

Rate Limiting은 API 서비스의 안정성과 공정성을 보장하는 핵심 메커니즘이다. 대규모 트래픽을 비동기로 처리하려면 Apache Kafka와 조합하는 것도 효과적인 전략이다. Token Bucket이 가장 범용적으로 쓰이지만, 요구사항에 따라 Sliding Window Counter도 좋은 선택이다. 분산 환경에서는 Redis가 사실상 표준이며, Spring Boot에서는 Bucket4j 라이브러리나 커스텀 어노테이션 기반 AOP로 깔끔하게 구현할 수 있다. 무엇보다 중요한 것은 클라이언트에게 명확한 Rate Limit 정보를 제공해 협력적인 트래픽 관리를 유도하는 것이다.

Spring Security 6 + JWT 인증 구현

doodoo3804@gmail.com (DoYoon Kim) — Wed, 01 Apr 2026 00:00:00 +0900

들어가며

이전 글(Spring Boot + JPA로 REST API 만들기)에서 기본적인 CRUD API를 구현했다. 이번에는 이 API에 인증(Authentication) 을 적용한다. 세션 기반 인증 대신 JWT(JSON Web Token) 를 사용해서 stateless한 인증 시스템을 만들 것이다.

Spring Security 6.x + Spring Boot 3.x 기준으로 작성했다. Spring Security 5.x 이하와 설정 방식이 상당히 다르니 주의하자.

Spring Security 아키텍처 개요

Spring Security는 서블릿 필터 체인 기반으로 동작한다. 요청이 Controller에 도달하기 전에 여러 보안 필터를 거치게 된다. 아키텍처를 더 깊이 이해하려면 Spring Security 아키텍처 완전 이해를 참고하자.

HTTP Request
    ↓
[DelegatingFilterProxy]
    ↓
[FilterChainProxy]
    ↓
[SecurityFilterChain]
    ├── DisableEncodeUrlFilter
    ├── SecurityContextHolderFilter
    ├── CsrfFilter
    ├── LogoutFilter
    ├── UsernamePasswordAuthenticationFilter  ← 우리가 대체할 부분
    ├── ExceptionTranslationFilter
    └── AuthorizationFilter
    ↓
DispatcherServlet → Controller

핵심 컴포넌트

SecurityFilterChain — 어떤 URL 패턴에 어떤 필터/인가 규칙을 적용할지 정의
AuthenticationManager — 인증 처리를 위임받는 핵심 인터페이스
AuthenticationProvider — 실제 인증 로직 수행 (DB 조회, 비밀번호 검증 등)
UserDetailsService — 사용자 정보를 로드하는 인터페이스
SecurityContextHolder — 인증된 사용자 정보를 ThreadLocal에 저장

JWT 인증에서는 UsernamePasswordAuthenticationFilter 대신 커스텀 JWT 필터를 끼워 넣어서, 매 요청마다 토큰을 검증하고 SecurityContext에 인증 정보를 세팅한다.

JWT 구조

JWT는 .으로 구분된 세 파트로 구성된다:

xxxxx.yyyyy.zzzzz
 ↑       ↑      ↑
Header  Payload  Signature

서명 알고리즘과 토큰 타입을 명시한다.

{
  "alg": "HS256",
  "typ": "JWT"
}

Payload (Claims)

토큰에 담길 데이터. 표준 클레임과 커스텀 클레임이 있다.

{
  "sub": "user@example.com",
  "iat": 1711900800,
  "exp": 1711987200,
  "roles": ["ROLE_USER"]
}

sub (subject) — 사용자 식별자
iat (issued at) — 발급 시각
exp (expiration) — 만료 시각

Signature

Header와 Payload를 인코딩한 값에 비밀키로 서명한다.

HMACSHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  secret
)

서명 알고리즘

알고리즘	방식	키	사용 사례
HS256	대칭키 (HMAC)	하나의 secret	단일 서버, 간단한 구조
RS256	비대칭키 (RSA)	private/public key pair	MSA, 외부 검증 필요 시

HS256은 구현이 간단하지만, 검증하는 쪽도 비밀키를 알아야 한다. MSA 환경에서는 RS256이 더 적합하다 — 발급 서버만 private key를 갖고, 다른 서비스는 public key로 검증만 하면 된다.

의존성 추가

// build.gradle
dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-security'
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'

    // JWT (jjwt 0.12.x)
    implementation 'io.jsonwebtoken:jjwt-api:0.12.6'
    runtimeOnly    'io.jsonwebtoken:jjwt-impl:0.12.6'
    runtimeOnly    'io.jsonwebtoken:jjwt-jackson:0.12.6'

    compileOnly 'org.projectlombok:lombok'
    annotationProcessor 'org.projectlombok:lombok'
    runtimeOnly 'com.h2database:h2'
}

구현

1. User Entity & Repository

@Entity
@Table(name = "users")
@Getter
@NoArgsConstructor(access = AccessLevel.PROTECTED)
public class User {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, unique = true)
    private String email;

    @Column(nullable = false)
    private String password;

    @Enumerated(EnumType.STRING)
    private Role role;

    @Builder
    public User(String email, String password, Role role) {
        this.email = email;
        this.password = password;
        this.role = role;
    }
}

public enum Role {
    ROLE_USER,
    ROLE_ADMIN
}

public interface UserRepository extends JpaRepository<User, Long> {
    Optional<User> findByEmail(String email);
}

2. UserDetailsService 구현

Spring Security가 사용자 정보를 로드할 때 사용하는 인터페이스다.

@Service
@RequiredArgsConstructor
public class CustomUserDetailsService implements UserDetailsService {

    private final UserRepository userRepository;

    @Override
    public UserDetails loadUserByUsername(String email) throws UsernameNotFoundException {
        User user = userRepository.findByEmail(email)
                .orElseThrow(() -> new UsernameNotFoundException("사용자를 찾을 수 없습니다: " + email));

        return org.springframework.security.core.userdetails.User.builder()
                .username(user.getEmail())
                .password(user.getPassword())
                .roles(user.getRole().name().replace("ROLE_", ""))
                .build();
    }
}

3. JwtTokenProvider

토큰 생성과 검증을 담당하는 핵심 클래스다.

@Component
public class JwtTokenProvider {

    private final SecretKey secretKey;
    private final long accessTokenValidity;
    private final long refreshTokenValidity;

    public JwtTokenProvider(
            @Value("${jwt.secret}") String secret,
            @Value("${jwt.access-token-validity}") long accessTokenValidity,
            @Value("${jwt.refresh-token-validity}") long refreshTokenValidity) {
        this.secretKey = Keys.hmacShaKeyFor(Decoders.BASE64.decode(secret));
        this.accessTokenValidity = accessTokenValidity;
        this.refreshTokenValidity = refreshTokenValidity;
    }

    // Access Token 생성
    public String createAccessToken(Authentication authentication) {
        return createToken(authentication, accessTokenValidity);
    }

    // Refresh Token 생성
    public String createRefreshToken(Authentication authentication) {
        return createToken(authentication, refreshTokenValidity);
    }

    private String createToken(Authentication authentication, long validity) {
        String authorities = authentication.getAuthorities().stream()
                .map(GrantedAuthority::getAuthority)
                .collect(Collectors.joining(","));

        Date now = new Date();
        Date expiry = new Date(now.getTime() + validity);

        return Jwts.builder()
                .subject(authentication.getName())
                .claim("roles", authorities)
                .issuedAt(now)
                .expiration(expiry)
                .signWith(secretKey)
                .compact();
    }

    // 토큰에서 Authentication 객체 추출
    public Authentication getAuthentication(String token) {
        Claims claims = parseClaims(token);

        String roles = claims.get("roles", String.class);
        Collection extends GrantedAuthority> authorities =
                Arrays.stream(roles.split(","))
                        .map(SimpleGrantedAuthority::new)
                        .collect(Collectors.toList());

        UserDetails principal = new org.springframework.security.core.userdetails.User(
                claims.getSubject(), "", authorities);

        return new UsernamePasswordAuthenticationToken(principal, token, authorities);
    }

    // 토큰 유효성 검증
    public boolean validateToken(String token) {
        try {
            parseClaims(token);
            return true;
        } catch (JwtException | IllegalArgumentException e) {
            return false;
        }
    }

    private Claims parseClaims(String token) {
        return Jwts.parser()
                .verifyWith(secretKey)
                .build()
                .parseSignedClaims(token)
                .getPayload();
    }
}

application.yml 설정:

jwt:
  # 최소 256-bit(32바이트) 이상의 Base64 인코딩 키
  secret: "Y2xhdWRlLWNvZGUtc3ByaW5nLXNlY3VyaXR5LWp3dC1zZWNyZXQta2V5LTMyYg=="
  access-token-validity: 1800000   # 30분 (ms)
  refresh-token-validity: 604800000 # 7일 (ms)

4. JwtAuthenticationFilter

매 요청마다 Authorization 헤더에서 JWT를 추출하고, 유효하면 SecurityContext에 인증 정보를 세팅한다.

@Component
@RequiredArgsConstructor
public class JwtAuthenticationFilter extends OncePerRequestFilter {

    private final JwtTokenProvider jwtTokenProvider;

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                    HttpServletResponse response,
                                    FilterChain filterChain)
            throws ServletException, IOException {

        String token = resolveToken(request);

        if (token != null && jwtTokenProvider.validateToken(token)) {
            Authentication auth = jwtTokenProvider.getAuthentication(token);
            SecurityContextHolder.getContext().setAuthentication(auth);
        }

        filterChain.doFilter(request, response);
    }

    private String resolveToken(HttpServletRequest request) {
        String bearer = request.getHeader("Authorization");
        if (bearer != null && bearer.startsWith("Bearer ")) {
            return bearer.substring(7);
        }
        return null;
    }
}

5. SecurityConfig

Spring Security 6.x에서는 WebSecurityConfigurerAdapter가 제거되었다. 대신 SecurityFilterChain을 @Bean으로 등록한다.

@Configuration
@EnableWebSecurity
@RequiredArgsConstructor
public class SecurityConfig {

    private final JwtAuthenticationFilter jwtAuthenticationFilter;
    private final CustomUserDetailsService userDetailsService;

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            // REST API이므로 CSRF 비활성화
            .csrf(csrf -> csrf.disable())

            // 세션 사용 안 함 (JWT는 stateless)
            .sessionManagement(session ->
                session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))

            // URL별 인가 규칙
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/auth/**").permitAll()
                .requestMatchers("/api/admin/**").hasRole("ADMIN")
                .anyRequest().authenticated()
            )

            // JWT 필터를 UsernamePasswordAuthenticationFilter 앞에 추가
            .addFilterBefore(jwtAuthenticationFilter,
                UsernamePasswordAuthenticationFilter.class);

        return http.build();
    }

    @Bean
    public AuthenticationManager authenticationManager(
            AuthenticationConfiguration config) throws Exception {
        return config.getAuthenticationManager();
    }

    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder();
    }
}

6. AuthController — 로그인 & 회원가입

@RestController
@RequestMapping("/api/auth")
@RequiredArgsConstructor
public class AuthController {

    private final AuthenticationManager authenticationManager;
    private final JwtTokenProvider jwtTokenProvider;
    private final UserRepository userRepository;
    private final PasswordEncoder passwordEncoder;

    @PostMapping("/signup")
    public ResponseEntity<String> signup(@RequestBody SignupRequest request) {
        if (userRepository.findByEmail(request.getEmail()).isPresent()) {
            return ResponseEntity.badRequest().body("이미 존재하는 이메일입니다.");
        }

        User user = User.builder()
                .email(request.getEmail())
                .password(passwordEncoder.encode(request.getPassword()))
                .role(Role.ROLE_USER)
                .build();

        userRepository.save(user);
        return ResponseEntity.status(HttpStatus.CREATED).body("회원가입 완료");
    }

    @PostMapping("/login")
    public ResponseEntity<TokenResponse> login(@RequestBody LoginRequest request) {
        Authentication authentication = authenticationManager.authenticate(
                new UsernamePasswordAuthenticationToken(
                        request.getEmail(), request.getPassword()));

        String accessToken = jwtTokenProvider.createAccessToken(authentication);
        String refreshToken = jwtTokenProvider.createRefreshToken(authentication);

        return ResponseEntity.ok(new TokenResponse(accessToken, refreshToken));
    }
}

DTO 클래스:

@Getter
@NoArgsConstructor
public class SignupRequest {
    private String email;
    private String password;
}

@Getter
@NoArgsConstructor
public class LoginRequest {
    private String email;
    private String password;
}

@Getter
@AllArgsConstructor
public class TokenResponse {
    private String accessToken;
    private String refreshToken;
}

로그인 플로우

전체 인증 흐름을 정리하면:

[회원가입]
POST /api/auth/signup { email, password }
    → PasswordEncoder.encode(password) → DB 저장

[로그인]
POST /api/auth/login { email, password }
    → AuthenticationManager.authenticate()
        → CustomUserDetailsService.loadUserByUsername()
        → BCrypt 비밀번호 검증
    → JwtTokenProvider.createAccessToken()
    → JwtTokenProvider.createRefreshToken()
    → { accessToken, refreshToken } 응답

[인증된 API 호출]
GET /api/posts (Authorization: Bearer )
    → JwtAuthenticationFilter.doFilterInternal()
        → resolveToken() → Bearer에서 토큰 추출
        → validateToken() → 서명 검증 + 만료 확인
        → getAuthentication() → SecurityContext에 세팅
    → Controller 정상 처리

토큰 갱신(Refresh) 전략

Access Token의 유효기간은 짧게 설정한다 (15~30분). 만료되면 Refresh Token으로 새 Access Token을 발급받는다.

@PostMapping("/refresh")
public ResponseEntity<TokenResponse> refresh(@RequestBody RefreshRequest request) {
    String refreshToken = request.getRefreshToken();

    if (!jwtTokenProvider.validateToken(refreshToken)) {
        return ResponseEntity.status(HttpStatus.UNAUTHORIZED).build();
    }

    Authentication auth = jwtTokenProvider.getAuthentication(refreshToken);
    String newAccessToken = jwtTokenProvider.createAccessToken(auth);

    // Refresh Token은 재사용 (RTR 전략을 쓰려면 여기서 새로 발급)
    return ResponseEntity.ok(new TokenResponse(newAccessToken, refreshToken));
}

RTR (Refresh Token Rotation) 전략

보안을 강화하려면 Refresh Token도 갱신할 때마다 새로 발급하고, 이전 토큰을 무효화한다. 이를 Refresh Token Rotation 이라 한다.

[기본 전략]
Access Token 만료 → Refresh Token으로 갱신 → 같은 Refresh Token 재사용

[RTR 전략]
Access Token 만료 → Refresh Token으로 갱신 → 새 Refresh Token 발급 + 이전 무효화

RTR을 구현하려면 Refresh Token을 DB나 Redis에 저장하고 관리해야 한다. 서버 부하는 증가하지만, 탈취된 Refresh Token의 피해를 최소화할 수 있다.

흔한 함정과 주의사항

방식	XSS 취약	CSRF 취약	구현 난이도
localStorage	O (JS로 접근 가능)	X	쉬움
HttpOnly Cookie	X (JS 접근 불가)	O	보통

권장: HttpOnly + Secure + SameSite=Strict 쿠키에 저장한다. XSS는 토큰 탈취로 이어지지만, CSRF는 SameSite 속성으로 효과적으로 방어된다.

// 쿠키로 토큰을 내려보내는 예시
ResponseCookie cookie = ResponseCookie.from("access_token", accessToken)
        .httpOnly(true)
        .secure(true)
        .sameSite("Strict")
        .path("/")
        .maxAge(Duration.ofMinutes(30))
        .build();

response.addHeader(HttpHeaders.SET_COOKIE, cookie.toString());

2. JWT + CSRF

JWT를 Authorization 헤더로 보내면 CSRF 보호가 불필요하다 — 브라우저가 자동으로 첨부하는 값이 아니기 때문이다. 하지만 JWT를 쿠키에 저장하면 CSRF 보호를 다시 활성화해야 한다.

// 쿠키 기반 JWT라면 CSRF를 활성화해야 한다
.csrf(csrf -> csrf
    .csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse())
    .csrfTokenRequestHandler(new CsrfTokenRequestAttributeHandler()))

3. 토큰 만료 처리

클라이언트는 401 Unauthorized 응답을 받으면 Refresh Token으로 갱신을 시도해야 한다. Axios interceptor 패턴이 일반적이다:

// Axios interceptor 예시
api.interceptors.response.use(
  response => response,
  async error => {
    const originalRequest = error.config;

    if (error.response?.status === 401 && !originalRequest._retry) {
      originalRequest._retry = true;

      const { data } = await api.post('/api/auth/refresh', {
        refreshToken: getRefreshToken()
      });

      setAccessToken(data.accessToken);
      originalRequest.headers.Authorization = `Bearer ${data.accessToken}`;
      return api(originalRequest);
    }

    return Promise.reject(error);
  }
);

4. 토큰 무효화 (로그아웃)

JWT는 stateless이므로 서버에서 강제 만료시킬 수 없다. 로그아웃 구현 방법:

블랙리스트 — Redis에 로그아웃된 토큰을 저장, 매 요청마다 확인
짧은 만료 — Access Token을 5~15분으로 짧게 설정해서 피해 최소화
토큰 버전 — DB에 사용자별 토큰 버전을 두고, 로그아웃 시 버전을 올림

5. Secret Key 관리

# 절대 이렇게 하지 마세요
jwt:
  secret: "mysecret"  # 너무 짧고, 코드에 하드코딩

# 환경변수나 외부 설정 관리 도구 사용
jwt:
  secret: ${JWT_SECRET}  # 환경변수에서 주입

프로덕션에서는 AWS Secrets Manager, HashiCorp Vault, 또는 Spring Cloud Config 같은 외부 설정 관리 도구를 사용해야 한다.

전체 프로젝트 구조

src/main/java/com/example/demo/
├── config/
│   └── SecurityConfig.java
├── controller/
│   └── AuthController.java
├── domain/
│   ├── User.java
│   └── Role.java
├── dto/
│   ├── LoginRequest.java
│   ├── SignupRequest.java
│   ├── RefreshRequest.java
│   └── TokenResponse.java
├── repository/
│   └── UserRepository.java
├── security/
│   ├── JwtTokenProvider.java
│   ├── JwtAuthenticationFilter.java
│   └── CustomUserDetailsService.java
└── DemoApplication.java

마무리

Spring Security + JWT 인증의 핵심은 SecurityFilterChain에 커스텀 JWT 필터를 끼워 넣는 것이다. 나머지는 토큰을 만들고, 검증하고, SecurityContext에 세팅하는 흐름을 따른다.

실무 체크리스트:

Access Token은 짧게 (15~30분), Refresh Token은 길게 (7~14일)
토큰은 HttpOnly Cookie에 저장 — localStorage는 XSS에 취약
비밀키는 환경변수로 관리, 코드에 절대 하드코딩하지 않기
금전적 피해가 큰 서비스라면 RTR 전략 도입 고려
로그아웃은 Redis 블랙리스트 + 짧은 Access Token 조합으로 구현

다음 글에서는 Spring Security + OAuth 2.0 소셜 로그인 (Google, Kakao)을 다룰 예정이다.

References

React Hooks 완전 정복 — useState부터 Custom Hook까지

doodoo3804@gmail.com (DoYoon Kim) — Wed, 01 Apr 2026 00:00:00 +0900

Class에서 Hooks로

React 16.8 이전에는 상태 관리와 생명주기 로직을 사용하려면 반드시 클래스 컴포넌트를 작성해야 했다.

class Counter extends React.Component {
  constructor(props) {
    super(props);
    this.state = { count: 0 };
    this.handleClick = this.handleClick.bind(this);
  }

  componentDidMount() {
    document.title = `클릭: ${this.state.count}`;
  }

  componentDidUpdate() {
    document.title = `클릭: ${this.state.count}`;
  }

  handleClick() {
    this.setState({ count: this.state.count + 1 });
  }

  render() {
    return <button onClick={this.handleClick}>{this.state.count}button>;
  }
}

문제는 명확했다:

this 바인딩: 매번 .bind(this)를 하거나 화살표 함수를 써야 한다
로직 분산: 같은 관심사의 코드가 componentDidMount, componentDidUpdate, componentWillUnmount에 흩어진다
재사용 어려움: 상태 로직을 공유하려면 HOC나 render props 패턴이 필요한데 “wrapper hell”을 만든다

Hooks는 이 문제를 함수 컴포넌트 안에서 상태와 생명주기를 사용할 수 있게 해서 해결했다.

function Counter() {
  const [count, setCount] = useState(0);

  useEffect(() => {
    document.title = `클릭: ${count}`;
  }, [count]);

  return <button onClick={() => setCount(count + 1)}>{count}button>;
}

코드가 절반으로 줄었고, 관련 로직이 한 곳에 모였다.

useState: 상태 관리의 기본

기본 사용법

const [value, setValue] = useState(initialValue);

핵심 1: 상태 업데이트는 비동기다

function Counter() {
  const [count, setCount] = useState(0);

  const handleClick = () => {
    setCount(count + 1);
    setCount(count + 1);
    setCount(count + 1);
    console.log(count); // 여전히 0 — 즉시 반영되지 않는다
  };
  // 결과: count는 1이 된다 (3이 아님!)
}

세 번 호출해도 count는 같은 클로저 값(0)을 참조하므로 setCount(0 + 1)이 세 번 실행될 뿐이다.

핵심 2: 함수형 업데이트

이전 상태를 기반으로 업데이트할 때는 함수형 업데이트를 사용한다:

const handleClick = () => {
  setCount(prev => prev + 1);
  setCount(prev => prev + 1);
  setCount(prev => prev + 1);
  // 결과: count는 3이 된다 ✅
};

prev는 항상 최신 상태를 보장하므로 연속 업데이트가 올바르게 누적된다.

핵심 3: 객체 상태는 불변하게

const [user, setUser] = useState({ name: '김도윤', age: 25 });

// ❌ 잘못된 방법 — 직접 변경
user.age = 26;
setUser(user); // React가 변경을 감지하지 못함 (같은 참조)

// ✅ 올바른 방법 — 새 객체 생성
setUser(prev => ({ ...prev, age: 26 }));

React는 참조 비교(Object.is)로 상태 변경을 감지한다. 같은 객체 참조를 전달하면 리렌더링이 발생하지 않는다.

useEffect: 부수 효과 관리

기본 구조

useEffect(() => {
  // 실행할 부수 효과
  return () => {
    // cleanup 함수 (선택)
  };
}, [dependencies]);

의존성 배열에 따라 실행 시점이 달라진다:

의존성 배열	실행 시점
생략	매 렌더링마다
`[]` (빈 배열)	마운트 시 1번
`[a, b]`	a 또는 b가 변경될 때

함정 1: 빈 의존성 배열에서 stale closure

function Timer() {
  const [count, setCount] = useState(0);

  useEffect(() => {
    const id = setInterval(() => {
      console.log(count); // 항상 0 — stale closure!
      setCount(count + 1); // 항상 0 + 1 = 1
    }, 1000);
    return () => clearInterval(id);
  }, []); // count를 의존성에 넣지 않았다
}

[]을 전달하면 effect는 마운트 시점의 count(0)를 영원히 참조한다. 해결 방법:

// 방법 1: 함수형 업데이트
setCount(prev => prev + 1);

// 방법 2: 의존성 배열에 추가 (단, 매번 재실행됨)
useEffect(() => { ... }, [count]);

// 방법 3: useRef로 최신 값 추적
const countRef = useRef(count);
countRef.current = count;

함정 2: 객체/배열 의존성

function UserProfile({ userId }) {
  const [user, setUser] = useState(null);
  
  // ⚠️ options가 매 렌더링마다 새 객체 → effect 무한 실행
  const options = { includeDetails: true };

  useEffect(() => {
    fetchUser(userId, options).then(setUser);
  }, [userId, options]); // options는 매번 새 참조!
}

객체와 배열은 매 렌더링마다 새 참조가 만들어진다. 해결:

// 방법 1: 의존성을 원시 값으로 분해
useEffect(() => {
  fetchUser(userId, { includeDetails: true }).then(setUser);
}, [userId]);

// 방법 2: useMemo로 참조 안정화
const options = useMemo(() => ({ includeDetails: true }), []);

Cleanup 함수의 중요성

useEffect(() => {
  const ws = new WebSocket('wss://api.example.com/feed');
  ws.onmessage = (event) => setMessages(prev => [...prev, event.data]);

  return () => {
    ws.close(); // 컴포넌트 언마운트 시 연결 종료
  };
}, []);

cleanup을 빠뜨리면 메모리 누수가 발생한다. 구독, 타이머, WebSocket, 이벤트 리스너는 반드시 cleanup에서 정리하자.

흔한 실수: useEffect 안에서 상태 설정 → 무한 루프

// ❌ 무한 루프
useEffect(() => {
  setCount(count + 1); // 상태 변경 → 리렌더링 → effect 재실행 → ...
});

// ❌ 미묘한 무한 루프
useEffect(() => {
  setItems([...items, newItem]); // items가 변경 → effect 재실행
}, [items]);

useCallback과 useMemo: 최적화, 그러나 신중하게

useMemo — 값 메모이제이션

const sortedList = useMemo(() => {
  return [...items].sort((a, b) => a.price - b.price);
}, [items]);

items가 변경되지 않으면 정렬을 다시 수행하지 않는다.

useCallback — 함수 메모이제이션

const handleSubmit = useCallback((data) => {
  api.post('/users', data);
}, []);

useCallback(fn, deps)는 사실 useMemo(() => fn, deps)와 동일하다. 함수 자체의 참조를 안정화한다.

언제 써야 하는가

// ✅ 사용이 정당한 경우
// 1. React.memo로 감싼 자식에게 전달하는 콜백
const MemoChild = React.memo(({ onClick }) => <button onClick={onClick}>Clickbutton>);

function Parent() {
  const handleClick = useCallback(() => {
    console.log('clicked');
  }, []);
  return <MemoChild onClick={handleClick} />;
}

// 2. useEffect 의존성에 들어가는 함수
const fetchData = useCallback(() => {
  return api.get(`/users/${userId}`);
}, [userId]);

useEffect(() => {
  fetchData().then(setData);
}, [fetchData]);

// 3. 비용이 큰 계산
const result = useMemo(() => {
  return heavyComputation(data); // 수만 건 데이터 처리
}, [data]);

남용하지 말 것

// ❌ 불필요한 useMemo — 단순 계산
const fullName = useMemo(() => `${firstName} ${lastName}`, [firstName, lastName]);
// 그냥 이렇게 쓰면 된다:
const fullName = `${firstName} ${lastName}`;

// ❌ 불필요한 useCallback — memo된 자식에게 전달하지 않는 콜백
const handleClick = useCallback(() => {
  setCount(c => c + 1);
}, []);
// 자식이 React.memo가 아니면 어차피 리렌더링된다

useMemo/useCallback 자체도 비용이 있다. 의존성 배열 비교, 이전 값 캐싱 등의 오버헤드가 발생한다. 단순한 연산에 적용하면 오히려 성능이 나빠진다. “측정 후 최적화”가 원칙이다.

useRef: DOM 접근과 뮤터블 값

DOM 접근

function TextInput() {
  const inputRef = useRef(null);

  const focusInput = () => {
    inputRef.current.focus();
  };

  return (
    <>
      <input ref={inputRef} type="text" />
      <button onClick={focusInput}>포커스button>
    
  );
}

렌더링과 무관한 뮤터블 값 저장

useRef는 .current를 변경해도 리렌더링을 트리거하지 않는다. 이 특성을 활용해 렌더링 사이에 값을 유지하면서도 리렌더링을 피할 수 있다.

function StopWatch() {
  const [elapsed, setElapsed] = useState(0);
  const intervalRef = useRef(null);

  const start = () => {
    intervalRef.current = setInterval(() => {
      setElapsed(prev => prev + 1);
    }, 1000);
  };

  const stop = () => {
    clearInterval(intervalRef.current);
  };

  return (
    <div>
      <span>{elapsed}초span>
      <button onClick={start}>시작button>
      <button onClick={stop}>정지button>
    div>
  );
}

이전 상태 값 추적

function usePrevious(value) {
  const ref = useRef();
  useEffect(() => {
    ref.current = value;
  });
  return ref.current;
}

function Counter() {
  const [count, setCount] = useState(0);
  const prevCount = usePrevious(count);
  return <p>현재: {count}, 이전: {prevCount}p>;
}

Custom Hook: 로직 재사용의 핵심

Custom Hook은 use로 시작하는 함수로, 내부에서 다른 Hook을 조합해 재사용 가능한 상태 로직을 캡슐화한다.

useFetch — API 호출 추상화

function useFetch(url) {
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    const controller = new AbortController();
    setLoading(true);

    fetch(url, { signal: controller.signal })
      .then(res => {
        if (!res.ok) throw new Error(`HTTP ${res.status}`);
        return res.json();
      })
      .then(setData)
      .catch(err => {
        if (err.name !== 'AbortError') setError(err);
      })
      .finally(() => setLoading(false));

    return () => controller.abort(); // cleanup: 컴포넌트 언마운트 시 요청 취소
  }, [url]);

  return { data, loading, error };
}

// 사용
function UserList() {
  const { data: users, loading, error } = useFetch('/api/users');

  if (loading) return <p>로딩 중...p>;
  if (error) return <p>에러: {error.message}p>;
  return <ul>{users.map(u => <li key={u.id}>{u.name}li>)}ul>;
}

useLocalStorage — localStorage와 상태 동기화

function useLocalStorage(key, initialValue) {
  const [value, setValue] = useState(() => {
    const stored = localStorage.getItem(key);
    return stored !== null ? JSON.parse(stored) : initialValue;
  });

  useEffect(() => {
    localStorage.setItem(key, JSON.stringify(value));
  }, [key, value]);

  return [value, setValue];
}

// 사용
function Settings() {
  const [theme, setTheme] = useLocalStorage('theme', 'light');
  return (
    <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
      현재 테마: {theme}
    button>
  );
}

useDebounce — 입력 디바운스

function useDebounce(value, delay) {
  const [debounced, setDebounced] = useState(value);

  useEffect(() => {
    const timer = setTimeout(() => setDebounced(value), delay);
    return () => clearTimeout(timer);
  }, [value, delay]);

  return debounced;
}

// 사용: 검색 입력 디바운스
function SearchBar() {
  const [query, setQuery] = useState('');
  const [results, setResults] = useState([]);
  const debouncedQuery = useDebounce(query, 300);

  useEffect(() => {
    if (debouncedQuery) {
      searchApi(debouncedQuery).then(setResults);
    }
  }, [debouncedQuery]);

  return <input value={query} onChange={e => setQuery(e.target.value)} />;
}

Custom Hook 설계 원칙:

하나의 관심사에 집중 — useFetch는 API 호출만, useLocalStorage는 로컬 저장소만
반환 값은 사용처에 맞게 — 단일 값이면 값 자체를, 여러 값이면 객체로
cleanup을 잊지 말 것 — 타이머, 구독, 요청 취소
Hook 규칙을 준수 — 내부에서 다른 Hook을 조건부로 호출하지 않기

Hook의 규칙과 그 이유

규칙 1: 최상위에서만 호출

// ❌ 조건문 안에서 호출
if (isLoggedIn) {
  const [user, setUser] = useState(null); // 금지!
}

// ❌ 반복문 안에서 호출
for (const item of items) {
  useEffect(() => { ... }); // 금지!
}

// ✅ 항상 컴포넌트/Hook 최상위에서 호출
const [user, setUser] = useState(null);
const [items, setItems] = useState([]);

이유: React는 Hook을 호출 순서로 식별한다. 내부적으로 Hook 상태를 배열(또는 연결 리스트)로 관리하며, 매 렌더링마다 같은 순서로 호출되어야 올바른 상태를 매칭할 수 있다. 조건부 호출은 순서를 깨뜨린다.

// 첫 렌더링:  useState(0) → useEffect → useState('')
//              Hook #0       Hook #1      Hook #2
//
// isLoggedIn이 false가 되면:
// 두번째 렌더링: useEffect → useState('')
//                Hook #0(!!!)  Hook #1(!!!)
// → Hook #0이 useState가 아닌 useEffect와 매칭 → 💥

규칙 2: React 함수 안에서만 호출

// ❌ 일반 함수에서 호출
function formatData(data) {
  const [formatted, setFormatted] = useState(data); // 금지!
}

// ✅ React 컴포넌트에서 호출
function DataDisplay({ data }) {
  const [formatted, setFormatted] = useState(data);
}

// ✅ Custom Hook에서 호출
function useFormattedData(data) {
  const [formatted, setFormatted] = useState(data);
  return formatted;
}

ESLint 플러그인 eslint-plugin-react-hooks를 설치하면 이 규칙 위반을 빌드 시점에 잡아준다:

npm install eslint-plugin-react-hooks --save-dev

{
  "plugins": ["react-hooks"],
  "rules": {
    "react-hooks/rules-of-hooks": "error",
    "react-hooks/exhaustive-deps": "warn"
  }
}

마무리

Hook은 단순한 API 변경이 아니라 React의 사고방식 자체를 바꾼 전환점이었다. 생명주기 중심에서 동기화 중심으로, 상속 기반에서 합성 기반으로의 전환이다.

핵심 정리:

Hook	용도	주의점
`useState`	상태 관리	비동기 업데이트, 객체 불변성
`useEffect`	부수 효과	의존성 배열, cleanup, stale closure
`useCallback`	함수 메모이제이션	React.memo와 함께 써야 의미 있음
`useMemo`	값 메모이제이션	측정 후 적용, 단순 계산에 남용 금지
`useRef`	DOM 접근 / 뮤터블 값	변경해도 리렌더링 안 됨
Custom Hook	로직 재사용	use 접두사, Hook 규칙 준수

클래스 컴포넌트를 억지로 Hook으로 바꿀 필요는 없다. 하지만 새 코드를 작성한다면 Hook이 기본이다. 공식 문서에서도 함수 컴포넌트 + Hook을 권장하고 있으며, React의 최신 기능(Server Components, Suspense 등)도 함수 컴포넌트를 전제로 설계되고 있다.

Kotlin Coroutines 실전 가이드

doodoo3804@gmail.com (DoYoon Kim) — Wed, 01 Apr 2026 00:00:00 +0900

Kotlin의 코루틴은 비동기 프로그래밍을 동기 코드처럼 작성할 수 있게 해주는 경량 동시성 프레임워크다. 이 글에서는 기본 개념부터 실전 패턴까지 정리한다.

1. Coroutine 기본 개념

1.1 suspend 함수

suspend 키워드는 함수가 일시 중단(suspend) 될 수 있음을 표시한다. suspend 함수는 코루틴 내부 또는 다른 suspend 함수에서만 호출할 수 있다.

suspend fun fetchUserData(userId: String): User {
    // 네트워크 호출 — 스레드를 블로킹하지 않고 일시 중단
    return apiService.getUser(userId)
}

일반 함수와의 차이:

일반 함수: 호출하면 완료될 때까지 스레드를 점유
suspend 함수: 중간에 실행을 양보(suspend)하고, 나중에 재개(resume)할 수 있음

1.2 launch — Fire and Forget

launch는 결과를 반환하지 않는 코루틴을 시작한다. 반환 타입은 Job이다.

fun main() = runBlocking {
    val job: Job = launch {
        delay(1000L)
        println("World!")
    }
    println("Hello,")
    job.join() // 코루틴 완료 대기
}
// 출력:
// Hello,
// World!

1.3 async/await — 결과 반환

async는 결과를 반환하는 코루틴을 시작한다. 반환 타입은 Deferred이며, await()로 결과를 받는다.

fun main() = runBlocking {
    val deferred: Deferred<Int> = async {
        delay(1000L)
        42
    }
    println("계산 결과: ${deferred.await()}")
}

빌더	반환 타입	용도
`launch`	`Job`	결과가 필요 없는 비동기 작업
`async`	`Deferred`	결과를 반환하는 비동기 작업
`runBlocking`	`T`	메인 함수/테스트에서 코루틴 진입점

2. CoroutineScope, CoroutineContext, Dispatcher

2.1 CoroutineScope

모든 코루틴은 CoroutineScope 안에서 실행된다. Scope는 코루틴의 생명주기를 관리한다.

class UserRepository {
    // 자체 스코프 — 필요 시 전체 취소 가능
    private val scope = CoroutineScope(SupervisorJob() + Dispatchers.IO)

    fun fetchUsers() {
        scope.launch {
            val users = apiService.getUsers()
            // ...
        }
    }

    fun clear() {
        scope.cancel() // 소속 코루틴 전체 취소
    }
}

Android에서는 viewModelScope, lifecycleScope 등 미리 정의된 스코프를 활용한다.

2.2 CoroutineContext

CoroutineContext는 코루틴의 실행 환경을 정의하는 불변 요소 집합이다.

주요 요소:

Job: 코루틴의 생명주기 관리
Dispatcher: 어떤 스레드에서 실행할지
CoroutineName: 디버깅용 이름
CoroutineExceptionHandler: 예외 처리기

val context = Dispatchers.IO + CoroutineName("data-loader") + exceptionHandler
launch(context) {
    // IO 디스패처에서 "data-loader"라는 이름으로 실행
}

2.3 Dispatcher 종류

Dispatcher	스레드 풀	용도
`Dispatchers.Main`	메인(UI) 스레드	UI 업데이트, 가벼운 작업
`Dispatchers.IO`	공유 스레드 풀 (64개)	네트워크, DB, 파일 I/O
`Dispatchers.Default`	CPU 코어 수만큼	CPU 집약적 연산 (정렬, JSON 파싱)
`Dispatchers.Unconfined`	호출 스레드 → 재개 스레드	특수 케이스, 테스트

launch(Dispatchers.IO) {
    val data = fetchFromNetwork()        // IO 스레드
    withContext(Dispatchers.Main) {
        updateUI(data)                    // 메인 스레드로 전환
    }
}

3. Structured Concurrency 패턴 및 Job 계층 구조

3.1 Structured Concurrency 원칙

Kotlin 코루틴의 핵심 설계 철학은 Structured Concurrency다:

모든 코루틴은 부모 스코프 안에서 실행된다.
부모가 취소되면 자식 코루틴도 모두 취소된다.
자식이 실패하면 부모에게 전파된다.
부모는 모든 자식이 완료될 때까지 완료되지 않는다.

fun main() = runBlocking {       // 부모
    launch {                      // 자식 1
        delay(2000L)
        println("자식 1 완료")
    }
    launch {                      // 자식 2
        delay(1000L)
        println("자식 2 완료")
    }
    // runBlocking은 두 자식이 모두 완료될 때까지 대기
}

3.2 Job 계층 구조

runBlocking (Job)
├── launch (Job - 자식 1)
│   └── launch (Job - 손자 1)
└── launch (Job - 자식 2)

취소 전파: 부모 Job 취소 → 모든 자식 취소

fun main() = runBlocking {
    val parentJob = launch {
        val child1 = launch {
            repeat(1000) { i ->
                println("자식 1: $i")
                delay(500L)
            }
        }
        val child2 = launch {
            repeat(1000) { i ->
                println("자식 2: $i")
                delay(300L)
            }
        }
    }
    delay(1300L)
    parentJob.cancel()  // 자식 1, 자식 2 모두 취소됨
    println("부모 취소 완료")
}

3.3 coroutineScope vs supervisorScope

// coroutineScope: 자식 하나가 실패하면 나머지도 취소
suspend fun failFast() = coroutineScope {
    launch { throw RuntimeException("실패!") }  // 전체 스코프 취소
    launch { delay(Long.MAX_VALUE) }             // 같이 취소됨
}

// supervisorScope: 자식 실패가 형제에게 전파되지 않음
suspend fun failIsolated() = supervisorScope {
    launch { throw RuntimeException("실패!") }  // 이것만 실패
    launch {
        delay(1000L)
        println("나는 계속 실행됨")              // 정상 실행
    }
}

4. 실전 예제

4.1 여러 API 병렬 호출 (async/await)

suspend fun loadDashboard(userId: String): Dashboard = coroutineScope {
    // 세 API를 병렬로 호출
    val userDeferred = async { userApi.getUser(userId) }
    val ordersDeferred = async { orderApi.getOrders(userId) }
    val recommendsDeferred = async { recommendApi.getRecommendations(userId) }

    // 모든 결과를 모아서 반환
    Dashboard(
        user = userDeferred.await(),
        orders = ordersDeferred.await(),
        recommendations = recommendsDeferred.await()
    )
}

순차 실행 시 3초 걸리는 작업이 병렬로 1초에 완료된다 (각 API가 1초라고 가정).

4.2 타임아웃 처리 (withTimeout)

suspend fun fetchWithTimeout(): String {
    return try {
        withTimeout(3000L) {
            // 3초 안에 완료되지 않으면 TimeoutCancellationException
            slowApi.fetchData()
        }
    } catch (e: TimeoutCancellationException) {
        "기본값 (타임아웃)"
    }
}

// null 반환 버전
suspend fun fetchOrNull(): String? {
    return withTimeoutOrNull(3000L) {
        slowApi.fetchData()
    }
}

4.3 재시도 패턴

suspend fun <T> retry(
    times: Int = 3,
    initialDelay: Long = 100L,
    factor: Double = 2.0,
    block: suspend () -> T
): T {
    var currentDelay = initialDelay
    repeat(times - 1) {
        try {
            return block()
        } catch (e: Exception) {
            println("재시도 ${it + 1}/$times — ${e.message}")
        }
        delay(currentDelay)
        currentDelay = (currentDelay * factor).toLong()
    }
    return block() // 마지막 시도 — 실패 시 예외 전파
}

// 사용
val result = retry(times = 3) {
    apiService.getUser("user-123")
}

5. Flow 기초

Flow는 비동기 데이터 스트림이다. RxJava의 Observable과 유사하지만 코루틴 기반이다.

5.1 Cold Stream

Flow는 cold stream이다 — collect가 호출될 때까지 실행되지 않는다.

import kotlinx.coroutines.flow.*

fun numberFlow(): Flow<Int> = flow {
    for (i in 1..5) {
        delay(100L)
        emit(i)  // 값 방출
    }
}

fun main() = runBlocking {
    numberFlow().collect { value ->
        println("수신: $value")
    }
}

5.2 Flow 연산자

fun main() = runBlocking {
    (1..10).asFlow()
        .filter { it % 2 == 0 }           // 짝수만
        .map { it * it }                    // 제곱
        .take(3)                            // 처음 3개만
        .collect { println(it) }            // 4, 16, 36
}

주요 연산자 정리:

연산자	설명
`map`	각 값 변환
`filter`	조건에 맞는 값만 통과
`take`	처음 N개만
`drop`	처음 N개 건너뛰기
`onEach`	각 값에 대해 부수 효과 실행
`flatMapConcat`	각 값을 새 Flow로 변환 후 순차 연결
`flatMapMerge`	각 값을 새 Flow로 변환 후 병렬 수집
`combine`	두 Flow의 최신 값 조합
`zip`	두 Flow의 값을 1:1 매칭

5.3 StateFlow와 SharedFlow

class UserViewModel : ViewModel() {
    // StateFlow — 항상 최신 값을 가지고 있음 (LiveData 대체)
    private val _uiState = MutableStateFlow(UiState.Loading)
    val uiState: StateFlow<UiState> = _uiState.asStateFlow()

    // SharedFlow — 이벤트 전달 (일회성 이벤트)
    private val _events = MutableSharedFlow<Event>()
    val events: SharedFlow<Event> = _events.asSharedFlow()

    fun loadUser(id: String) {
        viewModelScope.launch {
            _uiState.value = UiState.Loading
            try {
                val user = userRepository.getUser(id)
                _uiState.value = UiState.Success(user)
            } catch (e: Exception) {
                _uiState.value = UiState.Error(e.message)
                _events.emit(Event.ShowSnackbar("로드 실패"))
            }
        }
    }
}

6. 코루틴 예외 처리

6.1 launch vs async 예외 전파 차이

fun main() = runBlocking {
    // launch: 예외가 즉시 부모로 전파됨
    val job = launch {
        throw RuntimeException("launch 에러")
        // → 부모 코루틴까지 전파, try-catch로 잡을 수 없음
    }

    // async: await() 호출 시 예외 발생
    val deferred = async {
        throw RuntimeException("async 에러")
    }
    try {
        deferred.await()  // 여기서 예외 발생
    } catch (e: RuntimeException) {
        println("잡았다: ${e.message}")
    }
}

6.2 CoroutineExceptionHandler

launch의 예외를 잡기 위해 CoroutineExceptionHandler를 사용한다. 이 핸들러는 루트 코루틴에만 적용된다.

val handler = CoroutineExceptionHandler { _, exception ->
    println("예외 발생: ${exception.message}")
    // 로깅, 알림 등 처리
}

fun main() = runBlocking {
    val scope = CoroutineScope(SupervisorJob() + handler)

    scope.launch {
        throw RuntimeException("문제 발생!")
        // → handler에서 처리됨
    }

    scope.launch {
        delay(1000L)
        println("나는 정상 실행")  // SupervisorJob 덕분에 영향 없음
    }

    delay(2000L)
}

6.3 SupervisorJob

SupervisorJob은 자식의 실패가 다른 자식에게 전파되지 않게 한다.

val scope = CoroutineScope(SupervisorJob() + Dispatchers.IO)

scope.launch {
    // 자식 1 — 실패해도 자식 2에 영향 없음
    throw RuntimeException("자식 1 실패")
}

scope.launch {
    // 자식 2 — 정상 실행 계속
    delay(1000L)
    println("자식 2 완료")
}

일반 Job vs SupervisorJob 비교:

특성	Job	SupervisorJob
자식 실패 시	다른 자식 모두 취소	실패한 자식만 취소
부모 영향	부모도 취소	부모 유지
사용 시점	전체가 하나의 작업일 때	독립적인 작업들을 관리할 때

6.4 실전 예외 처리 패턴

sealed class Result<out T> {
    data class Success<T>(val data: T) : Result<T>()
    data class Error(val exception: Throwable) : Result<Nothing>()
}

suspend fun <T> safeApiCall(block: suspend () -> T): Result<T> {
    return try {
        Result.Success(block())
    } catch (e: CancellationException) {
        throw e  // 취소 예외는 반드시 재던져야 함!
    } catch (e: Exception) {
        Result.Error(e)
    }
}

// 사용
val result = safeApiCall { apiService.getUser(userId) }
when (result) {
    is Result.Success -> showUser(result.data)
    is Result.Error -> showError(result.exception.message)
}

주의: CancellationException을 삼키면 코루틴 취소가 작동하지 않는다. 반드시 재던져야 한다.

정리

개념	핵심
`suspend`	일시 중단 가능한 함수
`launch` / `async`	코루틴 빌더 (fire-and-forget / 결과 반환)
`Dispatcher`	실행 스레드 제어 (Main, IO, Default)
Structured Concurrency	부모-자식 관계로 생명주기 관리
`Flow`	비동기 cold stream
`SupervisorJob`	자식 실패 격리
`CoroutineExceptionHandler`	루트 코루틴 예외 처리

코루틴은 단순히 스레드를 대체하는 도구가 아니라, 구조화된 동시성을 통해 안전하고 관리 가능한 비동기 코드를 작성하게 해주는 설계 패러다임이다.

References

Kotlin 고급 문법

doodoo3804@gmail.com (DoYoon Kim) — Wed, 01 Apr 2026 00:00:00 +0900

Kotlin 고급 문법

Kotlin의 기본 문법에 이어, 실무와 코딩 테스트에서 자주 활용되는 고급 문법을 정리한다.

1. Lambda

val square: (Int) -> Int = { number -> number * number }

fun main() {
    println(square(5)) // 25
}

람다식은 value처럼 다룰 수 있는 익명 함수이다. 변수에 저장하거나 함수의 인자로 전달할 수 있다.

축약 표현

파라미터가 하나인 경우 it 키워드로 축약할 수 있다.

val double: (Int) -> Int = { it * 2 }
val names = listOf("Alice", "Bob", "Charlie")
val lengths = names.map { it.length } // [5, 3, 7]

여러 줄 람다

마지막 표현식이 반환값이 된다.

val processName: (String) -> String = { name ->
    val trimmed = name.trim()
    val upper = trimmed.uppercase()
    upper // 이 값이 반환됨
}

2. Higher-Order Functions (고차 함수)

함수를 매개변수로 받거나 함수를 반환하는 함수이다.

fun operate(a: Int, b: Int, operation: (Int, Int) -> Int): Int {
    return operation(a, b)
}

fun main() {
    val sum = operate(3, 4) { x, y -> x + y }
    val product = operate(3, 4) { x, y -> x * y }
    println(sum)     // 7
    println(product) // 12
}

마지막 파라미터가 람다인 경우, 괄호 밖으로 뺄 수 있다 (trailing lambda).

// 아래 두 표현은 동일
listOf(1, 2, 3).filter({ it > 1 })
listOf(1, 2, 3).filter { it > 1 }

3. Extension Functions (확장 함수)

기존 클래스를 수정하지 않고 새로운 함수를 추가할 수 있다.

fun String.addExclamation(): String {
    return this + "!"
}

fun Int.isEven(): Boolean = this % 2 == 0

fun main() {
    println("Hello".addExclamation()) // Hello!
    println(4.isEven())               // true
    println(7.isEven())               // false
}

실용적인 예시

fun <T> List<T>.secondOrNull(): T? {
    return if (this.size >= 2) this[1] else null
}

fun String.toSlug(): String {
    return this.lowercase()
        .replace(Regex("[^a-z0-9\\s-]"), "")
        .replace(Regex("\\s+"), "-")
        .trim('-')
}

4. Scope Functions (범위 함수)

Kotlin은 객체의 컨텍스트 내에서 코드 블록을 실행하는 5개의 scope function을 제공한다.

함수	객체 참조	반환값	사용 사례
`let`	`it`	람다 결과	null 체크 후 실행
`run`	`this`	람다 결과	객체 설정 + 결과 계산
`with`	`this`	람다 결과	객체의 여러 메서드 호출
`apply`	`this`	객체 자체	객체 초기화/설정
`also`	`it`	객체 자체	부수 효과 (로깅 등)

data class Person(
    var name: String = "",
    var age: Int = 0,
    var email: String = ""
)

// let: null-safe 처리
val name: String? = "Kotlin"
name?.let {
    println("Name length: ${it.length}")
}

// apply: 객체 초기화
val person = Person().apply {
    this.name = "DooDoo"
    this.age = 25
    this.email = "doodoo@example.com"
}

// also: 디버깅/로깅
val numbers = mutableListOf(1, 2, 3)
    .also { println("Before: $it") }
    .apply { add(4) }
    .also { println("After: $it") }

// run: 객체 설정 + 결과
val greeting = person.run {
    "Hello, $name! You are $age years old."
}

// with: 여러 속성 접근
val info = with(person) {
    println(name)
    println(age)
    "$name ($age)"
}

5. Data Class & Destructuring

data class User(val name: String, val age: Int, val email: String)

fun main() {
    val user = User("DooDoo", 25, "doodoo@example.com")

    // 자동 생성: toString, equals, hashCode, copy
    println(user)                        // User(name=DooDoo, age=25, email=doodoo@example.com)
    val older = user.copy(age = 26)      // name, email은 유지

    // Destructuring
    val (name, age, email) = user
    println("$name is $age years old")   // DooDoo is 25 years old

    // Map에서도 활용
    val map = mapOf("a" to 1, "b" to 2)
    for ((key, value) in map) {
        println("$key -> $value")
    }
}

6. Sealed Class

상속 가능한 클래스들의 집합을 제한할 때 사용한다. when 표현식에서 else 분기가 필요 없어진다.

sealed class Result<out T> {
    data class Success<T>(val data: T) : Result<T>()
    data class Error(val message: String) : Result<Nothing>()
    object Loading : Result<Nothing>()
}

fun handleResult(result: Result<String>) {
    when (result) {
        is Result.Success -> println("Data: ${result.data}")
        is Result.Error   -> println("Error: ${result.message}")
        is Result.Loading -> println("Loading...")
        // else 불필요 - 컴파일러가 모든 케이스를 확인
    }
}

7. Collection Operations

Kotlin의 컬렉션 API는 함수형 프로그래밍 스타일의 다양한 연산을 제공한다.

val numbers = listOf(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)

// 기본 변환
val doubled = numbers.map { it * 2 }           // [2, 4, 6, ..., 20]
val evens = numbers.filter { it % 2 == 0 }     // [2, 4, 6, 8, 10]
val sum = numbers.reduce { acc, n -> acc + n }  // 55

// 그룹화 & 분할
val grouped = numbers.groupBy { if (it % 2 == 0) "even" else "odd" }
// {odd=[1, 3, 5, 7, 9], even=[2, 4, 6, 8, 10]}

val (small, large) = numbers.partition { it <= 5 }
// small=[1,2,3,4,5], large=[6,7,8,9,10]

// flatMap
val nested = listOf(listOf(1, 2), listOf(3, 4), listOf(5))
val flat = nested.flatMap { it } // [1, 2, 3, 4, 5]

// 체이닝
val result = numbers
    .filter { it % 2 == 0 }
    .map { it * it }
    .sortedDescending()
    .take(3)
// [100, 64, 36]

8. Coroutines 기초

Kotlin 코루틴은 비동기 프로그래밍을 순차적인 코드처럼 작성할 수 있게 해준다.

import kotlinx.coroutines.*

fun main() = runBlocking {
    // launch: 결과를 반환하지 않는 코루틴
    val job = launch {
        delay(1000L)
        println("World!")
    }
    println("Hello,")
    job.join()

    // async: 결과를 반환하는 코루틴
    val deferred1 = async { fetchUserName() }
    val deferred2 = async { fetchUserAge() }
    println("${deferred1.await()} is ${deferred2.await()} years old")
}

suspend fun fetchUserName(): String {
    delay(1000L) // 네트워크 호출 시뮬레이션
    return "DooDoo"
}

suspend fun fetchUserAge(): Int {
    delay(1000L)
    return 25
}

주요 개념

suspend: 일시 중단 가능한 함수를 표시하는 키워드
launch: 결과를 반환하지 않는 코루틴 빌더 (Job 반환)
async: 결과를 반환하는 코루틴 빌더 (Deferred 반환)
runBlocking: 코루틴이 완료될 때까지 현재 스레드를 차단

// 구조화된 동시성 (Structured Concurrency)
suspend fun loadData() = coroutineScope {
    val users = async { fetchUsers() }
    val posts = async { fetchPosts() }
    // 둘 다 완료될 때까지 대기
    processData(users.await(), posts.await())
}

Dispatchers

// Dispatchers 종류
launch(Dispatchers.Main) { /* UI 작업 */ }
launch(Dispatchers.IO) { /* 네트워크, DB I/O */ }
launch(Dispatchers.Default) { /* CPU 집약 작업 */ }

Exception Handling

val handler = CoroutineExceptionHandler { _, exception ->
    println("예외 처리: $exception")
}
val job = CoroutineScope(Dispatchers.IO + handler).launch {
    throw RuntimeException("에러 발생")
}

Flow 기초

fun numberFlow(): Flow<Int> = flow {
    for (i in 1..5) {
        delay(100)
        emit(i)
    }
}

// collect
numberFlow().collect { value -> println(value) }

9. Inline Functions & Reified Types

inline 키워드는 함수 호출 오버헤드를 줄이고, reified는 제네릭 타입 정보를 런타임에 유지한다.

inline fun <reified T> List<*>.filterByType(): List<T> {
    return this.filterIsInstance<T>()
}

fun main() {
    val mixed: List<Any> = listOf(1, "hello", 2.0, "world", 3)
    val strings = mixed.filterByType<String>() // [hello, world]
    val ints = mixed.filterByType<Int>()       // [1, 3]
}

References

Kubernetes 핵심 개념 — Pod부터 Deployment까지

doodoo3804@gmail.com (DoYoon Kim) — Wed, 01 Apr 2026 00:00:00 +0900

왜 Kubernetes인가

이전 Docker 포스트에서 컨테이너를 만들고 docker-compose로 멀티 컨테이너 환경을 구성하는 법을 다뤘다. 로컬 개발이나 소규모 서비스에서는 충분하지만, 프로덕션 환경에서는 금방 한계에 부딪힌다.

컨테이너가 죽으면 누가 다시 띄우는가?
트래픽이 급증하면 컨테이너를 어떻게 늘리는가?
새 버전을 배포할 때 다운타임 없이 교체할 수 있는가?
서버가 여러 대일 때 어떤 서버에 컨테이너를 배치할 것인가?

Kubernetes(이하 k8s)는 이 문제들을 자동으로 해결해 주는 컨테이너 오케스트레이션 플랫폼이다.

문제	k8s가 제공하는 해법
컨테이너 장애	Self-healing — 컨테이너가 죽으면 자동 재시작
트래픽 급증	Auto Scaling — HPA로 Pod 수를 자동 조절
무중단 배포	Rolling Update — 순차적으로 새 버전 교체
서버 분산 배치	Scheduling — 리소스 상태에 따라 최적 노드 배치

핵심 아키텍처

Cluster

k8s의 최상위 단위. Control Plane(마스터)과 하나 이상의 Worker Node로 구성된다.

┌─────────────────── Cluster ───────────────────┐
│                                                │
│  ┌──── Control Plane ────┐                     │
│  │  API Server           │                     │
│  │  etcd                 │                     │
│  │  Scheduler            │                     │
│  │  Controller Manager   │                     │
│  └───────────────────────┘                     │
│                                                │
│  ┌── Worker Node 1 ──┐  ┌── Worker Node 2 ──┐ │
│  │  kubelet           │  │  kubelet           │ │
│  │  kube-proxy        │  │  kube-proxy        │ │
│  │  [Pod] [Pod]       │  │  [Pod] [Pod]       │ │
│  └────────────────────┘  └────────────────────┘ │
└────────────────────────────────────────────────┘

API Server: 모든 요청의 진입점. kubectl 명령이 여기로 간다.
etcd: 클러스터 상태를 저장하는 분산 key-value 저장소.
Scheduler: 새 Pod를 어느 노드에 배치할지 결정.
Controller Manager: Desired State와 현재 상태를 비교해 차이를 메꾼다.

Node

실제 컨테이너가 실행되는 물리/가상 머신. 각 노드에는 kubelet(Pod 관리 에이전트)과 kube-proxy(네트워크 규칙 관리)가 동작한다.

Pod

k8s에서 배포 가능한 가장 작은 단위. 하나 이상의 컨테이너를 포함하며, 같은 Pod 안의 컨테이너들은 네트워크(localhost)와 스토리지를 공유한다.

apiVersion: v1
kind: Pod
metadata:
  name: my-app
spec:
  containers:
    - name: app
      image: my-app:1.0
      ports:
        - containerPort: 8080

실무에서는 Pod를 직접 생성하는 일은 거의 없다. 항상 Deployment 같은 상위 오브젝트를 통해 관리한다.

Namespace

클러스터 안에서 리소스를 논리적으로 격리하는 단위. 팀별, 환경별로 나눠 사용한다.

kubectl get namespaces
# NAME              STATUS   AGE
# default           Active   10d
# kube-system       Active   10d
# production        Active   5d
# staging           Active   5d

핵심 오브젝트

Deployment

Pod의 원하는 상태(Desired State)를 선언하면, k8s가 그 상태를 유지해 준다. Pod 개수, 이미지 버전 등을 명시하면 Controller가 알아서 관리한다.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 3            # Pod 3개를 유지
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: app
          image: my-app:1.0
          ports:
            - containerPort: 8080
          resources:
            requests:
              cpu: "250m"
              memory: "256Mi"
            limits:
              cpu: "500m"
              memory: "512Mi"

Rolling Update는 Deployment의 기본 배포 전략이다. image: my-app:2.0으로 바꾸면 k8s가 새 Pod를 하나씩 띄우고 기존 Pod를 하나씩 종료한다. 다운타임이 없다.

# 이미지 업데이트 → Rolling Update 자동 실행
kubectl set image deployment/my-app app=my-app:2.0

# 배포 상태 확인
kubectl rollout status deployment/my-app

# 문제 시 롤백
kubectl rollout undo deployment/my-app

Service

Pod는 생성/삭제될 때마다 IP가 바뀐다. Service는 Pod 집합에 대한 안정적인 네트워크 엔드포인트를 제공한다. Label selector로 대상 Pod를 지정하고, 고정 IP(ClusterIP)와 DNS 이름을 부여한다.

타입	접근 범위	사용 시나리오
ClusterIP (기본)	클러스터 내부만	마이크로서비스 간 통신
NodePort	외부 (노드IP:포트)	개발/테스트 환경
LoadBalancer	외부 (클라우드 LB)	프로덕션 외부 노출

apiVersion: v1
kind: Service
metadata:
  name: my-app-service
spec:
  type: ClusterIP
  selector:
    app: my-app          # 이 label을 가진 Pod에 트래픽 전달
  ports:
    - port: 80           # Service가 받는 포트
      targetPort: 8080   # Pod에 전달하는 포트

ConfigMap & Secret

환경 설정과 민감 정보를 코드에서 분리한다.

# ConfigMap — 일반 설정
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  SPRING_PROFILES_ACTIVE: "production"
  LOG_LEVEL: "INFO"
---
# Secret — 민감 정보 (Base64 인코딩)
apiVersion: v1
kind: Secret
metadata:
  name: db-secret
type: Opaque
data:
  DB_PASSWORD: cGFzc3dvcmQxMjM=    # echo -n 'password123' | base64

Pod에서 참조:

spec:
  containers:
    - name: app
      image: my-app:1.0
      envFrom:
        - configMapRef:
            name: app-config
        - secretRef:
            name: db-secret

⚠️ Secret은 Base64일 뿐 암호화가 아니다. 프로덕션에서는 Sealed Secrets, Vault 등 별도 암호화 솔루션을 사용해야 한다.

자주 쓰는 kubectl 명령어

# 클러스터 정보
kubectl cluster-info
kubectl get nodes

# Pod 관리
kubectl get pods                          # Pod 목록
kubectl get pods -o wide                  # 노드 배치 정보 포함
kubectl describe pod            # Pod 상세 정보
kubectl logs                    # 로그 확인
kubectl logs  -f                # 실시간 로그
kubectl exec -it  -- /bin/sh    # Pod에 접속

# Deployment 관리
kubectl apply -f deployment.yaml          # 리소스 생성/업데이트
kubectl get deployments
kubectl scale deployment/my-app --replicas=5  # 스케일링
kubectl delete deployment my-app

# 디버깅
kubectl get events --sort-by='.lastTimestamp'
kubectl top pods                          # 리소스 사용량

실전 예제: Spring Boot 앱 k8s 배포

Docker 포스트에서 만든 Spring Boot 앱을 k8s에 배포해 보자. 하나의 파일에 Deployment와 Service를 함께 정의한다.

k8s-deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: spring-app
  labels:
    app: spring-app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: spring-app
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1           # 업데이트 시 최대 1개 추가 Pod
      maxUnavailable: 0     # 업데이트 중 사용 불가 Pod 0개 → 무중단
  template:
    metadata:
      labels:
        app: spring-app
    spec:
      containers:
        - name: spring-app
          image: my-registry/spring-app:1.0
          ports:
            - containerPort: 8080
          resources:
            requests:
              cpu: "250m"
              memory: "512Mi"
            limits:
              cpu: "1000m"
              memory: "1Gi"
          livenessProbe:
            httpGet:
              path: /actuator/health
              port: 8080
            initialDelaySeconds: 30
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /actuator/health/readiness
              port: 8080
            initialDelaySeconds: 10
            periodSeconds: 5
          envFrom:
            - configMapRef:
                name: app-config
            - secretRef:
                name: db-secret
---
apiVersion: v1
kind: Service
metadata:
  name: spring-app-service
spec:
  type: LoadBalancer
  selector:
    app: spring-app
  ports:
    - port: 80
      targetPort: 8080
      protocol: TCP

핵심 포인트:

livenessProbe: 컨테이너가 살아있는지 확인. 실패하면 재시작한다.
readinessProbe: 트래픽을 받을 준비가 되었는지 확인. 실패하면 Service에서 제외한다.
resources: 리소스 요청(requests)과 제한(limits)을 반드시 설정해야 Scheduler가 올바르게 배치한다.
maxUnavailable: 0: 업데이트 중에도 항상 3개 Pod가 가용하므로 무중단 배포가 보장된다.

배포 실행

# ConfigMap, Secret 먼저 생성
kubectl apply -f configmap.yaml
kubectl apply -f secret.yaml

# Deployment + Service 배포
kubectl apply -f k8s-deployment.yaml

# 확인
kubectl get all -l app=spring-app
# NAME                              READY   STATUS    RESTARTS   AGE
# pod/spring-app-6d4f8b7c9-abc12   1/1     Running   0          30s
# pod/spring-app-6d4f8b7c9-def34   1/1     Running   0          30s
# pod/spring-app-6d4f8b7c9-ghi56   1/1     Running   0          30s
#
# NAME                         TYPE           CLUSTER-IP      EXTERNAL-IP     PORT(S)
# service/spring-app-service   LoadBalancer   10.96.123.45    34.56.78.90     80:31234/TCP
#
# NAME                         READY   UP-TO-DATE   AVAILABLE   AGE
# deployment.apps/spring-app   3/3     3            3           30s

Docker Compose vs Kubernetes

기준	Docker Compose	Kubernetes
용도	로컬 개발, 단일 호스트	프로덕션, 멀티 호스트
스케일링	`docker-compose up --scale app=3` (수동)	HPA로 자동 스케일링
Self-healing	없음 (restart 정책만 존재)	Pod 자동 재시작 + 재배치
네트워킹	단일 호스트 내 브리지	클러스터 전체 Service Discovery
배포 전략	없음 (stop → start)	Rolling Update, Blue-Green, Canary
설정 관리	`.env` 파일	ConfigMap, Secret
학습 곡선	낮음	높음
설정 파일	`docker-compose.yml`	여러 YAML 매니페스트

이 둘은 경쟁 관계가 아니라 보완 관계다. 로컬에서는 Docker Compose로 빠르게 개발하고, 프로덕션에서는 k8s로 운영하는 것이 일반적인 패턴이다.

언제 k8s를 쓰고, 언제 과한가

k8s가 적합한 경우

마이크로서비스 아키텍처로 서비스가 5개 이상
트래픽 변동이 크고 오토스케일링이 필요
무중단 배포(Rolling Update, Canary)가 필수
멀티 클라우드 또는 하이브리드 클라우드 환경
팀 규모가 크고 여러 서비스를 독립적으로 배포

k8s가 과한 경우

모놀리식 앱 하나를 운영하는 경우
팀원이 1-3명이고 운영 인력이 부족한 경우
트래픽이 예측 가능하고 안정적인 경우
단순히 “이력서에 넣고 싶어서” (가장 흔한 이유…)

대안 선택지:

단일 서버: Docker Compose + Nginx
서버리스: AWS Lambda, Google Cloud Run
매니지드 PaaS: AWS ECS, Google App Engine
간소화된 k8s: k3s (경량 Kubernetes)

k8s를 도입하기 전에 “이 복잡도를 감당할 운영 역량이 있는가?”를 먼저 물어보자. 도구가 문제를 해결하는 것이 아니라, 도구를 운영할 수 있는 팀이 문제를 해결한다.

마무리

Kubernetes는 단순한 배포 도구가 아니라 선언적 인프라 관리 플랫폼이다. “컨테이너 3개를 유지하라”고 선언하면 k8s가 알아서 상태를 맞춰주는 것이 핵심 철학이다.

이번 포스트에서 다룬 내용을 정리하면:

Pod — 배포의 최소 단위, 직접 생성하지 않는다
Deployment — Pod의 Desired State를 선언하고 Rolling Update를 관리
Service — Pod에 안정적인 네트워크 접근을 제공
ConfigMap/Secret — 설정과 민감 정보를 코드에서 분리

다음 포스트에서는 Helm Chart를 활용한 패키지 관리와 Ingress를 통한 외부 라우팅을 다룰 예정이다.

MySQL vs PostgreSQL — 백엔드 개발자가 알아야 할 차이

doodoo3804@gmail.com (DoYoon Kim) — Wed, 01 Apr 2026 00:00:00 +0900

라이선스와 아키텍처 차이

라이선스

MySQL은 Oracle이 소유하고 있으며 듀얼 라이선스 정책을 따른다. Community Edition은 GPL v2로 무료이지만, 상용 라이선스가 별도로 존재한다. Oracle의 방향성에 따라 기능이 제한될 수 있다는 우려가 있어 MariaDB로 포크된 역사가 있다.

PostgreSQL은 PostgreSQL License(BSD 계열)로, 사실상 제한 없이 자유롭게 사용할 수 있다. 상용 제품에 포함해도 라이선스 비용이 없다. 기업 입장에서 법적 리스크가 가장 낮은 선택지다.

아키텍처

MySQL은 멀티스레드 기반이다. 하나의 프로세스 안에서 각 커넥션이 스레드로 처리된다. 메모리 사용 효율이 높고 커넥션 생성 비용이 낮다.

PostgreSQL은 멀티프로세스 기반이다. 각 커넥션마다 별도의 프로세스(backend process)가 생성된다. 프로세스 간 격리가 강해 안정적이지만, 커넥션 수가 많아지면 메모리 소모가 크다. 이 때문에 PostgreSQL에서는 PgBouncer 같은 커넥션 풀러를 사용하는 것이 일반적이다.

# PostgreSQL 커넥션 풀러 — PgBouncer 설정 예시
[databases]
mydb = host=127.0.0.1 port=5432 dbname=mydb

[pgbouncer]
listen_port = 6432
pool_mode = transaction
max_client_conn = 1000
default_pool_size = 20

JSON 지원 비교

두 데이터베이스 모두 JSON을 지원하지만, 깊이와 완성도에 차이가 있다.

MySQL의 JSON

MySQL 5.7부터 JSON 타입을 지원한다. 내부적으로 바이너리 포맷으로 저장한다.

CREATE TABLE products (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    name VARCHAR(255),
    attributes JSON
);

INSERT INTO products (name, attributes)
VALUES ('노트북', '{"brand": "Samsung", "ram": 16, "storage": "512GB"}');

-- JSON 필드 조회
SELECT name, attributes->>'$.brand' AS brand
FROM products
WHERE attributes->>'$.ram' = '16';

-- MySQL 8.0+: Multi-Valued Index
CREATE INDEX idx_tags ON products ((CAST(attributes->'$.tags' AS CHAR(50) ARRAY)));

PostgreSQL의 JSON

PostgreSQL은 JSON과 JSONB 두 가지 타입을 제공한다. JSONB는 바이너리 포맷으로 저장하며, 인덱싱과 연산 성능이 뛰어나다.

CREATE TABLE products (
    id BIGSERIAL PRIMARY KEY,
    name VARCHAR(255),
    attributes JSONB
);

INSERT INTO products (name, attributes)
VALUES ('노트북', '{"brand": "Samsung", "ram": 16, "tags": ["ultrabook", "2024"]}');

-- JSONB 연산자
SELECT name, attributes->>'brand' AS brand
FROM products
WHERE attributes @> '{"ram": 16}';    -- 포함 연산자

-- GIN 인덱스로 JSONB 전체 필드 인덱싱
CREATE INDEX idx_attributes ON products USING GIN (attributes);

-- JSONB 배열 요소 검색
SELECT * FROM products
WHERE attributes->'tags' ? 'ultrabook';

PostgreSQL의 JSONB가 @>, ?, ?| 같은 연산자와 GIN 인덱스를 제공하기 때문에 JSON 활용이 빈번한 프로젝트에서는 PostgreSQL이 유리하다.

Full-Text Search 비교

MySQL

MySQL은 InnoDB 엔진에서 FULLTEXT 인덱스를 지원한다.

CREATE TABLE articles (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    title VARCHAR(255),
    body TEXT,
    FULLTEXT INDEX ft_idx (title, body)
) ENGINE=InnoDB;

-- 자연어 검색
SELECT * FROM articles
WHERE MATCH(title, body) AGAINST('Redis 캐시 전략' IN NATURAL LANGUAGE MODE);

-- 불린 모드
SELECT * FROM articles
WHERE MATCH(title, body) AGAINST('+Redis -Memcached' IN BOOLEAN MODE);

한국어/중국어/일본어 등 CJK 문자는 기본적으로 N-gram 파서(ngram)를 설정해야 제대로 동작한다.

PostgreSQL

PostgreSQL은 tsvector와 tsquery를 이용한 강력한 Full-Text Search를 내장하고 있다.

CREATE TABLE articles (
    id BIGSERIAL PRIMARY KEY,
    title VARCHAR(255),
    body TEXT,
    search_vector TSVECTOR
);

-- tsvector 컬럼 자동 업데이트 트리거
CREATE FUNCTION update_search_vector() RETURNS TRIGGER AS $$
BEGIN
    NEW.search_vector := to_tsvector('simple', COALESCE(NEW.title, '') || ' ' || COALESCE(NEW.body, ''));
    RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER trg_search_vector
    BEFORE INSERT OR UPDATE ON articles
    FOR EACH ROW EXECUTE FUNCTION update_search_vector();

-- GIN 인덱스
CREATE INDEX idx_search ON articles USING GIN (search_vector);

-- 검색
SELECT title, ts_rank(search_vector, query) AS rank
FROM articles, to_tsquery('simple', 'Redis & 캐시') query
WHERE search_vector @@ query
ORDER BY rank DESC;

PostgreSQL의 FTS는 랭킹, 하이라이팅, 사전(dictionary) 커스터마이징 등 더 세밀한 제어가 가능하다. 다만 한국어 형태소 분석을 위해서는 별도 확장(예: textsearch_ko)이 필요하다.

트랜잭션과 MVCC 구현 차이

두 데이터베이스 모두 MVCC(Multi-Version Concurrency Control)를 지원하지만 구현 방식이 다르다.

MySQL (InnoDB)

InnoDB는 Undo Log 기반 MVCC를 사용한다. 행이 수정되면 이전 버전을 Undo Log에 보관하고, 다른 트랜잭션이 이전 버전을 읽어야 할 때 Undo Log를 참조한다.

-- MySQL 기본 격리 수준: REPEATABLE READ
SHOW VARIABLES LIKE 'transaction_isolation';
-- 'REPEATABLE-READ'

-- InnoDB는 REPEATABLE READ에서도 Phantom Read를 방지한다 (Gap Lock)
START TRANSACTION;
SELECT * FROM orders WHERE amount > 1000 FOR UPDATE;
-- Gap Lock으로 범위 내 INSERT 차단
COMMIT;

MySQL의 REPEATABLE READ는 Gap Lock 덕분에 Phantom Read를 사실상 방지하지만, 이로 인해 동시성이 떨어질 수 있다.

PostgreSQL

PostgreSQL은 테이블 내부에 다중 버전을 직접 저장하는 방식이다. 수정 시 기존 행을 삭제 표시하고 새 행을 삽입한다. 이 때문에 VACUUM으로 죽은 행(dead tuple)을 주기적으로 정리해야 한다.

-- PostgreSQL 기본 격리 수준: READ COMMITTED
SHOW default_transaction_isolation;
-- 'read committed'

-- SERIALIZABLE 격리 수준 사용
BEGIN TRANSACTION ISOLATION LEVEL SERIALIZABLE;
SELECT SUM(balance) FROM accounts WHERE branch = 'gangnam';
UPDATE accounts SET balance = balance - 1000 WHERE id = 1;
COMMIT;
-- 직렬화 충돌 시 에러 발생 → 애플리케이션에서 재시도 필요

PostgreSQL의 SERIALIZABLE은 SSI(Serializable Snapshot Isolation) 알고리즘을 사용하며, Lock 대신 충돌 감지 방식이라 동시성이 높다.

성능 비교

MySQL이 유리한 경우

단순 읽기 중심 워크로드: 단순 SELECT, 기본 키 조회가 많은 서비스
높은 커넥션 수: 멀티스레드 구조로 많은 동시 접속 처리에 유리
복제(Replication): 읽기 복제본 구성이 간단하고 안정적

-- MySQL: 기본 키 조회는 매우 빠르다
SELECT * FROM users WHERE id = 42;
-- Clustered Index 구조로 PK 조회 = 데이터 직접 접근

PostgreSQL이 유리한 경우

복잡한 쿼리: 서브쿼리, CTE, 윈도우 함수 등 복잡한 분석 쿼리
쓰기 중심 워크로드: MVCC 구현 특성상 쓰기 동시성이 높음
확장성: 사용자 정의 타입, 함수, 연산자 등 확장이 자유로움

-- PostgreSQL: CTE + 윈도우 함수 조합
WITH monthly_sales AS (
    SELECT
        DATE_TRUNC('month', order_date) AS month,
        category,
        SUM(amount) AS total
    FROM orders
    GROUP BY 1, 2
)
SELECT
    month,
    category,
    total,
    LAG(total) OVER (PARTITION BY category ORDER BY month) AS prev_month,
    ROUND((total - LAG(total) OVER (PARTITION BY category ORDER BY month))
        / LAG(total) OVER (PARTITION BY category ORDER BY month) * 100, 2) AS growth_pct
FROM monthly_sales
ORDER BY category, month;

실무 선택 기준

기준	MySQL	PostgreSQL
단순 CRUD 서비스	적합	적합
복잡한 분석 쿼리	보통	우수
JSON 활용 비중 높음	보통	우수
지리 데이터(GIS)	제한적	PostGIS로 우수
레거시/기존 인프라	MySQL이 이미 있다면 유지	—
라이선스 민감	주의 필요	자유
커뮤니티/생태계	매우 큼	크고 빠르게 성장 중

실무에서의 판단 기준: 기존에 MySQL 인프라가 갖춰져 있고 단순 CRUD가 대부분이라면 MySQL을 유지한다. 새 프로젝트를 시작하고, 복잡한 쿼리나 JSON 활용이 예상되며, 라이선스에 민감하다면 PostgreSQL을 선택한다.

Spring Boot 설정

MySQL 설정

// build.gradle
dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    runtimeOnly 'com.mysql:mysql-connector-j'
}

# application.yml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/mydb?useSSL=false&serverTimezone=Asia/Seoul&characterEncoding=UTF-8
    username: root
    password: password
    driver-class-name: com.mysql.cj.jdbc.Driver
  jpa:
    hibernate:
      ddl-auto: validate
    properties:
      hibernate:
        dialect: org.hibernate.dialect.MySQLDialect

PostgreSQL 설정

// build.gradle
dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    runtimeOnly 'org.postgresql:postgresql'
}

# application.yml
spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/mydb
    username: postgres
    password: password
    driver-class-name: org.postgresql.Driver
  jpa:
    hibernate:
      ddl-auto: validate
    properties:
      hibernate:
        dialect: org.hibernate.dialect.PostgreSQLDialect

정리

MySQL과 PostgreSQL은 모두 검증된 RDBMS이며, “어느 것이 더 좋다”는 단정은 무의미하다. 중요한 것은 프로젝트의 요구사항, 팀의 숙련도, 기존 인프라를 종합적으로 고려해 선택하는 것이다. 최근 업계 트렌드로는 PostgreSQL의 채택이 빠르게 늘고 있지만, MySQL이 여전히 거대한 생태계를 가지고 있다는 점도 무시할 수 없다.

Data Representation - Integer

doodoo3804@gmail.com (DoYoon Kim) — Wed, 01 Apr 2026 00:00:00 +0900

Integers, or whole number from elemental mathematics, are the most common and fundamental numbers used in the computers. It’s represented as fixed-point numbers, contrast to floating-point numbers in the machine. Today we are going to learn a whole bunch of way to encode it.

There are mainly two properties to make a integer representation different:

Size, of the number of bits used. usually the power of 2. e.g. 8-bit, 16-bit, 32-bit, 64-bit.
Signed or unsigned. there are also multiple schemas to encode a signed integers.

We are also gonna use the below terminologies throughout the post:

MSB: Most Significant Bit
LSB: Least Significant Bit

Prerequisite - `printf` Recap

We will quickly recap the integers subset of usages of printf. Basically, we used format specifier to interpolate values into strings:

Format Specifier

%[flags][width][.precision][length]specifier

specifier
- d, i : signed decimal
- u : unsigned decimal
- c : char
- p: pointer addr
- x / X : lower/upper unsigned hex
length
- l : long (at least 32)
- ll : long long (at least 64)
- h : short (usually 16)
- hh : short short (usually 8)

using namespace std;
int main()  {
  cout << "Size of int = "<< sizeof(int) << endl;
  cout << "Size of long = " << sizeof(long) << endl;
  cout << "Size of long long = " << sizeof(long long);
}
Output in 32 bit gcc compiler: 4 4 8
Output in 64 bit gcc compiler: 4 8 8

`inttypes.h` from C99

Also in cppreference.com

// signed int (d or i)
#define PRId8     "hhd"
#define PRId16    "hd"
#define PRId32    "ld"
#define PRId64    "lld"

// unsigned int (u)
#define PRIu8     "hhu"
#define PRIu16    "hu"
#define PRIu32    "u"
#define PRIu64    "llu"

// unsigned hex
#define PRIx8     "hhx"
#define PRIx16    "hx"
#define PRIx32    "x"
#define PRIx64    "llx"

// uintptr_t (64 bit machine word len)
#define PRIxPTR   "llx"

Unsigned Integers

The conversion between unsigned integers and binaries are trivial. Here, we can represent 8 bits (i.e. a byte) as a hex pair, e.g. 255 == 0xff == 0b11111111.

#include     // uintN_t
#include   // PRI macros

uint8_t u8 = 255;
printf("0x%02" PRIx8 "\n", u8); // 0xff
printf(  "%"   PRId8 "\n", u8); // 255

Signed Integers

Signed integers are more complicated. We need to cut those bits to halves to represent both positive and negative integers somehow.

There are four well-known schemas to encode it, according to signed number representation of wikipedia.

Sign magnitude 원码

It’s also called “sign and magnitude”. From the name we can see how straightforward it is: it’s basically put one bit (often the MSB) as the sign bit to represent sign and the remaining bits indicating the magnitude (or absolute value), e.g.

  binary   | sign-magn |  unsigned
-----------|-----------|------------
0 000 0000 |    +0     |     0
0 111 1111 |    127    |    127
...
1 000 0000 |    -0     |    128
1 111 1111 |   -127    |    255

It was used in early computer (IBM 7090) and now mainly used in the significand part in floating-point number

Pros:

simple and natural for human

Cons:

2 ways to represent zeros (+0 and -0)
not as good for machine
- add/sub/cmp require knowing the sign
  - complicate CPU ALU design; potentially more cycles

Ones’ complement 반码

It forms a negative integer by applying a bitwise NOT i.e. complement of its positive counterpart.

  binary   |  1s comp  |  unsigned
-----------|-----------|------------
0000 0000  |     0     |     0
0000 0001  |     1     |     1
...
0111 1111  |    127    |    127
1000 0000  |   -127    |    128
...
1111 1110  |    -1     |    254
1111 1111  |    -0     |    255

N.B. MSB can still be signified by MSB.

It’s referred to as ones’ complement because the negative can be formed by subtracting the positive from ones: 1111 1111 (-0)

  1111 1111       -0
- 0111 1111       127
---------------------
  1000 0000      -127

The benefits of the complement nature is that adding becomes simple, except we need to do an end-around carry to add resulting carry back to get the correct result.

  0111 1111       127
+ 1000 0001      -126
---------------------
1 0000 0000        0
          1       +1     <- add carry "1" back
---------------------
  0000 0001        1

Pros:

Arithmetics on machine are fast.

Cons:

still 2 zeros!

Two’s complement 보码

Most of the current architecture adopted this, including x86, MIPS, ARM, etc. It differs from one’s complement by one.

  binary   |  2s comp  |  unsigned
-----------|-----------|------------
0000 0000  |     0     |     0
0000 0001  |     1     |     1
...
0111 1111  |    127    |    127
1000 0000  |   -128    |    128
1000 0001  |   -127    |    129
...
1111 1110  |    -2     |    254
1111 1111  |    -1     |    255

N.B. MSB can still be signified by MSB.

It’s referred to as two’s complement because the negative can be formed by subtracting the positive from 2 ** N (congruent to 0000 0000 (+0)), where N is the number of bits.

E.g., for a uint8_t, the sum of any number and its two’s complement would be 256 (1 0000 0000):

1 0000 0000       256  = 2 ** 8
- 0111 1111       127
---------------------
  1000 0001      -127

Because of this, arithmetics become really easier, for any number x e.g. 127 we can get its two’s complement by:

~x => 1000 0000 bitwise NOT (like ones’ complement)
+1 => 1000 0001 add 1 (the one differed from ones’ complement)

Pros:

fast machine arithmetics
only 1 zero!
the minimal negative is -128

Cons:

asymmetric range: -128 to 127 for 8-bit

Offset binary 이동码

It’s also called excess-K or biased representation, where K is the biasing value (the new 0), e.g. in excess-128:

  binary   |  K = 128  |  unsigned
-----------|-----------|------------
0000 0000  |   -128(-K)|     0
0000 0001  |   -127    |     1
...
0111 1111  |    -1     |    127
1000 0000  |     0     |    128  (K)
1000 0001  |     1     |    129
...
1111 1111  |    127    |    255

It’s now mainly used for the exponent part of floating-point number.

Type Conversion & `printf`

This might be a little bit off topic, but I want to note down what I observed from experimenting. Basically, printf would not perform an implicit type conversion but merely interpret the bits arrangement of your arguments as you told it.

UB! stands for undefined behaviors

uint8_t u8 = 0b10000000; // 128
 int8_t s8 = 0b10000000; // -128

printf("%"PRIu8 "\n", u8);          // 128
printf("%"PRId8 "\n", u8);          // 128
printf("%"PRId8 "\n", (int8_t)u8);  // -128

printf("%"PRId8 "\n", s8);          // -128
printf("%"PRIu8 "\n", s8);          // 4294967168
printf("%"PRId8 "\n", (uint8_t)s8); // 128

printf("%"PRIxPTR "\n", s8);             // ffffff80
printf("%"PRIxPTR "\n", (uintptr_t)s8);  // ffffffffffffff80

Char & ASCII

Traditionally, char is represented in the computer as 8 bits as well. And really, ASCII is only defined between 0 and 127 and require 7 bits. (8-bit Extended ASCII is not quite well popularized and supported.)

It’s more complicated in extension such as Unicode nowadays, but we’ll ignore it for future posts dedicated for char and string representation.

So how is a char different with a byte?

Well, the answer is whether a char is a signed char (backed by int8_t) or a unsigned char (backed by uint8_t) is… implementation-defined. And most systems made it signed since most types (e.g. int) were signed by default.

N.B. int is standard-defined to be equivalent to signed int. This is not the case of char.

That’s why you often see such typedef such as:

typedef unsigned char Byte_t;
typedef uint8_t byte_t;

to emphasize the nature of byte should be just plain, unsigned, bits.

References

부동소수점(Floating Point) 표현 — IEEE 754 완전 정복

doodoo3804@gmail.com (DoYoon Kim) — Wed, 01 Apr 2026 00:00:00 +0900

이전 글(Data Representation - Integer)에서 정수의 표현 방식을 알아보았다. 정수는 fixed-point(고정소수점)으로 표현된다고 했는데, 이번에는 실수를 표현하는 방식인 부동소수점(floating-point) 을 다룬다.

핵심 주제는 현대 거의 모든 하드웨어가 채택한 IEEE 754 표준이다.

왜 부동소수점인가?

고정소수점(fixed-point)은 소수점의 위치가 고정되어 있다. 예를 들어 32비트 중 16비트를 정수부, 16비트를 소수부에 할당하면 표현 가능한 범위가 매우 좁다.

부동소수점은 소수점이 떠다닌다(float). 과학적 표기법(scientific notation)과 같은 원리로, 극도로 큰 수와 극도로 작은 수를 같은 비트 수로 표현할 수 있다.

과학적 표기법:  -2.625 = -1.0101 × 2^1

                 ↑ sign   ↑ significand  ↑ exponent

IEEE 754 구조

IEEE 754는 부동소수점 수를 세 부분으로 나눈다:

 [Sign] [Exponent (biased)] [Mantissa (fraction)]

형식	총 비트	Sign	Exponent	Mantissa	Bias
단정도 (Single, `float`)	32	1	8	23	127
배정도 (Double, `double`)	64	1	11	52	1023

각 필드의 의미

Sign bit (부호 비트) — 0이면 양수, 1이면 음수
Exponent (지수) — biased 표현 사용. 실제 지수 = 저장된 값 - Bias
Mantissa (가수, fraction) — 정규화된 이진수의 소수 부분. 앞의 1.은 implicit leading bit 로 생략된다 (정규화된 수의 경우)

즉, 값은 다음 공식으로 계산된다:

(-1)^sign × 1.mantissa × 2^(exponent - bias)

10진수 → IEEE 754 변환 예제

예제 1: `-6.75`를 단정도(32-bit)로 변환

Step 1. 부호 결정

음수이므로 Sign = 1

Step 2. 절대값을 이진수로 변환

6   = 110 (2진수)
0.75 → 0.75 × 2 = 1.5  → 1
       0.5  × 2 = 1.0  → 1
∴ 0.75 = .11

따라서 6.75 = 110.11

Step 3. 정규화 (Normalize)

110.11 = 1.1011 × 2^2

Step 4. Exponent 계산 (biased)

실제 지수 = 2
biased exponent = 2 + 127 = 129 = 1000 0001

Step 5. Mantissa 추출

1.1011에서 leading 1.을 제거 → 1011

23비트로 패딩: 1011 0000 0000 0000 0000 000

최종 결과:

Sign | Exponent  | Mantissa
  1  | 1000 0001 | 1011 0000 0000 0000 0000 000

Hex: 0xC0D80000

예제 2: IEEE 754 비트 → 10진수 역변환

0 | 0111 1110 | 1000 0000 0000 0000 0000 000

Sign = 0 → 양수
Exponent = 0111 1110 = 126 → 실제 지수 = 126 - 127 = -1
Mantissa = 1.1 (implicit leading 1 복원)
값 = +1.1 × 2^(-1) = 0.11 (2진) = 0.75

C 코드로 확인하기

#include 
#include 
#include 

void print_float_bits(float f) {
    uint32_t bits;
    memcpy(&bits, &f, sizeof(bits));

    uint32_t sign     = (bits >> 31) & 1;
    uint32_t exponent = (bits >> 23) & 0xFF;
    uint32_t mantissa = bits & 0x7FFFFF;

    printf("값: %f\n", f);
    printf("  Sign:     %u\n", sign);
    printf("  Exponent: %u (biased), %d (실제)\n", exponent, (int)exponent - 127);
    printf("  Mantissa: 0x%06X\n", mantissa);
    printf("  Hex:      0x%08X\n", bits);
    printf("\n");
}

int main(void) {
    print_float_bits(-6.75f);   // 예제 1 검증
    print_float_bits(0.75f);    // 예제 2 검증
    print_float_bits(0.1f);     // 무한소수 케이스
    return 0;
}

출력:

값: -6.750000
  Sign:     1
  Exponent: 129 (biased), 2 (실제)
  Mantissa: 0x580000
  Hex:      0xC0D80000

값: 0.750000
  Sign:     0
  Exponent: 126 (biased), -1 (실제)
  Mantissa: 0x400000
  Hex:      0x3F400000

값: 0.100000
  Sign:     0
  Exponent: 123 (biased), -4 (실제)
  Mantissa: 0x4CCCCD
  Hex:      0x3DCCCCCD

0.1의 mantissa가 0x4CCCCD인 것을 볼 수 있다. 0.1은 이진수로 0.0001100110011...로 무한 반복소수이기 때문에, 23비트에서 잘려 나가면서 오차가 발생한다.

특수 값 (Special Values)

IEEE 754는 exponent와 mantissa의 특정 조합으로 특수한 값을 표현한다.

  Exponent   |  Mantissa  |  의미
-------------|------------|------------------
  0000 0000  |  000...0   |  ±0 (부호 비트에 따라)
  0000 0000  |  ≠ 0       |  비정규화수 (denormalized)
  1111 1111  |  000...0   |  ±Infinity
  1111 1111  |  ≠ 0       |  NaN (Not a Number)
  그 외       |  any       |  정규화수 (normalized)

+0과 -0

IEEE 754는 양의 0과 음의 0을 구분한다. 대부분의 비교 연산에서 +0 == -0은 true지만, 비트 레벨에서는 다르다.

float pos_zero = 0.0f;
float neg_zero = -0.0f;

printf("%d\n", pos_zero == neg_zero); // 1 (true)
printf("%f\n", 1.0f / pos_zero);     // inf
printf("%f\n", 1.0f / neg_zero);     // -inf  ← 부호가 다르다!

Infinity

오버플로우 또는 0으로 나눌 때 발생한다. 산술 연산에서 전파된다:

float inf = 1.0f / 0.0f;     // +inf
float neg_inf = -1.0f / 0.0f; // -inf

printf("%f\n", inf + 1.0f);   // inf
printf("%f\n", inf + neg_inf); // nan (inf - inf는 정의 불가)

NaN (Not a Number)

정의 불가한 연산의 결과다. NaN은 자기 자신과도 같지 않다 — 이것이 NaN 탐지의 핵심이다.

#include 

float nan_val = 0.0f / 0.0f;

printf("%d\n", nan_val == nan_val);  // 0 (false!)
printf("%d\n", isnan(nan_val));      // 1 (true)

Java에서도 동일한 동작을 한다:

double nan = Double.NaN;

System.out.println(nan == nan);           // false
System.out.println(Double.isNaN(nan));    // true

비정규화수 (Denormalized / Subnormal Numbers)

Exponent가 전부 0이고 Mantissa가 0이 아닌 경우, implicit leading bit이 0 이 된다. 이를 통해 0에 매우 가까운 아주 작은 수를 표현한다.

값 = (-1)^sign × 0.mantissa × 2^(1 - bias)

단정도 기준으로 표현 가능한 가장 작은 양수:

정규화: 1.0 × 2^(-126) ≈ 1.175e-38
비정규화: 0.000...1 × 2^(-126) ≈ 1.401e-45

비정규화수 덕분에 0으로의 gradual underflow 가 가능하다.

정밀도 한계와 부동소수점 함정

0.1 + 0.2 != 0.3

부동소수점의 가장 유명한 함정이다.

System.out.println(0.1 + 0.2);           // 0.30000000000000004
System.out.println(0.1 + 0.2 == 0.3);    // false

printf("%.20f\n", 0.1 + 0.2);  // 0.30000000000000004441
printf("%.20f\n", 0.3);        // 0.29999999999999998890

원인: 0.1, 0.2, 0.3 모두 이진수로 무한반복소수이다. 유한 비트로 표현하면서 각각 미세한 오차가 발생하고, 이 오차들이 합산되면서 결과가 달라진다.

큰 수와 작은 수의 덧셈

float big   = 16777216.0f;  // 2^24, 정확히 표현 가능
float small = 1.0f;

System.out.println(big + small == big);  // true!

단정도의 mantissa가 23비트이므로 2^24에 1을 더해도 mantissa에 담을 수 없어 반올림되어 사라진다. 이를 absorption 현상이라 한다.

결합법칙이 성립하지 않는다

double a = 1e15, b = -1e15, c = 1.0;
System.out.println((a + b) + c);  // 1.0
System.out.println(a + (b + c));  // 0.0  ← 다르다!

부동소수점 연산은 (a + b) + c ≠ a + (b + c)일 수 있다. 이것이 수치 계산 라이브러리가 덧셈 순서까지 신경 쓰는 이유다 (Kahan summation 등).

정밀도 비교: epsilon 방식

부동소수점 비교는 == 대신 epsilon 비교를 사용해야 한다:

private static final double EPSILON = 1e-10;

public static boolean nearlyEqual(double a, double b) {
    return Math.abs(a - b) < EPSILON;
}

단, 값의 크기에 따라 적절한 epsilon이 달라지므로, 더 정교한 비교가 필요할 때는 relative epsilon 또는 ULP(Unit in the Last Place) 기반 비교를 사용한다:

// Java의 Math.ulp 활용
public static boolean nearlyEqual(double a, double b) {
    return Math.abs(a - b) <= Math.max(Math.ulp(a), Math.ulp(b));
}

단정도 vs 배정도 비교

속성	`float` (32-bit)	`double` (64-bit)
Mantissa 비트	23	52
유효 십진 자릿수	~7자리	~15-16자리
최대값	~3.4 × 10^38	~1.8 × 10^308
최소 정규화 양수	~1.2 × 10^-38	~2.2 × 10^-308
Exponent 범위	-126 ~ +127	-1022 ~ +1023

백엔드 개발자를 위한 실무 가이드

DB: FLOAT vs DECIMAL

-- FLOAT/DOUBLE: IEEE 754 기반, 근사값 저장
CREATE TABLE products (
    price FLOAT  -- 절대 하지 마세요!
);

-- DECIMAL: 고정소수점, 정확한 값 저장
CREATE TABLE products (
    price DECIMAL(10, 2)  -- 소수점 이하 2자리까지 정확
);

금액(money)은 절대 FLOAT/DOUBLE로 저장하지 않는다. 반올림 오차가 누적되면 회계 장부에서 수 원~수십 원의 차이가 발생한다.

FLOAT/DOUBLE — 과학 계산, 통계, 좌표(위도/경도) 등 근사값이 허용되는 경우에 사용
DECIMAL — 금액, 세율, 환율 등 정확한 값이 필요한 경우에 사용

Java: `double` vs `BigDecimal`

// 절대 이렇게 하면 안 된다
double price = 0.1;
double quantity = 3;
System.out.println(price * quantity);  // 0.30000000000000004

// BigDecimal 사용 (문자열 생성자 필수!)
BigDecimal price = new BigDecimal("0.1");
BigDecimal quantity = new BigDecimal("3");
System.out.println(price.multiply(quantity));  // 0.3

주의: new BigDecimal(0.1)은 이미 오차가 있는 double 값을 그대로 가져오므로 반드시 문자열 생성자 new BigDecimal("0.1")을 사용해야 한다.

System.out.println(new BigDecimal(0.1));
// 0.1000000000000000055511151231257827021181583404541015625

System.out.println(new BigDecimal("0.1"));
// 0.1

정리: 타입 선택 가이드

금액 계산       → BigDecimal (Java), DECIMAL (DB)
과학/통계 계산  → double
ML/그래픽스     → float (메모리/속도 중시)
좌표(위경도)    → double (FLOAT도 가능하나 정밀도 주의)

마무리

IEEE 754는 한정된 비트로 실수를 표현하기 위한 정교한 타협이다. 대부분의 경우 잘 작동하지만, 정밀도의 한계를 이해하지 못하면 디버깅하기 어려운 버그를 만들게 된다.

핵심 정리:

구조: Sign(1) + Exponent(biased) + Mantissa(implicit leading 1)
특수 값: ±0, ±Infinity, NaN — 각각 고유한 비트 패턴
함정: 0.1 + 0.2 != 0.3, absorption, 결합법칙 깨짐
실무 원칙: 돈은 BigDecimal/DECIMAL, 비교는 epsilon 방식

다음 글에서는 문자(Character)와 문자열(String) 인코딩 — ASCII, Unicode, UTF-8 — 을 다룰 예정이다.

References

Trie 자료구조 — 원리와 구현

doodoo3804@gmail.com (DoYoon Kim) — Wed, 01 Apr 2026 00:00:00 +0900

Trie란

검색 트리의 일종으로, 문자열을 저장하고 탐색하는데 효율적인 자료구조이다. Trie는 문자열의 접두사(Prefix)를 이용하여 트리를 구성하므로, 특히나 문자열 검색에 유용하다. 이름은 retrieval(검색)에서 유래되었다.

예를 들어 ["apple", "app", "april", "bat", "ball"]이라는 단어들을 저장한다고 하면, 공통 접두사를 공유하는 트리 구조가 만들어진다.

        (root)
       /      \
      a         b
      |         |
      p         a
     / \        |  \
    p   r       t   l
    |   |           |
    l   i           l
    |   |
    e   l

Trie의 특징

각 노드는 하나의 문자를 저장한다
루트 노드는 빈 문자열을 나타낸다
각 노드는 해당 노드까지의 문자열(prefix)을 나타내며, 단어의 끝을 표시하는 플래그(isEnd)를 가진다
자식 노드는 해당 문자 다음에 나타날 수 있는 문자를 저장하는 데 사용된다

시간 복잡도

연산	시간 복잡도
삽입	O(L)
검색	O(L)
접두사 검색	O(L)
삭제	O(L)

여기서 L은 문자열의 길이이다. HashMap으로 검색하면 O(L)이지만 접두사 기반 검색은 불가능하다. Trie는 접두사 검색까지 O(L)에 처리할 수 있다는 점이 핵심 장점이다.

공간 복잡도

최악의 경우 O(ALPHABET_SIZE × L × N)으로, N은 저장된 문자열의 수이다. 공통 접두사가 많을수록 공간 효율이 좋아진다.

Trie 구현 (Java)

노드 정의

class TrieNode {
    TrieNode[] children;
    boolean isEnd;

    public TrieNode() {
        children = new TrieNode[26]; // 소문자 알파벳만 고려
        isEnd = false;
    }
}

Trie 클래스

class Trie {
    private TrieNode root;

    public Trie() {
        root = new TrieNode();
    }

    // 삽입
    public void insert(String word) {
        TrieNode node = root;
        for (char c : word.toCharArray()) {
            int idx = c - 'a';
            if (node.children[idx] == null) {
                node.children[idx] = new TrieNode();
            }
            node = node.children[idx];
        }
        node.isEnd = true;
    }

    // 검색: 해당 단어가 존재하는지 확인
    public boolean search(String word) {
        TrieNode node = findNode(word);
        return node != null && node.isEnd;
    }

    // 접두사 검색: 해당 접두사로 시작하는 단어가 있는지 확인
    public boolean startsWith(String prefix) {
        return findNode(prefix) != null;
    }

    private TrieNode findNode(String str) {
        TrieNode node = root;
        for (char c : str.toCharArray()) {
            int idx = c - 'a';
            if (node.children[idx] == null) {
                return null;
            }
            node = node.children[idx];
        }
        return node;
    }
}

사용 예시

public static void main(String[] args) {
    Trie trie = new Trie();

    trie.insert("apple");
    trie.insert("app");
    trie.insert("april");

    System.out.println(trie.search("apple"));     // true
    System.out.println(trie.search("app"));       // true
    System.out.println(trie.search("ap"));        // false (삽입하지 않음)
    System.out.println(trie.startsWith("ap"));    // true (접두사로는 존재)
    System.out.println(trie.startsWith("bat"));   // false
}

Trie에서의 삭제

삭제는 삽입/검색보다 조금 더 복잡하다. 다른 단어의 접두사인 경우 노드 자체를 삭제하면 안 되기 때문이다.

public boolean delete(String word) {
    return delete(root, word, 0);
}

private boolean delete(TrieNode node, String word, int depth) {
    if (node == null) return false;

    if (depth == word.length()) {
        if (!node.isEnd) return false;
        node.isEnd = false;
        return isEmpty(node);
    }

    int idx = word.charAt(depth) - 'a';
    boolean shouldDeleteChild = delete(node.children[idx], word, depth + 1);

    if (shouldDeleteChild) {
        node.children[idx] = null;
        return !node.isEnd && isEmpty(node);
    }

    return false;
}

private boolean isEmpty(TrieNode node) {
    for (TrieNode child : node.children) {
        if (child != null) return false;
    }
    return true;
}

삭제 로직의 핵심:

단어의 끝 노드에서 isEnd = false로 설정
해당 노드에 자식이 없으면 노드를 삭제
재귀적으로 올라가며 불필요한 노드들을 정리

HashMap을 사용한 Trie

알파벳만 다루는 경우 배열이 효율적이지만, 유니코드 등 다양한 문자를 다뤄야 할 경우 HashMap을 사용할 수 있다.

class TrieNode {
    Map<Character, TrieNode> children;
    boolean isEnd;

    public TrieNode() {
        children = new HashMap<>();
        isEnd = false;
    }
}

이 방식은 메모리를 절약할 수 있지만, 배열 방식보다 접근 속도가 느릴 수 있다.

활용 사례

Trie는 다음과 같은 상황에서 자주 사용된다:

자동 완성(Autocomplete): 입력한 접두사에 해당하는 모든 단어를 빠르게 검색
맞춤법 검사(Spell Checker): 사전에 있는 단어인지 빠르게 확인
IP 라우팅(Longest Prefix Match): 네트워크에서 가장 긴 접두사 매칭
문자열 정렬: Trie에 삽입 후 DFS로 사전순 정렬 가능

코딩 테스트 Tip

Trie 관련 대표 문제:

LeetCode 208 - Implement Trie (기본 구현)
LeetCode 211 - Design Add and Search Words Data Structure (와일드카드 검색)
LeetCode 212 - Word Search II (2D 보드에서 단어 검색, Trie + DFS)
백준 5052 - 전화번호 목록 (접두사 판별)

References

시스템 디자인: 캐싱 전략 (Cache-Aside, Write-Through, Write-Behind)

doodoo3804@gmail.com (DoYoon Kim) — Sat, 28 Mar 2026 00:00:00 +0900

캐싱이 필요한 이유

데이터베이스는 신뢰성과 일관성에 최적화된 저장소다. 하지만 모든 요청이 DB까지 도달하면 응답 지연이 발생하고, 트래픽이 몰리면 DB가 병목이 된다. 캐시는 자주 접근하는 데이터를 메모리에 올려두어 응답 속도를 높이고 DB 부하를 줄이는 역할을 한다.

대표적인 인메모리 캐시 솔루션으로 Redis가 많이 사용된다. Redis를 활용한 구체적인 캐싱 패턴과 Cache Stampede 해결책은 Redis 캐싱 전략 완전 정복에서 상세히 다룬다.

1. Cache-Aside (Lazy Loading)

가장 널리 사용되는 패턴이다. 애플리케이션이 직접 캐시를 관리한다.

동작 흐름

읽기:
캐시에서 데이터 조회 (Cache Hit?)
Hit → 캐시 데이터 반환
Miss → DB에서 조회 → 캐시에 저장 → 반환

쓰기:
DB에 데이터 쓰기
캐시에서 해당 키 삭제 (invalidate)

Spring Boot + Redis 구현 예제

@Service
@RequiredArgsConstructor
public class ProductService {

    private final ProductRepository productRepository;
    private final RedisTemplate<String, Product> redisTemplate;

    private static final String KEY_PREFIX = "product:";
    private static final Duration TTL = Duration.ofMinutes(30);

    public Product findById(Long id) {
        String key = KEY_PREFIX + id;

        // 1. 캐시 조회
        Product cached = redisTemplate.opsForValue().get(key);
        if (cached != null) {
            return cached; // Cache Hit
        }

        // 2. Cache Miss → DB 조회
        Product product = productRepository.findById(id)
                .orElseThrow(() -> new NoSuchElementException("상품이 없습니다."));

        // 3. 캐시에 저장
        redisTemplate.opsForValue().set(key, product, TTL);
        return product;
    }

    @Transactional
    public void update(Long id, ProductUpdateRequest request) {
        Product product = productRepository.findById(id)
                .orElseThrow(() -> new NoSuchElementException("상품이 없습니다."));
        product.update(request);

        // DB 업데이트 후 캐시 무효화
        redisTemplate.delete(KEY_PREFIX + id);
    }
}

장단점

장점	단점
구현이 단순하고 직관적	첫 요청은 항상 Cache Miss (Cold Start)
실제로 요청된 데이터만 캐싱	캐시 만료 전까지 stale 데이터 가능
캐시 장애 시에도 DB에서 조회 가능	애플리케이션에 캐시 로직이 침투

2. Write-Through

데이터를 쓸 때 캐시와 DB에 동시에 쓰는 패턴이다.

동작 흐름

쓰기:
1. 캐시에 데이터 저장
2. 캐시가 동기적으로 DB에도 저장
→ 두 저장소가 항상 동기화됨

읽기:
1. 항상 캐시에서 읽기 (캐시에 최신 데이터 보장)

의사 코드

public void saveProduct(Product product) {
    // 캐시와 DB에 동시 저장
    redisTemplate.opsForValue().set(
        KEY_PREFIX + product.getId(), product, TTL
    );
    productRepository.save(product);
}

public Product findById(Long id) {
    // 캐시에서 바로 조회 (항상 최신)
    Product cached = redisTemplate.opsForValue().get(KEY_PREFIX + id);
    if (cached != null) {
        return cached;
    }
    // Fallback (캐시 장애 등)
    return productRepository.findById(id).orElseThrow();
}

장단점

장점	단점
캐시 데이터 일관성 보장	쓰기 지연 증가 (캐시 + DB 모두 기다림)
읽기 시 항상 Cache Hit	사용되지 않는 데이터까지 캐싱 (메모리 낭비)

3. Write-Behind (Write-Back)

데이터를 캐시에만 먼저 쓰고, DB 반영은 비동기로 나중에 하는 패턴이다.

동작 흐름

쓰기:
1. 캐시에 데이터 저장 (즉시 반환)
2. 백그라운드에서 일정 주기/조건에 따라 DB에 반영

읽기:
1. 캐시에서 읽기

개념 코드

// 쓰기 — 캐시에만 저장하고 큐에 등록
public void saveProduct(Product product) {
    redisTemplate.opsForValue().set(KEY_PREFIX + product.getId(), product);
    writeQueue.add(product); // 비동기 처리 큐
}

// 별도 스레드/스케줄러에서 주기적으로 DB 반영
@Scheduled(fixedDelay = 5000)
public void flushToDatabase() {
    List<Product> batch = writeQueue.drain();
    if (!batch.isEmpty()) {
        productRepository.saveAll(batch);
    }
}

장단점

장점	단점
쓰기 속도가 매우 빠름	캐시 장애 시 데이터 유실 위험
DB 부하 분산 (배치 처리)	구현 복잡도 높음
짧은 시간에 같은 키를 여러 번 업데이트하면 마지막 값만 DB에 반영 (write 최적화)	데이터 일관성 보장 어려움

어떤 전략을 언제 쓸까?

시나리오	추천 전략	이유
일반적인 읽기 중심 API	Cache-Aside	구현 간단, 필요한 데이터만 캐싱
데이터 정합성이 중요한 서비스	Write-Through	캐시 = DB 동기화 보장
쓰기가 매우 빈번한 서비스 (조회수, 좋아요)	Write-Behind	쓰기 성능 극대화, 배치 처리
세션 스토어	Write-Through	세션 유실 방지
랭킹/리더보드	Write-Behind	실시간 반영은 캐시, DB는 주기적 동기화

실무에서 흔히 하는 실수

TTL 설정 누락 — 캐시가 영원히 남아 메모리가 부족해진다
Cache Stampede — 인기 키의 TTL이 동시에 만료되어 DB에 요청이 몰린다 → TTL에 랜덤 값을 추가하자 (자세한 해결 전략은 Redis 캐싱 전략 참고)
캐시 무효화 순서 실수 — 캐시 삭제 후 DB 업데이트 vs DB 업데이트 후 캐시 삭제. 후자가 안전하다
직렬화 비용 무시 — 큰 객체를 매번 JSON 직렬화/역직렬화하면 오히려 느려질 수 있다

정리

캐싱은 시스템 성능을 크게 향상시킬 수 있지만, 일관성과 복잡도 사이의 트레이드오프가 항상 존재한다. 서비스의 읽기/쓰기 비율, 데이터 정합성 요구 수준, 장애 허용 범위를 고려해서 적절한 전략을 선택하자. 대부분의 경우 Cache-Aside로 시작하고, 필요에 따라 Write-Through나 Write-Behind를 부분적으로 도입하는 것이 현실적인 접근이다.

PostgreSQL 인덱스 제대로 이해하기

doodoo3804@gmail.com (DoYoon Kim) — Wed, 25 Mar 2026 00:00:00 +0900

인덱스가 왜 필요한가

100만 건의 주문 데이터에서 특정 사용자의 주문을 찾는다고 하자.

SELECT * FROM orders WHERE user_id = 42;

인덱스가 없으면 PostgreSQL은 Sequential Scan — 테이블의 모든 행을 처음부터 끝까지 읽는다. 행이 100만 개라면 100만 번 비교한다. 인덱스가 있으면 Index Scan으로 필요한 행만 빠르게 찾을 수 있다. 책의 목차와 같은 원리다.

B-Tree 인덱스

PostgreSQL의 기본 인덱스 타입은 B-Tree(Balanced Tree)다.

CREATE INDEX idx_orders_user_id ON orders (user_id);

B-Tree의 특징:

균형 트리 구조로 어떤 값을 찾든 동일한 깊이만큼만 탐색
동등 비교(=), 범위 비교(<, >, BETWEEN), 정렬(ORDER BY)에 모두 효과적
NULL 값도 인덱스에 포함됨
시간 복잡도: O(log n)

인덱스 종류 비교

타입	용도	예시
B-Tree	범용 (기본값)	대부분의 컬럼
Hash	동등 비교만	`WHERE status = 'ACTIVE'`
GIN	배열, Full-text Search	JSONB, tsvector
GiST	공간 데이터, 범위 타입	PostGIS, tsrange
BRIN	물리적 정렬된 대용량 데이터	시계열 데이터

EXPLAIN ANALYZE로 쿼리 분석하기

인덱스를 만들었는데 정말 사용되고 있는 걸까? EXPLAIN ANALYZE로 확인할 수 있다.

EXPLAIN ANALYZE
SELECT * FROM orders WHERE user_id = 42;

인덱스가 없을 때:

Seq Scan on orders  (cost=0.00..18726.00 rows=523 width=64)
  (actual time=0.031..92.145 rows=487 loops=1)
  Filter: (user_id = 42)
  Rows Removed by Filter: 999513
Planning Time: 0.089 ms
Execution Time: 92.312 ms

인덱스 생성 후:

Index Scan using idx_orders_user_id on orders  (cost=0.42..523.15 rows=523 width=64)
  (actual time=0.028..1.234 rows=487 loops=1)
  Index Cond: (user_id = 42)
Planning Time: 0.102 ms
Execution Time: 1.387 ms

92ms → 1.4ms로 약 66배 빨라졌다. 핵심 지표:

Seq Scan → Index Scan: 인덱스가 사용되고 있음
actual time: 실제 소요 시간 (ms)
Rows Removed by Filter: Seq Scan에서 버려진 행 수 (높을수록 비효율)

복합 인덱스 전략

여러 컬럼을 조합한 쿼리가 자주 사용된다면 복합 인덱스(Composite Index)를 고려하자.

-- 특정 사용자의 최근 주문을 자주 조회하는 경우
CREATE INDEX idx_orders_user_created
    ON orders (user_id, created_at DESC);

-- 이 쿼리에 최적화됨
SELECT * FROM orders
WHERE user_id = 42
ORDER BY created_at DESC
LIMIT 10;

복합 인덱스의 핵심 규칙: 컬럼 순서

복합 인덱스는 왼쪽 컬럼부터 순서대로 사용된다. 이를 Leftmost Prefix Rule이라 한다.

인덱스 (user_id, status, created_at)가 있을 때:

-- ✅ 인덱스 사용됨
WHERE user_id = 42
WHERE user_id = 42 AND status = 'PAID'
WHERE user_id = 42 AND status = 'PAID' AND created_at > '2026-01-01'

-- ❌ 인덱스 사용 안 됨 (user_id 없이 중간 컬럼부터 시작)
WHERE status = 'PAID'
WHERE status = 'PAID' AND created_at > '2026-01-01'

컬럼 순서 결정 기준

동등 조건(=)에 사용되는 컬럼 → 앞에 배치
범위 조건(>, <, BETWEEN)에 사용되는 컬럼 → 뒤에 배치
카디널리티(고유 값 수)가 높은 컬럼 → 앞에 배치

인덱스를 걸면 안 되는 경우

인덱스는 만능이 아니다. 오히려 성능을 떨어뜨리는 경우도 있다:

쓰기가 매우 빈번한 테이블: INSERT/UPDATE/DELETE 시 인덱스도 함께 갱신되므로 오버헤드 발생. 동시 쓰기가 많다면 트랜잭션 격리 수준도 함께 고려해야 한다
카디널리티가 극단적으로 낮은 컬럼: gender처럼 값이 2~3개뿐이면 Full Scan이 더 빠를 수 있음
테이블 크기가 작은 경우: 수천 건 이하라면 Seq Scan이 충분히 빠름

실무 팁

-- 사용되지 않는 인덱스 찾기
SELECT schemaname, tablename, indexname, idx_scan
FROM pg_stat_user_indexes
WHERE idx_scan = 0
ORDER BY pg_relation_size(indexrelid) DESC;

-- 인덱스 크기 확인
SELECT pg_size_pretty(pg_indexes_size('orders'));

-- 테이블 + 인덱스 전체 크기
SELECT pg_size_pretty(pg_total_relation_size('orders'));

사용되지 않는 인덱스는 쓰기 성능만 떨어뜨리므로, 주기적으로 확인하고 정리하는 것이 좋다.

정리

인덱스는 읽기 성능을 높이지만 쓰기 성능을 낮춘다 — 트레이드오프를 이해하자
EXPLAIN ANALYZE로 항상 실제 실행 계획을 확인하자
복합 인덱스는 컬럼 순서가 핵심이다
불필요한 인덱스는 정리하자 — 인덱스도 디스크와 메모리를 소비한다

Docker 입문: 컨테이너로 개발 환경 통일하기

doodoo3804@gmail.com (DoYoon Kim) — Fri, 20 Mar 2026 00:00:00 +0900

Docker를 왜 쓰는가

“제 컴퓨터에서는 되는데요?” — 개발자라면 한 번쯤 들어본 말이다.

팀원마다 OS, JDK 버전, 로컬 DB 설정이 다르면 동일한 코드가 다른 결과를 낳는다. Docker는 애플리케이션과 그 실행 환경을 하나의 패키지(컨테이너)로 묶어서 어디서든 동일하게 동작하도록 보장한다.

핵심 개념

Image vs Container

구분	Image	Container
비유	클래스	인스턴스
상태	불변(Immutable)	실행 중 변경 가능
저장	Docker Registry (Docker Hub 등)	로컬 머신

Image는 읽기 전용 템플릿이고, Container는 Image를 기반으로 생성된 실행 중인 프로세스다.

Layer 구조

Docker Image는 여러 개의 레이어로 구성된다. Dockerfile의 각 명령어(RUN, COPY 등)가 하나의 레이어를 생성하며, 변경되지 않은 레이어는 캐시를 활용해 빌드 속도를 높인다.

Dockerfile 작성

Spring Boot 애플리케이션을 컨테이너화하는 Dockerfile 예제:

# 빌드 스테이지
FROM eclipse-temurin:17-jdk-alpine AS builder
WORKDIR /app
COPY gradle/ gradle/
COPY gradlew build.gradle settings.gradle ./
RUN ./gradlew dependencies --no-daemon
COPY src/ src/
RUN ./gradlew bootJar --no-daemon

# 실행 스테이지
FROM eclipse-temurin:17-jre-alpine
WORKDIR /app
COPY --from=builder /app/build/libs/*.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]

여기서 사용한 Multi-stage Build의 장점:

빌드에 필요한 JDK + Gradle은 최종 이미지에 포함되지 않는다
최종 이미지에는 JRE + JAR만 들어가므로 이미지 크기가 훨씬 작다
빌드 도구가 없으므로 보안 공격 표면(Attack Surface)도 줄어든다

자주 쓰는 Docker 명령어

# 이미지 빌드
docker build -t my-app:1.0 .

# 컨테이너 실행
docker run -d -p 8080:8080 --name my-app my-app:1.0

# 실행 중인 컨테이너 확인
docker ps

# 로그 확인
docker logs -f my-app

# 컨테이너 내부 접속
docker exec -it my-app /bin/sh

# 컨테이너 정지 및 삭제
docker stop my-app && docker rm my-app

Docker Compose

실제 프로젝트에서는 애플리케이션 서버 하나만 띄우는 경우가 거의 없다. DB, Redis, 메시지 큐 등 여러 서비스를 함께 관리해야 한다. Docker Compose는 여러 컨테이너를 하나의 YAML 파일로 정의하고 한 번에 실행할 수 있게 해준다.

version: '3.8'

services:
  app:
    build: .
    ports:
      - "8080:8080"
    environment:
      SPRING_DATASOURCE_URL: jdbc:postgresql://db:5432/myapp
      SPRING_DATASOURCE_USERNAME: postgres
      SPRING_DATASOURCE_PASSWORD: secret
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: secret
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 3s
      retries: 5

volumes:
  pgdata:

주요 포인트:

depends_on + healthcheck — DB가 완전히 준비된 후 앱이 시작된다
volumes — 컨테이너가 삭제되어도 데이터가 유지된다
서비스 이름(db)이 곧 내부 DNS 호스트명이 된다 (jdbc:postgresql://db:5432/myapp)

실행은 단 한 줄:

docker compose up -d

.dockerignore

빌드 컨텍스트에서 불필요한 파일을 제외하면 빌드 속도가 빨라지고 이미지 크기도 줄어든다.

.git
.gradle
build
*.md
.env

정리

개념	핵심
Image	불변 실행 환경 템플릿
Container	Image 기반 실행 인스턴스
Dockerfile	Image 빌드 레시피
Docker Compose	다중 컨테이너 오케스트레이션
Volume	데이터 영속성 보장

Docker를 익히면 로컬 개발 환경 구축이 편해질 뿐 아니라, CI/CD 파이프라인과 Kubernetes로 나아가는 기반이 된다. 다음에는 GitHub Actions와 Docker를 연동한 CI/CD 파이프라인 구축을 다뤄볼 예정이다.

Spring Boot + JPA로 REST API 만들기

doodoo3804@gmail.com (DoYoon Kim) — Sun, 15 Mar 2026 00:00:00 +0900

들어가며

Spring Boot와 JPA를 사용하면 놀라울 정도로 적은 코드로 REST API를 만들 수 있다. 이번 글에서는 가장 기본적인 Entity → Repository → Service → Controller 계층 구조를 살펴보고, 간단한 게시글(Post) CRUD API를 구현해 본다.

프로젝트 세팅

start.spring.io에서 다음 의존성을 추가한다.

Spring Web — REST Controller
Spring Data JPA — ORM
H2 Database — 개발용 인메모리 DB
Lombok — 보일러플레이트 제거

application.yml 설정:

spring:
  datasource:
    url: jdbc:h2:mem:testdb
    driver-class-name: org.h2.Driver
  jpa:
    hibernate:
      ddl-auto: create-drop
    show-sql: true
    properties:
      hibernate:
        format_sql: true
  h2:
    console:
      enabled: true

1. Entity

Entity는 데이터베이스 테이블과 1:1로 매핑되는 클래스다. @Entity 어노테이션을 붙이면 JPA가 이 클래스를 기반으로 테이블을 자동 생성한다.

@Entity
@Getter
@NoArgsConstructor(access = AccessLevel.PROTECTED)
public class Post {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, length = 100)
    private String title;

    @Column(columnDefinition = "TEXT")
    private String content;

    private LocalDateTime createdAt;

    @Builder
    public Post(String title, String content) {
        this.title = title;
        this.content = content;
        this.createdAt = LocalDateTime.now();
    }

    public void update(String title, String content) {
        this.title = title;
        this.content = content;
    }
}

포인트 정리:

@Id + @GeneratedValue — 기본키 자동 생성
@NoArgsConstructor(access = PROTECTED) — JPA 스펙 요구사항 (기본 생성자 필요) + 외부 직접 생성 방지
update() 메서드로 Dirty Checking 활용 (트랜잭션 내에서 필드 값 변경 시 자동 UPDATE 쿼리)

2. Repository

Spring Data JPA의 JpaRepository를 상속하면 기본 CRUD 메서드가 자동으로 제공된다.

public interface PostRepository extends JpaRepository<Post, Long> {

    List<Post> findByTitleContaining(String keyword);
}

findByTitleContaining 같은 메서드 이름 기반 쿼리를 사용하면 별도의 SQL 작성 없이도 검색 기능을 구현할 수 있다. 내부적으로 LIKE '%keyword%' 쿼리가 생성된다.

3. Service

비즈니스 로직을 담당하는 계층이다. Controller에서 직접 Repository를 호출하지 않고 Service를 거치는 이유는 관심사 분리와 트랜잭션 관리 때문이다.

@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
public class PostService {

    private final PostRepository postRepository;

    // 게시글 전체 조회
    public List<Post> findAll() {
        return postRepository.findAll();
    }

    // 게시글 단건 조회
    public Post findById(Long id) {
        return postRepository.findById(id)
                .orElseThrow(() -> new IllegalArgumentException("해당 게시글이 없습니다. id=" + id));
    }

    // 게시글 생성
    @Transactional
    public Long save(String title, String content) {
        Post post = Post.builder()
                .title(title)
                .content(content)
                .build();
        return postRepository.save(post).getId();
    }

    // 게시글 수정
    @Transactional
    public void update(Long id, String title, String content) {
        Post post = findById(id);
        post.update(title, content); // Dirty Checking
    }

    // 게시글 삭제
    @Transactional
    public void delete(Long id) {
        Post post = findById(id);
        postRepository.delete(post);
    }
}

@Transactional(readOnly = true)를 클래스 레벨에 걸고, 쓰기 작업에만 @Transactional을 따로 붙이는 패턴이 일반적이다. 읽기 전용 트랜잭션은 Hibernate의 플러시 모드를 MANUAL로 설정하기 때문에 성능상 이점이 있다.

4. Controller

클라이언트의 HTTP 요청을 받아서 Service에 위임하고, 결과를 JSON으로 반환한다.

@RestController
@RequestMapping("/api/posts")
@RequiredArgsConstructor
public class PostController {

    private final PostService postService;

    @GetMapping
    public List<Post> findAll() {
        return postService.findAll();
    }

    @GetMapping("/{id}")
    public Post findById(@PathVariable Long id) {
        return postService.findById(id);
    }

    @PostMapping
    public ResponseEntity<Long> save(@RequestBody PostSaveRequest request) {
        Long id = postService.save(request.getTitle(), request.getContent());
        return ResponseEntity.status(HttpStatus.CREATED).body(id);
    }

    @PutMapping("/{id}")
    public ResponseEntity<Void> update(@PathVariable Long id,
                                        @RequestBody PostUpdateRequest request) {
        postService.update(id, request.getTitle(), request.getContent());
        return ResponseEntity.ok().build();
    }

    @DeleteMapping("/{id}")
    public ResponseEntity<Void> delete(@PathVariable Long id) {
        postService.delete(id);
        return ResponseEntity.noContent().build();
    }
}

전체 흐름 정리

Client → Controller → Service → Repository → Database
                         ↕
                      Entity (JPA 영속성 컨텍스트)

Controller: HTTP 요청/응답 처리
Service: 비즈니스 로직 + 트랜잭션 경계
Repository: 데이터 접근 추상화
Entity: 데이터베이스 테이블 매핑

이 4계층 구조를 지키면 각 레이어의 역할이 명확해지고, 테스트 작성과 유지보수가 훨씬 수월해진다.

마무리

이번 글에서는 Spring Boot + JPA의 가장 기본적인 패턴을 다뤘다. 실무에서는 여기에 DTO 변환, 예외 처리(@ControllerAdvice), Validation, 페이징 처리 등이 추가된다. 또한 연관 관계가 복잡해지면 JPA N+1 문제를 반드시 이해해야 한다. 다음 글에서는 이 API에 Spring Security를 적용하는 방법을 알아보겠다.

How to use React in Jekyll app

doodoo3804@gmail.com (DoYoon Kim) — Fri, 04 Aug 2023 00:00:00 +0900

How to Use React in Jekyll

Create react app

Create react app in base directory that your Jekyll project.
Use below code

npx create-react-app dev-react-pages
cd dev-react-pages
npm start

Then, you can see dev-react-pages application and will starting. dev-react-pages is only develop folder. Now, we will create react-pages that deployment only.

Add react settings

Add below lines to ignore node_modules when we commit.

dev-react-pages/node_modules/
dev-react-pages/build/

Also add below lines in Jekyll project _config.yml. Jekyll doesn’t have to know about react.

exclude:
  - node_modules
  - dev-react-pages

Make your react webpage uri

Make your react project webpage uri to add below line. Thar will be {your git-hub-pages-uri}\{react-uri}.
There is an example https://doodoo3804.github.io/react-pages/

"homepage": "/react-pages/"

Write build and deployment scrit

To deploy react page, build and copy results to deployment directory that we made first step and commit then. There need some lines to build and deployment. To do this easily, we going to write some lines in react application package.json.

"scripts": {
  "start": "react-scripts start",
  "build": "react-scripts build",
  "test": "react-scripts test",
  "eject": "react-scripts eject",
  
  // add here
    "predeploy": "npm run build",
    "purge": "rmdir /s /q ..\\react-pages\\static && xcopy .\\build\\* ..\\react-pages\\ /E /y",
    "deploy": "npm run purge && npm run frontmatter"
},

After that, yarn run deploy to build and copy results. Last step is check your react page and commit all results.

Minimum Spanning Tree

doodoo3804@gmail.com (DoYoon Kim) — Wed, 12 Jul 2023 00:00:00 +0900

MST 최소 신장 트리

신장 트리란 하나의 그래프가 있을 때 모든 노드를 포함하면서 사이클이 존재하지 않는 부분 그래프를 의미한다.
최소한의 비용으로 신장 트리를 찾는 것이 MST 알고리즘이다.

MST 구현

1. 그루스칼(Kruskal)

그리디 알고리즘의 일종으로 분류

모든 간선에 대하여 정렬을 수행한 뒤에 가장 거리가 짧은 간선부터 집합에 포함
사이클을 발생하는 경우 집합에서 제외한다.
일종의 트리 구조이므로 최종적으로 만들어지는 신장 트리에 포함되는 간선의 개수가 노드의 개수 - 1과 같다.

그루스칼 알고리즘 구현
[ with C++ ]

// 정점이 7개인 그래프로 예시
const int V = 7;
vector<vector<pair<int, int>>>graph;

struct Edge {
    int src, dest, weight;
};

// 노드 x의 부모를 찾는 함수
int find(vector<int>& parent, int x) {
    if (parent[x] != x) {
        parent[x] = find(parent, parent[x]);
    }
    return parent[x];
}

// 두 노드가 속한 집합을 합치는 함수
void merge(vector<int>&parent, vector<int>& rank, int u, int v) {
    u = find(parent, u);
    v = find(parent, v);
    if (rank[u] > rank[v]) {
        swap(u, v);
    }
    parent[u] = v;
    if(rank[u] == rank[v]) {
        rank[v]++;
    }
}

// 그루스칼 알고리즘
vector<Edge> kruskal() {
    // 그래프의 간선을 모두 추출한 뒤, 가중치를 기준으로 오름차순으로 정렬
    vector<Edge> edges;
    vector<int>parent(V);
    vector<int>rank(V);

    for(int i = 0; i < V; ++i) {
        // 맨 처음 부모는 자기 자신으로 초기화
        parent[i] = i;
        rank[i] = 1;
        for (auto& edge : graph[i]) {
            edges.push_back({i, edge.first, edge.second});
        }
    }
    // 가중치를 기준으로 정렬
    sort(edges.begin(), edges.end(), [](Edge x, Edge y) {
        return x.weight < y.weight;
    });

    // 간선을 하나씩 선택하며, 그루스칼 알고리즘 적용
    vector<Edge> result;
    for (auto& edge : edges) {
        int u = edge.src, v = edge.dest, weight = edge.weight;
        if (find(parent, u) != find(parent, v)) {
            merge(parent, rank, u, v);
            result.push_back(edge);
        }
    }
    return result;
}

int main() {
    vector<Edge> result = kruskal();
    return 0;
}

Floyd Warshall

doodoo3804@gmail.com (DoYoon Kim) — Tue, 11 Jul 2023 00:00:00 +0900

플로이드-워셜 알고리즘이란

그래프에서 모든 노드 쌍 간의 최단 경로를 찾는 알고리즘 다익스트라와 다르게 음수 가중치를 가진 그래프에서도 동작한다. 모든 지점에서 다른 모든 지점까지의 최단 경로를 모두 구해야 하는 경우에 사용할 수 있다. DP(Dynamic Programming)를 기반으로 동작한다. 점화식은 아래와 같다.

D_ab = min(D_ab, D_ak + D_kb)

A에서 B로 가는 최소 비용과 A에서 K를 거쳐 B로 가는 비용을 비교하여 더 작은 값으로 갱신 다익스트라 알고리즘에 비해서 구현이 쉽다.

플로이드-워셜 구현 — [ with C++ ]

#define INF 2134567890

int main() {
    // 그래프 예시
    vector<vector<int>> graph = {
        {0, 5, INF, 10},
        {INF, 0, 3, INF},
        {INF, INF, 0, 1},
        {INF, INF, INF, 0},
    };

    // 그래프의 인접 행렬을 dist로 복사
    int n = graph.size();
    vector<vector<int>>dist(n, vector<int>(n));
    for (int i = 0; i < n; ++i) {
        for (int j = 0; j < n; ++j) {
            dist[i][j] = graph[i][j];
        }
    }

    // 플로이드 워셜 알고리즘
    // k : 중간 거치는 노드
    for (int k = 0; k < n; ++k) {
        // (i j) vs (i k j)
        for (int i = 0; i < n; ++i) {
            for (int j = 0; j < n; ++j) {
                if (dist[i][k] != INF && dist[k][j] != INF && dist[i][k] + dist[k][j] < dist[i][j]) {
                    dist[i][j] = dist[i][k] + dist[k][j];
                }
            }
        }
    }
    return 0;
}

Kotlin vs Java

doodoo3804@gmail.com (DoYoon Kim) — Wed, 21 Jun 2023 00:00:00 +0900

개발자들은 평생동안 코드를 쓰는 것 보다 읽는 것에 더 많은 시간을 할애한다. 코틀린은 가독성에 초점을 뒀다. 「이사코바」

많은 서비스의 Backend 시스템은 자바로 이루어져 있습니다. 몇몇 회사와 개발자들이 Backend에 코틀린을 사용하려는 모습을 보이고 있습니다. 코틀린은 자바와 완벽하게 호환이 되므로 대체될 수 있습니다. 또 구글에서 코틀린을 1 언어로 채택하고 있는 걸 보면 코틀린은 여러 면에서 유리합니다.

Why we should learn kotlin?

정적 타입

동적 타입 언어에서 발생할 수 있는 런타임 오류를 어느 정도 예방이 가능하다. NPE(NullPointException)을 컴파일 단계에서 예방할 수 있습니다.

간결성

자바에 비해서 코드가 간결하고 직관적입니다. 그렇기에 배우기 쉽습니다. (~~물론 자바에 비해서..~~) Jetbrain 에서 만든 언어이기 때문에 Intellij IDEA에 적용하기 좋습니다. 일례로 자바로 작성된 코드를 코틀린 파일에 붙여 넣으면 IDEA에서 자동으로 코틀린으로 변환해줍니다.

Kotlin vs Java

변수 상수

Java
- 변수 : 그냥 선언
- 상수 : final을 사용함

String str = "";
final String str = "";

kotlin
- 변수 : var(variable)로 선언
- 상수 : val(value)로 선언

var str = ""
val str = ""

객체 초기화

java
- new로 객체를 초기화하고 초기화된 객체를 이용하여 초기 작업을 진행합니다.
여러 객체를 생성해야 하는 상황이라면 불편해지고, 가독성이 떨어집니다.

Intent testIntent = new Intent(this, SecondActivity.class);
testIntent.putExtra("ext1", 1);
testIntent.putExtra("ext2", 2);
testIntent.putExtra("ext3", "3");
testIntent.putExtra("ext4", "4");
testIntent.putExtra("ext5", false);

kotlin
- apply block을 이용하여 초기화 작업을 수행합니다. 초기화된 객체 자신을 this로 칭하기 때문에 따로 선언하지 않고 초기화 작업을 진행해 줄 수 있습니다. 여러 객체를 생성하더라도 block으로 감싸서 진행하기 때문에 가독성이 좋고, 코드를 관리하기 수월합니다.

val testIntent = Intent(this, SecondActivity::class.java).apply {
    putExtra("ext1", 1)
    putExtra("ext2", 2)
    putExtra("ext3", "3")
    putExtra("ext4", "4")
    putExtra("ext5", false)
}

Lambda

kotlin
자바에서는 람다를 사용할 때 매개변수를 사용했지만, 코틀린에서는 이를 생략하고 it이라는 암묵적 변수로 작성할 수 있습니다. (~~예시가 좀 잘못됐다…~~) 아래 2번 코드의 3줄 모두 같은 기능을 수행합니다.

// 1
class User {
    val name : String
}
fun main() {
    val user = listOf {
        user1 = User("A"),
        user2 = User("B")
    }
    val selectUser = user.filter {it.name == "A"}
    println("Selected user is ${selectUser.joinToString(separator = ", ") { it.name }}")
}
// 2
people.maxBy(Person::age)
people.maxBy(p -> p.age)
people.maxBy(it.age)

NPE(NullPointException)

java
- 자바는 기본적으로 Nullable로 선언됩니다. @Nullable과 @NonNull을 사용하여 Null타입을 구분합니다.
- 자바 변수에 Null이 들어오는 경우를 체크하고 NPE를 방지하고 싶다면 if를 사용합니다.

@Nullable String strNullable = null;
@NonNull String strNonNull = "";

if (strNullable != null) {
    strNullable.split("/");
}

kotlin
- ?를 사용하여 null이 가능함을 구분할 수 있습니다.
- 코틀린에서는 NPE를 방지하기 위해 ?를 사용합니다. 만약 Null이라면 split()은 실행되지 않습니다.

var strNullable: String? = null
var strNonNull: String = ""

strNullable?.split("/")

생성자

java
- getter setter 등 Lombok의 @(Annotation)을 많이 선언해 주어야 하는 불편함이 있습니다.

@Getter
@Builder
@AllArgsConstructor
public class User {
  @NotNull(message = "name is required")
  private String name;
  @Nullable
  private String lastName;  
 
  public User(String name) {
    this.name = name;
    this.lastName = "NO LASTNAME";
  }
}

kotlin - 코틀린은 @(Annotation)이 내장되어 있어 Lombok을 사용하지 않습니다. var를 통해 선언하는 것으로 DTO로 사용할 수 있습니다.

class User(
    var name: String,
    var lastName : String? = "NO LASTNAME",
)

Conclusion

자바와 코틀린은 완벽 호환이 된다고는 하지만 많은 부분 코틀린이 더 간결한 방식으로 다릅니다. 위에서 다 다루지 못한 내용들이 많이 있지만 다음 글들을 통해서 확인하면 좋습니다.
「Kotlin 기본 문법」

참고

백엔드 개발자의 코틀린 입문기 - 코틀린이 얼마나 좋길래? 자바에서 옮겨가도 될까?https://seolin.tistory.com/146
Kotlin vs Java: strengths, weaknesses and when to use which https://kruschecompany.com/kotlin-vs-java/
[Kotlin] Kotlin vs. Java - 코틀린, 자바 차이점 비교 https://dev-imaec.tistory.com/36
Java vs Kotlin 비교 / 안드로이드 앱 개발 승자는??? https://mondayless.tistory.com/25
[kotlin vs java ] 코틀린과 자바의 차이, 코틀린의 장점 https://juhi.tistory.com/72
Kotlin으로 프로젝트 하기 https://brunch.co.kr/@purpledev/5

Kotlin 기본 문법

doodoo3804@gmail.com (DoYoon Kim) — Tue, 20 Jun 2023 00:00:00 +0900

Kotlin 기본 문법

1. 함수

fun helloWorld() : Unit {
    println("Hello World")
}
fun add (a : Int, b : Int) : Int {
    return a + b
}

함수에서 return 값이 없는 경우면 Unit을 작성하지만 생략해도 가능하다.
return 값이 있다면 그 타입을 : 뒤에 작성한다.

2. var vs val

val a : Int = 10
var b : Int = 9
var c = 100
var s = "String"

val은 value로 상수를 의미, 변하지 않는 값이다. var는 variable로 변수를 의미 변하는 값이다.
kotlin에서는 변수의 타입을 자동으로 추론하기 때문에 c에서 처럼 : Int를 적지 않아도 가능하다. 이는 Int 에서만 적용되는 것이 아니라 모두 적용된다.(s의 경우)

3. String template

val name = "doodoo"
println("my name is ${name}")

큰 따옴표(““)안에 변수를 넣으려면 ${변수 이름} 이렇게 사용하면 된다.

4. 조건식

fun maxBy1 (a : Int, b : Int) : Int {
    if (a > b) {
        return a
    } else {
        return b
    }
}

fun maxBy2 (a : Int, b : Int) = if (a > b) a else b

maxBy1 함수는 아래 maxBy2 처럼 간결하게 적을 수 있다.

5. when

Java에서의 switch

fun checkNum(score : Int) {
    when (score) {
        0 -> println("0")
        1,2 -> println("1 or 2")
        else -> println("other scores")
    }
    var b : Int = when(score) {
        0 -> 0
        else -> 1
    }
    when(score) {
        in 90..100 -> println("great")
        in 50..80 -> println("not bad")
        else -> println("try hard")
    }
}

변수 할당에서 when을 사용할 수 있다. 이 경우에는 함수에서 사용한 것과는 다르게 else로 기본 값을 반드시 써줘야 한다.
when에서 범위를 설정하려면 in 90..100 처럼 사용하면 된다.

6. Expression vs Statement

Expression은 변수를 어떤 값을 할당하거나 변환하는 것, 즉 값을 만들어 내는 것이다. kotlin에서 모든 함수는 Expression이다.
Statement는 값을 만들지 않고 문장을 실행하는 것(?)

7. Array vs List

val array = arrayOf(1, 2, 3)
val list = listOf(1, 2, 3)

val array2 = arrayOf(1, "s", 3.14f)
val list2 = listOf(1, "s", 3.14f)

val arrayList = arrayListOf<Int>()

list는 interface로 get만 존재하므로 list[0] = 3와 같이 값을 변경하는 것은 불가능하다. 반면 array는 가능
arrayList는 add remove 등으로 변경이 가능하다.

8. for vs while

for (i in 1..10) {
    println(i)
}
for (i in 1..10 step 2) {
    println(i)
}
for (i in 10 downTo 1) {
    println(i)
}
val students = arrayListOf("a", "b", "c")
for ((index, name) in students.withIndex()) {
    println("$index $name")
}
var index = 0
while(index < 5) {
    println(index)
    index ++
}

첫 번째 for문은 1부터 10까지
두 번째 for문은 2간격으로 1부터 10까지
세 번째 for문은 10부터 1까지
네 번째 for문은 withIndex()를 사용하여 index와 value를 둘 다 가져올 수 있다. (python 에서의 enumerate와 동일)

9. NonNull 과 Nullable

var name : String = "doodoo"
var nullName : String? = null

var nullNameInUpperCase = nullName?.toUpperCase()

String은 NonNull 타입인데 ?를 사용하면 null을 할당 / null이 될 수 있다.
초기 변수 할당이 아닌 때에도 nullable 타입을 할당하려고 하면 ?를 사용하면 된다.

val lastName : String? = null
val fullName : name + " " + (lastName ?: "No LastName")

val email : String ?= "doodoo3804@gmail.com"
email?.let {
    println("my email is ${email}")
}

?: elvis expression
null인 경우의 default 값을 적어준다.
보통 ?.let을 사용하여 null이 아닌 경우의 함수를 짠다. !! null이 절대로 될 수 없는 경우에 사용

10. class

open class Human constructor(val name : String = "default name") {
    constructor(name : String, age : Int) : this(name) {
        println(name, age)
    }
    init {
        println("walk")
    }
    open fun eating() {
        println("eat")
    }
}
class NotHuman : Human(){
    override fun eating() {
        super.eating()
        println("not eating")
    }
}
fun main() {
val human1 = Human("doodoo")
val human2 = Human("doodoos", 99)
val notHuman = NotHuman()
}

kotlin의 class는 기본적으로 final class이다. 그렇기 때문에 같은 파일 내에 있더라도 override하여 사용할 수 없다. 상속하여 사용하기 위해서는 open 예약어를 사용한다. class내부의 fun도 같은 문제가 있어 open을 사용한다. 상속받은 parameter 역시 사용 가능하다.

주생성자 : name 이라는 String을 할당하기 위해 사용 class 이름 옆에 constructor를 작성한다. 이는 생략 가능
부생성자 : class 내부에 constructor를 선언, 부생성자는 주생성자에게서 this를 통해 값을 받아와야만 한다.
init : 생성되었을 때 자동으로 실행하는 부분
super : 만약 부모로 부터 상속 받아 사용해야 하는 경우 사용한다.
open : 상속을 받기 위한 부분에 사용하는 예약어

Segment tree

doodoo3804@gmail.com (DoYoon Kim) — Mon, 19 Jun 2023 00:00:00 +0900

세그먼트 트리란

주어진 쿼리에 대해 빠르게 응답하기 위해 만들어진 자료구조이다.
따라서 많은 쿼리가 반복되는 상황에 유리하다.

세그먼트 트리의 전체 크기

크기가 N인 배열에 대해

트리의 높이 - ceil(log2(N))
세그먼트 트리의 크기 - 1 << (트리의 높이 + 1)

세그먼트 트리생성

세그먼트 트리는 full binary tree에 가깝기에 배열에 모든 값들이 꽉차서 올 가능성이 매우 높다.
포인터보다는 배열을 사용하여 작성한다.

         1
       ⁄   ∖
     2       3
    ⁄  ∖    ⁄  ∖
  4     5  6    7

루트 노드 = 1로 생각한다.
이때 루트 노드의 왼쪽은 2번, 오른쪽은 3번이 된다.
2번 노드의 왼쪽은 4번, 오른쪽은 5번이 된다.
3번 노드의 왼쪽은 6번, 오른쪽은 7번이 된다…

|현재 노드가 node라면|
노드의 왼쪽 자식 배열 번호 : node * 2
노드의 오른쪽 자식 배열 번호 : node * 2 + 1

세그먼트 트리 구현

[ with C++ ]
아래 코드에서 tree 배열은 세그먼트 트리가 만들어지는 배열
arr 배열은 처음에 입력받아 생성된 배열을 의미한다.

1. 초기화 과정 (init)

long long init(vector<long long> &arr, vector<long long> &tree, int node, int start, int end) {
    if (start == end) return tree[node] = arr[start];
    int mid = (end + start) / 2;
    return tree[node] = init(arr, tree, node * 2, start, mid) + init(arr, tree, node * 2 + 1, mid + 1, end);
}

2. 갱신 과정 (update)

void update(vector<long long> &tree, int node, int start, int end, int index, long long diff) {
    if (!(start <= index && index <= end)) return;
    tree[node] += diff;
    if (start != end) {
        int mid = (start + end) / 2;
        update(tree, node * 2, start, mid, index, diff);
        update(tree, node * 2 + 1, mid + 1, end, index, diff);
    }
}

3. 합 과정 (sum)

이 부분은 쿼리에 따라 달라질 수 있다.

long long sum(vector<long long> &tree, int node, int start, int end, int left, int right) {
    if (left > end || right < start) return 0;
    if (left <= start && end <= right) return tree[node];
    int mid = (start + end) / 2;
    return sum(tree, node * 2, start, mid, left, right) + sum(tree, node * 2 + 1, mid + 1, left, right);
}