develop

AI Agent란

KJihun — Wed, 15 Apr 2026 14:19:09 +0900

기존 AI가 "질문하면 답하는" 방식이었다면,

AI 에이전트는 목표를 주면 스스로 계획을 세우고, 도구를 사용하고, 여러 단계를 거쳐 작업을 완수하는 AI이다.

어떻게 스스로 계획을 세우고 작업을 완수할 수 있을까?

에이전트가 어떻게 사고하는지에 대해 찾아보았다.

에이전트 내부 사고 루프 (Cognitive Architecture)

Planning (계획): 사용자 요청을 분석하여 이를 달성하기 위한 작은 단위의 단계(Step)들로 나눈다.
Tool Use (도구 사용): 웹 검색, 코드 실행, 데이터베이스 조회 등 외부 API를 호출하여 필요한 정보나 결과를 얻는다.
Action & Observation (실행 및 관찰): 결과를 확인하고, 확인한 내용을 바탕으로 ReAct 방식으로 계획을 수정하거나 다음 단계로 넘어갈지 결정한다.
Memory (메모리): 이전 대화 맥락이나 중간 결과물들을 기억하고 참조한다

ReAct

에이전트는 단일 작업을 처리할 때 ReAct(Reason + Act) 패턴이 가장 널리 쓰인다.

ReAct 란 Reason + Act 의 합성어로, 문제를 해결하는 과정에서 추론과 행동을 결합하는 새로운 패러다임이다.

기존의 언어 모델들이 주로 추론이나 행동 중 하나에 집중했던 반면, ReAct는 이 두 가지 기능을 통합하여 시너지 효과를 창출한다.

실행(Act)과 그 결과에 대한 관찰(Observation), 그리고 이를 바탕으로 한 새로운 사고(Thought)를 반복하여 결과를 도출한다.

예시

AI 에이전트에게 "게시판 만들어줘" 라고 요구할 경우

1. Planning (계획 단계)

사용자의 "게시판 만들어줘"라는 추상적인 요청을 실행 가능한 단위로 쪼갠다.

실행 가능한 단위: 에이전트가 한 번의 도구 호출이나 한 번의 추론으로 성공/실패 여부를 확인할 수 있는 최소한의 작업

사고(Thought): "게시판을 만들려면 데이터 스키마 정의, API 엔드포인트 구현(CRUD), 프런트엔드 UI 구성이 필요하겠군. 우선 기술 스택을 결정하고 단계별로 진행하자."
수립된 계획
1. 기술 스택 선정 (예: Spring Boot + JPA)
2. 게시글(Post) 엔티티 및 Repository 생성
3. CRUD 기능이 담긴 Controller 및 Service 구현
4. 동작 확인을 위한 테스트

2. Tool Use (도구 사용 및 실행)

에이전트가 실제로 코드를 작성하거나 파일을 생성하는 도구를 호출한다

Action (Act): create_file("Post.java", "public class Post { ... }")
Action (Act): create_file("PostController.java", "...")
에이전트는 이 과정에서 개발 환경에 접근하거나 코드 생성 라이브러리를 사용하게 된다

3. Action & Observation (관찰 및 계획 수정)

도구 사용 후 돌아온 결과를 확인하고 다음 행동을 결정한다.

Observation (관찰): 코드 생성은 완료되었으나, 빌드 도구 실행 중 에러가 발생함을 확인
Thought (재판단): "아, 빌드 설정 파일(pom.xml 또는 build.gradle)에 의존성을 추가하는 단계를 빠뜨렸구나. 계획에 '의존성 체크' 단계를 추가하고 수정해야겠다."
Revised Action (수정된 실행)

4. Memory (메모리 참조)

작업 중간중간 이전 단계에서 결정한 사항을 잊지 않고 기억해 불필요하게 비대해지는 설계를 방지한다.

최종적인 에이전트의 흐름 요약

[Thought] "게시판 제작 시작. 우선 DB 구조부터 잡자."
[Action] 엔티티 코드 작성 및 파일 저장.
[Observation] 저장 완료. 문법 오류 없음.
[Thought] "성공적이야. 이제 이 데이터를 다룰 컨트롤러를 만들 차례군."
[Action] 컨트롤러 코드 작성.
[Observation] 작성 중 특정 라이브러리 참조 에러 발생.
[Thought] "오타가 있었네. 다시 수정해서 저장하자." (ReAct에 의한 계획 수정)
[Final Output] "게시판 기본 코드 구현이 완료되었습니다. Post, Service, Controller 파일을 확인해 보세요."

자료를 찾다보니 어떤 식으로 요청을 해야 토큰 소모량을 효율적으로 사용하고, 정확한 결괏값을 뽑아낼 수 있을지 감이 잡혔다.

AI 에이전트의 특성을 고려하여 하이브리드 방식이 가장 토큰 효율이 좋다고 판단했다.

구조: 디테일 하게 쪼개지 않고 한번의 요청으로 처리한다
- 엔티티 구조와 API 명세서 같은 설계도는 한 번의 요청으로 크게 뽑는다
- 설계도가 이미 존재한다면 설계도를 분석을 요청하여 컨텍스트를 주입(Context Injection) 시킨다
구현: "방금 만든 설계를 바탕으로 PostController의 등록 기능만 구현해줘" 식으로 실제 로직은 쪼개서 요청한다

구조를 AI에게 구현하게 시킬 경우, AI가 전체 맥락을 파악한 상태이기 때문에 세부 작업을 수행할 때 일관성도 훨씬 높아진다.

PDF 내보내기 첫 페이지 공백 및 잘림

KJihun — Wed, 1 Apr 2026 16:26:38 +0900

문제

PDF 인쇄 및 출력 시 첫 페이지가 공백으로 출력되고,

특정 기준(송장번호)으로 페이지 나누기(page-break-after: always)가 동작하지 않음

1. #printDiv에 position: absolute 추가 : 첫 페이지 공백 해결, 페이지 나누기 안 됨

2. #printDiv에 position: fixed 추가첫 페이지 공백 해결, 페이지 나누기 안 됨
3. #printDiv에 position 제거: 페이지 나누기 정상, 첫 페이지 공백 재발

4. console.log로 부모 체인 디버깅: 근본 원인 발견

원인

AdminLTE의 CSS가 .content-wrapper에 overflow: hidden을 적용하고 있었음
  - overflow: hidden → Block Formatting Context(BFC) 생성
  - BFC 내부에서는 브라우저 인쇄 엔진이 부모 경계를 넘는 page-break를 삽입하지 않음
  - #printDiv가 .content-wrapper 안에 있으므로 page-break-after: always가 무시됨

  그리고 visibility: hidden은 요소를 숨기되 공간은 유지하므로, position 없이는 숨겨진 요소들의 공간이 #printDiv를 밀어내어 첫
  페이지가 공백이 됨

