feat: Spring AOP를 활용한 MDC 로깅 아키텍처 구축 (#96)

* [BOOK-93] feat: infra - AOP 설정을 위한 AopConfig 클래스 추가

* [BOOK-93] feat: apis, infra - InfraBaseConfigGroup에 AOP 설정 클래스 추가 및 apis 모듈에서 사용 가능하도록 추가

* [BOOK-93] feat: infra, global-utils - 서비스 및 컨트롤러 레이어에 대한 로깅을 위한 Aspect 및 Pointcut 설정 추가

* [BOOK-93] chore: domain, infra - Spring Data Commons 및 Spring Web 추가 및 불필요한 의존성 정리

* [BOOK-93] chore: logback 의존성 제외 후 Log4j2 추가 및 서비스 레이어 AOP 로깅 시 파라미터 이름도 로깅할 수 있도록 kotlinOptions.javaParameters = true 옵션 추가

* [BOOK-93] chore: Dependencies.kt에 Spring Data Commons, Spring Web, Log4j2 의존성 추가

* [BOOK-93] delete: domain - 사용하지 않는 CoreDomainConfig.kt 파일 삭제

* [BOOK-93] feat: gateway - MDC 기반 요청 로깅 필터 구현 및 사용자/클라이언트 정보 기록

- HTTP 요청 시 traceId, client IP, 요청 정보, 사용자 ID를 MDC에 저장
- JWT 인증 사용자의 subject를 userId로 기록, 인증되지 않은 경우 "GUEST"로 처리
- 요청 처리 완료 후 MDC 클리어하여 다음 요청에 영향 없음
- OncePerRequestFilter 상속으로 각 요청마다 한 번만 실행

* [BOOK-93] feat: gateway - MdcLoggingFilter를 BearerTokenAuthenticationFilter 이후에 배치하여 JWT 인증 후 사용자 정보 MDC에 기록하도록 구현

* [BOOK-93] feat: infra - Log4j2 설정 파일 추가로 로깅 구성 및 패턴 정의

* [BOOK-93] feat: infra - 비동기 MDC 전파 작업을 위한 MdcTaskDecorator 클래스 추가 및 AsyncConfig에 등록

* [BOOK-93] chore: infra - 사용하지 않는 import문 제거

* [BOOK-93] feat: global-utils - MethodArgumentTypeMismatchException 전역 예외 처리기에 등록

* [BOOK-93] refactor: infra - mdc에서 이미 로깅하기 때문에 시간 로깅 제외

* [BOOK-93] chore: kapt 관련 의존성 정리 및 코드레빗 리뷰 반영

* [BOOK-93] chore: infra - datetime(6)로 로그 패턴 수정

* [BOOK-93] refactor: gateway - 신뢰할 수 있는 프록시 서버 뒤에서만 XFF를 신뢰할 수 있도록 변경

* [BOOK-93] chore: global-utils - 필요하지 않는 괄호 제외

* [BOOK-93] chore: buildSrc - KAPT 플러그인 추가

* [BOOK-93] fix: infra - 함수/메서드 오버라이드 관련 경고 해결

* [BOOK-93] refactor: infra - 마스킹 로직 리팩토링

* [BOOK-93] refactor: infra - 실행 전 MDC를 명시적으로 clear하여 이전 작업의 MDC 완전히 제거

* [BOOK-93] chore: apis - 디버깅용 로그 주석처리

* [BOOK-93] refactor: infra - prod 환경에서만 마스킹처리하도록 리팩토링

* [BOOK-93] refactor: infra - 배열의 타입까지 로그에 남길 수 있도록 리팩토링

Author: move-hoon

apis/build.gradle.kts

@@ -22,7 +22,7 @@ dependencies {
     implementation(Dependencies.BouncyCastle.BC_PROV)
     implementation(Dependencies.BouncyCastle.BC_PKIX)
 
-    annotationProcessor(Dependencies.Spring.CONFIGURATION_PROCESSOR)
+    kapt(Dependencies.Spring.CONFIGURATION_PROCESSOR)
 
     testImplementation(Dependencies.Spring.BOOT_STARTER_TEST)
     testImplementation(Dependencies.TestContainers.MYSQL)

apis/src/main/kotlin/org/yapp/apis/book/service/AladinBookQueryService.kt

@@ -25,7 +25,7 @@ class AladinBookQueryService(
     private val MAX_ALADIN_RESULTS = 200 // Added constant
 
     override fun searchBooks(request: BookSearchRequest): BookSearchResponse {
-        log.info { "Service - Converting BookSearchRequest to AladinBookSearchRequest and calling Aladin API for book search." }
+//        log.info { "Service - Converting BookSearchRequest to AladinBookSearchRequest and calling Aladin API for book search." }
         val aladinSearchRequest = AladinBookSearchRequest.of(
             request.validQuery(),
             request.queryType,
@@ -44,7 +44,7 @@ class AladinBookQueryService(
                 throw BookException(BookErrorCode.ALADIN_API_SEARCH_FAILED, exception.message)
             }
 
-        log.info { "Before filtering - Full Response: $response" }
+//        log.info { "Before filtering - Full Response: $response" }
 
         val transformedItems = response.item.mapNotNull { item ->
             val validIsbn13 = getValidAndFilteredIsbn13(item)
@@ -75,13 +75,13 @@ class AladinBookQueryService(
             searchCategoryName = response.searchCategoryName,
             item = transformedItems
         )
-        log.info { "After filtering - Full Response: $filteredResponse" }
+//        log.info { "After filtering - Full Response: $filteredResponse" }
 
         return BookSearchResponse.of(filteredResponse, isLastPage) // Passed isLastPage
     }
 
     override fun getBookDetail(request: BookDetailRequest): BookDetailResponse {
-        log.info("Service - Converting BookDetailRequest to AladinBookLookupRequest and calling Aladin API for book detail lookup.")
+//        log.info("Service - Converting BookDetailRequest to AladinBookLookupRequest and calling Aladin API for book detail lookup.")
         val aladinLookupRequest = AladinBookLookupRequest.from(request.validIsbn13())
         val response: AladinBookDetailResponse = aladinApi.lookupBook(aladinLookupRequest)
             .onSuccess { response ->

apis/src/main/kotlin/org/yapp/apis/config/InfraConfig.kt

@@ -13,6 +13,7 @@ import org.yapp.infra.InfraBaseConfigGroup
         InfraBaseConfigGroup.REST_CLIENT,
         InfraBaseConfigGroup.QUERY_DSL,
         InfraBaseConfigGroup.PAGE,
+        InfraBaseConfigGroup.AOP
     ]
 )
 class InfraConfig

build.gradle.kts

@@ -48,13 +48,22 @@ subprojects {
     apply(plugin = Plugins.Kotlin.JPA)
     apply(plugin = Plugins.Kotlin.JVM)
     apply(plugin = Plugins.JACOCO)
+    apply(plugin = Plugins.Kotlin.KAPT)
 
     java {
         toolchain {
             languageVersion.set(JavaLanguageVersion.of(Versions.JAVA_VERSION.toInt()))
         }
     }
 
+    configurations.all {
+        exclude(group = "org.springframework.boot", module = "spring-boot-starter-logging")
+    }
+
+    dependencies {
+        implementation(Dependencies.Spring.STARTER_LOG4J2)
+    }
+
     plugins.withId(Plugins.Kotlin.ALLOPEN) {
         extensions.configure<org.jetbrains.kotlin.allopen.gradle.AllOpenExtension> {
             annotation("jakarta.persistence.Entity")
@@ -71,6 +80,7 @@ subprojects {
                 "-Xconsistent-data-class-copy-visibility"
             )
             jvmTarget = Versions.JAVA_VERSION
+            javaParameters = true
         }
     }
 }

buildSrc/src/main/kotlin/Dependencies.kt

@@ -12,6 +12,9 @@ object Dependencies {
         const val BOOT_STARTER_OAUTH2_CLIENT = "org.springframework.boot:spring-boot-starter-oauth2-client"
         const val KOTLIN_REFLECT = "org.jetbrains.kotlin:kotlin-reflect"
         const val CONFIGURATION_PROCESSOR = "org.springframework.boot:spring-boot-configuration-processor"
+        const val SPRING_DATA_COMMONS = "org.springframework.data:spring-data-commons"
+        const val SPRING_WEB = "org.springframework:spring-web"
+        const val STARTER_LOG4J2 = "org.springframework.boot:spring-boot-starter-log4j2"
     }
 
     object Database {

buildSrc/src/main/kotlin/Plugins.kt

@@ -11,6 +11,7 @@ object Plugins {
         const val SPRING = "org.jetbrains.kotlin.plugin.spring"
         const val JPA = "org.jetbrains.kotlin.plugin.jpa"
         const val JVM = "org.jetbrains.kotlin.jvm"
+        const val KAPT = "org.jetbrains.kotlin.kapt"
 
         object Short {
             const val KAPT = "kapt"

domain/build.gradle.kts

@@ -2,9 +2,9 @@ import org.springframework.boot.gradle.tasks.bundling.BootJar
 
 dependencies {
     implementation(project(Dependencies.Projects.GLOBAL_UTILS))
-    implementation(Dependencies.Spring.BOOT_STARTER_WEB)
-    implementation(Dependencies.Spring.BOOT_STARTER_DATA_JPA)
     testImplementation(Dependencies.Spring.BOOT_STARTER_TEST)
+    implementation(Dependencies.Spring.SPRING_DATA_COMMONS) // Pageable, Page용
+    implementation(Dependencies.Spring.SPRING_WEB) // HttpsStatus용으로 추가한 것이기 때문에 추후 Global-utils 모듈에 httpStatus를 정의하고 이를 의존해서 사용하도록 바꾸면 해당 의존성 삭제 가능
 }
 
 tasks {

domain/src/main/kotlin/org/yapp/domain/config/CoreDomainConfig.kt

@@ -0,0 +1,79 @@
+package org.yapp.gateway.filter
+
+import jakarta.servlet.FilterChain
+import jakarta.servlet.http.HttpServletRequest
+import jakarta.servlet.http.HttpServletResponse
+import org.slf4j.MDC
+import org.springframework.security.core.context.SecurityContextHolder
+import org.springframework.security.oauth2.jwt.Jwt
+import org.springframework.stereotype.Component
+import org.springframework.web.filter.OncePerRequestFilter
+import java.util.*
+
+@Component
+class MdcLoggingFilter : OncePerRequestFilter() {
+    companion object {
+        private const val TRACE_ID_HEADER = "X-Request-ID"
+        private const val XFF_HEADER = "X-Forwarded-For"
+        private const val X_REAL_IP_HEADER = "X-Real-IP"
+        private const val TRACE_ID_KEY = "traceId"
+        private const val USER_ID_KEY = "userId"
+        private const val CLIENT_IP_KEY = "clientIp"
+        private const val REQUEST_INFO_KEY = "requestInfo"
+        private const val DEFAULT_GUEST_USER = "GUEST"
+    }
+
+    override fun doFilterInternal(
+        request: HttpServletRequest,
+        response: HttpServletResponse,
+        filterChain: FilterChain
+    ) {
+        val traceId = resolveTraceId(request)
+        populateMdc(request, traceId)
+
+        try {
+            filterChain.doFilter(request, response)
+        } finally {
+            MDC.clear()
+        }
+    }
+
+    private fun resolveTraceId(request: HttpServletRequest): String {
+        val incomingTraceId = request.getHeader(TRACE_ID_HEADER)
+        return incomingTraceId?.takeIf { it.isNotBlank() }
+            ?: UUID.randomUUID().toString().replace("-", "")
+    }
+
+    private fun populateMdc(request: HttpServletRequest, traceId: String) {
+        MDC.put(TRACE_ID_KEY, traceId)
+        MDC.put(CLIENT_IP_KEY, extractClientIp(request))
+        MDC.put(REQUEST_INFO_KEY, "${request.method} ${request.requestURI}")
+
+        val userId = resolveUserId()
+        MDC.put(USER_ID_KEY, userId ?: DEFAULT_GUEST_USER)
+    }
+
+    private fun extractClientIp(request: HttpServletRequest): String {
+        val xffHeader = request.getHeader(XFF_HEADER)
+        if (!xffHeader.isNullOrBlank()) {
+            return xffHeader.split(",").first().trim()
+        }
+
+        val xRealIp = request.getHeader(X_REAL_IP_HEADER)
+        if (!xRealIp.isNullOrBlank()) {
+            return xRealIp.trim()
+        }
+
+        return request.remoteAddr
+    }
+
+    private fun resolveUserId(): String? {
+        val authentication = SecurityContextHolder.getContext().authentication ?: return null
+
+        return when (val principal = authentication.principal) {
+            is Jwt -> principal.subject
+            else -> principal?.toString()
+        }
+    }
+}
+

gateway/src/main/kotlin/org/yapp/gateway/filter/MdcLoggingFilter.kt

@@ -2,21 +2,23 @@ package org.yapp.gateway.security
 
 import org.springframework.context.annotation.Bean
 import org.springframework.context.annotation.Configuration
+import org.springframework.core.convert.converter.Converter
+import org.springframework.security.authentication.AbstractAuthenticationToken
 import org.springframework.security.config.annotation.web.builders.HttpSecurity
 import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity
 import org.springframework.security.config.http.SessionCreationPolicy
-import org.springframework.core.convert.converter.Converter
-import org.springframework.http.HttpMethod
-import org.springframework.security.authentication.AbstractAuthenticationToken
 import org.springframework.security.oauth2.jwt.Jwt
+import org.springframework.security.oauth2.server.resource.web.authentication.BearerTokenAuthenticationFilter
 import org.springframework.security.web.SecurityFilterChain
+import org.yapp.gateway.filter.MdcLoggingFilter
 
 @Configuration
 @EnableWebSecurity
 class SecurityConfig(
     private val jwtAuthenticationConverter: Converter<Jwt, out AbstractAuthenticationToken>,
     private val customAuthenticationEntryPoint: CustomAuthenticationEntryPoint,
-    private val customAccessDeniedHandler: CustomAccessDeniedHandler
+    private val customAccessDeniedHandler: CustomAccessDeniedHandler,
+    private val mdcLoggingFilter: MdcLoggingFilter
 ) {
     companion object {
         private val WHITELIST_URLS = arrayOf(
@@ -53,6 +55,7 @@ class SecurityConfig(
                 it.requestMatchers("/api/v1/admin/**").hasRole("ADMIN")
                 it.anyRequest().authenticated()
             }
+            .addFilterAfter(mdcLoggingFilter, BearerTokenAuthenticationFilter::class.java)
 
         return http.build()
     }