Skip to content

BE Architecture

wcorn edited this page Apr 5, 2026 · 3 revisions

BE 코드 아키텍처

Spring Boot 멀티모듈 프로젝트 구조를 정의한다. 모든 BE 모듈은 이 아키텍처를 따른다.

1. 설계 원칙

원칙 설명
인프라 단위 분리 도메인 모듈은 하나의 인프라(RDB or Redis)만 책임진다
의존성 단방향 app → core/domain → common. 역방향 금지
공통 모듈 최소화 common은 순수 Java 타입만. Spring 의존성 없음
비즈니스 분리 도메인 모듈은 서비스 비즈니스를 모른다. 비즈니스 조합은 app에서

2. 모듈 구조

be/
├── build.gradle                        # 루트: 공통 플러그인, 전체 설정
├── settings.gradle                     # 모듈 등록
│
├── orino-common/                       # 공통 모듈 (순수 Java)
├── orino-domain-rdb/                   # 도메인 모듈 — MySQL (Entity, Repository)
├── orino-domain-redis/                 # 도메인 모듈 — Redis
├── orino-core-web/                     # 내부 모듈 — Web, Security, JWT
└── orino-app-api/                      # 어플리케이션 모듈 — API 서버 (조립)

3. 계층별 상세

3.1 orino-common — 공통 모듈

순수 Java만 사용한다. Spring 의존성 없음.

포함 대상: 응답/에러 타입, 공통 enum, 유틸리티

ds.project.orino.common/
├── response/
│   ├── ApiResponse.java
│   └── CustomResponseCode.java
└── exception/
    ├── CustomException.java
    ├── ErrorCode.java
    └── ErrorResponse.java
// orino-common/build.gradle
dependencies {
    // 없음 — 순수 Java
}

3.2 orino-domain-rdb — 도메인 모듈 (MySQL)

JPA Entity, Repository, JPA 설정을 관리한다. 서비스 비즈니스를 모른다.

포함 대상: Entity, JPA Repository, JPA Config

각 도메인은 entity/, repository/ 하위 패키지로 구성한다.

ds.project.orino.domain/
├── config/
│   └── JpaAuditingConfig.java
└── {도메인}/
    ├── entity/
    │   └── {Entity}.java
    └── repository/
        └── {Entity}Repository.java
// orino-domain-rdb/build.gradle
dependencies {
    api project(':orino-common')
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    runtimeOnly 'com.mysql:mysql-connector-j'
}

3.3 orino-domain-redis — 도메인 모듈 (Redis)

Redis 오퍼레이션만 담당한다. RDB를 모른다.

포함 대상: Redis Repository, Redis 관련 설정

ds.project.orino.redis/
└── {도메인}/
    └── {Name}Repository.java
// orino-domain-redis/build.gradle
dependencies {
    api project(':orino-common')
    implementation 'org.springframework.boot:spring-boot-starter-data-redis'
}

3.4 orino-core-web — 내부 모듈 (Web 인프라)

Web, Security, JWT, Swagger 등 횡단 관심사를 담당한다. 도메인/어플리케이션 비즈니스를 모른다.

포함 대상: Security 설정, JWT 처리, 예외 핸들러, Swagger 설정

ds.project.orino.core/
├── security/
│   ├── SecurityConfig.java
│   └── JwtAuthenticationFilter.java
├── jwt/
│   ├── JwtTokenProvider.java
│   └── JwtProperties.java
└── web/
    ├── GlobalExceptionHandler.java
    └── OpenApiConfig.java
// orino-core-web/build.gradle
dependencies {
    api project(':orino-common')
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-security'
    implementation 'io.jsonwebtoken:jjwt-api:0.12.6'
    runtimeOnly 'io.jsonwebtoken:jjwt-impl:0.12.6'
    runtimeOnly 'io.jsonwebtoken:jjwt-jackson:0.12.6'
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:3.0.2'
}

3.5 orino-app-api — 어플리케이션 모듈

하위 모듈을 조립하여 실행 가능한 API 서버를 완성한다.

포함 대상: Controller, Application Service, DTO, application.yml

각 도메인은 controller/, service/, dto/ 하위 패키지로 구성한다.

ds.project.orino/
├── OrinoApplication.java           # @SpringBootApplication (베이스 패키지)
└── {도메인}/
    ├── controller/
    │   └── {Domain}Controller.java
    ├── service/
    │   └── {Domain}Service.java
    └── dto/
        ├── {Name}Request.java
        └── {Name}Response.java
// orino-app-api/build.gradle
plugins {
    id 'org.springframework.boot'
}