해결 방법

  @media print {
      .content-wrapper { overflow: visible !important; }
  }

- overflow: visible로 BFC를 해제하여 page-break 정상 동작
- position: absolute로 숨겨진 요소들의 공간을 무시하고 첫 페이지 공백 해결

알게 된 것

1. overflow: hidden은 자손의 page-break를 차단한다 — BFC 경계를 넘는 페이지 나누기를 브라우저가 삽입하지 않음
2. position: absolute/fixed는 page-break를 무효화한다 — 문서 흐름에서 벗어난 요소에 page-break가 적용되지 않음

단, overflow: visible로 BFC를 해제하면 position: absolute에서도 page-break가 동작함
  3. visibility: hidden은 display: none과 다르다 — 요소를 안 보이게 하지만 공간은 그대로 차지함
  4. 직접 작성한 CSS에 없더라도 프레임워크가 적용한 overflow, transform 등이 인쇄 레이아웃에 영향을 줌
  5. getComputedStyle로 부모 체인을 추적하면 원인을 빠르게 찾을 수 있다

[MONITORING] 예외발생 시 Slack 으로 알림 보내기

KJihun — Wed, 1 Apr 2026 16:26:12 +0900

1. 코드작성

public enum ErrorLevel {
    LOW(Level.INFO, false),
    MEDIUM(Level.WARN, false),
    HIGH(Level.ERROR, true),
    CRITICAL(Level.ERROR, true);
}

- 에러레벨 ENUM으로 작성

if (level.isSlackNotify()) slackNotifier.send(e, request);

- true일 경우 심각한 예외로 지정, slack에 메세지 전달

public class SlackNotifier {

    @Value("${slack.webhook.url:}")
    private String webhookUrl;

    private final RestClient restClient = RestClient.create();

    private static final DateTimeFormatter FORMATTER = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");

    @Async
    public void send(Exception e, HttpServletRequest request) {
        if (webhookUrl == null || webhookUrl.isBlank()) {
            log.warn("Slack webhook URL이 설정되지 않아 알림을 보내지 않습니다.");
            return;
        }

        try {
            ErrorLevel level = (e instanceof BaseException be) ? be.getErrorCode().getLevel() : ErrorLevel.CRITICAL;
            String emoji = (level == ErrorLevel.CRITICAL) ? ":rotating_light:" : ":warning:";
            String mention = (level == ErrorLevel.CRITICAL) ? "<!channel> " : "";
            String errorCode = (e instanceof BaseException be) ? be.getErrorCode().name() : "INTERNAL_ERROR";

            String stackTrace = getStackTrace(e, 10);

            String payload = """
                    {
                      "blocks": [
                        {
                          "type": "header",
                          "text": {
                            "type": "plain_text",
                            "text": "%s [%s] 예외 발생"
                          }
                        },
                        {
                          "type": "section",
                          "fields": [
                            { "type": "mrkdwn", "text": "*Error Code:*\\n`%s`" },
                            { "type": "mrkdwn", "text": "*Level:*\\n`%s`" },
                            { "type": "mrkdwn", "text": "*URI:*\\n`%s %s`" },
                            { "type": "mrkdwn", "text": "*Time:*\\n`%s`" }
                          ]
                        },
                        {
                          "type": "section",
                          "text": {
                            "type": "mrkdwn",
                            "text": "*Message:*\\n```%s```"
                          }
                        },
                        {
                          "type": "section",
                          "text": {
                            "type": "mrkdwn",
                            "text": "*StackTrace:*\\n```%s```"
                          }
                        }
                      ],
                      "text": "%s%s [%s] %s"
                    }
                    """.formatted(
                    emoji, level,
                    errorCode,
                    level,
                    request.getMethod(), request.getRequestURI(),
                    LocalDateTime.now().format(FORMATTER),
                    escapeJson(e.getMessage()),
                    escapeJson(stackTrace),
                    mention, emoji, level, escapeJson(e.getMessage())
            );

            restClient.post()
                    .uri(webhookUrl)
                    .contentType(MediaType.APPLICATION_JSON)
                    .body(payload)
                    .retrieve()
                    .toBodilessEntity();

            log.info("Slack 알림 발송 완료 [{}]", level);
        } catch (Exception ex) {
            log.error("Slack 알림 발송 실패", ex);
        }
    }

    private String getStackTrace(Exception e, int maxLines) {
        StringWriter sw = new StringWriter();
        e.printStackTrace(new PrintWriter(sw));
        String[] lines = sw.toString().split("\n");
        StringBuilder sb = new StringBuilder();
        for (int i = 0; i < Math.min(lines.length, maxLines); i++) {
            sb.append(lines[i]).append("\n");
        }
        if (lines.length > maxLines) {
            sb.append("... ").append(lines.length - maxLines).append(" more lines");
        }
        return sb.toString().trim();
    }

    private String escapeJson(String text) {
        if (text == null) return "null";
        return text
                .replace("\\", "\\\\")
                .replace("\"", "\\\"")
                .replace("\n", "\\n")
                .replace("\r", "\\r")
                .replace("\t", "\\t");
    }

- 메세지 전송 포맷 설정 및 알림 보내기

2. Slack 워크스페이스 생성

