[🔥TroubleShooting - TicToc🔥] 장기 프로젝트 이대로.. 괜찮을까..❓💦💦

._mung·2025년 3월 7일

TROUBLESHOOTING TicToc

TicToc

목록 보기

1/6

📌 프로젝트 소개

팀원 : 개인 프로젝트
기간 : 2025.01 ~ 진행 중
링크 : https://github.com/M-ung/TicToc_Server
서비스 내용 : 당신의 시간에 가치를 매기다, 시간 거래 경매 플랫폼

🔥TroubleShooting🔥

Problems

초기 개발 단계에서는 늘 하던대로 프로젝트를 단일모듈로 구성했고, 크게 domain과 global로 디렉토리를 나누고 레이어드 아키텍처로 적용했다. 하지만 개인 프로젝트로서 장기적으로 지속적인 개발이 필요했기 때문에 다음과 같은 문제점이 발생했다.

1. 유지보수와 확장성의 어려움
2. 배포할 때 빌드 속도 저하
3. 테스트 코드 작성의 불편함

How

위 문제들을 해결하기 위해서 기존의 단일모듈 프로젝트보다 헥사고날 아키텍처를 기반으로 한 멀티모듈 프로젝트로 변경하는 것이 좋다고 생각했다. 그래서 아래 방법을 적용하기로 했다.

1. 프로젝트 멀티모듈 세팅
2. 헥사고날 아키텍처 적용

Process

1. 프로젝트 멀티모듈 세팅
먼저 단일모듈에서 멀티모듈 프로젝트로 구성하고, 각 모듈 계층을 아래와 같이 구성했다.

📍 디렉토리 구조

