스프링 사전과제 가이드 7편: Advanced Patterns

시리즈 네비게이션

📚 전체 로드맵: 스프링 사전과제 가이드 로드맵 참고

서론

시리즈의 마지막 편으로, 차별화를 보여줄 수 있는 고급 패턴들을 다룬다. 모든 과제에 적용할 필요는 없지만, 상황에 맞게 활용하면 설계 역량을 보여줄 수 있다.

7편에서 다루는 내용:

• 이벤트 기반 아키텍처
• 비동기 처리
• 파일 처리
• API 버저닝
• 아키텍처 패턴
• 멀티 모듈 프로젝트

목차

• 이벤트 기반 아키텍처
• 비동기 처리
• 파일 처리
• API 버저닝
• 아키텍처 패턴
• 멀티 모듈 프로젝트
• 정리

이벤트 기반 아키텍처

1. Spring Events 기본

이벤트를 활용하면 도메인 로직과 부가 기능(알림, 로깅 등)을 분리할 수 있다.

// 이벤트 정의
public record OrderCreatedEvent(
    Long orderId,
    Long memberId,
    Integer totalAmount,
    LocalDateTime occurredAt
) {
    public OrderCreatedEvent(Order order) {
        this(order.getId(), order.getMember().getId(),
             order.getTotalAmount(), LocalDateTime.now());
    }
}

// 이벤트 발행
@Service
@RequiredArgsConstructor
public class OrderService {

    private final OrderRepository orderRepository;
    private final ApplicationEventPublisher eventPublisher;

    @Transactional
    public Long createOrder(OrderCreateCommand command) {
        Order order = Order.create(command);
        orderRepository.save(order);

        // 이벤트 발행
        eventPublisher.publishEvent(new OrderCreatedEvent(order));

        return order.getId();
    }
}

// 이벤트 리스너
@Component
@RequiredArgsConstructor
public class OrderEventListener {

    private static final Logger log = LoggerFactory.getLogger(OrderEventListener.class);
    private final NotificationService notificationService;

    @EventListener
    public void handleOrderCreated(OrderCreatedEvent event) {
        log.info("Order created: orderId={}, memberId={}",
                 event.orderId(), event.memberId());

        // 알림 발송
        notificationService.sendOrderConfirmation(event.memberId(), event.orderId());
    }
}

// 이벤트 정의
data class OrderCreatedEvent(
    val orderId: Long,
    val memberId: Long,
    val totalAmount: Int,
    val occurredAt: LocalDateTime = LocalDateTime.now()
) {
    constructor(order: Order) : this(
        orderId = order.id!!,
        memberId = order.member.id!!,
        totalAmount = order.totalAmount
    )
}

// 이벤트 발행
@Service
class OrderService(
    private val orderRepository: OrderRepository,
    private val eventPublisher: ApplicationEventPublisher
) {
    @Transactional
    fun createOrder(command: OrderCreateCommand): Long {
        val order = Order.create(command)
        orderRepository.save(order)

        eventPublisher.publishEvent(OrderCreatedEvent(order))

        return order.id!!
    }
}

// 이벤트 리스너
@Component
class OrderEventListener(
    private val notificationService: NotificationService
) {
    private val log = LoggerFactory.getLogger(javaClass)

    @EventListener
    fun handleOrderCreated(event: OrderCreatedEvent) {
        log.info("Order created: orderId={}, memberId={}", event.orderId, event.memberId)
        notificationService.sendOrderConfirmation(event.memberId, event.orderId)
    }
}

2. @TransactionalEventListener

트랜잭션 상태에 따라 이벤트 처리 시점을 제어할 수 있다.

@Component
@RequiredArgsConstructor
public class OrderEventListener {

    private final NotificationService notificationService;

    /**
     * 트랜잭션 커밋 후 실행
     * - 주문 저장이 확정된 후에만 알림 발송
     */
    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
    public void handleOrderCreatedAfterCommit(OrderCreatedEvent event) {
        notificationService.sendOrderConfirmation(event.memberId(), event.orderId());
    }

    /**
     * 트랜잭션 롤백 시 실행
     * - 실패 로깅 등
     */
    @TransactionalEventListener(phase = TransactionPhase.AFTER_ROLLBACK)
    public void handleOrderCreatedOnRollback(OrderCreatedEvent event) {
        // 실패 로깅
    }
}

3. 비동기 이벤트 처리