  1. https://slack.com/create 접속
  2. 이메일 입력 → 인증코드 확인
  3. 워크스페이스 이름 입력 (예: dkdk-team)
  4. 알림용 채널 생성 (예: #서버-알림)

1. Slack App 생성 + Webhook 발급

1. https://api.slack.com/apps → Create New App → From scratch
2. App 이름 입력 (예: dkdk-alert), 위에서 만든 워크스페이스 선택

3. Incoming Webhooks → 토글 On → Add New Webhook

5. 생성된 Webhook URL 복사

6. 설정에 붙여넣기
slack.webhook.url=https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX

[MONITORING] Prometheus + Grafana + docker

KJihun — Tue, 31 Mar 2026 13:51:08 +0900

1. Spring Boot에 메트릭 엔드포인트 추가

build.gradle에 Actuator + Micrometer 의존성 추가

  // Monitoring
  implementation 'org.springframework.boot:spring-boot-starter-actuator'
  implementation 'io.micrometer:micrometer-registry-prometheus'

application.yml(또는 .properties)에 엔드포인트 노출

  management:
	endpoints:
      web:
        exposure:
          include: health, info, prometheus
    metrics:
      tags:
        application: dkdk-backend

2. Prometheus + Grafana를 Docker Compose에 추가

  prometheus:
    image: prom/prometheus:latest
    container_name: dkdk_prometheus
    restart: always
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus/prometheus.yml:/etc/prometheus/prometheus.yml
      - prometheus_data:/prometheus
    extra_hosts:
      - "host.docker.internal:host-gateway"

  grafana:
    image: grafana/grafana:latest
    container_name: dkdk_grafana
    restart: always
    ports:
      - "3001:3000"
    volumes:
      - grafana_data:/var/lib/grafana
    environment:
      GF_SECURITY_ADMIN_USER: admin
      GF_SECURITY_ADMIN_PASSWORD: admin
    depends_on:
      - prometheus

3. Docker Compose 실행

접속 URL
  - Prometheus: http://localhost:9090
  - Grafana: http://localhost:3001 (ID: admin / PW: admin)
  - 메트릭 원본: http://localhost:8080/actuator/prometheus

4. Grafana에서 Prometheus 데이터소스 연결

  1. Grafana 로그인 → 좌측 메뉴 → Connections → Data Sources → Add data source
  2. Prometheus 선택
  3. URL에 http://prometheus:9090 입력 → Save & Test

5. 대시보드 추가

- Grafana 좌측 → Dashboards → Import
- Dashboard ID 4701 입력 (JVM Micrometer 대시보드) → Load → Prometheus 데이터소스 선택 → Import

이후 JVM 메모리, GC, HTTP 요청 수/응답시간 등을 실시간으로 모니터링할 수 있다

시스템 설계(모놀리식 vs 마이크로서비스 아키텍처)

KJihun — Tue, 9 Dec 2025 12:19:41 +0900

최근에 Spring Batch와 RabbitMQ를 활용하며 대규모 트래픽 처리와 대용량 데이터 처리에 관심이 생겼다. 그러다

“이런 트래픽이 실제 서비스에서 발생한다면, 시스템을 어떻게 설계해야 안정적이고 효율적으로 운영할 수 있을까?”

라는 고민이 들었고, 그 궁금증을 계기로 시스템 설계에 대해 본격적으로 공부하게 되었다.

시스템 설계란?

시스템 설계는 웹 서비스가 트래픽이 많아지거나 데이터량이 커지더라도

안정적으로 동작할 수 있도록 구조를 설계하는 과정이다.

서비스가 커질수록 단순한 CRUD 구조만으로는 한계가 생긴다.
성능, 확장성, 신뢰성, 유지보수성을 고려하여 구조를 잡아야 한다.
실제로는 하나의 서버/DB로는 부족해지며 여러 컴포넌트를 나누고 연결해야 한다.

시스템 설계를 공부하면서 가장 먼저 접하게 된 개념이 모놀리식 아키텍처와 마이크로서비스 아키텍처(MSA)다.

모놀리식 아키텍처 (Monolithic Architecture)

모든 기능(UI, 비즈니스 로직, 데이터 처리 등)을 하나의 애플리케이션 코드베이스로 구성한 구조이다.

모든 것이 한 프로젝트 안에서 실행되며, 하나의 프로세스로 배포된다.

일반적으로 단일 DB와 단일 서버 구조를 사용한다
동일 애플리케이션을 여러 서버에 배포하면 로드밸런싱은 가능하지만, 구조는 여전히 일체형이다

장점

초기 개발과 배포가 간단하다
모든 코드가 한곳에 있어 테스트 및 디버깅이 쉽다
API 통신이 필요 없어서 성능 측면에서 단순하다

단점

코드가 커지면 변경이 어렵고, 한 부분 수정 시 전체 빌드/배포가 필요하다
특정 기능에 트래픽이 몰려도 전체 애플리케이션을 확장해야 한다
한 서비스의 장애가 전체 시스템에 영향을 줄 수 있다 (단일 장애점)

마이크로서비스 아키텍처 (Microservices Architecture, MSA)

애플리케이션을 작은 단위의 독립적인 서비스들로 나누어 구성하는 구조이다.

각 서비스는 하나의 도메인(예: 인증, 주문 등)을 책임지고 독립적으로 개발·배포된다.

각 서비스는 자신의 데이터베이스를 갖는다 (Database per Service)
공통 인프라: API Gateway, Service Discovery, Message Queue 등과 함께 구성된다
- API Gateway: 모든 요청의 진입점, 라우팅 처리
- Service Discovery: 각 서비스의 위치(IP/포트) 동적 관리
- Message Queue: 비동기 이벤트 처리 (예: Kafka, RabbitMQ)

장점

기능 단위로 독립 배포 가능하여 빠른 릴리즈와 롤백이 가능하다
특정 서비스만 선택적으로 확장(수평 확장)할 수 있다
서비스마다 적절한 기술 스택을 선택할 수 있다
한 서비스 장애가 전체에 영향을 주지 않도록 격리 가능하다

단점

서비스 간 통신(API)으로 인한 지연 및 장애 전파 가능성
인프라/운영 복잡도 증가 (서비스 디스커버리, 모니터링, 로깅 등 필요)
설계 미숙 시 데이터 정합성과 트랜잭션 문제가 발생할 수 있음

로드 밸런싱 (Load Balancing)

수평 확장을 통해 특정 서비스의 서버 수를 늘렸다고 해도,

트래픽이 고르게 분산되지 않으면 확장의 효과를 제대로 누릴 수 없다.

이러한 문제를 해결하기 위한 대표적인 방법이 바로 로드밸런싱(Load Balancing)이다. 로드밸런싱은

사용자 요청을 여러 서버에 균등하게 분산하여 과부하를 방지하고, 응답 속도를 향상시키는 핵심 기술이다.

장점

서버의 부하 분산으로 처리 성능 향상
하나의 서버가 죽더라도 나머지 서버로 트래픽을 자동 전환 (고가용성)

구현 방식

L4 (IP 기반), L7 (경로/헤더 기반)
라운드로빈, 최소 연결 수, 가중치 기반 분산
Nginx, HAProxy, AWS ELB 등으로 구현

데이터베이스 설계 (SQL vs NoSQL)

로드밸런싱을 통해 애플리케이션 레벨의 트래픽을 효과적으로 분산시켰다면,

마지막으로 중요한 설계 요소는 데이터베이스(DB)다.

DB는 대표적으로 SQL과 NoSQL로 나뉘며, 데이터의 특성과 목적에 따라 유연하게 선택하는 것이 중요하다.

SQL (관계형 DB)

스키마 기반 테이블 구조, 엄격한 데이터 정합성
복잡한 쿼리, 트랜잭션 처리에 적합
대표: MySQL, PostgreSQL, Oracle

NoSQL (비관계형 DB)

스키마가 유연하며, 대용량 분산 저장에 적합
키-값, 문서, 그래프 등 다양한 형태
대표: MongoDB, Redis, Cassandra

선택 기준 및 조합 사례

사용자 정보, 결제 등 정합성이 중요한 데이터 → SQL
캐시, 로그, 추천 등 대량 처리/성능 중심 데이터 → NoSQL
실제 시스템에서는 두 가지 DB를 혼합하여 사용하는 경우가 많다

내결함성 (Fault Tolerance)

아무리 잘 설계된 시스템이라도 서버나 데이터베이스에 장애가 발생할 수 있다.

그렇기 때문에 시스템 일부에 문제가 생기더라도 전체 서비스는 문제 없이 동작할 수 있도록 하는

내결함성(Fault Tolerance) 역시 중요한 설계 요소다.

실제 서비스 환경에서는 서비스의 신뢰성과 직결되기 때문에 반드시 고려되어야 한다.

이를 구현하기 위한 대표적인 방법으로는

서버 및 DB의 이중화, 헬스 체크, 장애 발생 시 자동 전환(Failover) 등이 있다.

마무리하며

최근 Spring Batch와 RabbitMQ를 활용한 프로젝트를 진행하며

많은 양의 데이터와 요청이 한꺼번에 몰릴 경우 시스템이 어떻게 병목될 수 있는지 고민하게 되었고,

그 과정을 통해 자연스럽게 시스템 설계에 관해 찾아보고 학습하게 되었다.

이를 계기로 단순한 코드 작성보다 서비스를 안정적으로 운영할 수 있는 설계가 중요하다는 걸 느꼈다.

공부를 통해 막연했던 개념들이 실제 구조 속에서

어떻게 연결되고 역할을 하는지 이해되기 시작했다.

작은 프로젝트라도 직접 구조를 설계해보며 감각을 익히고,

앞으로는 설계가 서비스에 끼치는 영향을 몸소 체험해보고 싶다.

[OS] 세마포어(Semaphore)와 뮤텍스(Mutex)

KJihun — Fri, 17 Oct 2025 16:47:46 +0900

세마포어(Semaphore)와 뮤텍스(Mutex)

다중 스레드 환경에서 웹 애플리케이션을 개발할 때, 공유 자원(Shared Resource) 에 대한 접근 제어는 피할 수 없는 문제다
여러 스레드가 동시에 동일한 데이터를 수정하려 하면, 데이터 무결성이 깨지거나 경쟁 상태(Race Condition) 가 발생할 수 있다.

이러한 문제를 해결하기 위한 대표적인 동기화 기법이 세마포어(Semaphore) 와 뮤텍스(Mutex) 이다.
이들은 모두 운영체제(OS) 수준에서 공유 자원에 대한 접근을 제어하기 위해 사용되는 동기화 메커니즘으로,
자원 접근을 제어하는 ‘락(lock)’을 관리하는 기술이라 할 수 있다.

즉, 낙관적 락(Optimistic Lock), 비관적 락(Pessimistic Lock), 분산 락(Distributed Lock) 등이
서버나 데이터베이스 수준에서 웹 개발자가 구현하는 락이라면,
세마포어와 뮤텍스는 운영체제 차원에서 제공되는 락 관리 기법이다.

세마포어 (Semaphore)

공유 자원에 동시 접근 가능한 개수를 제어하는 역할이다.

일반적으로 1 이상의 값을 가지며, 해당 값은 동시 접근을 허용하는 허용치를 나타낸다.

특징

소유권이 없다 (누가 잠갔는가를 추적하지 않는다) → 세마포어를 잠근 스레드가 아니더라도 해제할 수 있다
상대적으로 많은 오버헤드를 가진다(정수 카운터 관리 등)

작동 방식

`P()` (Wait)와 `V()` (Signal) 두 가지 연산을 사용한다.

`P()`: 세마포어 값을 감소시키고, 이 값이 0보다 작아질 경우 대기 상태로 전환
`V()`: 세마포어 값을 증가시키고, 대기 중인 프로세스나 스레드를 실행 상태로 전환

뮤텍스 (Mutex)

데이터 무결성과 경쟁 상태(Race Condition)를 방지하기 위한 상호 배제(Mutual Exclusion) 기반의 동기화 기법이다.

공유 자원에 대한 접근을 단 하나의 프로세스 또는 스레드에게만 허용하여 데이터의 일관성을 보장한다.
이진 상태를 가지며(Lock, Unlock) 임계 영역이 잠겨있는지 여부를 나타낸다.
소유권을 가진다. 뮤텍스의 상태변화는 한 스레드 또는 프로세스만 가능하다.
하나의 공유 자원에 여러 프로세스나 스레드가 접근하려고 할 때 임계구역 보호를 위해 사용된다.
세마포어 보다 오버헤드가 적다(이진 상태 체크)

작동 방식

뮤텍스를 소유하고 있는 스레드 또는 프로세스만이 뮤텍스를 해제하거나 잠그는 것이 가능하다
스레드가 뮤텍스를 잠그면, 다른 스레드는 해당 뮤텍스를 얻을 때까지 대기한다.

세마포어의 값이 1인 경우, 뮤텍스와 같은 용도로 사용될 수 있다.

그러나 세마포어가 설계된 목적을 벗어나기 때문에 일반적으로 뮤텍스를 사용하는 것이 더 명확하고 안전하다.
따라서 세마포어를 뮤텍스로 사용하는 것은 가능하지만, 뮤텍스가 상호 배제를 위해 더 적합한 동기화 기법이다.

요약

세마포어는 접근 가능한 자원 수량을 제어하고,
뮤텍스는 데이터 무결성과 경쟁 상태(Race Condition) 를 방지하기 위해 사용한다.

두 기법 모두 단일 시스템 내 스레드 간의 코드 실행 및 리소스 접근을 비관적으로 제어하는 기법이다.

낙관적 락(Optimistic Lock)과 비관적 락(Pessimistic Lock)

동시에 여러 트랜잭션이 같은 데이터를 수정하려고 할 때, 데이터의 정합성(Consistency)이 깨질 수 있다.이를 방지하기 위해, 트랜잭션 간의 충돌을 제어하는 동시성 제어(Concurrency Control) 기법이

developerhun.tistory.com

낙관적 락(Optimistic Lock)과 비관적 락(Pessimistic Lock)

KJihun — Fri, 17 Oct 2025 16:34:17 +0900

동시에 여러 트랜잭션이 같은 데이터를 수정하려고 할 때, 데이터의 정합성(Consistency)이 깨질 수 있다.
이를 방지하기 위해, 트랜잭션 간의 충돌을 제어하는 동시성 제어(Concurrency Control) 기법이 필요하다.

세마포어(Semaphore)와 뮤텍스(Mutex)는 운영체제(OS) 수준에서 스레드 간 자원 접근을 제어하기 위해

시스템 락을 거는 방법이다.
반면, 낙관적 락과 비관적 락은 서버 애플리케이션 혹은 데이터베이스(DB) 레벨에서 적용되는 동시성 제어방식이다.

즉, 단일 프로세스 내의 스레드 동기화가 아니라,
여러 트랜잭션이 같은 데이터를 수정하려 할 때 데이터의 정합성(Consistency)을 유지하기 위한 방법이라 할 수 있다.

비관적 락 (Pessimistic Lock)

비관적 락은 “충돌이 자주 일어날 것이다”라고 비관적으로 가정하고,
데이터를 읽거나 수정하기 전에 먼저 락을 걸어 다른 트랜잭션의 접근을 차단하는 방식이다.

즉, 한 트랜잭션이 데이터를 조회하거나 수정하는 동안,
다른 트랜잭션은 그 데이터에 접근할 수 없다.

동작 방식

트랜잭션이 데이터를 읽기 or 수정 전에 lock을 획득한다.
다른 트랜잭션이 해당 데이터에 접근하려 하면, 락이 해제될 때까지 대기(blocking) 된다.
작업이 완료되면 트랜잭션이 커밋 또는 롤백되며 락이 해제된다.

장점

데이터 정합성을 강력하게 보장한다.
구현이 비교적 간단하고 직관적이다.

단점

락으로 인한 대기 시간이 길어져 시스템 전체의 성능 저하를 유발할 수 있다.
락을 너무 오래 유지하면 데드락(Deadlock)이 발생할 위험이 크다.

DB 락 적용 예시

BEGIN;

SELECT * 
FROM account 
WHERE id = 1 
FOR UPDATE;  -- 베타적 락

UPDATE account 
SET balance = balance - 100 
WHERE id = 1;

COMMIT;

FOR UPDATE를 사용하면 Exclusive Lock(배타적 락)이 걸려 다른 트랜잭션은 이 데이터가 커밋될 때까지 접근할 수 없다.

서버 락 적용 예시

private final Object lock = new Object();

public void withdraw(Long accountId, int amount) {
    synchronized (lock) {
        Account account = accountRepository.findById(accountId);
        account.decreaseBalance(amount);
        accountRepository.save(account);
    }
}

한 스레드가 synchronized 블록에 들어가면 다른 스레드는 해당 블록이 끝날 때까지 대기한다.
즉, 서버 프로세스 내에서만 뮤텍스(Mutex) 수준의 락 제어가 이루어진다.

낙관적 락 (Optimistic Lock)

낙관적 락은 "충돌이 잘 일어나지 않을 것이다"라고 낙관적으로 가정하고,
트랜잭션이 데이터를 수정할 때 버전(Version)을 비교하여 충돌 여부를 확인하는 방식이다.

즉, 락을 걸지 않고 자유롭게 접근하되, 커밋 시점에 충돌을 검증한다.

동작 방식

데이터를 읽을 때, 현재 버전(version) 정보를 함께 가져온다.
수정 시, WHERE 조건에 버전을 포함하며, 업데이트 성공시 version 값을 증가시킨다.
버전이 일치하지 않을 경우 업데이트하지 않으며, UPDATE 결과가 0건이 되어 충돌이 감지된다.
충돌 시에는 OptimisticLockException 또는 개발자가 정의한 예외를 발생시켜 재시도 로직을 처리한다.

장점

락을 걸지 않으므로 대기 시간이 없어 높은 처리량(Throughput)을 기대할 수 있다.
데드락의 위험이 없다.

단점

커밋 시점에 충돌을 확인하므로, 롤백 처리 비용이 발생할 수 있다.
충돌이 자주 발생한다면, 계속되는 재시도로 인해 오히려 성능이 저하될 수 있다.
재시도 로직을 개발자가 직접 구현해야 하는 복잡성이 있다.

DB 락 적용 예시

-- 1. 데이터 조회 시 현재 version을 함께 가져온다.
SELECT id, balance, version 
FROM account 
WHERE id = 1;

-- 2. 업데이트 시 version을 비교하며, 일치하면 balance와 version을 동시에 갱신한다.
UPDATE account
SET balance = balance - 100,
    version = version + 1
WHERE id = 1
  AND version = 5;

// 동시성 발생 시 처리 예시(Mybatis)
int updated = jdbcTemplate.update(
    "UPDATE account SET balance = ?, version = version + 1 WHERE id = ? AND version = ?",
    newBalance, accountId, currentVersion
);

if (updated == 0) {
    throw new OptimisticLockConflictException("다른 트랜잭션에서 데이터가 변경되었습니다.");
}

서버 락 적용 예시

@Entity
public class Account {
    @Id
    private Long id;

    @Version  // JPA가 자동으로 version 필드 기반 낙관적 락을 관리
    private int version;

    // ....
}

@Service
public class AccountService {

    @Transactional
    public void withdraw(Long accountId, int amount) {
        Account account = accountRepository.findById(accountId)
                 .orElseThrow(() -> new RuntimeException("계좌를 찾을 수 없습니다."));

        account.decreaseBalance(amount);
        // JPA가 flush 시점에 version 비교 → 불일치 시 OptimisticLockException 발생
    }
}

// 예외 처리 및 재시도 로직
try {
    accountService.withdraw(1L, 1000);
} catch (OptimisticLockException e) {
    // 재시도 로직 또는 사용자 알림 처리
    throw new CustomRetryException("다른 사용자가 데이터를 수정했습니다. 다시 시도해주세요.");
}

@Version 필드가 있으면 JPA는 내부적으로 WHERE id=? AND version=? 조건으로 UPDATE를 수행한다.
version이 일치하지 않으면 OptimisticLockException이 발생한다.
프레임워크가 던지는 예외를 잡아 재시도 또는 사용자에게 알림하는 로직을 추가할 수 있다.

비교요약 : 비관적 락 vs. 낙관적 락

항목 (Category)	비관적 락 (Pessimistic Lock)	낙관적 락 (Optimistic Lock)
기본 가정	충돌이 자주 발생할 것이라고 가정한다.	충돌이 거의 발생하지 않을 것이라고 가정한다.
락 시점	데이터에 접근하는 시점에 락을 건다.	데이터를 수정하고 커밋하는 시점에 충돌을 확인한다.
성능	락으로 인한 대기 때문에 성능 저하가 발생할 수 있다.	락 대기가 없어 높은 처리량을 제공한다.
데이터 정합성	락을 통해 강력하게 보장한다.	커밋 시점에 버전을 비교하여 보장한다.
주요 단점	데드락 발생 가능성, 성능 저하.	잦은 충돌 시 롤백 및 재시도 비용 증가.
구현 복잡도	비교적 간단하다.	재시도 로직 구현이 필요하여 복잡할 수 있다.

어떤 락을 선택해야 할까?

비관적 락이 적합한 경우

쓰기 충돌이 빈번하게 발생할 것으로 예상되는 환경
금액, 재고 등 데이터 정합성이 매우 중요하여 롤백 비용이 대기 비용보다 큰 경우
트랜잭션 처리 시간이 짧아 락 유지 시간이 길지 않은 경우

낙관적 락이 적합한 경우

읽기 작업이 대부분이고 쓰기 작업은 드물게 발생하는 환경
충돌이 발생해도 재시도 처리가 간단하거나 사용자에게 알림으로 충분한 경우
높은 동시성과 처리량이 중요한 서비스

비관적 락과 낙관적 락 중 어느 것이 절대적으로 우수하다고 말할 수는 없다.

애플리케이션의 특성과 데이터의 성격에 따라 적절한 방식을 선택하는 것이 중요하다.

분산 락(distributed lock) 이란?

KJihun — Thu, 16 Oct 2025 14:06:42 +0900

동시성 문제를 해결하기 위해 뮤텍스(Mutex), 세마포어(Semaphore)나

데이터베이스의 비관적/낙관적 락을 떠올리게 된다.

하지만 이 기법들은 모두 모놀리식(Monolithic) 아키텍처 안에서만 동작한다.

하지만 MSA 환경에서는 각 서비스가 독립된 서버와 데이터베이스를 사용하는 것이 일반적이다.

프로세스 간에는 메모리를 공유하지 않기 때문에 서로의 락 상태를 확인하거나 제어할 수 없다.
즉, 한 서버에서 설정한 락을 다른 서버가 인식할 방법이 없다.

따라서 여러 대의 서버가 네트워크를 통해 동일한 공유 자원(예: 재고, 쿠폰, 포인트 등) 에 접근할 수 있는 상황에서는
분산 락(Distributed Lock) 이 필요하다.

분산 락(distributed lock) 이란?

공통 저장소에 락의 상태를 저장하고 각 프로세스가 이 상태를 읽어 락을 획득하거나 해제하는 방식으로 동작한다.

즉, 모든 노드가 공통된 저장소를 통해 락 상태를 공유하여 서로 다른 서버 간 자원 접근을 제어할 수 있게 된다.

분산 락의 동작 원리

공통 저장소에 락의 상태(소유자 식별자, 만료 시간 등)를 저장한다.
락을 얻고자 하는 프로세스는 저장소에 락 생성을 시도한다.
성공하면 해당 자원에 대한 접근 권한을 가지며, 작업이 끝나면 락을 해제한다.
네트워크 장애/크래시로 락이 영구적으로 남는 것을 막기 위해 TTL(만료시간)을 둔다.

자주 사용되는 공통 저장소

Redis

인메모리라 빠르고 SET NX PX 같은 원자적 연산 또는 RedLock 알고리즘을 활용해 분산 락을 구현한다.
응답성이 중요한 시나리오에 자주 사용된다.

Zookeeper

분산 코디네이터로서 노드 간 상태 동기화, ephemeral node 기반의 락, 순서 노드 등을 제공한다.
일관성(Consistency)을 중시할 때 유리하다.

Database

GET_LOCK() 같은 Named Lock, 혹은 행을 이용한 낙관/비관적 락으로 구현 가능.
영속성과 ACID 트랜잭션의 장점이 있지만 성능이 떨어질 수 있다.

구현 방식과 원리

Redis 기반 분산 락

Redis에서는 SET 명령의 NX(존재하지 않을 때만)와 PX(만료시간 설정) 옵션을 활용하여 락을 구현한다.

락을 요청하는 노드는 고유한 토큰(UUID 등)을 함께 저장해 락의 소유권을 나타낸다.

이 방식은 원자적으로 락을 획득하므로 여러 노드가 동시에 요청하더라도 한 노드만 성공하게 된다.

락 해제 시에는 저장된 토큰과 자신의 토큰을 비교해 일치할 때만 해제하는 방식으로 안전성을 보장한다.

Redis — RedLock 알고리즘

RedLock은 여러 개의 독립된 Redis 인스턴스에 동일한 키로 락을 요청하고,

과반수 이상에서 성공하면 락을 획득한 것으로 간주하는 알고리즘이다.

이를 통해 단일 Redis 장애에 대한 내성을 확보할 수 있다.

하지만 네트워크 지연이나 시계 불일치로 인한 잠재적 위험이 있으므로, 복잡도가 높은 환경에서는 주의 깊은 검토가 필요하다.

Zookeeper 기반 락

Zookeeper는 분산 코디네이터로, ephemeral(임시) znode를 이용해 락을 구현한다.

각 클라이언트는 순차 노드를 생성하고 자신의 바로 앞 순서 노드가 삭제될 때까지 감시한다.

가장 작은 번호의 노드를 가진 클라이언트가 락을 획득하며, 세션이 끊기면 해당 노드가 자동 삭제되어 락이 해제된다.

이 방식은 강한 일관성을 보장하지만, 설정과 관리가 비교적 복잡하다.

Database 기반 락

DB에서는 GET_LOCK() 같은 Named Lock을 활용하거나 특정 행에 비관적 락(SELECT ... FOR UPDATE)을 거는 방식으로 구현할 수 있다. 단순하고 트랜잭션 일관성을 보장하지만, DB 부하가 높아질 수 있으며 대규모 트래픽에는 적합하지 않을 수 있다.

핵심 고려사항

분산 락이 제대로 동작하려면 다음을 만족해야 한다.

락 획득의 원자성 (Atomicity)

락을 획득하거나 실패하는 과정이 반드시 원자적으로 수행되어야 한다.
(여러 프로세스가 동시에 락을 요청하더라도, 단 하나만 성공해야 함)

락 소유권 (Ownership)

어떤 노드가 락을 획득했는지 식별할 수 있어야 하며,
다른 노드가 실수로 해당 락을 해제하지 않도록 해야 한다.
(예: UUID, 스레드 ID, 토큰 값 등으로 식별)

락 만료 (Expiration)

네트워크 장애나 서버 다운 등의 이유로 락이 해제되지 않는 상황을 방지하기 위해
일정 시간이 지나면 자동으로 락이 해제되도록 설정한다.

락 해제의 안전성 (Safety)

락을 해제할 때, 반드시 “내가 획득한 락인지” 확인한 뒤 해제해야 한다.
그렇지 않으면 다른 노드의 락을 해제해버리는 위험이 있다.

Spring Batch를 활용한 쿠폰발급 및 메일전송

KJihun — Wed, 15 Oct 2025 14:24:50 +0900

중고물품 거래 플랫폼을 개발하면서, 마케팅 측면에서 유저가 이메일 수신을 허용하도록 유도하기 위해 생일인 유저에게 생일 쿠폰을 자동으로 발송하는 기능을 구현했다.

이 기능을 어떤 방식으로 구현할지 고민하던 중,

확장성과 유지보수성을 고려하여 Spring Batch를 도입하기로 결정했다.

Spring Batch란?

Spring Batch는 대용량 데이터를 효율적으로 처리하기 위한 Java 기반 배치 프레임워크다.

주로 청크(Chunk) 단위로 데이터를 나누어 처리함으로써, 상황에 따라 메모리를 유연하게 사용할 수 있다는 장점이 있다.

Spring Batch의 청크 처리 구조는 다음과 같은 구성요소로 이루어진다.

1. Scheduler → 배치 실행을 트리거(JobLauncher 실행) 한다.
2. JobLauncher → 스케줄러로부터 호출되어 Job을 실행한다.
3. Job → 여러 개의 Step으로 구성되며, 각 Step의 실행 순서를 관리한다.
4. Step → 독립적인 작업 단위로, 각 Step 내부에서 Reader, Processor, Writer를 통해 데이터가 처리된다.
5. JobRepository → Step의 실행 상태와 이력을 관리하는 저장소 역할을 한다.
6. TransactionManager → 청크 단위의 커밋과 롤백을 관리하여 안정적인 배치 처리를 보장한다.

Scheduler와 Batch의 차이

프로젝트를 진행하며 많은 사람들이 Scheduler와 Batch를 혼동하는 경우가 있었다.
이를 간단히 비유하자면,

Scheduler는 “알람 시계”이고,
Batch는 “알람이 울린 후 수행하는 일”이다.

즉, Scheduler는 Job을 실행시키는 역할, Batch는 실제 데이터를 처리하는 역할을 담당한다.

Scheduler의 구현 방식

Scheduler는 일반적으로 두 가지 방식으로 구현된다.

단일 서버 환경(Monolithic) 에서는 어떤 방식으로 구현하여도 문제 없지만,
Quartz 방식은 트리거가 발생한 기록을 DB 에 저장하여 다중서버 환경(MSA)에서 중복실행을 방지할 수 있다는 차이점이 있다.

Batch에서 데이터 읽기 (Reader)

Scheduler를 통해 Batch가 실행되면, 데이터 처리를 위해 DB에서 데이터를 조회해야 한다.

Spring Batch에서는 데이터를 읽는 방식에 따라 세 가지 Reader가 자주 사용된다.

1. CursorItemReader

Cursor 방식은 DB와 연결을 유지하며 하나씩 가져오는 방식으로,

메모리에 하나의 데이터만 적재되기 때문에 메모리 사용량이 적다.

하지만 하나의 DB 커넥션을 오랜 시간 점유하기 때문에, 멀티스레드 처리에는 부적합하다.

2. PagingItemReader

Paging 방식은 일정한 데이터 개수만큼 조회하여 메모리에 적재한 뒤,
DB 연결을 끊고 해당 데이터를 모두 처리하면 다음 페이지를 다시 조회하는 방식이다.
이 방식은 DB 커넥션을 오래 점유하지 않기 때문에 멀티스레드 환경에서도 안전하게 동작한다.

3. List Reader

List 방식은 데이터를 한 번에 모두 메모리에 로드한 뒤, 리스트 형태로 순차적으로 처리하는 방식이다.
따라서 메모리 사용량이 많아 대용량 데이터 처리에는 부적합하며, 일반적으로 소량의 데이터 처리나 테스트용으로 사용된다.

Batch에서 데이터 저장 (Writer)

데이터를 읽는 방식만큼 중요한 것이 데이터 저장 방식이다.
Spring Batch는 데이터를 청크(Chunk) 단위로 저장한다.

Chunk는 DB에 값을 저장하기 위해 사용되는 논리적 단위로

하나의 처리가 끝났다면 DB에 바로 저장되는 방식이 아닌 Chunk에 적재한 후,

Chunk가 가득 찼다면 Chunk 단위로 DB에 저장하는 방식이다.
Chunk 하나에 하나의 트랜잭션이 적용되기 때문에 DB부하 감소 및 처리성능이 향상된다.

단, 청크 단위로 커밋 및 롤백이 이루어지기 때문에 에러 발생 시 해당 청크 전체가 롤백된다는 점에 유의해야 한다.

구현 중 발생한 트러블 및 트러블슈팅

TransientDataAccessResourceException

문제 Spring batch 사용 시 Read 방식을 List로 구현하였을 때에는 정상적으로 동작이 수행되었다이후, read방식을 paging 으로 변경 후 quartz가 실행되었을 때, TransientDataAccessResourceException 발생하였다. org

developerhun.tistory.com

DDD, 헥사고날 아키텍처, 멀티모듈 — 개념 및 흐름

KJihun — Sun, 14 Sep 2025 14:40:53 +0900

들어가며

현대 애플리케이션은 복잡한 비즈니스 규칙과 빠른 기술 교체 요구를 동시에 맞닥뜨린다.

이를 잘못 설계하면 코드가 외부 라이브러리·프레임워크에 묶여 변경이 어렵고, 여러 팀이 동시에 작업할 때 충돌이 잦아진다.

DDD, 헥사고날, 멀티모듈은 이러한 문제를 해결하는 실용적인 조합이다.

이 글은 DDD → 헥사고날 → 멀티모듈 순으로 설명할 예정이다.

도메인 주도 설계 (DDD; Domain-Driven Design)

도메인 주도 설계.. 알듯 말듯한 단어이다.

도메인 중심으로 설계를 한다는 것 같은데..

과연 DDD에서 말하는 도메인은 무엇일까?

DDD에서 도메인은 현실 세계에서 해결해야 하는 비즈니스 문제 영역을 정의하는 것이라 볼 수 있다.

예를들어 티켓 예매 프로그램을 만든다고 가정할 경우

예매(티켓 발급, 결제, 취소, 환불 등)
사용자(회원가입, 로그인, 프로필 관리 등)
공연(공연 일정, 좌석 배치, 공연 정보 등)

그렇다면 객체와 어떤 차이점이 있을까?

도메인이 현실 세계에서 해결해야 하는 비즈니스 문제 영역을 정의한다면

객체는 그 문제 영역을 소프트웨어 안에서 구현하는 구체적인 단위다. (예: Order 엔티티, PaymentService)

다음으로는 DDD 의 계층에 대해 간단하게 알아보자.

DDD의 계층 구조

총 4개의 계층을 가진다.

Presentation Layer (UI Layer)
- 사용자의 요청을 받아 Application Layer 에 전달하는 계층
- Client로부터 request를 받고 response를 return 하는 API
- 웹 애플리케이션 기준 Controller가 대표적인 구현체
Application Layer
- Domain Layer에 구현된 메서드를 호출하여 하나의 기능을 수행하는 계층
- 여러 도메인 메서드를 호출하고 순서를 제어
- 여러 도메인 호출을 하나의 트랜잭션으로 묶음
- 논리적 검증이나 데이터 기반 접근 제어
Domain Layer
- 기능별로 비즈니스 로직을 작성하는 계층
- 기능별로 메서드로 작성하여야 하며, Application Layer가 호출하여 사용한다
Infrastructure Layer
- DB 접근(JPA, JDBC), 메시지 브로커, 외부 API 연동 등 외부와의 통신을 담당하는 계층
- 해당 계층에서 얻어온 정보를 다른 계층에 전달하는 역할

헥사고날 아키텍처 (Hexagonal Architecture / Ports & Adapters)

DDD에서 말하는 도메인은 외부 기술(JPA, DB, 프레임워크 등)에 의존하지 않고 순수한 비즈니스 규칙을 표현해야 한다.
하지만 일반적인 계층형 아키텍처에서는 도메인 코드가 외부 기술과 강하게 결합되어, DB를 바꾸거나 프레임워크를 교체할 때 도메인까지 수정해야 하는 문제가 발생한다.

이를 해결하기 위한 패턴이 헥사고날 아키텍처(Hexagonal Architecture)이다.

헥사고날 아키텍처의 핵심은

도메인은 외부를 직접 알지 못하고, 포트(Port, 추상화 인터페이스)만을 알고 있으며,

실제 동작은 어댑터(Adapter, 구현체)가 담당한다는 것이다.

Hexagonal Architecture의 계층 구조

Domain Core (중앙)
- POJO 도메인 코드(인프라 의존성 없음)
- 예: Entity, VO, Service
Ports (인터페이스)
- 도메인이 외부에 기대는 기능 추상화
- 예: OrderRepository, PaymentGateway
Adapters (구현체)
- 포트를 실제 기술로 구현
- 예: JpaOrderRepository, StripePaymentGatewayAdapter
- Inbound Adapter: 외부 요청 들어오는 곳 (REST Controller, CLI, MQ Consumer)
- Outbound Adapter: 외부로 나가는 곳 (DB, Kafka, API)

멀티모듈 (Multi-module)

헥사고날 아키텍처를 통해 도메인과 기술 구현체를 명확히 분리하면,
도메인은 외부 변화에 영향을 받지 않고 안정적으로 유지할 수 있다.

하지만 프로젝트 규모가 커지고 여러 도메인이 함께 존재하면,
코드가 한 프로젝트 안에 섞여 관리되면서 복잡성이 커지고 유지보수성이 떨어질 수 있다.
이를 해결하는 방법 중 하나가 멀티모듈 구조(Multi-Module Architecture)이다.

멀티모듈은 하나의 프로젝트를 역할이나 도메인 단위로 나누어 관리하는 방식이다.
즉, 애플리케이션 전체를 하나의 거대한 모놀리식 코드베이스로 두지 않고,
도메인별 / 계층별 / 공통 모듈별로 나누어 각각 독립적인 모듈로 관리한다.

멀티모듈의 계층 구조 예시

멀티모듈은 헥사고날 아키텍처와 결합하여 사용할 때 가장 큰 효과를 발휘한다.
예를 들어, 공연 예매 시스템을 멀티모듈로 나눈다면 다음과 같은 구조를 가질 수 있다

project-root/
 ├─ ticket-domain/          ️ 티켓 도메인 (Entity, VO, Domain Service)
 ├─ ticket-application/     ️ 티켓 애플리케이션 서비스 (유스케이스, 트랜잭션 관리)
 ├─ ticket-infra/           ️ 티켓 인프라 (DB, 외부 API, Messaging)
 │
 ├─ user-domain/             사용자 도메인
 ├─ user-application/        사용자 애플리케이션 서비스
 ├─ user-infra/              사용자 인프라
 │
 ├─ common/                 ️ 공통 유틸리티, 공용 DTO, 에러 처리
 └─ app/                     실제 실행 진입점 (API 서버, Batch, CLI)

Domain: 순수한 비즈니스 로직 (POJO), 외부 의존성 없음
Application: 유스케이스, 트랜잭션 제어, 도메인 서비스 orchestration
Infra: Port의 구현체, DB/JPA, 메시징, 외부 API 연동
App: Controller, Batch Job, MQ Consumer 등), 최종 실행 가능 애플리케이션

이 계층 구조를 헥사고날 아키텍처와 결합하면

Domain = Core
Application = Service Orchestration
Infra = Outbound Adapter
App = Inbound Adapter

로 자연스럽게 매핑된다.

멀티모듈 분리 시 얻을 수 있는 이점

관심사 분리: 도메인·공통·외부 연동 등을 모듈 단위로 나누어 코드 가독성과 유지보수성을 높임
재사용성 증대: 공통 모듈을 여러 서비스에서 활용할 수 있어 중복을 줄이고 일관성을 확보
의존성 관리 용이: 모듈별로 필요한 라이브러리만 의존하도록 설정해 빌드 크기와 충돌 위험을 줄임
병렬 개발 및 협업 효율성: 팀 단위로 모듈을 분리해 독립적으로 개발·테스트 가능 → 충돌 최소화
확장성과 안정성: 새로운 기능 추가 시 기존 모듈에 영향을 덜 주며, 특정 모듈만 교체하거나 개선 가능

멀티모듈 구조는 모듈 단위로 코드를 나누어 각 모듈이 필요한 의존성만 가지도록 설계함으로써, 빌드 속도를 줄이고 불필요한 라이브러리 충돌을 최소화할 수 있다.
이렇게 명확하게 모듈 경계를 설정하면, 여러 개발자가 동시에 같은 코드베이스에서 작업하더라도 충돌 가능성을 줄이고 독립적인 개발이 가능해진다.

또한, 각 모듈이 독립적인 단위로 관리되기 때문에, 서비스 확장이 필요할 때는 특정 모듈만 교체하거나 개선하는 것이 용이하며, 전체 애플리케이션에 미치는 영향을 최소화할 수 있다.

즉, 멀티모듈은 빌드 효율과 의존성 관리의 기술적 장점을 제공함과 동시에, 팀 단위 협업과 서비스 확장성까지 자연스럽게 지원하는 구조라고 볼 수 있다.

결론

DDD를 통해 문제 영역을 명확히 정의하고,
헥사고날 아키텍처로 도메인을 외부 기술로부터 철저히 격리하며,
멀티모듈 구조로 코드베이스를 역할 단위로 나누면,

결과적으로 변화에 유연하고 유지보수가 쉬우며, 팀 단위 협업과 확장성까지 고려한 견고한 아키텍처를 구현할 수 있다.