NestJS + TypeORM 프로젝트에서 typeorm-transactional 패키지의 @Transactional() 데코레이터를 사용하면, 서로 다른 Repository에서 실행되는 Query들이 하나의 트랜잭션으로 묶이게 된다.

@Transactional()
async createMasterUser(dto: CreateMasterUserDto) {
    // 서로 다른 repository지만 같은 트랜잭션으로 묶임.
      const savedCompany = await this.companyRepository.save(companyData);
    await this.userRepository.save({companyId: savedCompany.id, ...UserData);
}

logging을 통해 터미널을 보니 하나의 트랜잭션으로 묶이는 걸 보고 어떻게 별도의 Repository 토큰을 가진 객체들이 하나의 트랜잭션을 공유할 수 있는지 궁금해졌다.

핵심: AsyncLocalStorage

typeorm-transactional은 Node.js의 내장 API인 AsyncLocalStorage(ALS) 를 사용한다.

AsyncLocalStorage란?

AsyncLocalStorage는 비동기 작업 전체에 걸쳐 컨텍스트를 유지하는 기능을 제공한다. Java의 ThreadLocal과 비슷한 개념이지만, 싱글 스레드인 Node.js의 비동기 환경에 맞게 설계되엇다.

import { AsyncLocalStorage } from 'async_hooks';

const asyncLocalStorage = new AsyncLocalStorage();

// run() 내부에서 실행되는 모든 비동기 코드는 동일한 storage에 접근 가능
asyncLocalStorage.run({ requestId: 'abc-123' }, async () => {
    await someAsyncFunction();         // getStore() -> { requestId: 'abc-123' }
      await anotherASyncFunction();     // getStore() -> { requestId: 'abc-123' }
});

핵심 동작 원리:

• run(store, callback): 새로운 컨텍스트를 생성하고 store를 설정
• getStore(): 현재 비동기 컨텍스트의 store를 조회
• callback 내에서 호출되는 모든 비동기 작업에 컨텍스트가 자동 전파됨

@Transactional() 동작 원리

1단계: 초기화

어플리케이션 시작 전에 트랜잭션 컨텍스트를 초기화한다.

// main.ts
import { initializeTransactionalContext, StoreageDriver, addTransactionalDataSource} from 'typeorm-transactional';

initializeTransactionalContext({ storageDriver: StorageDriver.AUTO });

// DataSource 등록
addTransactionalDataSource(dataSource);

⚠️ initializeTrasactionalContext() 는 반드시 어플리케이션 초기화 전에 호출해야 한다.

2단계: @Transactional() 데코레이터

데코레이터가 메서드를 감싸서 트랜잭션 컨텍스트를 생성한다.

// 내부 동작을 단순화한 의사 코드
function Transactional() {
    return function(target, key, descriptor) {
        const originalMethod = descriptor.value;

      descriptor.value = async function(...args) {
          // 1. 트랜잭션 시작
        return dataSource.transaction(async (trasactionalEntityManager) => {
          // 2. AsyncLocalStorage에 트랜잭션 EntityManager 저장
          return asyncLocalStorage.run(
            { entityManager: trasactionalEntityManager },
            // 3. 원본 메서드 실행
            () => originalMethod.apply(this, args)
            );
        });
      };
    };
}

3단계: Repository에서 트랜잭션 EntityManager 사용

typeorm-transactional 은 DataSource의 메서드들을 패치(fetch) 한다.

// 패치된 repository 메서드 (의사 코드)
async save(entity) {
  // AsyncLocalStorage에서 현재 컨텍스트 store 조회
  const store = asyncLocalStorage.getStore();

  if (store?.entityManager) {
      // 트랜잭션 컨텍스트가 존재하면 해당 EntityManager 사용
    return store.entityManager.getRepository(this.target).save(entity);
  }

  // 없으면 일반 EntityManager 사용
  return originalSave(entity);
}

전체 Flow

1. createMasterUser() 호출
   │
2. @Transactional() 데코레이터가 가로챔
   │
3. DataSource.transaction() 시작
   │  └─ 트랜잭션용 EntityManager 생성
   │
4. AsyncLocalStorage.run(store, callback) 실행
   │  └─ store = { entityManager: 트랜잭션EM }
   │
5. ┌─ callback 내부 (async context 유지) ─────────────────┐
   │                                                    │
   │  Company save() 호출                               │
   │    └─ companyRepository.save()                     │
   │       └─ getStore() → 트랜잭션 EM 획득                │
   │       └─ 트랜잭션 EM으로 INSERT 실행                   │
   │                                                    │
   │  User Save() 호출                                  │
   │    └─ userRepository.save()                        │
   │       └─ getStore() → 동일한 트랜잭션 EM 획득           │
   │       └─ 트랜잭션 EM으로 INSERT 실행                    │
   │                                                    │
   └────────────────────────────────────────────────────┘
   │
6. 성공 → COMMIT / 예외 발생 → ROLLBACK

정리

결론: Repository 토큰이 달라도 같은 DataSource를 사용하고, @Transactional() 내부에서 호출되면 AsyncLocalStorage를 통해 동일한 트랜잭션 EntityManager를 공유하게 된다.

참고 자료

• typeorm-transactional GitHub
• Node.js AsyncLocalStorage 공식 문서

😮‍💨 시작은 단순한 에러 메시지였다.

Spring Boot 4.0으로 프로젝트를 마이그레이션을 하는데, Redis 설정에서 낯선 에러를 마주쳤다.

Unresolved reference 'DefaultTyping'.

분명히 이전 버전에서 동작이 잘 되었는데, 4.0으로 버전을 올린 후 왜 DefaultTyping 을 찾을 수 없나는 건지..

// 기존 코드 (Spring Boot 3.x)
private fun redisObjectMapper(): ObjectMapper =
    JsonMapper.builder()
    .addModule(KotlinModule.Builder().build())
    .activateDefaultTyping(
        BasicPolymorphicTypeValidator.builder()
            .allowIfSubType(Any::class.java)
            .build(),
        ObjectMapper.DefaultTyping.NON_FINAL // ❗️ 에러 발생!
    )
    .build()

🤔 문제의 원인: Jackson 2 -> Jackson 3

Spring Boot 4.0의 가장 큰 변화 중 하나는 Jackson 2에서 Jackson 3로의 전환이다.

패키지 변경

DefaultTyping 위치 변경

Jackson 3에서는 DefaultTyping enum이 ObjectMapper 내부 클래스에서 별도 클래스로 분리가 되었다.

// Jackson 2.x
ObjectMapper.DefaultTyping.NON_FINAL

// Jackson 3.x
import tolls.jackson.databind.DefaultTyping
DefaultTyping.NON_FINAL

🛠️ 첫 번째 시도: DefaultTyping의 import 수정

import를 수정하고 다시 빌드를 해보았다.

import tools.jackson.databind.DefaultTyping
import tools.jackson.databind.ObjectMapper
import tools.jackson.databind.json.JsonMapper

그런데 이번에는 다른 에러가 발생했다.

None of the following candidates is applicable:
constructor<T : Any!>(mapper: ObjectMapper, type: Class<T!>): Jackson2JsonRedisSerializer<T>
constructor<T : Any!>(mapper: ObjectMapper, javaType: JavaType): Jackson2JsonRedisSerializer<T>

Jackson2JsonRedisSerializer가 tools.jackson.databind.ObjectMapper를 받지 않는 것 같았다.

🤔 두 번째 문제: Serializer 호환성

API 문서를 찾아보니

@Deprecated(since="4.0", forRemoval=true) public class Jackson2JsonRedisSerializer<T>

Jackson2JsonRedisSerializer가 Spring Boot Redis 4.0에서 Deprecated가 되었다.

새로운 Serializer 등장

Spring Data Redis 4.0에서는 Jackson 3 전용 Serializer가 새로 추가되었다.

클래스 이름에서 2가 빼진 것이 핵심이다.

🔥 최종 해결: JacksonJsonRedisSerializer 사용

완성된 RedisConfig

package com.example.dotzip.common.config

import org.springframework.beans.factory.annotation.Value
import org.springframework.cache.annotation.EnableCaching
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.data.redis.cache.RedisCacheConfiguration
import org.springframework.data.redis.cache.RedisCacheManager
import org.springframework.data.redis.connection.RedisConnectionFactory
import org.springframework.data.redis.connection.lettuce.LettuceConnectionFactory
import org.springframework.data.redis.core.RedisTemplate
import org.springframework.data.redis.core.StringRedisTemplate
import org.springframework.data.redis.serializer.JacksonJsonRedisSerializer
import org.springframework.data.redis.serializer.RedisSerializationContext
import org.springframework.data.redis.serializer.StringRedisSerializer
import tools.jackson.databind.ObjectMapper
import tools.jackson.databind.json.JsonMapper
import tools.jackson.module.kotlin.KotlinModule

@Configuration
@EnableCaching
class RedisConfig {

    @Value("\${spring.data.redis.host}")
    private lateinit var host: String

    @Value("\${spring.data.redis.port}")
    private var port: Int = 6379

    @Bean
    fun redisConnectionFactory(): RedisConnectionFactory {
        return LettuceConnectionFactory(host, port)
    }

    @Bean
    fun redisObjectMapper(): ObjectMapper =
        JsonMapper.builder()
            .addModule(KotlinModule.Builder().build())
            .build()

    @Bean
    fun redisCacheManager(
        connectionFactory: RedisConnectionFactory,
        redisObjectMapper: ObjectMapper
    ): RedisCacheManager {
        val serializer = JacksonJsonRedisSerializer(redisObjectMapper, Any::class.java)

        val cacheConfig = RedisCacheConfiguration.defaultCacheConfig()
            .serializeKeysWith(
                RedisSerializationContext.SerializationPair.fromSerializer(StringRedisSerializer())
            )
            .serializeValuesWith(
                RedisSerializationContext.SerializationPair.fromSerializer<Any>(serializer)
            )

        return RedisCacheManager.builder(connectionFactory)
            .cacheDefaults(cacheConfig)
            .build()
    }

    @Bean
    fun redisTemplate(
        connectionFactory: RedisConnectionFactory,
        redisObjectMapper: ObjectMapper
    ): RedisTemplate<String, Any> {
        val serializer = JacksonJsonRedisSerializer(redisObjectMapper, Any::class.java)

        return RedisTemplate<String, Any>().apply {
            setConnectionFactory(connectionFactory)
            keySerializer = StringRedisSerializer()
            valueSerializer = serializer
            hashKeySerializer = StringRedisSerializer()
            hashValueSerializer = serializer
        }
    }

    @Bean
    fun stringRedisTemplate(connectionFactory: RedisConnectionFactory): StringRedisTemplate {
        return StringRedisTemplate(connectionFactory)
    }
}

📋 마이그레이션 체크리스트

Spring Boot 3.x -> 4.0 Redis 설정 마이그레이션 시 확인해야 할 사항들:

1. Jackson 패키지 변경

// Before (Jackson 2)
import com.fasterxml.jackson.databind.ObjectMapper
import com.fasterxml.jackson.module.kotlin.KotlinModule

// After (Jackson 3)
import tools.jackson.databind.ObjectMapper
import tools.jackson.module.kotlin.KotlinModule

2. DefaultTyping 위치 변경 (필요한 경우)

dependencies {
    implementation("tools.jackson.module:jackson-module-kotlin")
    implementation("org.springframework.boot:spring-boot-starter-data-redis")
}

💡 삽질을 줄이기

1. 공식 마이그레이션 가이드를 먼저 확인해보기.

메이저 버전 업그레이드 시 항상 공식 마이그레이션 가이드를 먼저 읽어보는 습관을 들이기로 한다.

• Jackson 3 Migration Guide
• Spring Boot 4.0 Release Notes

2. API 문서에서 Deprecated 확인

에러가 발생하면 해당 클래스의 API 문서를 확인해보고 Deprecated 여부와 대체 클래스를 확인해 볼 수 있다.

• Spring Data Redis API Docs

🎯 정리

Spring Boot 4.0 마이그레이션은 생각보다 많은 변화가 있었다. 특히 Jackson 3 전환은 Redis, REST API, 메시지 직렬화 등 다양한 곳에 영향을 미치니 꼼꼼히 확인하는게 좋을 거 같다.

Kotlin에서 const val과 val은 모두 재할당이 불가능한 값이다. 하지만 두 키워드는 컴파일 타임 상수 여부와 JVM 바이트코드 생성 방식에서 큰 차이가 있다.

1. val

val은 읽기 전용 프로퍼티 (read-only property) 이다.

val name = "John"

• 재할당은 불가능
• 하지만 컴파일 타임 상수가 아님
• 런타임에 계산되는 값도 가능

val currentTime = System.currentTimeMillis()

2. const val 이란?

const val은 컴파일 타임 상수 (compile-time constant) 이다.

• 반드시 val = top-level 또는 object / companion object 내부
• primitive 타입 또는 String
• getter 불가
• 컴파일 시점에 값이 확정됨.

const val MAX_COUNT = 10

3. JVM 관점에서 차이

Kotlin은 JVM 위에서 동작하므로 결국 Java 바이트코드로 변환된다.

3.1 object 안에서 val 사용

object Constants {
    val NAME = "John"
}

Java로 디컴파일 할 경우

public final class Constants {
    @NotNull
    private static final String NAME = "John";

    @NotNull
    public final String getNAME() {
        return NAME;
    }

    public static final Constants INSTANCE;

    static {
        INSTANCE = new Constants();
    }
}

상수를 사용했을 때

println(Constants.NAME)

→ Java에서는

Constants.INSTANCE.getNAME();

즉,

• getter 호출
• INSTANCE 접근 필요
• 값이 인라인되지 않음

3.2 object 안에서 const val 사용

object Constants {
    const val NAME = "John"
}

Java로 디컴파일 할 경우

public final class Constants {
    public static final String NAME = "John";
}

getter가 없다.

그리고 사용된 코드에서는

System.out.println("John");

→ 값이 직접 인라인이 되다.

4. 이런 차이가 발생하는 이유

const val은 JVM에서 다음과 같이 처리된다.

public static final

그리고 compile-time constant여서 사용하는 쪽 클래스의 constant pool에 값이 복사된다.

즉,

println(Constants.NAME)

은 실제 바이트코드에서

println("John");

이 된다.

반면 val은

• 객체 프로퍼티
• getter 필요
• INSTANCE 접근 필요
• 인라인이 되지 않음

🤔 5. IDE가 const val을 추천하는 이유

IntelliJ에서 val보다 const val을 추천한다.

• object 내부
• primitive / String 타입
• 값이 리터럴

이유는 아래와 같다.

1. 불필요한 getter 제거
2. INSTANCE 접근 제거
3. 바이트코드 단순화
4. 성능에 대한 이점
5. 어노테이션에서 사용 가능

Spring Book를 이용해서 Kafka 관련 테스트 코드를 실행하는데 아래와 같은 에러가 발생했다.

Caused by: org.apache.kafka.common.KafkaException: Socket server failed to bind to localhost:9092: Address already in use.

Caused by: java.util.concurrent.CompletionException: java.lang.RuntimeException: Unable to start acceptor for ListenerName(PLAINTEXT)

###

docker-compose로 kafka 실행 중

services:
  zookeeper:
    image: confluentinc/cp-zookeeper:7.5.0
    container_name: hhplus-zookeeper
    environment:
      ZOOKEEPER_CLIENT_PORT: 2181
      ZOOKEEPER_TICK_TIME: 2000
    ports:
      - "2181:2181"
    networks:
      - test-network
    restart: unless-stopped

  kafka:
    image: confluentinc/cp-kafka:7.5.0
    container_name: hhplus-kafka
    depends_on:
      - zookeeper
    ports:
      - "9092:9092"
    environment:
      KAFKA_BROKER_ID: 1
      KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181
      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://kafka:9092
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: PLAINTEXT:PLAINTEXT,PLAINTEXT_HOST:PLAINTEXT
      KAFKA_INTER_BROKER_LISTENER_NAME: PLAINTEXT
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
      KAFKA_AUTO_CREATE_TOPICS_ENABLE: "true"
    networks:
      - test-network
    restart: unless-stopped

networks:
  test-network:
    driver: bridge

테스트 코드

```kotlin
@DataJpaTest
@ComponentScan(basePackages = ["com.hhplus.ecommerce"])
@EmbeddedKafka(
    partitions = 1,
    topics = ["order-created", "payment-completed", "coupon-issued"],
    brokerProperties = ["listeners=PLAINTEXT://localhost:9092", "port=9092"]
)
@TestPropertySource(
    properties = [
        "spring.kafka.enabled=true",
        "spring.kafka.bootstrap-servers=localhost:9092",
        "spring.kafka.consumer.group-id=test-group"
    ]
)
class KafkaTest {
    // ...
}

문제 원인

port가 충돌이 돼서 두 개의 kafka 인스턴스가 동일한 9092 port를 사용하려고 했음

1. Docker Compose의 Kafka: localhost:9092 port 사용
2. @EmbeddedKafka: 테스트 실행 시 localhost:9092 port 사용하려고 시도

잘못된 접근

처음에는 "테스트를 위해서 Kafka가 필요해서 Docker로 Kafka를 띄워놓자"라는 생각으로 docker-compose로 kafka, zookeeper 를 실행했다.

그런데 @EmbeddedKafka도 함께 사용하면서 동일한 port를 두번 바인딩하려는 문제가 발생했다.

해결 방법

✅ 방법 1: @EmbeddedKafka를 제거하고 Docker kafka 사용

Docker Compose로 이미 Kafka를 띄웠다면, @EmbeddedKafka를 제거하고 Docker Kafka를 테스트에서도 사용하는 것이 좋습니다.

@DataJpaTest
@ComponentScan(basePackages = ["com.hhplus.ecommerce"])
// @EmbeddedKafka 제거!
@TestPropertySource(
    properties = [
        "spring.jpa.hibernate.ddl-auto=create-drop",
        "spring.datasource.url=jdbc:h2:mem:testdb",
        "spring.datasource.driver-class-name=org.h2.Driver",
        "spring.jpa.database-platform=org.hibernate.dialect.H2Dialect",
        "spring.kafka.enabled=true",
        "spring.kafka.bootstrap-servers=localhost:9093",  // Docker의 호스트 포트 사용
        "spring.kafka.consumer.group-id=test-group"
    ]
)
class KafkaTest {
    // Docker Kafka 사용
}

주의사항: Docker Compose의 PLAINTEXT_HOST://localhost:9093 리스너를 사용한다.

장점

• 실제 운영 환경과 유사한 통합 테스트
• Docker Compose 설정을 테스트에서도 재사용
• 별도의 Kafka 인스턴스 관리 불필요

단점

• 테스트 전에 Docker Kafka가 실행 중이어야 함
• CI/CD 환경에서 Docker 설정 필요

✅ 방법 2: Docker 중지하고 @EmbeddedKafka만 사용

완전히 격리된 테스트 환경을 원한다면 Docker를 내리고 @EmbeddedKafka만 사용한다.

# 테스트 전
docker-compose down

# 테스트 실행
./gradlew test

# 로컬 개발 시 다시 시작
docker-compose up -d

장점

• 완전히 독립적인 테스트 환경
• 외부 의존성 없이 테스트 실행 가능
• CI/CD 환경에서도 동일하게 동작

단점

• 테스트할 때마다 Docker를 내렸다 올려야 함
• 로컬 개발과 테스트 환경 전환 번거로움

결론

Docker Compose로 Kafka를 띄워놨다면, @EmbeddedKafka를 제거하고 Docker Kafka를 테스트에서 사용한다.

핵심은 한 가지 Kafka 인스턴스만 사용하는 것이다. 두 개를 동시에 사용하려고 하면 포트 충돌이 발생하기 때문이다.

선택 기준

참고: 멀티 포트 설정의 의미

Docker Compose에서 두 개의 포트를 노출한 이유:

ports:
  - "9092:9092"  # 컨테이너 간 통신용 (PLAINTEXT://kafka:9092)
  - "9093:9093"  # 호스트 접근용 (PLAINTEXT_HOST://localhost:9093)

• 9092: Docker 네트워크 내부에서 사용 (컨테이너끼리 통신)
• 9093: 호스트(로컬 PC)에서 접근할 때 사용 (애플리케이션 → Kafka)

이 글에서는 Apache Kafka를 로컬 환경에 띄우고, CLI를 사용하여 토픽 생성, 메시지 발생 및 구독을 직접 실습하는 방법을 적어보려고 한다.

(이 가이드는 Docker Descktop이 설치된 MacOS 환경을 기준으로 작성되어있다.)

1. 환경 설정: Docker-Compose Kafka 클러스터 실행

카프카는 안정적인 실행을 위해 메터데이터를 관리하는 Zookeper와 함께 구동된다. Docker를 사용하여 이 두 서버를 동시에 실행한다.

1.1. docker-compose.yml 파일 작성

작업 폴더를 생성한 후, 아래 내용을 docker-compose.yml 파일을 작성한다. 이 설정은 카프카 브로커를 localhost:9092 포트로 외부에 노출한다.

services:
  zookeeper:
    image: confluentinc/cp-zookeeper:7.5.0
    container_name: zookeeper
    environment:
      ZOOKEEPER_CLIENT_PORT: 2181
      ZOOKEEPER_TICK_TIME: 2000

  kafka:
    image: confluentinc/cp-kafka:7.5.0
    container_name: kafka
    depends_on:
      - zookeeper
    ports:
      - "9092:9092" # 호스트 포트: 컨테이너 포트
    environment:
      KAFKA_BROKER_ID: 1
      KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181
      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://localhost:9092
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1

1.2. 컨테이너 실행

터미널에서 docker-compose.yml 파일이 있는 디렉토리로 이동하여 실행한다.

# 백그라운드에서 컨테이너 실행
docker-compose up -d

# 실행 상태 확인
docker ps

💡 확인: kafka와 zookeeper 두 컨네이터 상태가 Up으로 표시되면 성공.

2. CLI를 이용하여 실시간 메시지 흐름 실습

컨테이너가 정상적으로 실행되었다면, 이제 카프카의 기본 명령어 도구를 사용하여 메시지 흐름을 알아보도록하자. 모든 명령은 카프카 컨테이너 내부에서 실행된다.

2.1. 컨테이너 접속 및 토픽 생성

메시지를 주고받기 위해 study-topic이라는 이름의 토픽을 먼저 생성한다.

# 카프카 컨테이너 내부 쉘 접속
docker exec -it kafka /bin/bash

# 토픽 생성 명령어
kafka-topics --create --topic study-topic --bootstrap-server localhost:9092 --replication-factor 1

2.2. Consumper (구독자) 실행

새로운 터미널 탭을 열고, 컨테이너에 다시 접속한 뒤 Consumer를 실행한다. Consumer는 --from-beginnig 옵션으로 기존에 저장된 메시지부터 읽기 시작한다.

# 새 터미널 탭에서 카프카 컨테이너 접속
docker exec -it kafka /bin/bash

# Consumer 실행 (구독 시작)
kafka-console-consumer --topic study-topic --from-beginning --bootstrap-server localhost:9092
# 이제 이 창은 메시지를 기다리는 상태가 된다.

2.3. Producer (발행자) 실행

또 다른 새로운 터미널 탭을 열고, Producer를 실행하여 메시지를 발행한다.

# 세 번째 터미널 탭에서 카프카 컨테이너 접속
docker exec -it kafka /bin/bash

# Producer 실행 (메시지 발행 시작)
kafka-console-producer --topic study-topic --bootstrap-server localhost:9092

📌 실습 및 확인

1. Producer 터미널에 메시지를 입력하고 Enter.
2. 메시지를 입력하는 즉시 Consumer 터미널에 메시지가 출력되는 것을 확인.
3. Consumper 터미널을 종료하지 않은 채 Producer로 메시지를 계속 보내보면 이것이 실시간 스트리밍의 핵심이라고 알 수 있다.

2.4. 영속성 (Durability) 확인

Consumper를 종료한 후, Producer로 메시지를 5개 더 보내본다. 그리고 Consumper를 다시 실행한다.

# Consumer를 다시 실행 (새로운 Consumer)
docker exec -it kafka /bin/bash
kafka-console-consumer --topic study-topic --from-beginning --bootstrap-server localhost:9092

💡 확인: Consumer가 꺼져있을 때 전송했던 5개의 메시지를 포함하여 모든 메시지가 다시 출력된다. 이는 카프카가 메시지를 디스크에 안전하게 저장(영속성) 하기 때문이다.

3. 실습 환경 정리

실습을 마쳤다면, 불필요한 리소스 사용을 막기 위해 컨테이너를 종료한다.

# docker-compose.yml이 있는 폴더에서 실행
docker-compose down

이제 카프카의 기본적인 메시지 발생/구독 흐름을 이해하게 됐다. 실제 어플리케이션에 카프카를 적용하여 사용해보면서 심화적인 과정을 배우면 될 거 같다.

1. kafka의 정의 및 특징

카프카는 대규모 데이터를 실시간으로 처리를 하기 위해 설계된 분산 이벤트 스트리밍 플랫폼이다.

2. kafka의 주요 구성 요소

Broker (브로커)

• kafka 클러스터를 구성하는 개별 서버다.
• 데이터를 수신, 저장하고 consumer에게 전달하는 핵심 역할을 한다.

Topic & Partition (토픽과 파티션)

• Topic: 데이터가 저장되는 카테고리(이름표). (예: user-login-logs)
• Partition: 하나의 토픽을 여러 개로 나눈 물리적인 저장 단위.
  • partition을 통해 병렬 처리가 가능해지고, 데이터는 파티션 내에서 Offset 순서대로 저장된다.

Producer / Consumer (프로듀서 / 컨슈머)

• Producer: 메시지를 생성하여 특정 토픽으로 발행(Publish)하는 주체.
• Consumer: 토픽을 구독(Subscribe)하여 데이터를 가져와서 처리하는 주체.
• Consumer Group: 여러 consumper가 협력하여 하나의 토픽을 병렬로 처리할 수 있게 돕는 단위.

3. 왜 대용량 시스템에서 kafka를 사용할까?

대용량 시스템에서 kafka가 필수적인 이유는 아래와 같다.

1. 압도적인 처리량 (High Throughput)
   • 일반적인 메시지 큐와 달리 디스크 순차 쓰기(Sequential I/O)와 Zero-copy 기술을 사용하여 초당 수백만 건의 데이터를 처리할 수 있다.
2. 느슨한 결합 (Decoupling)
   • 데이터를 보내는 곳과 받는 곳이 서로의 존재를 몰라도 된다. kafka가 중간 큐 역할을 해주므로 시스템 간 의존성이 낮아진다.
3. 데이터 유실 방지
   • 데이터를 디스크에 물리적으로 저장하고 복제본을 유지하기 때문에, 갑작스러운 서버 다운에도 데이터가 안전하게 보존된다.
4. 유연한 확장성
   • 트래픽이 늘어나면 브로커 서버를 추가하거나 파티션을 늘리는 방식으로 아주 쉽게 성능을 확장할 수 있다.

이커머스 서비스를 개발하다 보면 가장 신경 쓰이는 부분은 바로 데이터 정합성이다. 혼자 테스트를 통해서 실행했던 기능들이 수천 명이 동시에 "결제"나 "선착순 쿠폰 발급"을 받으려고 할 때 순식간에 무너질 수 있다.

그래서 공부하면서 진행한 이커머스 프로젝트에서 발생한 동시성 이슈를 해결하기 위해 비관적 락(Perssimistic Lock), 낙관적 락(Optimistic Lock), 그리고 분산 락(Distributed Lock) 을 어떻게 적용했는지, 그리고 분산 락 적용 시 겪었던 트랜잭션 범위 문제를 어떻게 해결했는지 정리하려고 한다.

동시성 제저 기법 비교 (개념편)

프로젝트에 적용하기 앞서, 세 가지 락의 특징을 간단히 짚고 넘어가자면

비관적 락 (Perssimistic Lock)

• 개념: 충돌이 발생할 수 있다는 상황을 비관적으로 가정하면서 데이터를 읽을 때부터 DB Lock을 걸어버리는 방식이다. (SELECT ... FOR UPDATE)
• 장점: 데이터 정합성을 강력하게 보장한다.
• 단점: 락을 잡고 있는 동안 다른 트랜잭션이 대기를 해야하기 때문에 성능 저하가 발생할 수 있고, Deadlcok 위험이 있다.
• 적용처: 주문, 결제 (데이터의 절대적인 무결성이 속도보다 중요하다고 판단)

낙관적 락 (Optimistic Lock)

• 개념: 여러 서버(또는 인스턴스)가 공통으로 사용하는 저장소(주로 Redis)를 이용해서 락을 제어.
• 장점: DB 부하를 줄일 수 있고, 분산 환경에서 정합성을 보장.
• 단점: 구현이 복잡하면서 별도의 인프라(Redis 등)가 필요
• 적용처: 선착순 쿠폰 발급 (짧은 시간에 트래픽이 몰리는 구간).

시나리오별 적용 전략

현재 이 프로젝트에서는 각 비즈니스 로직 특성에 맞추어 다른 전략으로 진행했다.

Case 1 - 주문 및 결제 (비관적 락)

주문과 결제는 포인트 차감, 재고 감소 등 데이터의 정확성이 최우선이다. 트래픽이 쿠폰만큼 순간적으로 폭발할 가능성은 적지만, 동시에 같은 주문 건을 처리하는 것을 막기 위해 비관적 락을 사용했다.

// Repository
@Lock(LockModeType.PESSIMISTIC_WRITE)
@Query("select p from Payment p where p.id = :id")
fun findByIdForUpdate(id: Long): Payment?

Case 2 - 선착순 쿠폰 발급 (분산 락)

선착순 이벤트는 DB 락으로만 제어를 한다면 수많은 대기열이 DB 커넥션을 점유하면서 전체 서비스 장애로 이어질 수 있다. 따라서 Redis를 이용한 분산 락을 도입했다.

하지만, 여기서 "분산 락과 DB 트랜잭션의 범위" 문제가 있었다.

문제 상황 - 분산 락을 썼는데 데이터 정합성 ❌

처음에는 아래와 같은 구조로 코드를 짰다. (데이터 정합성을 위해서 DB 락까지 이중으로 건 상황)

• 기존 로직 (문제점)
  1. @Transactional 시작
  2. 분산 락 획득 (Redis)
  3. 불안해서 DB 비관적 락도 획득
  4. 쿠폰 발급 로직 수행
  5. 분산 락 해제
  6. @Transactional 커밋

이렇게 분산 락 + DB 비관적 락 을 혼용하게 되면 데드락 위험이 커지면서 성능도 떨어진다. 목표는 "DB 락 없이 분산락만으로 깔끔하게 처리하는 것" 이었다.

하지만 단순히 DB 락을 빼고 분산 락만 사용한다면 동시성 이슈가 다시 발생했다. 이유는 트랜잭션 커밋 시점과 락 해제 시점이 불일치했다.

1. Thread A가 로직을 다 수행하고 락을 해제함.
2. 하지만 Thread A의 DB 트랜잭션은 아직 커밋되지 않음 (DB 반영전)
3. 그 사이 Thread B가 락을 획득하고 데이터를 읽음. -> Thread A의 변경 상항을 못 보고 과거 데이터를 읽음
4. 결국 정합성 깨짐.

해결 Facade 패턴으로 락 범위 제어하기

이 문제를 해결하기 위해서는 "락의 범위가 트랜잭션의 범위보다 커야 한다." 즉, 트랜잭션이 완전히 커밋된 후에 락을 풀어야 한다.

이를 위해서 Facade 패턴을 적용하여 비즈니스 로직(트랜잭션)을 락으로 감싸는 구조로 리팩토링했다.

1. 사용자가 쿠폰 발급 시 Redisson Lock을 획득하고 획득 성공 여부 판단
2. 쿠폰 발급 트랜잭션을 시작하고 쿠폰을 발급하는 로직 실행.
3. 트랜잭션 커밋 -> DB 반영
4. 획득한 Redisson Lock 해제

코드 예시 (Kotlin)

CouponService (트랜잭션 담당) 순수한 비즈니스 로직만 담당하며, @Transactional을 가진다.

@Service
class CouponService(
    private val couponRepository: CouponRepository
) {
    @Transactional // 트랜잭션은 여기서만 동작.
    fun issueCoupon(couponId: Long, userId: Long) {
        val coupon = couponRepository.findById(couponId)
            ?: throw IllegalArgumentException("쿠폰이 없습니다.")

        coupon.decreaseQuantity() // 수량 감소

        // 발급 로직
    }
}

CoupnFacade (락 제어 담당) 트랜잭션 없이 락의 획득 및 해제만 담당하면서, 실제 로직은 Service에 위임한다.

@Component
class CouponFacade(
    private val redissonClient: RedissonClient,
    private val couponSerivce: CouponService
) {
    fun issueCouponWithLock(userId: Long, couponId: Long) {
        val lock = redissonClient.getLock("coupon_lock:$couponId")

        try {
            // 락 획득 시도
            val available = lock.tryLock(10, 1, TimeUnit.SECONDS)

            if (!available) {
                return
            }

            couponService.issueCoupon(couponId, userId)
        } catch (e: InterruptedException) {
            throw RuntimeException(e)
        } finally {
            if(lock.isLocked && lock.isHeldByCurrentThread) {
                lock.unlock()
            }
        }
    }
}

결론

이번 프로젝트를 통해서 상황에 맞는 동시성 제어 방식이 무엇인지 깊이 고민할 수 있었다.

1. 비관적 락: 데이터 정합성이 중요한 결제/주문 로직에 적합하다고 판단.
2. 분산 락: 트래픽이 몰리는 선착순 이벤트에 적합하며, DB 부하를 줄인다.
3. 트랜잭션과 락의 범위: 분산 락 사용 시 반드시 "Lock 획득 -> Transaction 시작/종료 -> Lock 해제" 순서를 지켜야 데이터 정합성이 깨지지 않는다.

단순히 "락을 걸었다"에서 끝나는게 아니라, DB의 격리 수준과 트랜잭션의 생명주기기까지 고려해야 완벽한 동시성 제어가 가능하단걸 알게되었다.

이 의문을 해결하는 핵심이 의존성 역전 원칙이었다. SOLID 원칙 중 마지막 "D"에 해당하는 이 원칙은, 제대로 이해하면 아키텍처 설계의 핵심을 꿰뚫을 수 있다.

🤔 문제 상황

@Service
class OrderService(
    private val mySqlOrderRepository: MySqlOrderRepository  // 구체 클래스에 의존 💥
) {
    fun createOrder(order: Order): Order {
        return mySqlOrderRepository.save(order)
    }
}

@Repository
class MySqlOrderRepository {
    fun save(order: Order): Order {
        // MySQL에 저장하는 구체적인 로직
        val sql = "INSERT INTO orders ..."
        // ...
        return order
    }
}

문제점

1. MySQL에서 MongoDB로 변경하려면? -> OrderService 코드 수정이 필요 💥
2. 테스트하려면 -> 실제 MySQL이 필요 💥
3. Service가 저수준 모듈(DB)에 의존 -> 비즈니스 로직이 기술에 종속 💥

🎯 의존성 역전 원칙이란?

Robert C. Martin이 정의한 원칙!

A. 고수준 모듈은 저수준 모듈에 의존해서는 안된다. 둘 다 추상화에 의존

B. 주상화는 세부사항에 의존해서는 안되고, 세부사항이 추상화에 의존해야 한다.

용어 정리

📊 전통적 의존성 vs 역전된 의존성

전통적 의존성 (나쁜 예)

┌─────────────────┐
│  OrderService   │  (고수준)
└────────┬────────┘
         ↓ 의존 (직접 참조)
┌─────────────────┐
│ MySqlRepository │  (저수준)
└─────────────────┘

문제: 고수준 모듈이 저수준 모듈에 의존 → 변경에 취약

역전된 의존성 (좋은 예)

┌─────────────────┐
│  OrderService   │  (고수준)
└────────┬────────┘
         ↓ 의존 (인터페이스)
┌─────────────────────┐
│ OrderRepository     │  (추상화 - Interface)
└─────────┬───────────┘
          ↑ 구현 (implements)
┌─────────────────────┐
│ MySqlRepository     │  (저수준)
└─────────────────────┘

해결: 고수준과 저수준 모두 추상화에 의존 -> 유연함!

🔑 코드로 이해하기

❌ 나쁜 예: DIP 위반

// Service가 구체 클래스에 직접 의존
@Service
class OrderService(
    private val mySqlOrderRepository: MySqlOrderRepository  // 💥 구체 클래스
) {
    fun createOrder(order: Order): Order {
        return mySqlOrderRepository.save(order)
    }
}

@Repository
class MySqlOrderRepository {
    fun save(order: Order): Order {
        // MySQL 저장 로직
    }
}

문제점:

// MongoDB로 변경하려면 Service 코드 수정 필요!
@Service
class OrderService(
    // private val mySqlOrderRepository: MySqlOrderRepository  // 삭제
    private val mongoOrderRepository: MongoOrderRepository     // 추가
) {
    fun createOrder(order: Order): Order {
        return mongoOrderRepository.save(order)  // 메서드 호출도 변경
    }
}

✅ 좋은 예: DIP 적용

1단계: 인터페이스 정의 (Domain Layer)

// domain/order/OrderRepository.kt
package com.hhplus.ecommerce.domain.order

// ✅ 고수준 모듈(Domain)이 정의하는 인터페이스
interface OrderRepository {
    fun save(order: Order): Order
    fun findById(id: Long): Order?
    fun findByUserId(userId: Long): List<Order>
}

2단계: Service는 인터페이스에 의존 (Application Layer)

// application/order/OrderService.kt
package com.hhplus.ecommerce.application.order

import com.hhplus.ecommerce.domain.order.OrderRepository  // 인터페이스
import com.hhplus.ecommerce.domain.order.Order

@Service
class OrderService(
    private val orderRepository: OrderRepository  // ✅ 추상화에 의존!
) {
    fun createOrder(order: Order): Order {
        return orderRepository.save(order)
    }
}

3단계: 구현체들 (Infrastructure Layer)

// infrastructure/order/MySqlOrderRepository.kt
package com.hhplus.ecommerce.infrastructure.order

import com.hhplus.ecommerce.domain.order.OrderRepository  // Domain 인터페이스
import com.hhplus.ecommerce.domain.order.Order

@Repository
@Primary  // 기본 구현체
class MySqlOrderRepository : OrderRepository {
    override fun save(order: Order): Order {
        // MySQL 저장 로직
        println("MySQL에 저장")
        return order
    }

    override fun findById(id: Long): Order? {
        // MySQL 조회 로직
    }
}

// infrastructure/order/MongoOrderRepository.kt
package com.hhplus.ecommerce.infrastructure.order

import com.hhplus.ecommerce.domain.order.OrderRepository
import com.hhplus.ecommerce.domain.order.Order

@Repository
class MongoOrderRepository : OrderRepository {
    override fun save(order: Order): Order {
        // MongoDB 저장 로직
        println("MongoDB에 저장")
        return order
    }

    override fun findById(id: Long): Order? {
        // MongoDB 조회 로직
    }
}

장점:

• DB 변경 시 Service 코드는 전혀 수정할 필요없음.
• application.yml 또는 @Primary만 변경하면 끝.

🔁 의존성 방향이 역전되는 이유

전통적 방식

// OrderService.kt (상위 모듈)
class OrderService(
    private val repository: MySqlOrderRepository  // 하위 모듈 직접 참조
)

// MySqlOrderRepository.kt (하위 모듈)
class MySqlOrderRepository {
    // 구현
}

의존성 방향: OrderService -> MySqlOrderRepository

DIP 적용

// Domain Layer
interface OrderRepository {  // 고수준 모듈이 정의
    fun save(order: Order): Order
}

// Application Layer
class OrderService(
    private val repository: OrderRepository  // 인터페이스 의존
)

// Infrastructure Layer
class MySqlOrderRepository : OrderRepository {  // 인터페이스 구현
    override fun save(order: Order): Order { ... }
}

의존성 방향:

• OrderService -> OrderRepository (인터페이스)
• MySqlOrderRepository -> OrderRepository (인터페이스 구현)

핵심: 구현체가 인터페이스에 의존하므로, 의존성 방향이 역전됨.

전통정: 상위 -> 하위 역전됨: 상위 -> 인터페이스 <- 하위

🎯 실제 적용 예시

예시1: 알림 시스템

// ❌ DIP 위반
@Service
class OrderService(
    private val smtpEmailService: SmtpEmailService  // SMTP에 강하게 결합
) {
    fun createOrder(order: Order) {
        // ...
        smtpEmailService.sendEmail(
            to = "user@example.com",
            subject = "주문 완료",
            body = "주문이 완료되었습니다"
        )
    }
}

class SmtpEmailService {
    fun sendEmail(to: String, subject: String, body: String) {
        // SMTP 프로토콜로 이메일 전송
    }
}

이 코드의 문제는 이메일을 slack으로 알림을 변경하려면 Service 전체 수정이 필요하다.

// ✅ DIP 적용
// domain/port/NotificationPort.kt (Domain이 정의)
interface NotificationPort {
    fun sendOrderConfirmation(order: Order)
}

// application/order/OrderService.kt
@Service
class OrderService(
    private val notificationPort: NotificationPort  // 추상화에 의존
) {
    fun createOrder(order: Order) {
        // ...
        notificationPort.sendOrderConfirmation(order)  // 구현 방법은 모름!
    }
}

// infrastructure/notification/EmailNotificationAdapter.kt
@Component
class EmailNotificationAdapter : NotificationPort {
    override fun sendOrderConfirmation(order: Order) {
        // SMTP로 이메일 전송
    }
}

// infrastructure/notification/SlackNotificationAdapter.kt
@Component
class SlackNotificationAdapter : NotificationPort {
    override fun sendOrderConfirmation(order: Order) {
        // Slack API로 메시지 전송
    }
}

이 코드의 장점은 이메일에서 slacke으로 변경을 할 때 Service 코드 수정이 불필요하다.

🧪 테스트 용이성

❌ DIP 미적용 (테스트 어려움)

class OrderServiceTest {
    @Test
    fun `주문 생성 테스트`() {
        val service = OrderService(
            MySqlOrderRepository()
        )

        // MySQL이 없으면 테스트 불가
    }
}

✅ DIP 적용 (테스트 쉬움)

// 테스트용 Fake Repository
class FakeOrderRepository : OrderRepository {
    private val storage = mutableMapOf<Long, Order>()

    override fun save(order: Order): Order {
        storage[order.id!!] = order
        return order
    }

    override fun findById(id: Long): Order? = storage[id]
}

class OrderServiceTest {
    @Test
    fun `주문 생성 테스트`() {
        // ✅ DB 없이도 테스트 가능!
        val fakeRepository = FakeOrderRepository()
        val service = OrderService(fakeRepository)

        val order = service.createOrder(
            Order.create(userId = 1L, items = listOf(...))
        )

        assertNotNull(order.id)
    }

    @Test
    fun `주문 생성 시 알림 전송 테스트`() {
        // ✅ Mock으로 쉽게 검증
        val mockNotification = mock<NotificationPort>()
        val service = OrderService(
            orderRepository = fakeRepository,
            notificationPort = mockNotification
        )

        service.createOrder(order)

        verify(mockNotification).sendOrderConfirmation(any())
    }
}

📁 레이어드 아키텍처에서 DIP

┌─────────────────────────────────────┐
│  Application Layer                  │
│  ┌────────────────┐                 │
│  │ OrderService   │                 │
│  └────────┬───────┘                 │
└───────────┼─────────────────────────┘
            ↓ 의존 (인터페이스)
┌───────────────────────────────────────┐
│  Domain Layer                         │
│  ┌────────────────────────────────┐   │
│  │ OrderRepository (interface)    │   │  ← 고수준이 정의!
│  └────────────────────────────────┘   │
└───────────────────────────────────────┘
            ↑ 구현 (implements)
┌───────────────────────────────────────┐
│  Infrastructure Layer                 │
│  ┌────────────────────────────────┐   │
│  │ MySqlOrderRepository           │   │  ← 저수준이 구현!
│  │ (implements OrderRepository)   │   │
│  └────────────────────────────────┘   │
└───────────────────────────────────────┘

핵심은 Domain이 인터페이스를 정의하고, infrastructure가 구현을 한다.

의존성 역전 원칙은 단순히 "인터페이스를 만들자"가 아니라 "누가 인터페이스를 정의하고 소유하는가" 의 문제다. 고수준 모듈이 필요로 하는 것을 인터페이스로 정의하고, 저수준 모듈이 그것을 구현하게 만드는 것. 이것이 의존성을 역전시키는 핵심이다!

클린 아키텍처는 레이어드 아키텍처의 문제점을 해결하고 더 엄격한 의존성 규칙을 적용한 아키텍처 패턴이다. Rovert C.Martin이 제안한 이 패턴은 비즈니스 로직을 외부로부터 완전히 독립시키는 것을 목표로 한다.

🙀 레이어드 아키텍처의 한계

레이어드 아키텍처에서는 아래와 같은 구조를 사용했다.

Presentation -> Application -> Domain <- Infrastructure

하지만 규모가 커지면 어떤 문제가 발생할까?

// ❌ 레이어드 아키텍처의 흔한 실수
@Service
class OrderService(
    private val orderRepository: OrderRepository,  // Domain 인터페이스
    private val emailService: EmailService,        // 외부 서비스
    private val paymentGateway: PaymentGateway    // 외부 API
) {
    fun createOrder(order: Order) {
        // 비즈니스 로직이 외부 시스템과 강하게 결합됨 💥
        orderRepository.save(order)
        emailService.sendOrderConfirmation(order)   // SMTP 의존
        paymentGateway.processPayment(order)        // PG사 API 의존
    }
}

위 코드의 문제점은 아래와 같다.

• 비즈니스 로직이 외부 시스템(이메일, 결제)과 강하게 결합
• SMTP 서버가 없으면 테스트 불가능
• 결제 게이트웨이를 바꾸려면 Service 수정 필요

🎯 클린 아키텍처란?

의존성은 항상 안쪽(고수준 정책)을 향한다 -> 이것이 클린 아키텍처의 핵심 규칙이다.

동심원 구조

┌─────────────────────────────────────────────────┐
│  Frameworks & Drivers (최외곽)                    │
│  ┌───────────────────────────────────────────┐  │
│  │  Interface Adapters                       │  │
│  │  ┌─────────────────────────────────────┐  │  │
│  │  │  Application Business Rules         │  │  │
│  │  │  ┌───────────────────────────────┐  │  │  │
│  │  │  │  Enterprise Business Rules    │  │  │  │
│  │  │  │  (Entities)                   │  │  │  │
│  │  │  └───────────────────────────────┘  │  │  │
│  │  │  (Use Cases)                        │  │  │
│  │  └─────────────────────────────────────┘  │  │
│  │  (Controllers, Presenters, Gateways)      │  │
│  └───────────────────────────────────────────┘  │
│  (Web, DB, UI, External Interfaces)             │
└─────────────────────────────────────────────────┘

의존성 방향은 항상 외부 -> 내부이다.

4개의 계층

Entities (Enterprise Business Rules)

가장 안쪽 - 핵심 비즈니스 규칙

// domain/order/Order.kt
data class Order(
    val id: Long?,
    val userId: Long,
    val items: List<OrderItem>,
    private var status: OrderStatus,
    private val _totalAmount: BigDecimal
) {
    val totalAmount: BigDecimal get() = _totalAmount

    // ✅ 비즈니스 규칙만 포함 (외부 의존성 ZERO)
    fun cancel() {
        require(status == OrderStatus.PENDING) {
            "대기 중인 주문만 취소할 수 있습니다"
        }
        status = OrderStatus.CANCELLED
    }

    fun complete() {
        require(status == OrderStatus.PENDING) {
            "대기 중인 주문만 완료할 수 있습니다"
        }
        status = OrderStatus.COMPLETED
    }

    fun canCancel(): Boolean = status == OrderStatus.PENDING

    companion object {
        fun create(userId: Long, items: List<OrderItem>): Order {
            require(items.isNotEmpty()) { "주문 상품이 비어있습니다" }

            val totalAmount = items.sumOf { it.calculateAmount() }

            return Order(
                id = null,
                userId = userId,
                items = items,
                status = OrderStatus.PENDING,
                _totalAmount = totalAmount
            )
        }
    }
}

특징은

• 순수 비즈니스 로직만 포함
• 프레임워크, DB, UI 등 모든 외부 의존성으로부터 독립
• 변경 빈도가 가장 낮음

Use Case (Application Business Rules)

애플리케이션 특화 비즈니스 규칙

// application/order/usecase/CreateOrderUseCase.kt
interface CreateOrderUseCase {
    fun execute(command: CreateOrderCommand): Order
}

// application/order/usecase/CreateOrderUseCaseImpl.kt
@Component
class CreateOrderUseCaseImpl(
    private val orderRepository: OrderRepository,        // 포트(인터페이스)
    private val stockRepository: StockRepository,        // 포트(인터페이스)
    private val notificationPort: NotificationPort,      // 포트(인터페이스)
    private val paymentPort: PaymentPort                 // 포트(인터페이스)
) : CreateOrderUseCase {

    override fun execute(command: CreateOrderCommand): Order {
        // 1. 재고 확인 및 차감
        val stock = stockRepository.findById(command.productId)
            ?: throw ProductNotFoundException()
        stock.decrease(command.quantity)

        // 2. 주문 생성 (Entity가 비즈니스 규칙 처리)
        val order = Order.create(
            userId = command.userId,
            items = command.items
        )

        // 3. 결제 처리 (포트를 통해)
        paymentPort.processPayment(order)

        // 4. 알림 전송 (포트를 통해)
        notificationPort.sendOrderConfirmation(order)

        // 5. 저장
        stockRepository.save(stock)
        return orderRepository.save(order)
    }
}

특징은

• 애플리케이션의 use case 구현
• Entity를 조율
• 외부 시스템과의 통신은 포트(interface)를 통해서 진행.

Interface Adapters(Controllers, Presenters, Gateways)

외부와 내부를 연결하는 어댑터

// adapter/in/web/OrderController.kt (Input Adapter)
@RestController
@RequestMapping("/api/orders")
class OrderController(
    private val createOrderUseCase: CreateOrderUseCase
) {
    @PostMapping
    fun createOrder(@RequestBody request: CreateOrderRequest): OrderResponse {
        // DTO → Command 변환
        val command = CreateOrderCommand(
            userId = request.userId,
            items = request.items.map { 
                OrderItem(it.productId, it.quantity) 
            }
        )

        // Use Case 호출
        val order = createOrderUseCase.execute(command)

        // Domain → DTO 변환
        return OrderResponse.from(order)
    }
}

// adapter/out/persistence/OrderRepositoryAdapter.kt (Output Adapter)
@Repository
class OrderRepositoryAdapter(
    private val jpaRepository: JpaOrderRepository
) : OrderRepository {  // Domain의 포트 구현

    override fun save(order: Order): Order {
        val entity = OrderEntity.from(order)
        val saved = jpaRepository.save(entity)
        return saved.toDomain()
    }

    override fun findById(id: Long): Order? {
        return jpaRepository.findById(id)
            .map { it.toDomain() }
            .orElse(null)
    }
}

// adapter/out/notification/EmailNotificationAdapter.kt (Output Adapter)
@Component
class EmailNotificationAdapter(
    private val emailService: EmailService
) : NotificationPort {  // Domain의 포트 구현

    override fun sendOrderConfirmation(order: Order) {
        emailService.send(
            to = getUserEmail(order.userId),
            subject = "주문 확인",
            body = "주문이 완료되었습니다. 주문번호: ${order.id}"
        )
    }
}

특징

• Controller: 웹 요청을 Use Case 호출로 변환 (Input Adapter)
• Repository Adapter: Domain 포트를 실제 DB 연동으로 구현 (Output Adapter)
• Notification Adapter: Domain 포트를 실제 이메일 서비스로 구현 (Output Adapter)

Framworks & Drivers

가장 바깥쪽 - 프레임워크와 도구

// infrastructure/config/EmailConfig.kt
@Configuration
class EmailConfig {
    @Bean
    fun emailService(): EmailService {
        return SmtpEmailService(/* SMTP 설정 */)
    }
}

특징

• Spring, JPA, SMTP 등 구체적인 기술
• 가장 자주 변경되는 계층
• 내부 계층에 영향을 주지 않음

🔑 핵심 개념: 포트와 어댑터 (Hexagonal Architecture)

클린 아키텍처는 헥사고날 아키텍처(Ports And Adapter)와 매우 유사하다.

Port

Domain이 정의하는 interface

// domain/port/out/NotificationPort.kt (Output Port)
interface NotificationPort {
    fun sendOrderConfirmation(order: Order)
    fun sendShippingNotification(order: Order)
}

// domain/port/out/PaymentPort.kt (Output Port)
interface PaymentPort {
    fun processPayment(order: Order): PaymentResult
    fun refund(order: Order): RefundResult
}

// domain/port/in/CreateOrderUseCase.kt (Input Port)
interface CreateOrderUseCase {
    fun execute(command: CreateOrderCommand): Order
}

Adapter

포트의 구현체

// adapter/out/notification/EmailNotificationAdapter.kt
@Component
class EmailNotificationAdapter : NotificationPort {
    override fun sendOrderConfirmation(order: Order) {
        // SMTP로 이메일 전송
    }
}

// adapter/out/notification/SlackNotificationAdapter.kt
@Component
class SlackNotificationAdapter : NotificationPort {
    override fun sendOrderConfirmation(order: Order) {
        // Slack API로 메시지 전송
    }
}

장점: email에서 slack으로 변경해도 Domain, Use case는 수정 불필요.

📁 클린 아키텍처 프로젝트 구조

src/main/kotlin/com/hhplus/ecommerce/
│
├── domain/                          # 1️⃣ Entities (최내부)
│   ├── order/
│   │   ├── Order.kt                # 비즈니스 규칙
│   │   ├── OrderItem.kt
│   │   └── OrderStatus.kt
│   │
│   └── port/                        # 포트 정의
│       ├── in/                      # Input Port (Use Case 인터페이스)
│       │   ├── CreateOrderUseCase.kt
│       │   └── CancelOrderUseCase.kt
│       │
│       └── out/                     # Output Port
│           ├── OrderRepository.kt
│           ├── NotificationPort.kt
│           └── PaymentPort.kt
│
├── application/                     # 2️⃣ Use Cases
│   └── order/
│       ├── CreateOrderUseCaseImpl.kt
│       └── CancelOrderUseCaseImpl.kt
│
├── adapter/                         # 3️⃣ Interface Adapters
│   ├── in/                          # Input Adapter
│   │   └── web/
│   │       └── OrderController.kt
│   │
│   └── out/                         # Output Adapter
│       ├── persistence/
│       │   └── OrderRepositoryAdapter.kt
│       │
│       ├── notification/
│       │   ├── EmailNotificationAdapter.kt
│       │   └── SlackNotificationAdapter.kt
│       │
│       └── payment/
│           └── TossPaymentAdapter.kt
│
└── infrastructure/                  # 4️⃣ Frameworks & Drivers
    ├── config/
    │   ├── DatabaseConfig.kt
    │   └── EmailConfig.kt
    │
    └── external/
        └── TossPaymentClient.kt

🔄 의존성 흐름

┌──────────────────────────────────────────┐
│  Controller (Adapter In)                 │
└────────────┬─────────────────────────────┘
             ↓ 호출
┌──────────────────────────────────────────┐
│  Use Case (Application)                  │
└─────┬──────────────────┬─────────────────┘
      ↓ 의존             ↓ 의존
┌─────────────┐    ┌──────────────────────┐
│   Entity    │    │   Port (인터페이스)   │
│  (Domain)   │    │   (Domain)           │
└─────────────┘    └──────────┬───────────┘
                              ↑ 구현
                   ┌──────────────────────┐
                   │  Adapter Out         │
                   │  (Persistence 등)    │
                   └──────────────────────┘

핵심: 모든 의존성이 Domain을 바라봄

🆚 레이어드 아키텍처 VS 클린 아키텍처

🤔 언제 클린 아키텍처를 사용할까?

✅ 클린 아키텍처가 적합한 경우

1. 비즈니스 로직이 복잡한 경우
   • 금융, 이커머스, 헬스케어 등
2. 외부 시스템 의존성이 많은 경우
   • 결제 게이트웨이, 이메일 서비스, SMS, Push 알림 등
3. 장기 운영 프로젝트
   • 기술 스택 변경 가능성이 높은 경우
4. 테스트가 중요한 경우
   • TDD를 적극적으로 적용하는 프로젝트

❌ 클린 아키텍처가 과한 경우

1. 단순 CRUD 애플리케이션
   • 복잡한 비즈니스 로직이 없는 경우
2. 프로토타입이나 MVP
   • 빠른 개발이 최우선인 경우
3. 소규모 팀
   • 아키텍처 유지보수 비용이 부담되는 경우

✅ 클린 아키텍처의 장점

1. 독립성

// ✅ Domain과 Use Case는 외부 기술을 전혀 모름
class Order {
    // Spring, JPA, SMTP 등 외부 의존성 ZERO
}

// ✅ 외부 시스템 교체가 자유로움
// EmailNotificationAdapter → SlackNotificationAdapter
// TossPaymentAdapter → KakaoPaymentAdapter

2. 테스트 용이성

class CreateOrderUseCaseTest {
    @Test
    fun `주문 생성 시 알림이 전송된다`() {
        // Mock 생성이 쉬움 (인터페이스만 구현)
        val mockNotification = mock<NotificationPort>()
        val useCase = CreateOrderUseCaseImpl(
            orderRepository = mockOrderRepository,
            notificationPort = mockNotification
        )

        useCase.execute(command)

        verify(mockNotification).sendOrderConfirmation(any())
    }
}

3. 비즈니스 로직 보호

• UI가 바뀌어도 Domain은 안전
• DB가 바뀌어도 Domain은 안전
• framwork가 바뀌어도 Domain은 안전

⚠️ 클린 아키텍처의 단점

1. 높은 초기 비용

• 보일러 플레이트 코드 증가
• 인터페이스와 구현체를 각각 관리

2. 러닝커브

• 팀원 모두가 아키텍처를 이해해야 함
• 잘못 적용하면 오히려 복잡도만 증가

3. 과도한 추상화 위험

interface FindUserPort {
    fun findById(id: Long): User?
}

interface SaveUserPort {
    fun save(user: User): User
}

// ✅ 적절한 수준
interface UserRepository {
    fun findById(id: Long): User?
    fun save(user: User): User
}

‼️ 실무 팁

1. 작게 시작하기

처음부터 완벽한 클린 아키텍처를 적용하려 하지 말기.

1단계: 레이어드 아키텍처로 시작 2단계: Domain을 중심으로 리팩토링 3단계: 외부 의존성을 Port로 분리 4단계: Adapter 패턴 적용

2. Port는 Domain 관점에서 정의

// ❌ 기술 중심
interface SmtpEmailPort {
    fun sendSmtpEmail(to: String, subject: String, body: String)
}

// ✅ Domain 중심
interface NotificationPort {
    fun notifyOrderCreated(order: Order)
    fun notifyOrderShipped(order: Order)
}

3. 과도한 분리는 금물

// ❌ 너무 세분화
interface FindOrderByIdPort
interface FindOrderByUserIdPort
interface SaveOrderPort
interface DeleteOrderPort

// ✅ 적절한 그룹핑
interface OrderRepository {
    fun findById(id: Long): Order?
    fun findByUserId(userId: Long): List<Order>
    fun save(order: Order): Order
    fun delete(id: Long)
}

📊 정리

핵심 원칙:

• Domain은 최중심에, 순수하게
• 외부 의존성은 Port/Adapter로 분리
• 의존성은 항상 내부를 향하도록
• 과도한 추상화는 피하되, 핵심은 지키기

클린 아키텍처는 "완벽한 설계" 가 아니라 "비즈니스 로직을 보호하는 도구" 다. 프로젝트의 규모와 복잡도에 맞게 적절히 적용하는 것이 중요하다. 처음부터 모든 것을 완벽하게 하려고 하지 말고, Domain을 중심을 두고 점진적으로 개선을 해나가면 좋을 거 같다. DDD 공부? 😓~~

특히 "도메인 모델이 비즈니스 규칙을 포함해야 한다"는 요구사항을 보고, Service에 모든 로직을 때려박는 방식이 얼마나 잘못된 것인지 깨달았다. 그래서 레이어드 아키텍처에 대해서 알아보고 싶어서 글에 정리를 해보게 됐다.

🤔 문제 상황

// ❌ 흔히 보는 잘못된 코드
@Service
class OrderService(
    private val orderRepository: OrderRepository,
    private val stockRepository: StockRepository
) {
    fun createOrder(productId: Long, quantity: Int): Order {
        val stock = stockRepository.findById(productId)

        // Service에 비즈니스 규칙이 흩어짐
        if (stock.quantity < quantity) {
            throw Exception("재고 부족")
        }
        stock.quantity -= quantity  // 직접 수정 💥

        val totalAmount = stock.price * quantity  // Service에서 계산 💥

        val order = Order(
            productId = productId,
            quantity = quantity,
            totalAmount = totalAmount
        )

        stockRepository.save(stock)
        return orderRepository.save(order)
    }
}

문제점

• 비즈니스 규칙이 Service에 흩어져있음.
• Domain 객체가 단순 데이터 컨테이너로 전락 (Anemic Domain Model)
• 같은 로직이 여러 Service에 중복될 가능성
• 테스트하기 어려움

레이어드 아키텍처란?

관심사의 분리(Separation of Concerns) 를 통해 시스템을 계층으로 나누는 아키텍처 패턴이다. 각 계층은 명확한 책임을 가지며, 상위 계층은 하위 계층에만 의존한다.

4계층 구조

┌─────────────────────────────────────┐
│   Presentation Layer (표현 계층)      │  ← 외부와의 접점 (Controller, DTO)
├─────────────────────────────────────┤
│   Application Layer (응용 계층)       │  ← 비즈니스 흐름 조율 (Service)
├─────────────────────────────────────┤
│   Domain Layer (도메인 계층)          │  ← 핵심 비즈니스 규칙 (Domain Model)
├─────────────────────────────────────┤
│   Infrastructure Layer (인프라 계층)   │  ← 데이터 저장, 외부 연동
└─────────────────────────────────────┘

프로젝트 구조

src/main/kotlin/com/hhplus/ecommerce/
│
├── presentation/                    # 1️⃣ Presentation Layer
│   └── order/
│       ├── OrderController.kt
│       └── dto/
│           ├── CreateOrderRequest.kt
│           └── OrderResponse.kt
│
├── application/                     # 2️⃣ Application Layer
│   └── order/
│       └── OrderService.kt
│
├── domain/                          # 3️⃣ Domain Layer (핵심!)
│   ├── order/
│   │   ├── Order.kt                # 비즈니스 규칙 포함
│   │   └── OrderRepository.kt      # 인터페이스만
│   │
│   └── product/
│       ├── Stock.kt                # 비즈니스 규칙 포함
│       └── ProductRepository.kt    # 인터페이스만
│
└── infrastructure/                  # 4️⃣ Infrastructure Layer
    └── order/
        └── InMemoryOrderRepository.kt  # 구현체

각 계층의 역할

1️⃣ Presentation Layer (표현 계층)

역할: HTTP 요청/응답 처리, DTO 변환

@RestController
@RequestMapping("/api/orders")
class OrderController(
    private val orderService: OrderService
) {
    @PostMapping
    fun createOrder(@RequestBody request: CreateOrderRequest): OrderResponse {
        // 1. 입력 검증 (DTO)
        // 2. Application Layer 호출
        val order = orderService.createOrder(
            userId = request.userId,
            items = request.items
        )
        // 3. DTO로 변환하여 응답
        return OrderResponse.from(order)
    }
}

DTO가 Presentation에 있는 이유:

• 외부 통신 전용 객체
• API 스펙 변경이 Domain에 영향 없음
• 필요한 정보만 선택적으로 노출

2️⃣ Application Layer (응용 계층)

역할: 비즈니스 흐름 조율, 트랜잭션 관리

// ✅ Service는 흐름만 조율
@Service
class OrderService(
    private val orderRepository: OrderRepository,
    private val stockRepository: StockRepository
) {
    @Transactional
    fun createOrder(userId: Long, items: List<OrderItem>): Order {
        // 1. 재고 조회
        val stock = stockRepository.findById(items.first().productId)
            ?: throw ProductNotFoundException()

        // 2. Domain 객체에 비즈니스 규칙 실행 위임
        stock.decrease(items.first().quantity)

        // 3. Domain 객체가 주문 생성 로직 처리
        val order = Order.create(
            userId = userId,
            items = items
        )

        // 4. 저장
        stockRepository.save(stock)
        return orderRepository.save(order)
    }
}

Application Layer가 하는 일:

• ✅ 여러 Repository에서 데이터 조회
• ✅ Domain 객체들 간의 상호작용 조율
• ✅ 트랜잭션 경계 관리
• ❌ 비즈니스 규칙 직접 구현 (Domain에 위임!)

3️⃣ Domain Layer (도메인 계층) - 가장 중요! 🌟

역할: 핵심 비즈니스 규칙 포함

// domain/product/Stock.kt
data class Stock(
    val productId: Long,
    private var quantity: Int  // private으로 캡슐화
) {
    // ✅ 비즈니스 규칙을 Domain이 직접 처리
    fun decrease(amount: Int) {
        require(amount > 0) { "감소 수량은 양수여야 합니다" }

        // 비즈니스 규칙: 재고 부족 시 예외
        if (quantity < amount) {
            throw InsufficientStockException(
                "재고 부족: 요청 $amount, 현재 $quantity"
            )
        }

        quantity -= amount
    }

    fun isAvailable(amount: Int): Boolean = quantity >= amount
}

// domain/order/Order.kt
data class Order(
    val id: Long?,
    val userId: Long,
    val items: List<OrderItem>,
    private val _totalAmount: BigDecimal
) {
    val totalAmount: BigDecimal get() = _totalAmount

    companion object {
        // ✅ 생성 로직도 Domain이 관리
        fun create(userId: Long, items: List<OrderItem>): Order {
            require(items.isNotEmpty()) { "주문 상품이 비어있습니다" }

            val totalAmount = items.sumOf { it.calculateAmount() }

            return Order(
                id = null,
                userId = userId,
                items = items,
                _totalAmount = totalAmount
            )
        }
    }
}

Domain Layer의 특징:

• 순수 비즈니스 로직만 포함
• 어떤 프레임워크에도 의존하지 않음 (Spring, JPA 등)
• 테스트가 가장 쉬움

4️⃣ Infrastructure Layer (인프라 계층)

역할: Repository 인터페이스의 실제 구현

// domain/product/ProductRepository.kt (인터페이스만!)
interface ProductRepository {
    fun save(product: Product): Product
    fun findById(id: Long): Product?
    fun findAll(): List<Product>
}
kotlin// infrastructure/product/InMemoryProductRepository.kt (구현체)
@Repository
class InMemoryProductRepository : ProductRepository {
    private val storage = ConcurrentHashMap<Long, Product>()
    private val idGenerator = AtomicLong(1)

    override fun save(product: Product): Product {
        val id = product.id ?: idGenerator.getAndIncrement()
        val newProduct = product.copy(id = id)
        storage[id] = newProduct
        return newProduct
    }

    override fun findById(id: Long): Product? {
        return storage[id]
    }

    override fun findAll(): List<Product> {
        return storage.values.toList()
    }
}

🎯 의존성 역전 원칙 (DIP)

핵심: Domain이 Infrastructure를 의존하지 않고, Infrastructure가 Domain을 의존한다.

전통적인 방식 (나쁜 예):
Service → Repository 구현체 (강한 결합)

레이어드 아키텍처 (좋은 예):
Service → Repository 인터페이스 ← Repository 구현체 (약한 결합)

장점:

• InMemory → JPA → MongoDB로 변경해도 Domain, Application은 수정 불필요
• Mock 객체로 쉽게 테스트 가능

⚠️ 자주하는 실수

1. CouponStatus를 Infrastructure에 두는 실수

// ❌ 잘못된 위치
infrastructure/coupon/CouponStatus.kt

// ✅ 올바른 위치
domain/coupon/CouponStatus.kt

이유: CouponStatus는 도메인 개념이지 구현 세부사항이 아니다!

2. DTO를 Domain으로 착각하는 실수

// ❌ 잘못된 위치
presentation/order/dto/Order.kt  // 이건 DTO여야 함

// ✅ 올바른 구조
domain/order/Order.kt                    // Domain Model
presentation/order/dto/OrderResponse.kt  // DTO

3. Service에 비즈니스 로직을 넣는 실수

// ❌ 나쁜 예: Service에 비즈니스 규칙
@Service
class StockService {
    fun decreaseStock(stock: Stock, amount: Int) {
        if (stock.quantity < amount) {
            throw Exception("재고 부족")
        }
        stock.quantity -= amount  // 외부에서 직접 수정
    }
}

// ✅ 좋은 예: Domain 모델이 비즈니스 규칙 포함
class Stock {
    private var quantity: Int

    fun decrease(amount: Int) {
        if (quantity < amount) {
            throw InsufficientStockException()
        }
        quantity -= amount
    }
}

✅ 장점

1. 유지보수성

* 변경의 영향 범위가 명확하게 제한됨
* 각 계층이 독립적으로 진화 가능

2. 테스트 용이성

// Domain 로직 단위 테스트 (프레임워크 없이)
class StockTest {
    @Test
    fun `재고가 부족하면 예외가 발생한다`() {
        val stock = Stock(productId = 1, quantity = 5)

        assertThrows<InsufficientStockException> {
            stock.decrease(10)
        }
    }
}

3. 기술 독립성

• Domain은 순수 비즈니스 로직만 포함
• 프레임워크 교체 가능 (Spring → Ktor 등)

📊 정리

핵심 원칙:

• Domain은 어디에도 의존하지 않음 (순수)
• 비즈니스 규칙은 Domain Model에
• Application은 흐름 조율만
• Infrastructure는 Domain 인터페이스 구현

제대로 된 레이어드 아키텍처를 적용하면, 코드의 책임이 명확해지고 테스트와 유지보수가 훨씬 쉬워진다. Service에 모든 걸 때려박는 습관에서 벗어나, Domain이 중심이 되는 설계를 하자!

🎯 이번 주에 겪었던 문제

이번 주차를 진행하며 다음과 같은 문제를 겪었다. • TDD(Test Driven Development) 에 대한 잘못된 인식이 있었음 • 무조건 비즈니스 로직을 구현하기 전에 테스트 코드를 작성해야 한다고 오해하고 있었음 • 모든 기능에 대해 테스트 코드를 작성해야 한다고 생각했었음 • 단일 책임 원칙(SRP) 에 따른 테스트 코드 작성 방식의 중요성을 깨달음 • 멀티 스레드 환경에서의 동시성 제어 방법 고민

🔍 시도해본 것들

문제를 해결하기 위해 아래와 같은 시도를 진행했다. • PointService 에 단일 책임 원칙이 무시된 채 너무 많은 책임이 집중되어 있었는데, validation 로직을 UserPoint 도메인 클래스로 분리 • 멀티 스레드 환경에서 동시성 제어를 위해 ReentrantLock 사용 • 테스트 코드 작성 시 단일 책임 원칙을 지키기 위해 각 클래스 단위로 테스트 코드 작성

✅ 문제를 어떻게 해결했는가?

• 서비스 레이어에서 중복 역할을 수행하던 validation 로직을 도메인 객체로 분리하면서 책임이 명확해지고 테스트 범위도 깔끔하게 정리됨 • ReentrantLock을 도입하여 동시에 여러 스레드가 접근하는 상황을 제어하여 데이터 정합성을 보장함 • 클래스 단위로 테스트 코드를 작성하면서 테스트 대상의 역할이 명확해지고 유지보수성이 향상됨

💡 새롭게 알게 된 것

시도를 통해 아래와 같은 점을 새롭게 알게 된 것들이 있다. • TDD는 구현 전에 무조건 테스트를 작성하는 것이 아니라, 설계를 가이드하고 피드백 루프를 촉진하는 철학적 접근이라는 것 • 모든 기능에 대해 테스트 코드를 작성할 필요는 없으며, 핵심 비즈니스 로직 중심으로 테스트하는 것이 효율적이라는 점 • 멀티 스레드 환경에서는 동시성 제어가 필수이며, 그렇지 않으면 데이터 정합성 문제가 발생할 수 있음

🔥 지난 목표 회고

지난주에 설정했던 목표는 다음과 같은 결과가 나왔다.

✅ 잘된 점 • 과제를 하루 전날 제출하여 일정 관리가 비교적 잘 됨

❌ 아쉬운 점 • 동시성 제어에 대한 이해도가 아직 부족하다고 느낌 • 컨디션 관리를 못 했음 → 더 많은 학습이 필요함

🎯 다음 목표 설정

📌 단기 목표

• 이커머스 프로젝트 과제를 기간 내에 완수하기
• 동시성 제어 이론 + 실습 코드 더 많이 경험해보기

반복적인 성장을 위한 루틴으로 가져갈 예정!!

Study 과제 중 TDD를 기반으로 테스트 코드를 작성하는데, 포인트 충전/사용 시스템을 Kotlin 으로 개발하면서 요구 사항에 "동시성 문제 해결" 이 있었다. 실제 데이터베이스를 사용하는게 아닌 인메모리를 사용하게 되면서 DB의 Transaction 없이 동시성을 처리를 해야했다.

그래서 Kotlin, Java에 내장되어있는 lock 매커니즘을 이용해서 처리를 해서 정리를 해보려고 한다.

문제 상황

class PointService(
    private val userPointTable: UserPointTable,
    private val pointHistoryTable: PointHistoryTable
) {
    fun chargeUserPoint(userId: Long, amount: Long): UserPoint {
        val current = userPointTable.selectById(userId)  // 현재: 1000
        val newPoint = current.point + amount             // 1000 + 100 = 1100
        return userPointTable.insertOrUpdate(userId, newPoint)
    }
}

만약 두 명의 사용자가 동시에 100 포인트를 충전한다면?

• 예상: 1000 -> 1200
• 실제: 1000 -> 1100

Race Condition 발생

Thread A: selectById(1) → 1000 읽음
Thread B: selectById(1) → 1000 읽음
Thread A: 1000 + 100 = 1100
Thread B: 1000 + 100 = 1100
Thread A: insertOrUpdate(1, 1100)
Thread B: insertOrUpdate(1, 1100) 💥 덮어쓰기!

Spring Boot는 멀티 스레드 환경이기 때문에 각 HTTP 요청이 별도 스레드에서 처리되며, 같은 데이터에 여러 스레드가 동시 접근할 수 있다.

해결 방법

내장되어 있는 ConcurrentHashMap을 사용해서 해결을 했다.

// ❌ HashMap은 thread-safe하지 않음
private val userLocks = HashMap<Long, Any>()

// ✅ ConcurrentHashMap은 thread-safe
private val userLocks = ConcurrentHashMap<Long, Lock>()

if 조건문 으로 처리를 했던 코드는 require() 함수로 대체를 한다.

// Kotlin답게 - 간결하고 명확
require(amount > 0) { "충전 금액은 양수여야 합니다." }
require(amount % 100 == 0L) { "포인트 사용은 100 단위로만 가능합니다." }

// 조건이 true여야 할 것을 작성!

장점은 다음과 같다.

• ✅ kotlin의 표현식 기반 문법과 잘 어울림
• ✅ 간결하고 직관적
• ✅ JVM 최적화 지원
• ✅ 별도의 라이브러리 불필요

마무리

Kotlin으로 Spring Boot를 개발한다면, 언어의 특성을 살려 더 간결하고 안전한 동시성 제어를 구현할 수 있다. Redis나 외부 라이브러리를 이용하지 않고 동시성 제어를 할 수 있다.

원래 회사에서 REST API를 통해서 클라이언트와 API 통신을 하고 있었는데 불필요한 join문과 수시로 바뀌는 기획에 대응을 하기 위해서 클라이언트 입맛에 맞게 데이터를 조회할 수 있도록 GraphQL을 도입하기로 했다.

사용을 하면서 GraphQL로 file을 upload 하는 API를 개발할 때 2022년도에 구현을 하지 못해서 file upload는 REST API를 사용했던 경험이 있다.

하지만 이번에는 온전히 GraphQL을 사용하면서 file upload 기능을 구현하고 싶어서 글을 정리하게 됐다.

GraphQL로 file upload 하기

먼저 GraphQL에서 Mutation을 이용하여 file upload를 구현 할 것이다. file을 upload를 하기 위해서 graphql-upload 라이브러리를 사용할 것이다.

> npm i graphql-upload
> npm i -D @types/graphql-upload

위 명령어를 통해서 graphql-upload 라이브러리를 설치해준다. (yarn으로 설치해도 됨) 이때, nestjs src/main.ts 에서 graphql upload express를 활성화해줘야 한다.

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import graphqlUploadExpress from 'graphql-upload/graphqlUploadExpress.mjs';

async function bootstrap() {
    const app = await NestFactory.create(AppModule);

    app.use(graphqlUploadExpress());
    await app.listen(3000);
}

bootstrap();

이때, 주의사항은 import graphqluploadExpress from 'graphql-upload' 혹은 import { graphqlUploadExpress } from 'graphql-upload' 이렇게 import를 하게 되면 해당 모듈을 찾지 못하는 에러가 발생한다.

무조건 graphql-upload/graphqlUploadExpress.mjs에서 import를 해야한다!

다음 단계는 이제 file을 upload 할 resolver에서 파라미터 처리를 해줘야 하는데 기존제 REST API를 사용할 때 처럼 file과 관련된 데코레이터를 붙여줘야 한다.

import { Args, Mutation, Resolver } from '@nestjs/graphql'
import GraphqlUpload, { FileUpload } from 'graphql-upload/GraphQLUpload.mjs'

@Resolver()
export class UploadResolver {
    constructor() {}

    @Mutation(() => String)
    async uploadFile(@Args('file', { type: () => GraphqlUpload }) file: FileUpload) {
        console.log(file);
    }
}

이렇게 앞서 src/main.ts에서 import 한 거 처럼 특정 경로에서 import를 해준다. 위 예제 코드를 작성하고 playground 혹은 graphiql 이 곳에서 테스트를 할 수 없다. 왜냐하면 이 두 곳은 file upload를 지원하지 않는다.

그래서 찾은게 Altair다. UI/UX가 훌륭하다. Altair를 사용해서 file을 upload 하고, schema를 작성해준다.

위에 이미지처럼 변수를 만들어서 사용해도 좋고 편한 방법이 있다면 편한 방법으로 하면된다. 이렇게 설정을 했으면 이제 server로 request를 해주면 console.log(file)을 통해 터미널을 확인해보면

{
    filename: string;
    mimetype: string;
    encoding: string;
}

이런식으로 file 정보를 얻을 수 있다. 이 값을 통해서 AWS S3 Bucket에 upload를 할 수 있다.

마무리

이처럼 GraphQL을 이용해서 file upload를 하는 방법에 대해서 알아봤다. 별거 아니지만 과거에 완료하지 못한 기능을 구현하게 돼서 REST API에 의존하지 않을 수 있었다. 과거에 구현하지 못한 GraphQL file upload를 구현해서 뿌듯함,,

Docker image를 local에서 build를 한 후 이를 저장하고 압축해서 보관하거든 다른 환경으로 이동할 수 있다. 솔직히 DockerHub에 image를 등록해서 사용할 수 있지만 리소스가 부족한 환경에서는 이 방법이 괜찮다고 생각했다.

아래에서는 image build 후 추출 및 압축 처리를 하는 방법을 설명을 하려고 한다.

1. Docker image build

먼저 Docker image를 build하기 위해서 Dockerfile을 작성해야 한다. (예제는 nodeJS)

FROM node:18-alpine

WORKDIR /app

COPY package*.json ./

RUN npm install

COPY . .

RUN npm install -g typescript ts-node

EXPOSE 8080

CMD ["npm", "start"]

2. Docker image 저장

Dockerfile을 작성하고 나면 이 파일을 이용해서 image build를 해준다.

docker save -o my-image.tar my-image

만약 여러 image를 하나의 압축파일로 만들고 싶을 때 -o "압축 파일 이름" 뒤에 image 이름들을 적어주면 된다.

docker save -o my-images.tar my-image my-image2

3. 압축한 Docker image load

압축한 이미지 파일을 다시 이미지로 불러오기 위해서 아래와 같은 명령어를 사용할 수 있다.

docker load < my-image.tar

다시 docker에 image를 build가 됐고, 확인을 하기 위해서는

docker image

명령어를 통해서 확인할 수 있다.

2개의 서버와 mongoDB, MySQL을 docker-compose를 이용해서 build를 하고, 실행하는 단계에서 문제가 발생했다. MySQL과 연결되어 있는 한 서버에서 Database Connection 관련 에러가 발생했고,

이 문제는 MySQL docker image가 build 되면서 docker container가 준비 상태가 아니라서 발생한 문제였다.

해결

해결하기 위해서 depends_on만 사용하지 않고, healthcheck 옵션을 사용해서 MySQL docker container가 준비 상태에 도달할 때까지 MySQL을 사용하는 docker container server는 대기를 하도록 했다.

  mysql:
    image: mysql:latest
    container_name: mysql
    restart: always
    ports:
      - '3309:3306'
    environment:
      - MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
      - MYSQL_DATABASE=${MYSQL_DATABASE}
    volumes:
      - mysql_data:/var/lib/mysql
    networks:
      - custom_network
    healthcheck:
      test: ['CMD', 'mysqladmin', 'ping', '-h', 'localhost', '-uroot', '-proot']
      timeout: 20s
      retries: 5

MySQL docker container가 healthcheck 옵션을 사용하면서 준비 상태까지 도달하게 되면 MySQL을 사용하는 docker container server는 그제서야 docker container 생성을 실행하게 된다.

    depends_on:
      mysql:
        condition: service_healthy
      mongo:
        condition: service_started
    networks:
      - custom_network

MySQL을 사용하는 docker container server에서는 depends_on 옵션에서 mysql docker container service가 service_healthy 상태에 도달할 때까지 대기하도록 했다.

이렇게 yaml 파일을 작성하고 docker-compose up -d 명령어를 실행하게 되면 기대했던 대로 MySQL docker container가 준비 상태에 도달할 때 까지 대기를 하면서 Database Connection 관련 에러가 발생하지 않게 되었다.

하지만 Fargate는 EC2 대비 비용이 비교적 비싼 편이다. 따라서 초기 비용을 줄이기 위해 EC2를 사용하는 경우가 많다.

이 포스트에서는 EC2를 사용해서 배포하는 방법을 알아보고자 한다.

VPC

ECS로 배포를 하기 전에 먼저 VPC를 생성해야 한다.

VPC는 네트워크 범위를 정의하고, 서브넷, 인터넷 게이트웨이, 라우팅 테이블 등을 생성하여 네트워크 환경을 구성한다.

VPC 생성

vpc를 생성하기 위해서 IPv4 CIDR 블록또는 IP주소 범위를 입력해야 한다.

수동으로 입력할 수 있지만 CIDR 블록의 크기는 /16에서 /28 사이로 입력을 해야 한다.

기본적으로 제공되는 10.0.0.0/16 블록을 사용할 수 있지만 사용자가 원하는 블록을 입력할 수 있다.

10.0.0.0은 IP 주소를 가리키고, /16은 네트워크 범위를 가리키는데, 이 때 네트워크 범위는 2^(32-n) 개의 네트워크 범위를 가지게 된다.

따라서 /16은 2^(32-16) = 65536개의 네트워크 범위를 가지게된다.

위와 같이 IP주소와 범위를 지정해주고 생성을 해주면 된다.

IP주소는 어떤 IP 주소를 할당해야 하는지 헷갈릴 수 있다.

어떤 IP 주소를 할당해야 할지?

VPC에서는 CIDR 블록을 선택할 떄 고려해야 할 사항이 있다.

1. 사설 IP 대역을 사용

VPC에서는 공개 IP가 아니라 사설 IP를 사용한다. RFC 1918 표준에 따라 아래와 같은 사설 IP 대역을 사용해야 한다.

• 10.0.0.0 (AWS에서 가장 많이 사용됨)
• 172.16.0.0
• 192.168.0.0

💡 AWS에서는 10.0.0.0 IP 대역을 많이 사용한다.

2. 예상 네트워크 크기에 맞게 CIDR 블록 선택

VPC 내에서 EC2, RDS, ALB, Lambda, ECS 등 AWS 리소스가 몇 개나 필요한지 예측을 해야 한다.

• 대규모 서비스: 10.0.0.0/16 (최대 65536개의 IP 주소)
• 중규모 서비스: 10.0.0.0/20 (최대 4096개의 IP 주소)
• 소규모 서비스: 10.0.0.0/24 (최대 256개의 IP 주소)

💡 서브넷을 분할할 계획이라면 /16, 서브넷에서 /24를 사용하는 것이 좋다.

3. 서브넷을 어떻게 나눌 것인지

VPC내에서 서브넷을 나누어 사용할 계획이라면 미리 CIDR 블록의 범위를 크게 설정하는 것이 좋다. 예를들어 VPC를 10.0.0.0/16을 사용하고, 서브넷은 /24 범위로 나누는 경우가 많다.

💡 VPC는 큰 범위로 설정하고, 서브넷은 보다 작은 범위로 설정하는 것이 관리하기 편하다.

아래는 이미지 빌드 후 추출 및 압축 처리를 하는 벙법을 설명을 하고자 한다.

1. Docker 이미지 빌드

먼저 Docker 이미지를 빌드하기 위해서 Dockerfile을 작성해야 한다. (여기서는 node로 예시를 들겠다.)

FROM node:18-alpine

WORKDIR /app

COPY package*.json ./

RUN npm install

COPY . .

RUN npm install -g typescript ts-node

EXPOSE 8080

CMD ["npm", "start"]

Dockerfile을 작성하고 나면 이 파일을 이용해서 이미지를 빌드를 해준다.

docker build -t my-image .

my-image:1.0을 해주면 version을 1.0으로 지정해줄 수 있고, 적지 않으면 latest로 지정된다.

.은 현재 디렉토리를 가리킨다.

이미지 목록을 확인하려면 docker images 명령어를 사용하면 된다.

2. Docker 이미지 저장

이미지를 빌드 후에 이미지 저장을 위해서 아래와 같은 명령어를 사용한다.

docker save -o my-image.tar my-image

만약 여러 이미지를 하나의 압축파일로 만들고 싶을 땐 -o "압축 파일 이름" 뒤에 이미지 이름들을 적어주면 된다.

docker save -o my-images.tar my-image my-image2

3. 압축한 docker 이미지 load

압축한 이미지 파일을 다시 이미지로 불러오기 위해서 아래와 같은 명령어를 사용할 수 있다.

docker load < my-image.tar

다시 docker에 image를 빌드가 됐고, 확인하고 싶으면

docker images

명령어를 사용하면 된다.

2개의 서버와 mongoDB, MySQL을 docker-compose를 이용해서 build 하고 실행하는 단계에서 문제가 발생했다. MySQL과 연결되어 있는 한 서버에서 Database Connection 관련 에러가 발생했고, 이 문제는 MySQL image가 build가 되면서 container가 준비 상태가 아니라서 발생한 문제였다.

depends_on 옵션을 사용했지만 depends_on은 단순히 실행 순서를 보장하는 것이며 container가 준비 상태인지 확인하지 않아서 발생한 문제였다.

해결

해결하기 위해서 depends_on만 사용하지 않고, healthcheck 옵션을 사용해서 MySQL container가 준비 상태에 도달할 때까지 MySQL을 사용하는 서버는 대기를 하도록 했다.

  mysql:
    image: mysql:latest
    container_name: mysql
    restart: always
    ports:
      - '3309:3306'
    environment:
      - MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
      - MYSQL_DATABASE=${MYSQL_DATABASE}
    volumes:
      - mysql_data:/var/lib/mysql
    networks:
      - custom_network
    healthcheck:
      test: ['CMD', 'mysqladmin', 'ping', '-h', 'localhost', '-uroot', '-proot']
      timeout: 20s
      retries: 5

MySQL container가 healthcheck 옵션을 사용하면서 준비 상태까지 도달하게 되면 MySQL을 사용하는 서버는 그제서야 container 생성을 실행하게 된다.

    depends_on:
      mysql:
        condition: service_healthy
      mongo:
        condition: service_started
    networks:
      - custom_network

MySQL을 사용하는 서버에서는 depends_on 옵션에서 mysql 서비스가 service_healthy 상태가 될 때까지 대기하도록 했다.

이렇게 yaml 파일을 작성하고 docker-compose up -d 명령어를 실행하게 되면 기대했던 대로 MySQL container가 준비 상태가 될 때 까지 대기를 하면서

Database Connection 관련 에러가 발생하지 않게 되었다.

FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory

이 에러는 그냥 말 그대로 메모리 사용량이 증가하면서 Javascript엔진이 터져버린 것이다.

NodeJs의 기본적인 메모리 제한은 512MB다. 그럼 내가 처리를 하려고 하는 이 API가 메모리 한계를 뚫은 것...

메모리 누수가 존재하다 생각해서 코드를 봤지만 누수가 될만한 코드는 없었고, 단지 180만번의 반복문을 돌려야 하는 코드로 인해서 메모리 점유율이 상당했던것.

해결 방법으로는

1. 더 큰 메모리를 할당한다.
2. 메모리 누수를 개선한다.

2번 방법은 찾아봤을 때 해당되지 않아서 1번 방법을 사용을 해보려고 한다. 우선 현재 메모리를 확인해 줄 필요가 있다.

node -e 'console.log(v8.getHeapStatistics().heap_size_limit/(1024*1014)'

그 후 아래와 같이 늘리고 싶은 용량을 적으면 메모리 용량이 변경된다.

export NODE_OPTIONS=--max_old_space_size=5000

이렇게 매번 대용량의 작업을 할 때 용량을 늘려줘야 하는건가.. 맘 같아서 캐시 메모리에 넣어서 작업을 진행하던지 하고 싶지만

이 프로젝트는 회사에서 단발성이기 때문에 이것저것 도입을하기가 무척 애매모호한 상황이라서 어려운 것 같다.

Spring Boot를 이용해서 Spring Security 실습을 하는 도중 JWT 발급 관련해서 아래와 같은 에러가 발생했다.

Unable to determine a suitable MAC or Signature algorithm for the specified key using available heuristics: either the key size is too weak be used with available algorithms, or the key size is unavailable (e.g. if using a PKCS11 or HSM (Hardware Security Module) key store). If you are using a PKCS11 or HSM keystore, consider using the JwtBuilder.signWith(Key, SecureDigestAlgorithm) method instead.

위 내용과 같이 에러 메시지를 자세히 살펴보니 secretKey 사이즈가 부족하다는 것이었다.

해결 방법

해결 방법은 간단하게도 secretKey의 사이즈를 더 늘려주었더니 해결이되었다. 참고로 HS256 알고리즘을 사용하는 경우, SecretKey는 최소한 256비트 (32바이트) 이상의 길이를 가져야 한다.