@Component
@RequiredArgsConstructor
public class OrderEventListener {

    private final NotificationService notificationService;

    @Async
    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
    public void handleOrderCreatedAsync(OrderCreatedEvent event) {
        // 비동기로 실행되어 메인 트랜잭션에 영향 없음
        notificationService.sendOrderConfirmation(event.memberId(), event.orderId());
    }
}

비동기 처리

1. @Async 설정

@Configuration
@EnableAsync
public class AsyncConfig implements AsyncConfigurer {

    @Override
    public Executor getAsyncExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(5);
        executor.setMaxPoolSize(10);
        executor.setQueueCapacity(100);
        executor.setThreadNamePrefix("async-");
        executor.setRejectedExecutionHandler(new ThreadPoolExecutor.CallerRunsPolicy());
        executor.initialize();
        return executor;
    }

    @Override
    public AsyncUncaughtExceptionHandler getAsyncUncaughtExceptionHandler() {
        return (ex, method, params) -> {
            Logger log = LoggerFactory.getLogger(method.getDeclaringClass());
            log.error("Async method {} threw exception: {}", method.getName(), ex.getMessage(), ex);
        };
    }
}

2. @Async 사용

@Service
@RequiredArgsConstructor
public class NotificationService {

    private static final Logger log = LoggerFactory.getLogger(NotificationService.class);
    private final EmailSender emailSender;
    private final SmsSender smsSender;

    @Async
    public void sendOrderConfirmation(Long memberId, Long orderId) {
        log.info("Sending order confirmation: memberId={}, orderId={}", memberId, orderId);

        // 이메일 발송 (비동기로 실행)
        emailSender.send(memberId, "주문 확인", "주문이 완료되었습니다.");
    }

    @Async
    public CompletableFuture<Boolean> sendSmsAsync(String phoneNumber, String message) {
        boolean result = smsSender.send(phoneNumber, message);
        return CompletableFuture.completedFuture(result);
    }
}

3. CompletableFuture 활용

@Service
@RequiredArgsConstructor
public class ProductAggregationService {

    private final ProductService productService;
    private final ReviewService reviewService;
    private final InventoryService inventoryService;

    /**
     * 여러 서비스에서 데이터를 병렬로 조회
     */
    public ProductDetailResponse getProductDetail(Long productId) {
        CompletableFuture<Product> productFuture =
            CompletableFuture.supplyAsync(() -> productService.getProduct(productId));

        CompletableFuture<List<Review>> reviewsFuture =
            CompletableFuture.supplyAsync(() -> reviewService.getReviews(productId));

        CompletableFuture<Integer> stockFuture =
            CompletableFuture.supplyAsync(() -> inventoryService.getStock(productId));

        // 모든 비동기 작업 완료 대기
        CompletableFuture.allOf(productFuture, reviewsFuture, stockFuture).join();

        return ProductDetailResponse.of(
            productFuture.join(),
            reviewsFuture.join(),
            stockFuture.join()
        );
    }

    /**
     * 타임아웃 적용
     */
    public ProductDetailResponse getProductDetailWithTimeout(Long productId) {
        try {
            CompletableFuture<ProductDetailResponse> future = CompletableFuture.supplyAsync(() ->
                getProductDetail(productId)
            );

            return future.get(5, TimeUnit.SECONDS);
        } catch (TimeoutException e) {
            throw new ServiceTimeoutException("Product detail fetch timeout");
        } catch (Exception e) {
            throw new ServiceException("Failed to fetch product detail", e);
        }
    }
}

파일 처리

1. 파일 업로드

@RestController
@RequestMapping("/api/v1/files")
@RequiredArgsConstructor
public class FileController {

    private final FileService fileService;

