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

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 {

gateway/src/main/kotlin/org/yapp/gateway/filter/MdcLoggingFilter.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/security/SecurityConfig.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()
     }

global-utils/src/main/kotlin/org/yapp/globalutils/annotation/NoLogging.kt

@@ -0,0 +1,5 @@
+package org.yapp.globalutils.annotation
+
+@Target(AnnotationTarget.FUNCTION)
+@Retention(AnnotationRetention.RUNTIME)
+annotation class NoLogging

global-utils/src/main/kotlin/org/yapp/globalutils/exception/GlobalExceptionHandler.kt

@@ -9,6 +9,7 @@ import org.springframework.web.HttpRequestMethodNotSupportedException
 import org.springframework.web.bind.MethodArgumentNotValidException
 import org.springframework.web.bind.annotation.ExceptionHandler
 import org.springframework.web.bind.annotation.RestControllerAdvice
+import org.springframework.web.method.annotation.MethodArgumentTypeMismatchException
 
 /**
  * Global exception handler for the application.
@@ -159,6 +160,27 @@ class GlobalExceptionHandler {
         return ResponseEntity(error, commonErrorCode.getHttpStatus())
     }
 
+    /**
+     * 메서드 파라미터 타입 변환 실패 처리
+     *
+     * 주로 @RequestParam, @PathVariable 등에서 클라이언트가 잘못된 타입의 값을 전달했을 때 발생합니다.
+     * 예: 문자열을 int 타입으로 변환 시도
+     */
+    @ExceptionHandler(MethodArgumentTypeMismatchException::class)
+    protected fun handleMethodArgumentTypeMismatch(ex: MethodArgumentTypeMismatchException): ResponseEntity<ErrorResponse> {
+        val commonErrorCode = CommonErrorCode.INVALID_REQUEST
+
+        log.warn { "Method argument type mismatch: ${ex.name}, value: ${ex.value}, requiredType: ${ex.requiredType}" }
+
+        val error = ErrorResponse.builder()
+            .status(commonErrorCode.getHttpStatus().value())
+            .message("Invalid value '${ex.value}' for parameter '${ex.name}'. Expected type: ${ex.requiredType?.simpleName}")
+            .code(commonErrorCode.getCode())
+            .build()
+
+        return ResponseEntity(error, commonErrorCode.getHttpStatus())
+    }
+
     /**
      * 그 외 모든 예외 처리
      *

infra/build.gradle.kts

@@ -1,30 +1,25 @@
 import org.springframework.boot.gradle.tasks.bundling.BootJar
 
-plugins {
-    kotlin(Plugins.Kotlin.Short.KAPT) version Versions.KOTLIN
-}
-
 dependencies {
     implementation(project(Dependencies.Projects.GLOBAL_UTILS))
     implementation(project(Dependencies.Projects.DOMAIN))
     implementation(Dependencies.Spring.BOOT_STARTER_WEB)
     implementation(Dependencies.Spring.BOOT_STARTER_DATA_JPA)
     implementation(Dependencies.Spring.BOOT_STARTER_DATA_REDIS)
+    implementation(Dependencies.Spring.KOTLIN_REFLECT)
+
     implementation(Dependencies.RestClient.HTTP_CLIENT5)
     implementation(Dependencies.RestClient.HTTP_CORE5)
-    testImplementation(Dependencies.Spring.BOOT_STARTER_TEST)
-
-    implementation(Dependencies.Spring.KOTLIN_REFLECT)
 
     implementation(Dependencies.Database.MYSQL_CONNECTOR)
 
-
     implementation(Dependencies.Flyway.MYSQL)
 
     implementation(Dependencies.QueryDsl.JPA)
-    kapt(Dependencies.QueryDsl.APT)
 
+    kapt(Dependencies.QueryDsl.APT)
 
+    testImplementation(Dependencies.Spring.BOOT_STARTER_TEST)
     testImplementation(Dependencies.TestContainers.MYSQL)
     testImplementation(Dependencies.TestContainers.JUNIT_JUPITER)
     testImplementation(Dependencies.TestContainers.REDIS)

infra/src/main/kotlin/org/yapp/infra/InfraBaseConfigGroup.kt

@@ -2,6 +2,7 @@ package org.yapp.infra
 
 import org.yapp.infra.config.external.api.RestClientConfig
 import org.yapp.infra.config.external.redis.RedisConfig
+import org.yapp.infra.config.internal.aop.AopConfig
 import org.yapp.infra.config.internal.async.AsyncConfig
 import org.yapp.infra.config.internal.jpa.JpaConfig
 import org.yapp.infra.config.internal.page.PageConfig
@@ -15,5 +16,6 @@ enum class InfraBaseConfigGroup(
     PAGE(PageConfig::class.java),
     REDIS(RedisConfig::class.java),
     REST_CLIENT(RestClientConfig::class.java),
-    QUERY_DSL(QuerydslConfig::class.java)
+    QUERY_DSL(QuerydslConfig::class.java),
+    AOP(AopConfig::class.java)
 }

infra/src/main/kotlin/org/yapp/infra/aop/aspect/ControllerLoggingAspect.kt

@@ -0,0 +1,62 @@
+package org.yapp.infra.aop.aspect
+
+import jakarta.servlet.http.HttpServletRequest
+import org.aspectj.lang.ProceedingJoinPoint
+import org.aspectj.lang.annotation.Around
+import org.aspectj.lang.annotation.Aspect
+import org.slf4j.LoggerFactory
+import org.springframework.stereotype.Component
+import org.springframework.web.context.request.RequestContextHolder
+import org.springframework.web.context.request.ServletRequestAttributes
+import org.yapp.infra.aop.properties.LoggingAopProperties
+import java.time.Duration
+import java.time.Instant
+
+@Aspect
+@Component
+class ControllerLoggingAspect(
+    private val properties: LoggingAopProperties
+) {
+    private val log = LoggerFactory.getLogger(ControllerLoggingAspect::class.java)
+
+    @Around("org.yapp.infra.aop.pointcut.CommonPointcuts.controller() && !org.yapp.infra.aop.pointcut.CommonPointcuts.noLogging()")
+    fun logController(joinPoint: ProceedingJoinPoint): Any? {
+        if (!properties.controller.enabled) {
+            return joinPoint.proceed()
+        }
+
+        val startTime = Instant.now()
+        logRequestStart(joinPoint)
+
+        try {
+            val result = joinPoint.proceed()
+            logRequestSuccess(startTime)
+            return result
+        } catch (e: Throwable) {
+            throw e
+        }
+    }
+
+    private fun logRequestStart(joinPoint: ProceedingJoinPoint) {
+        val signature = joinPoint.signature
+        val className = signature.declaringType.simpleName
+        val methodName = signature.name
+
+        val request = getCurrentRequest()
+        val httpMethod = request?.method ?: "UNKNOWN"
+        val uri = request?.requestURI ?: "UNKNOWN"
+
+        log.info("[API-REQ] {} {} | Controller: {}.{}", httpMethod, uri, className, methodName)
+    }
+
+    private fun logRequestSuccess(startTime: Instant) {
+        val executionTimeMs = getExecutionTimeMs(startTime)
+        log.info("[API-RES] Logic Duration: {}ms", executionTimeMs)
+    }
+
+    private fun getCurrentRequest(): HttpServletRequest? =
+        (RequestContextHolder.getRequestAttributes() as? ServletRequestAttributes)?.request
+
+    private fun getExecutionTimeMs(startTime: Instant): Long =
+        Duration.between(startTime, Instant.now()).toMillis()
+}