tictoc-api ## 🗂️ API 관련 모듈
├── Dockerfile
├── build.gradle
└── src
    ├── main
    │   ├── java
    │   │   └── tictoc
    │   │       ├── TicTocApiApplication.java
    │   │       ├── auction 
    │   │       │   ├── adapter (## 🗂️ API 요청을 처리하는 컨트롤러)
    │   │       │   ├── dto (## 🗂️ 데이터 전송 객체)
    │   │       │   ├── mapper (## 🗂️ 객체 변환)
    │   │       │   ├── port (## 🗂️ 비지니스 로직 인터페이스)
    │   │       │   ├── application (## 🗂️ 비지니스 로직 구현체)
    │   │       ├── bid
    │   │       │   ├── adapter (## 🗂️ API 요청을 처리하는 컨트롤러)
    │   │       │   ├── dto (## 🗂️ 데이터 전송 객체)
    │   │       │   ├── mapper (## 🗂️ 객체 변환)
    │   │       │   ├── port (## 🗂️ 비지니스 로직 인터페이스)
    │   │       │   ├── application (## 🗂️ 비지니스 로직 구현체)
    │   │       ├── user
    │   │       │   ├── adapter (## 🗂️ API 요청을 처리하는 컨트롤러)
    │   │       │   ├── dto (## 🗂️ 데이터 전송 객체)
    │   │       │   ├── mapper (## 🗂️ 객체 변환)
    │   │       │   ├── port (## 🗂️ 비지니스 로직 인터페이스)
    │   │       │   ├── application (## 🗂️ 비지니스 로직 구현체)
    │   │       ├── config
    │   │       │   ├── CorsFilter.java 
    │   │       │   ├── SpringDocOpenApiConfig.java (## 📄 Swagger)
    │   │       │   ├── WebConfig.java
    │   │       │   └── security
    │   ├── resources
    │   │   ├── application.yml (## 📄 공통 application.yml)
    │   │   ├── application-dev.yml (## 📄 개발 application.yml)
    │   │   ├── application-prod.yml (## 📄 배포 application.yml)

tictoc-batch (## 🗂️ Spring Batch 관련 모듈)
├── Dockerfile
├── build.gradle
└── src
    ├── main
    │   ├── java
    │   │   └── tictoc
    │   │       ├── TicTocBatchApplication.java
    │   │       ├── userLoginHistory
    │   │       │   ├── config (## 🗂️ Spring Batch)
    │   │       │   ├── event (## 🗂️ Kafka Consumer)
    │   │       │   ├── scheduler (## 🗂️ Spring Batch Scheduler)
    │   ├── resources
    │   │   ├── application.yml (## 📄 공통 application.yml)
    │   │   ├── application-dev.yml (## 📄 개발 application.yml)
    │   │   ├── application-prod.yml (## 📄 배포 application.yml)

tictoc-common (## 🗂️ 공통 로직 관련 모듈)
├── build.gradle
└── src
    ├── main
    │   ├── java
    │   │   └── tictoc
    │   │       ├── TicTocCommonApplication.java
    │   │       ├── annotation (## 🗂️ 커스텀 어노테이션)
    │   │       ├── aspect (## 🗂️ AOP)
    │   │       ├── config (## 🗂️ 공통 설정)
    │   │       ├── constants (## 🗂️ 공통 상수)
    │   │       ├── error (## 🗂️ 커스텀 에러)
    │   │       ├── model (## 🗂️ 공통 객체)
    │   ├── resources
    │   │   ├── application-common.yml (## 📄 common application.yml)

tictoc-domain (## 🗂️ 도메인 관련 모듈)
├── build.gradle
└── src
    ├── main
    │   ├── java
    │   │   └── tictoc
    │   │       ├── TicTocDomainApplication.java
    │   │       ├── auction
    │   │       │   ├── adapter (## 🗂️ DB와 연결하는 구현체)
    │   │       │   ├── dto (## 🗂️ 데이터 전송 객체)
    │   │       │   ├── event (## 🗂️ Redis Event)
    │   │       │   ├── exception (## 🗂️ 커스텀 예러)
    │   │       │   ├── model (## 🗂️ 도메인 엔티티)
    │   │       │   ├── port (## 🗂️ DB와 연결하는 인터페이스)
    │   │       │   ├── repository (## 🗂️ DB와 접근하는 저장소)
    │   │       ├── bid
    │   │       │   ├── adapter (## 🗂️ DB와 연결하는 구현체)
    │   │       │   ├── dto (## 🗂️ 데이터 전송 객체)
    │   │       │   ├── exception (## 🗂️ 커스텀 예러)
    │   │       │   ├── model (## 🗂️ 도메인 엔티티)
    │   │       │   ├── port (## 🗂️ DB와 연결하는 인터페이스)
    │   │       │   ├── repository (## 🗂️ DB와 접근하는 저장소)
    │   │       ├── config (## 🗂️ 도메인 설정)
    │   │       ├── notification
    │   │       │   ├── model (## 🗂️ 도메인 엔티티)
    │   │       ├── payment
    │   │       │   ├── model (## 🗂️ 도메인 엔티티)
    │   │       ├── propfile
    │   │       │   ├── adapter (## 🗂️ DB와 연결하는 구현체)
    │   │       │   ├── model (## 🗂️ 도메인 엔티티)
    │   │       │   ├── port (## 🗂️ DB와 연결하는 인터페이스)
    │   │       │   ├── repository (## 🗂️ DB와 접근하는 저장소)
    │   │       ├── user
    │   │       │   ├── adapter (## 🗂️ DB와 연결하는 구현체)
    │   │       │   ├── dto (## 🗂️ 데이터 전송 객체)
    │   │       │   ├── exception (## 🗂️ 커스텀 예러)
    │   │       │   ├── model (## 🗂️ 도메인 엔티티)
    │   │       │   ├── port (## 🗂️ DB와 연결하는 인터페이스)
    │   │       │   ├── repository (## 🗂️ DB와 접근하는 저장소)
    │   ├── resources
    │   │   ├── application-domain.yml (## 📄 domain application.yml)

tictoc-external (## 🗂️ 와부 로직 관련 모듈)
├── build.gradle
└── src
    ├── main
    │   ├── java
    │   │   └── tictoc
    │   │       ├── TicTocExternalApplication.java
    │   │       │   ├── config (## 🗂️ openFeign 설정)
    │   │       ├── kakao (## 🗂️ Kakao 연결)
    │   ├── resources
    │   │   ├── application-external.yml (## 📄 external application.yml)

tictoc-infrastructure (## 🗂️ Redis, Kafka 관련 모듈)
├── build.gradle
└── src
    ├── main
    │   ├── java
    │   │   └── tictoc
    │   │       ├── TicTocInfrastructureApplication.java
    │   │       ├── kafka 
    │   │       │   ├── config (## 🗂️ Kafka 설정)
    │   │       │   ├── event (## 🗂️ Kafka Producer)
    │   │       │   ├── exception (## 🗂️ 커스텀 예러)
    │   │       ├── redis 
    │   │       │   ├── auction
    │   │       │   │   ├── adapter (## 🗂️ Redis 비지니스 로직 구현체)
    │   │       │   │   ├── port (## 🗂️ Redis 비지니스 로직 인터페이스)
    │   │       │   ├── config (## 🗂️ Redis 설정)
    │   │       │   ├── exception (## 🗂️ 커스텀 예러)
    │   ├── resources
    │   │   ├── application-infrastructure.yml (## 📄 infrastructure application.yml)

그리고 각 모듈이 정상적으로 돌아갈 수 있게 settings.gradle을 아래와 같이 작성했다.
📍 settings.gradle

rootProject.name = 'TicToc'
include 'tictoc-common'
include 'tictoc-api'
include 'tictoc-domain'
include 'tictoc-infrastructure'
include 'tictoc-batch'
include 'tictoc-external'

또 tictoc-api와 tictoc-batch는 애플리케이션을 동작시킬 모듈이고 tictoc-domain, tictoc-common, tictoc-external, tictoc-infrastructure은 의존할 모듈이기에 아래와 같이 build.gradle을 작성했다.

📍 tictoc-api build.gradle

bootJar {
    archiveBaseName = "app"
    archiveVersion = ""
}

processResources {
    from(project(":tictoc-common").file("src/main/resources")) {
        into("BOOT-INF/classes")
    }
    from(project(":tictoc-domain").file("src/main/resources")) {
        into("BOOT-INF/classes")
    }
    from(project(":tictoc-infrastructure").file("src/main/resources")) {
        into("BOOT-INF/classes")
    }
    from(project(":tictoc-external").file("src/main/resources")) {
        into("BOOT-INF/classes")
    }
}

jar {
    enabled = false
}

dependencies {
    implementation project(':tictoc-common')
    implementation project(':tictoc-domain')
    implementation project(':tictoc-infrastructure')
    implementation project(':tictoc-external')

    // Swagger
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.1.0'
    implementation 'javax.servlet:javax.servlet-api:4.0.1'

    //security
    implementation 'org.springframework.boot:spring-boot-starter-validation'
    implementation 'org.springframework.boot:spring-boot-starter-security'
    testImplementation 'org.springframework.security:spring-security-test'
    implementation group: 'io.jsonwebtoken', name: 'jjwt-api', version: '0.11.5'
    implementation group: 'io.jsonwebtoken', name: 'jjwt-impl', version: '0.11.5'
    implementation group: 'io.jsonwebtoken', name: 'jjwt-jackson', version: '0.11.5'

    // mapstruct
    implementation 'org.mapstruct:mapstruct:1.5.5.Final'
    annotationProcessor 'org.mapstruct:mapstruct-processor:1.5.5.Final'
}

📍 tictoc-batch build.gradle

bootJar {
    archiveBaseName = "app"
    archiveVersion = ""
}

processResources {
    from(project(":tictoc-domain").file("src/main/resources")) {
        into("BOOT-INF/classes")
    }
}

jar {
    enabled = false
}

dependencies {
    // Spring Batch
    implementation 'org.springframework.boot:spring-boot-starter-batch'
    implementation 'org.springframework.batch:spring-batch-core'

    implementation project(':tictoc-domain')
    implementation project(':tictoc-common')
    implementation project(':tictoc-infrastructure')
}

📍 tictoc-domain build.gradle

bootJar.enabled = false

jar.enabled = true

dependencies {
    implementation project(':tictoc-common')
    implementation project(':tictoc-infrastructure')

    // mysql
    runtimeOnly 'com.mysql:mysql-connector-j'
}

def generated = layout.buildDirectory.dir("generated/querydsl")

sourceSets {
    main {
        java {
            srcDirs += generated
        }
    }
}

clean.doLast {
    file(generated).deleteDir()
}

📍 tictoc-common build.gradle

bootJar.enabled = false
jar.enabled = true

dependencies {
}

📍 tictoc-external build.gradle

bootJar.enabled = false
jar.enabled = true

dependencies {
    implementation project(':tictoc-common')
}

📍 tictoc-infrastructure build.gradle

bootJar.enabled = false
jar.enabled = true

dependencies {
    implementation project(':tictoc-common')

    // redis
    implementation 'org.springframework.boot:spring-boot-starter-data-redis'
    implementation 'com.fasterxml.jackson.datatype:jackson-datatype-jsr310'
}

마지막으로 각 모듈에 역할에 맞게 application.yml 파일을 아래와 같이 작성했다.

📍 application.yml (tictoc-api)

jwt:
  secret: ${JWT_SECRET}
  accessTokenExpireTime: ${JWT_ACCESS_EXPIRE_TIME}
  refreshTokenExpireTime: ${JWT_REFRESH_EXPIRE_TIME}
server:
  port: 8080
  tomcat:
    threads:
      max: 200
      min-spare: 10
    accept-count: 100
spring:
  jpa:
    database-platform: org.hibernate.dialect.MySQL8Dialect
    hibernate:
      ddl-auto: update
    properties:
      hibernate:
        format_sql: true
        show_sql: false
  profiles:
    active: dev
    include:
      - domain
      - external
      - infrastructure
  config:
    import: optional:file:.env[.properties]
  threads:
    virtual:
      enabled: true
  servlet:
    multipart:
      max-file-size: 5MB
logging.level:
  org.hibernate.SQL: debug
  org.hibernate.orm.jdbc.bind: trace
  org.springframework.web.cors: DEBUG

📍 application.yml (tictoc-batch)

jwt:
  secret: ${JWT_SECRET}
  accessTokenExpireTime: ${JWT_ACCESS_EXPIRE_TIME}
  refreshTokenExpireTime: ${JWT_REFRESH_EXPIRE_TIME}
server:
  port: 8081
  tomcat:
    threads:
      max: 200
      min-spare: 10
    accept-count: 100
spring:
  profiles:
    active: dev
    include:
      - domain
      - external
      - infrastructure
  config:
    import: optional:file:.env[.properties]
  batch:
    jdbc:
      initialize-schema: always
  threads:
    virtual:
      enabled: true
  servlet:
    multipart:
      max-file-size: 5MB
logging.level:
  org.hibernate.SQL: debug
  org.hibernate.orm.jdbc.bind: trace
  org.springframework.web.cors: DEBUG

📍 application-domain.yml

spring:
  datasource:
    master:
      hikari:
        driver-class-name: com.mysql.cj.jdbc.Driver
        jdbc-url: jdbc:mysql://${DB_HOST}:${MASTER_DB_PORT}/${DB_NAME}?allowPublicKeyRetrieval=true&useSSL=false&serverTimezone=Asia/Seoul&characterEncoding=UTF-8
        username: ${DB_USER}
        password: ${DB_PASSWORD}
    slave:
      hikari:
        driver-class-name: com.mysql.cj.jdbc.Driver
        jdbc-url: jdbc:mysql://${DB_HOST}:${SLAVE_DB_PORT}/${DB_NAME}?allowPublicKeyRetrieval=true&useSSL=false&serverTimezone=Asia/Seoul&characterEncoding=UTF-8
        username: ${DB_USER}
        password: ${DB_PASSWORD}

📍 application-external.yml

feign:
  kakao:
    kakao_get_token_name: ${KAKAO_GET_TOKEN_NAME}
    kakao_get_profile_name: ${KAKAO_GET_PROFILE_NAME}
    kakao_get_token_info_name: ${KAKAO_GET_TOKEN_INFO_NAME}
    get-kauth-url: ${KAKAO_KAUTH_URL}
    get-kapi-url: ${KAKAO_KAPI_URL}
    redirect: ${KAKAO_REDIRECT}
    rest-api-key: ${KAKAO_REST_API_KEY}

📍 application-infrastructure.yml

spring:
  cache:
    type: redis
  data:
    redis:
      host: ${REDIS_HOST}
      port: ${REDIS_PORT}
  kafka:
    bootstrap-servers: ${KAFKA_HOST}:${KAFKA_PORT}
    producer:
      key-serializer: org.apache.kafka.common.serialization.StringSerializer
      value-serializer: org.apache.kafka.common.serialization.StringSerializer
    listener:
      type: ${KAFKA_TYPE}
    consumer:
      group-id: ${KAFKA_GROUP}
      auto-offset-reset: latest
      key-deserializer: org.apache.kafka.common.serialization.StringDeserializer
      value-deserializer: org.apache.kafka.common.serialization.StringDeserializer

2. 헥사고날 아키텍처 적용
위에 적은 디렉토리 구조를 보면 헥사고날 아키텍처를 활용한 것을 알 수 있다. 아키텍처 구조는 아래와 같다.

클라이언트가 요청을 보내면, 먼저 tictoc-api 모듈의 Controller 계층에서 이를 수신한다. 그 다음, 비즈니스 로직의 인터페이스 계층인 UseCase를 통해 요청이 전달되며, 해당 요청은 구현체인 Service 계층에서 처리된다.
비즈니스 로직 과정에서 도메인 객체 및 DB 접근이 필요할 경우, tictoc-domain 모듈의 Port 인터페이스를 통해 데이터를 요청한다. 그 다음, Port 인터페이스의 구현체인 Adaptor는 Repository를 활용하여 DB에 접근하여 수행하는 흐름이다.

위 사진을 보면 DB가 Master와 Slave로 나눠져 있고, Query와 Command라는 단어가 보인다. 이는 다음 글에서 자세히 다루겠지만, 이해를 돕기 위해 간단히 설명하겠다.

Query와 Command를 나누는 기준은 크게 역할이 "쓰기"냐 "읽기"냐에 따라 결정한다. 이렇게 하는 이유는 CQRS패턴, DB분리, 속도 개선, 등 여러 이유가 있겠지만, 저는 프로젝트를 최대한 모듈화하고 싶고 객체를 역할 별로 깔끔하게 관리하고 싶어서 위 네이밍 법칙을 가져오고 있다.
그리고 이번 프로젝트에서는 DB를 Mysql을 사용하고 있는데, 이를 Master와 Slave로 나눠서 위 아키텍처 그림대로 관리할 예정이다.

Result

문제 해결로 아래와 같은 결과를 얻었다.
1. 유지보수성 및 확장성 향상.
2. 비즈니스 로직과 데이터 접근 로직 분리.

최종 프로젝트 모듈 형태는 아래와 같다.

또 "경매 등록" 기능을 아래와 같이 헥사고날 아키텍처로 구현했다.

📍 AuctionCommandController.java

📍 AuctionCommandUseCase.java

📍 AuctionCommandService.java

📍 AuctionRepositoryPort.java

📍 AuctionRepositoryAdapter.java

📍 AuctionRepository.java

Thoughts

이전까지 단일모듈로 개발을 해왔었고 멀티모듈이 있다는 사실을 이번에 처음 알았다. 이전까지 단일모듈로 개발을 하면서 디렉토리와 클래스의 개수가 늘어날 때마다 관리하고 원하는 파일 찾기가 어려웠었다.
이번 멀티모듈로 변경한 후 개발을 쭉 대략 2개월 가까이 진행해 보았는데, 확실히 원하는 파일 찾기가 단일모듈일 때보다 훨씬 수월해졌다.
또 모듈을 여러 개로 나눈 덕에 build 시간 또한 단축된 느낌이 들었다.
앞으로 이 프로젝트를 확장해 나가는 데에 있어서 프로젝트를 관리하기 전보다 어렵지 않을 것 같다.

헥사고날 아키텍처라는 단어 또한 이번에 처음 들어봤다. 처음에는 클린 아키텍처를 먼저 알게 되었어서 이를 적용해 보려고 했는데, 구글에서 래퍼런스를 찾기가 쉽지 않았다. 그래서 클린 아키텍처에서 파생된 헥사고날 아키텍처가 있다는 사실을 알고 알아보게 되었고, 클린 아키텍처보다 래퍼런스도 많이 있기에 이를 택했다.
적용한 결과, 비즈니스 로직에서 데이터베이스나 외부 API에 직접 의존하는 것이 아니라,
UseCase, Port와 같은 인터페이스를 통해서만 접근할 수 있도록 제한할 수 있었다. 이 덕분에 DB 내용을 변경할 때, 비즈니스 로직을 변경할 필요가 없어지는 장점과 코드가 훨씬 깔끔해지는 효과를 얻을 수 있었다.

마지막으로 헥사고날 아키텍처 중 "도메인과 엔티티"를 분리하는 내용이 있었다. 도메인과 엔티티를 분리하면 비즈니스 로직과 데이터 저장 로직을 명확하게 구분할 수 있어서 유지보수성과 확장성이 향상한다는 장점이 있다.
이를 처음에 적용해 보았지만, 사실 이를 분리해서 얻는 이점보다 코드의 복잡성만 늘어나서 얻는 단점이 크다고 생각했다.
예를 들어 Update 관련 기능을 구현할 때, 도메인과 엔티티를 분리하지 않는다면 "더티 체킹"을 통해 굳이 Save를 다시 할 필요가 없었다. 하지만 도메인과 엔티티를 분리한다면, 해당 엔티티를 JPA를 통해 찾고, 찾은 엔티티를 도메인으로 변경, 도메인을 수정, 도메인을 엔티티로 변경, 엔티티를 JPA를 통해 다시 저장하는 과정을 거쳐야 했다.
그래서 "도메인과 엔티티" 분리는 적용하지 않고 이 글의 "🔥TroubleShooting🔥"을 해결했다.

._mung

💻 💻 💻

다음 포스트