    @PostMapping(consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    public ResponseEntity<FileUploadResponse> uploadFile(
            @RequestParam("file") MultipartFile file) {

        FileUploadResponse response = fileService.upload(file);
        return ResponseEntity.status(HttpStatus.CREATED).body(response);
    }

    @PostMapping(value = "/multiple", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    public ResponseEntity<List<FileUploadResponse>> uploadFiles(
            @RequestParam("files") List<MultipartFile> files) {

        List<FileUploadResponse> responses = fileService.uploadMultiple(files);
        return ResponseEntity.status(HttpStatus.CREATED).body(responses);
    }
}

@Service
@RequiredArgsConstructor
public class FileService {

    private static final Logger log = LoggerFactory.getLogger(FileService.class);
    private static final List<String> ALLOWED_EXTENSIONS = List.of("jpg", "jpeg", "png", "gif", "pdf");
    private static final long MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB

    @Value("${file.upload-dir}")
    private String uploadDir;

    public FileUploadResponse upload(MultipartFile file) {
        validateFile(file);

        String originalFilename = file.getOriginalFilename();
        String extension = getExtension(originalFilename);
        String storedFilename = UUID.randomUUID() + "." + extension;
        Path filePath = Paths.get(uploadDir, storedFilename);

        try {
            Files.createDirectories(filePath.getParent());
            file.transferTo(filePath);

            log.info("File uploaded: original={}, stored={}", originalFilename, storedFilename);

            return new FileUploadResponse(storedFilename, originalFilename, file.getSize());
        } catch (IOException e) {
            throw new FileUploadException("Failed to upload file", e);
        }
    }

    private void validateFile(MultipartFile file) {
        if (file.isEmpty()) {
            throw new InvalidFileException("File is empty");
        }

        if (file.getSize() > MAX_FILE_SIZE) {
            throw new InvalidFileException("File size exceeds limit");
        }

        String extension = getExtension(file.getOriginalFilename());
        if (!ALLOWED_EXTENSIONS.contains(extension.toLowerCase())) {
            throw new InvalidFileException("File type not allowed: " + extension);
        }
    }

    private String getExtension(String filename) {
        return filename.substring(filename.lastIndexOf(".") + 1);
    }
}

2. 파일 다운로드

@GetMapping("/{filename}")
public ResponseEntity<Resource> downloadFile(@PathVariable String filename) {
    Resource resource = fileService.loadAsResource(filename);

    String contentDisposition = ContentDisposition.attachment()
        .filename(filename, StandardCharsets.UTF_8)
        .build()
        .toString();

    return ResponseEntity.ok()
        .header(HttpHeaders.CONTENT_DISPOSITION, contentDisposition)
        .contentType(MediaType.APPLICATION_OCTET_STREAM)
        .body(resource);
}

public Resource loadAsResource(String filename) {
    try {
        Path filePath = Paths.get(uploadDir).resolve(filename).normalize();
        Resource resource = new UrlResource(filePath.toUri());

        if (resource.exists() && resource.isReadable()) {
            return resource;
        } else {
            throw new FileNotFoundException("File not found: " + filename);
        }
    } catch (MalformedURLException e) {
        throw new FileNotFoundException("File not found: " + filename, e);
    }
}

3. S3 연동 (AWS)

// build.gradle
implementation 'software.amazon.awssdk:s3:2.21.0'

@Configuration
public class S3Config {

    @Value("${aws.region}")
    private String region;

    @Bean
    public S3Client s3Client() {
        return S3Client.builder()
            .region(Region.of(region))
            .build();
    }
}

@Service
@RequiredArgsConstructor
public class S3FileService {

    private final S3Client s3Client;

    @Value("${aws.s3.bucket}")
    private String bucket;

    public String upload(MultipartFile file) {
        String key = "uploads/" + UUID.randomUUID() + "_" + file.getOriginalFilename();

        try {
            PutObjectRequest request = PutObjectRequest.builder()
                .bucket(bucket)
                .key(key)
                .contentType(file.getContentType())
                .build();

            s3Client.putObject(request, RequestBody.fromInputStream(
                file.getInputStream(), file.getSize()));

            return key;
        } catch (IOException e) {
            throw new FileUploadException("Failed to upload to S3", e);
        }
    }

    public byte[] download(String key) {
        GetObjectRequest request = GetObjectRequest.builder()
            .bucket(bucket)
            .key(key)
            .build();

        try (ResponseInputStream<GetObjectResponse> response = s3Client.getObject(request)) {
            return response.readAllBytes();
        } catch (IOException e) {
            throw new FileDownloadException("Failed to download from S3", e);
        }
    }
}

API 버저닝

1. URI 버저닝 (가장 일반적)

@RestController
@RequestMapping("/api/v1/products")
public class ProductControllerV1 {

    @GetMapping("/{id}")
    public ProductResponseV1 getProduct(@PathVariable Long id) {
        // V1 응답
    }
}

@RestController
@RequestMapping("/api/v2/products")
public class ProductControllerV2 {

    @GetMapping("/{id}")
    public ProductResponseV2 getProduct(@PathVariable Long id) {
        // V2 응답 (필드 추가 등)
    }
}

2. Header 버저닝

@RestController
@RequestMapping("/api/products")
public class ProductController {

    @GetMapping(value = "/{id}", headers = "X-API-VERSION=1")
    public ProductResponseV1 getProductV1(@PathVariable Long id) {
        // V1 응답
    }

    @GetMapping(value = "/{id}", headers = "X-API-VERSION=2")
    public ProductResponseV2 getProductV2(@PathVariable Long id) {
        // V2 응답
    }
}

3. Accept Header 버저닝

@RestController
@RequestMapping("/api/products")
public class ProductController {

    @GetMapping(value = "/{id}", produces = "application/vnd.myapp.v1+json")
    public ProductResponseV1 getProductV1(@PathVariable Long id) {
        // V1 응답
    }

    @GetMapping(value = "/{id}", produces = "application/vnd.myapp.v2+json")
    public ProductResponseV2 getProductV2(@PathVariable Long id) {
        // V2 응답
    }
}

아키텍처 패턴

1. 계층형 아키텍처 (기본)

┌─────────────────────────────────────┐
│         Controller (Presentation)    │
├─────────────────────────────────────┤
│            Service (Business)        │
├─────────────────────────────────────┤
│         Repository (Persistence)     │
├─────────────────────────────────────┤
│              Domain (Entity)         │
└─────────────────────────────────────┘

대부분의 과제에서 사용하는 기본 구조다.

2. Hexagonal Architecture (포트와 어댑터)

                    ┌─────────────────┐
    Driving         │                 │        Driven
    Adapters        │    Application  │        Adapters
                    │      Core       │
┌──────────┐       │                 │       ┌──────────┐
│Controller│──────▶│  ┌───────────┐  │──────▶│Repository│
└──────────┘       │  │  Domain   │  │       └──────────┘
                    │  │  Service  │  │
┌──────────┐       │  └───────────┘  │       ┌──────────┐
│  Event   │──────▶│                 │──────▶│ External │
│ Listener │       │                 │       │   API    │
└──────────┘       └─────────────────┘       └──────────┘

src/main/java/com/example/
├── application/              # Application Layer
│   ├── port/
│   │   ├── in/              # Inbound Ports (Use Cases)
│   │   │   └── CreateOrderUseCase.java
│   │   └── out/             # Outbound Ports
│   │       ├── OrderRepository.java
│   │       └── PaymentGateway.java
│   └── service/
│       └── OrderService.java
├── domain/                   # Domain Layer
│   ├── Order.java
│   └── OrderItem.java
└── adapter/                  # Adapter Layer
    ├── in/
    │   └── web/
    │       └── OrderController.java
    └── out/
        ├── persistence/
        │   └── OrderJpaAdapter.java
        └── external/
            └── PaymentGatewayAdapter.java

// Inbound Port (Use Case Interface)
public interface CreateOrderUseCase {
    Long createOrder(CreateOrderCommand command);
}

// Outbound Port
public interface OrderRepository {
    Order save(Order order);
    Optional<Order> findById(Long id);
}

// Application Service
@Service
@RequiredArgsConstructor
public class OrderService implements CreateOrderUseCase {

    private final OrderRepository orderRepository;  // Port 사용
    private final PaymentGateway paymentGateway;    // Port 사용

    @Override
    @Transactional
    public Long createOrder(CreateOrderCommand command) {
        Order order = Order.create(command);
        orderRepository.save(order);
        paymentGateway.process(order);
        return order.getId();
    }
}

// Outbound Adapter
@Repository
@RequiredArgsConstructor
public class OrderJpaAdapter implements OrderRepository {

    private final OrderJpaRepository jpaRepository;

    @Override
    public Order save(Order order) {
        return jpaRepository.save(order);
    }

    @Override
    public Optional<Order> findById(Long id) {
        return jpaRepository.findById(id);
    }
}

3. CQRS (Command Query Responsibility Segregation)

명령(쓰기)과 조회(읽기)를 분리하는 패턴이다.

src/main/java/com/example/order/
├── command/                  # 명령 (쓰기)
│   ├── CreateOrderCommand.java
│   ├── OrderCommandService.java
│   └── OrderCommandRepository.java
└── query/                    # 조회 (읽기)
    ├── OrderQueryService.java
    ├── OrderQueryRepository.java
    └── OrderDetailResponse.java

// Command Service (쓰기)
@Service
@RequiredArgsConstructor
@Transactional
public class OrderCommandService {

    private final OrderRepository orderRepository;

    public Long createOrder(CreateOrderCommand command) {
        Order order = Order.create(command);
        return orderRepository.save(order).getId();
    }

    public void cancelOrder(Long orderId) {
        Order order = orderRepository.findById(orderId)
            .orElseThrow(() -> new OrderNotFoundException(orderId));
        order.cancel();
    }
}

// Query Service (읽기)
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
public class OrderQueryService {

    private final OrderQueryRepository queryRepository;

    public OrderDetailResponse getOrderDetail(Long orderId) {
        return queryRepository.findOrderDetail(orderId)
            .orElseThrow(() -> new OrderNotFoundException(orderId));
    }

    public Page<OrderSummaryResponse> getMyOrders(Long memberId, Pageable pageable) {
        return queryRepository.findOrdersByMemberId(memberId, pageable);
    }
}

멀티 모듈 프로젝트

1. 멀티 모듈이란?

하나의 프로젝트를 여러 모듈로 분리하여 관심사를 분리하고 의존성을 명확히 하는 구조다.

marketplace/
├── build.gradle (root)
├── settings.gradle
├── marketplace-api/           # API 모듈 (Controller, 실행)
├── marketplace-domain/        # 도메인 모듈 (Entity, Service)
├── marketplace-infra/         # 인프라 모듈 (Repository, 외부 연동)
└── marketplace-common/        # 공통 모듈 (Utils, Exception)

2. 멀티 모듈 구조 옵션

멀티 모듈 설계에는 두 가지 접근 방식이 있다.

settings.gradle

rootProject.name = 'marketplace'

include 'marketplace-api'
include 'marketplace-domain'
include 'marketplace-infra'
include 'marketplace-common'

rootProject.name = "marketplace"

include("marketplace-api")
include("marketplace-domain")
include("marketplace-infra")
include("marketplace-common")

Root build.gradle

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.2.0'
    id 'io.spring.dependency-management' version '1.1.4'
}

allprojects {
    group = 'com.example'
    version = '1.0.0'

    repositories {
        mavenCentral()
    }
}

subprojects {
    apply plugin: 'java'
    apply plugin: 'io.spring.dependency-management'

    java {
        sourceCompatibility = JavaVersion.VERSION_17
    }

    dependencies {
        compileOnly 'org.projectlombok:lombok'
        annotationProcessor 'org.projectlombok:lombok'
        testImplementation 'org.springframework.boot:spring-boot-starter-test'
    }

    dependencyManagement {
        imports {
            mavenBom "org.springframework.boot:spring-boot-dependencies:3.2.0"
        }
    }

    test {
        useJUnitPlatform()
    }
}

// Root 프로젝트는 빌드하지 않음
bootJar.enabled = false
jar.enabled = false

plugins {
    java
    id("org.springframework.boot") version "3.2.0"
    id("io.spring.dependency-management") version "1.1.4"
}

allprojects {
    group = "com.example"
    version = "1.0.0"

    repositories {
        mavenCentral()
    }
}

subprojects {
    apply(plugin = "java")
    apply(plugin = "io.spring.dependency-management")

    configure<JavaPluginExtension> {
        sourceCompatibility = JavaVersion.VERSION_17
    }

    the<io.spring.gradle.dependencymanagement.dsl.DependencyManagementExtension>().apply {
        imports {
            mavenBom("org.springframework.boot:spring-boot-dependencies:3.2.0")
        }
    }

    dependencies {
        "compileOnly"("org.projectlombok:lombok")
        "annotationProcessor"("org.projectlombok:lombok")
        "testImplementation"("org.springframework.boot:spring-boot-starter-test")
    }

    tasks.withType<Test> {
        useJUnitPlatform()
    }
}

tasks.named<org.springframework.boot.gradle.tasks.bundling.BootJar>("bootJar") {
    enabled = false
}

tasks.named<Jar>("jar") {
    enabled = false
}

3. 각 모듈 설정

marketplace-common (공통 모듈)

// marketplace-common/build.gradle
dependencies {
    // 공통 유틸리티만 포함
}

marketplace-common/
└── src/main/java/com/example/common/
    ├── exception/
    │   ├── BusinessException.java
    │   ├── ErrorCode.java
    │   └── ErrorResponse.java
    └── util/
        └── DateUtils.java

marketplace-domain (도메인 모듈)

// marketplace-domain/build.gradle
dependencies {
    implementation project(':marketplace-common')

    // JPA
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'

    // Validation
    implementation 'org.springframework.boot:spring-boot-starter-validation'
}

marketplace-domain/
└── src/main/java/com/example/domain/
    ├── member/
    │   ├── Member.java
    │   ├── MemberRepository.java (인터페이스)
    │   └── MemberService.java
    ├── product/
    │   ├── Product.java
    │   ├── ProductRepository.java (인터페이스)
    │   └── ProductService.java
    └── order/
        ├── Order.java
        ├── OrderRepository.java (인터페이스)
        └── OrderService.java

marketplace-domain/
└── src/main/java/com/example/domain/
    ├── common/
    │   └── BaseEntity.java
    ├── member/
    │   ├── Member.java
    │   └── Role.java
    ├── product/
    │   ├── Product.java
    │   ├── ProductImage.java
    │   └── ProductStatus.java
    ├── order/
    │   ├── Order.java
    │   ├── OrderItem.java
    │   └── OrderStatus.java
    └── category/
        └── Category.java

marketplace-infra (인프라 모듈)

// marketplace-infra/build.gradle
dependencies {
    implementation project(':marketplace-common')
    implementation project(':marketplace-domain')

    // JPA 구현체
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    runtimeOnly 'com.h2database:h2'
    runtimeOnly 'com.mysql:mysql-connector-j'

    // QueryDSL (선택)
    implementation 'com.querydsl:querydsl-jpa:5.0.0:jakarta'
    annotationProcessor 'com.querydsl:querydsl-apt:5.0.0:jakarta'

    // Redis (선택)
    implementation 'org.springframework.boot:spring-boot-starter-data-redis'
}

marketplace-infra/
└── src/main/java/com/example/infra/
    ├── persistence/
    │   ├── member/
    │   │   ├── MemberJpaRepository.java
    │   │   └── MemberRepositoryImpl.java
    │   ├── product/
    │   │   └── ProductRepositoryImpl.java
    │   └── order/
    │       └── OrderRepositoryImpl.java
    ├── cache/
    │   └── RedisCacheConfig.java
    └── external/
        └── PaymentGatewayClient.java

marketplace-infra/
└── src/main/java/com/example/infra/
    ├── member/
    │   └── MemberJpaRepository.java
    ├── product/
    │   ├── ProductJpaRepository.java
    │   ├── ProductJpaRepositoryCustom.java
    │   └── ProductJpaRepositoryImpl.java (QueryDSL)
    ├── order/
    │   ├── OrderJpaRepository.java
    │   ├── OrderJpaRepositoryCustom.java
    │   └── OrderJpaRepositoryImpl.java (QueryDSL)
    └── category/
        └── CategoryJpaRepository.java

marketplace-api (API 모듈)

// marketplace-api/build.gradle
plugins {
    id 'org.springframework.boot'
}

dependencies {
    implementation project(':marketplace-common')
    implementation project(':marketplace-domain')
    implementation project(':marketplace-infra')

    // Web
    implementation 'org.springframework.boot:spring-boot-starter-web'

    // Security
    implementation 'org.springframework.boot:spring-boot-starter-security'
    implementation 'io.jsonwebtoken:jjwt-api:0.12.3'
    runtimeOnly 'io.jsonwebtoken:jjwt-impl:0.12.3'
    runtimeOnly 'io.jsonwebtoken:jjwt-jackson:0.12.3'

    // Swagger
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.3.0'
}

bootJar {
    enabled = true
    archiveFileName = 'marketplace-api.jar'
}

marketplace-api/
└── src/main/java/com/example/api/
    ├── MarketplaceApplication.java
    ├── config/
    │   ├── SecurityConfig.java
    │   └── SwaggerConfig.java
    ├── controller/
    │   ├── MemberController.java
    │   ├── ProductController.java
    │   └── OrderController.java
    ├── dto/
    │   ├── request/
    │   └── response/
    └── security/
        ├── JwtTokenProvider.java
        └── JwtAuthenticationFilter.java

marketplace-api/
└── src/main/java/com/example/api/
    ├── MarketplaceApplication.java
    ├── config/
    │   ├── SecurityConfig.java
    │   ├── SwaggerConfig.java
    │   └── DataInitializer.java
    ├── member/
    │   ├── MembersController.java
    │   ├── AuthController.java
    │   ├── AuthService.java
    │   ├── MemberService.java
    │   └── dto/
    ├── product/
    │   ├── ProductController.java
    │   ├── ProductService.java
    │   └── dto/
    ├── order/
    │   ├── OrderController.java
    │   ├── OrderService.java
    │   ├── dto/
    │   └── event/
    ├── category/
    │   ├── CategoryController.java
    │   └── CategoryService.java
    └── security/
        ├── JwtTokenProvider.java
        └── JwtAuthenticationFilter.java

4. 모듈 간 의존성 규칙

Option A (정석) - 의존성 역전 적용

┌─────────────────┐
│  marketplace-api │  ← Controller, Security
├─────────────────┤
│     depends on   │
├─────────────────┤
│ marketplace-domain │  ← Entity, Service, Repository 인터페이스
├─────────────────┤
│ (does not depend) │  ← domain은 infra를 의존하지 않음!
├─────────────────┤
│ marketplace-infra │  ← Repository 구현체 (domain 인터페이스 구현)
├─────────────────┤
│     depends on   │
├─────────────────┤
│ marketplace-common │  ← 공통 유틸, 예외
└─────────────────┘

핵심: domain → infra 의존 금지, Repository 인터페이스/구현 분리

Option B (간소화) - 실용적 접근

┌─────────────────┐
│  marketplace-api │  ← Controller, Service, Security
├─────────────────┤
│     depends on   │
├─────────────────┤
│ marketplace-domain │  ← Entity만
│ marketplace-infra │  ← JpaRepository, QueryDSL
├─────────────────┤
│     depends on   │
├─────────────────┤
│ marketplace-common │  ← 공통 유틸, 예외
└─────────────────┘

핵심: api가 domain과 infra를 모두 조합하여 사용. domain은 순수 Entity만 포함

5. Repository 구현 패턴

Option A: 인터페이스/구현 분리 (DIP)

// marketplace-domain/src/.../ProductRepository.java (인터페이스)
public interface ProductRepository {
    Product save(Product product);
    Optional<Product> findById(Long id);
    List<Product> findByCategory(Category category);
    Page<Product> search(ProductSearchCondition condition, Pageable pageable);
}

// marketplace-infra/src/.../ProductRepositoryImpl.java (구현체)
@Repository
@RequiredArgsConstructor
public class ProductRepositoryImpl implements ProductRepository {