dependencies {
    implementation project(':orino-core-web')
    implementation project(':orino-domain-rdb')
    implementation project(':orino-domain-redis')

    implementation 'org.springframework.boot:spring-boot-starter'
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
    implementation 'org.springframework.boot:spring-boot-starter-validation'
    developmentOnly 'org.springframework.boot:spring-boot-devtools'

    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    testImplementation 'org.springframework.boot:spring-boot-testcontainers'
    testImplementation 'org.testcontainers:testcontainers-junit-jupiter'
    testImplementation 'org.testcontainers:testcontainers-mysql'
    testImplementation 'com.redis:testcontainers-redis:2.2.4'
}

4. 의존성 그래프

orino-app-api
  │ (implementation)
  ├── orino-core-web ── (api) ── orino-common
  ├── orino-domain-rdb ── (api) ── orino-common
  └── orino-domain-redis ── (api) ── orino-common

규칙:

  • 의존 방향: app → core/domain → common (단방향)
  • core ↔ domain 간 의존 없음
  • domain-rdb ↔ domain-redis 간 의존 없음
  • 하위 모듈은 api로 common을 노출하고, app은 implementation으로 하위 모듈을 참조

5. 루트 Gradle 설정

// settings.gradle
rootProject.name = 'orino'
include 'orino-common'
include 'orino-domain-rdb'
include 'orino-domain-redis'
include 'orino-core-web'
include 'orino-app-api'
// build.gradle (루트)
plugins {
    id 'java'
    id 'org.springframework.boot' version '4.0.3' apply false
    id 'io.spring.dependency-management' version '1.1.7'
}

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

    group = 'ds.project'
    version = '0.0.1-SNAPSHOT'

    java {
        toolchain {
            languageVersion = JavaLanguageVersion.of(25)
        }
    }

    ext['jackson-2-bom.version'] = '2.21.1'

    repositories {
        mavenCentral()
    }

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

    tasks.withType(Test).configureEach {
        useJUnitPlatform()
    }
}

6. 컴포넌트 스캔 전략

모든 모듈의 베이스 패키지를 ds.project.orino 하위로 통일한다.

모듈 패키지
orino-common ds.project.orino.common
orino-domain-rdb ds.project.orino.domain
orino-domain-redis ds.project.orino.redis
orino-core-web ds.project.orino.core
orino-app-api ds.project.orino (루트)

OrinoApplication이 ds.project.orino 패키지에 위치하므로, 하위 모듈의 모든 @Component가 자동 스캔된다. 별도 @ComponentScan 설정이 필요 없다.

7. 코드 배치 기준

판단 기준: "이 코드가 둘 이상의 인프라/도메인을 알아야 하는가?"

구분 위치 역할
Entity, Repository domain-rdb 또는 domain-redis 단일 인프라 CRUD, 도메인 규칙
Application Service app-api 여러 도메인 조합, 비즈니스 유스케이스
Controller app-api HTTP 요청/응답 매핑
DTO (Request/Response) app-api API 직렬화
횡단 관심사 (Security, JWT 등) core-web 비즈니스 무관한 인프라
공통 타입 (응답, 에러, enum) common 순수 Java, Spring 무관

새 도메인 추가 시

  1. orino-domain-rdb에 {도메인}/entity/, {도메인}/repository/ 패키지 추가
  2. Redis가 필요하면 orino-domain-redis에도 추가
  3. orino-app-api에 {도메인}/controller/, {도메인}/service/, {도메인}/dto/ 패키지 추가

7-1. 관측성

BE는 Micrometer + OpenTelemetry로 계측하고 구조화 로깅(JSON)을 Loki에 전송한다.

  • 로깅: logback-spring.xml + MdcLoggingFilter (requestId, userId, traceId MDC 주입)
  • 메트릭: Micrometer Prometheus Registry (관리 포트 9090)
  • 트레이스: micrometer-tracing-bridge-otel → Alloy(OTLP) → Tempo

상세: 관측성 (Observability)

8. 선택 근거

결정 대안 선택 이유
5개 모듈 3개(common+domain+app) 인프라 분리(RDB/Redis)와 횡단관심사 분리로 의존성 최적화
도메인을 RDB/Redis 분리 단일 domain 모듈 "하나의 모듈 = 하나의 인프라" 원칙. Redis 불필요 모듈 추가 시 불필요한 의존 방지
core-web이 domain을 모름 core-web → domain 의존 JWT 필터가 memberId만 파싱하고 DB 조회 안 함. 도메인 무관하게 재사용 가능
공통 모듈 순수 Java Spring 포함 공통 모듈의 저주 방지. 의존성 덩어리, 불필요한 AutoConfiguration 차단

Clone this wiki locally