    private final ProductJpaRepository jpaRepository;
    private final ProductQueryRepository queryRepository;

    @Override
    public Product save(Product product) {
        return jpaRepository.save(product);
    }

    @Override
    public Optional<Product> findById(Long id) {
        return jpaRepository.findById(id);
    }

    @Override
    public List<Product> findByCategory(Category category) {
        return jpaRepository.findByCategory(category);
    }

    @Override
    public Page<Product> search(ProductSearchCondition condition, Pageable pageable) {
        return queryRepository.search(condition, pageable);
    }
}

// JPA Repository (infra 내부에서만 사용)
interface ProductJpaRepository extends JpaRepository<Product, Long> {
    List<Product> findByCategory(Category category);
}

Option B: QueryDSL Custom Repository 패턴

JpaRepository에 QueryDSL을 통합하는 Spring Data 표준 패턴이다.

// marketplace-infra/src/.../ProductJpaRepository.kt
interface ProductJpaRepository : JpaRepository<Product, Long>, ProductJpaRepositoryCustom {
    fun findBySellerId(sellerId: Long, pageable: Pageable): Page<Product>
    fun findByStatusOrderBySalesCountDesc(status: ProductStatus, pageable: Pageable): List<Product>
}

// marketplace-infra/src/.../ProductJpaRepositoryCustom.kt
interface ProductJpaRepositoryCustom {
    fun findByIdWithLock(id: Long): Optional<Product>
    fun search(
        keyword: String?,
        categoryId: Long?,
        minPrice: BigDecimal?,
        maxPrice: BigDecimal?,
        status: ProductStatus?,
        sellerId: Long?,
        pageable: Pageable
    ): Page<Product>
}

// marketplace-infra/src/.../ProductJpaRepositoryImpl.kt
class ProductJpaRepositoryImpl(
    private val queryFactory: JPAQueryFactory
) : ProductJpaRepositoryCustom {

    private val product = QProduct.product

    override fun findByIdWithLock(id: Long): Optional<Product> {
        val result = queryFactory
            .selectFrom(product)
            .where(product.id.eq(id))
            .setLockMode(LockModeType.PESSIMISTIC_WRITE)
            .fetchOne()
        return Optional.ofNullable(result)
    }

    override fun search(
        keyword: String?,
        categoryId: Long?,
        minPrice: BigDecimal?,
        maxPrice: BigDecimal?,
        status: ProductStatus?,
        sellerId: Long?,
        pageable: Pageable
    ): Page<Product> {
        val content = queryFactory
            .selectFrom(product)
            .where(
                keywordContains(keyword),
                categoryIdEq(categoryId),
                priceGoe(minPrice),
                priceLoe(maxPrice),
                statusEq(status),
                sellerIdEq(sellerId),
                notDeleted()
            )
            .offset(pageable.offset)
            .limit(pageable.pageSize.toLong())
            .orderBy(product.createdAt.desc())
            .fetch()

        val countQuery = queryFactory
            .select(product.count())
            .from(product)
            .where(/* 동일 조건 */)

        return PageableExecutionUtils.getPage(content, pageable) {
            countQuery.fetchOne() ?: 0L
        }
    }

    private fun keywordContains(keyword: String?) =
        keyword?.takeIf { it.isNotBlank() }?.let {
            product.name.containsIgnoreCase(it)
                .or(product.description.containsIgnoreCase(it))
        }

    // ... 기타 조건 메서드
}

// Service에서 직접 JpaRepository 사용
@Service
class ProductService(
    private val productJpaRepository: ProductJpaRepository,  // 직접 주입
    private val memberJpaRepository: MemberJpaRepository,
    private val categoryJpaRepository: CategoryJpaRepository
) {
    fun searchProducts(req: ProductSearchRequest, pageable: Pageable): Page<ProductResponse> {
        return productJpaRepository.search(
            keyword = req.keyword,
            categoryId = req.categoryId,
            minPrice = req.minPrice,
            maxPrice = req.maxPrice,
            status = req.status?.let { ProductStatus.valueOf(it) },
            sellerId = req.sellerId,
            pageable = pageable
        ).map { ProductResponse.from(it) }
    }
}

6. 빌드 및 실행

# 전체 빌드
./gradlew build

# 특정 모듈만 빌드
./gradlew :marketplace-api:build

# 실행
./gradlew :marketplace-api:bootRun

# JAR 생성
./gradlew :marketplace-api:bootJar
# → marketplace-api/build/libs/marketplace-api.jar

7. Docker 설정 (멀티 모듈)

# Dockerfile
FROM gradle:8.5-jdk17 AS builder

WORKDIR /app

# Gradle 파일 먼저 복사 (캐싱)
COPY build.gradle settings.gradle ./
COPY gradle ./gradle
COPY marketplace-common/build.gradle ./marketplace-common/
COPY marketplace-domain/build.gradle ./marketplace-domain/
COPY marketplace-infra/build.gradle ./marketplace-infra/
COPY marketplace-api/build.gradle ./marketplace-api/

RUN gradle dependencies --no-daemon || true

# 소스 복사 및 빌드
COPY . .
RUN gradle :marketplace-api:bootJar --no-daemon -x test

# Runtime
FROM eclipse-temurin:17-jre-alpine

WORKDIR /app
COPY --from=builder /app/marketplace-api/build/libs/marketplace-api.jar app.jar

RUN addgroup -S spring && adduser -S spring -G spring
USER spring:spring

EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]

// 잘못된 예: A → B → A
marketplace-domain → marketplace-infra (X)
marketplace-infra → marketplace-domain (O)

정리

체크리스트

핵심 포인트

1. 이벤트: 부가 기능 분리, @TransactionalEventListener로 트랜잭션 제어
2. 비동기: 응답에 불필요한 작업 분리, 스레드풀 설정 필수
3. 파일 처리: 검증 필수, 저장 경로 보안 고려
4. API 버저닝: URI 방식이 가장 명확
5. 아키텍처: 과제 규모에 맞게 선택, 오버엔지니어링 주의
6. 멀티 모듈: 의존성 역전 원칙, domain → infra 의존 금지

시리즈를 마쳤습니다! 종합 과제 에서 1~7편의 내용을 모두 활용해보세요.

👉 이전: 6편 - DevOps & Deployment 👉 다음: 종합 과제