OkHttp Interceptor를 활용한 공통 에러 처리 & 로깅 전략

이전 글에서는 Retrofit + Kotlin Flow를 통해 실시간 데이터 처리를 구현하는 방법을 다뤘습니다. 이번 글에서는 네트워크 계층의 핵심인 OkHttp Interceptor를 활용해 공통 에러 처리와 로깅을 관리하는 전략을 정리합니다.

1. Interceptor란?

OkHttp Interceptor는 네트워크 요청(Request)과 응답(Response)에 공통 동작을 삽입할 수 있는 기능입니다. 이를 활용하면 모든 API 호출에 대해 인증 토큰 추가, 공통 헤더 주입, 에러 처리, 로깅 등을 간단히 처리할 수 있습니다.

• 공통 인증 헤더 추가
• 응답 코드별 에러 처리
• 네트워크 요청/응답 로깅
• 토큰 만료 시 자동 갱신

2. 로깅 Interceptor

기본적으로 OkHttp는 HttpLoggingInterceptor를 제공합니다. 개발 중에는 BASIC 또는 BODY 모드로 설정해 디버깅에 활용합니다.

val logging = HttpLoggingInterceptor().apply {
    level = HttpLoggingInterceptor.Level.BODY
}

val client = OkHttpClient.Builder()
    .addInterceptor(logging)
    .build()

실서비스에서는 민감한 데이터가 로그에 노출되지 않도록 반드시 주의해야 합니다.

3. 공통 헤더 Interceptor

모든 요청에 공통으로 붙는 헤더는 Interceptor에서 처리하는 것이 깔끔합니다.

class HeaderInterceptor : Interceptor {
    override fun intercept(chain: Interceptor.Chain): Response {
        val request = chain.request().newBuilder()
            .addHeader("Accept", "application/json")
            .addHeader("User-Agent", "MyApp Android")
            .build()
        return chain.proceed(request)
    }
}

4. 에러 처리 Interceptor

API 호출 시 공통 에러 처리를 넣을 수 있습니다. 예를 들어, 401(UnAuthorized) 응답이면 토큰 만료로 간주하고 갱신을 시도할 수 있습니다.

class ErrorHandlingInterceptor(
    private val tokenProvider: TokenProvider,
    private val refreshApi: AuthApi
) : Interceptor {
    override fun intercept(chain: Interceptor.Chain): Response {
        var request = chain.request()
        var response = chain.proceed(request)

        if (response.code == 401) {
            synchronized(this) {
                response.close()
                val newToken = runBlocking { tokenProvider.refreshTokenIfNeeded(refreshApi) }
                request = request.newBuilder()
                    .header("Authorization", "Bearer $newToken")
                    .build()
                response = chain.proceed(request)
            }
        }

        return response
    }
}

5. Interceptor 체인 구성

Interceptor는 순서대로 실행되므로, 일반적으로 아래와 같이 추가합니다:

val client = OkHttpClient.Builder()
    .addInterceptor(HeaderInterceptor())        // 공통 헤더
    .addInterceptor(ErrorHandlingInterceptor(tokenProvider, refreshApi)) // 에러 처리
    .addInterceptor(HttpLoggingInterceptor().apply {
        level = HttpLoggingInterceptor.Level.BASIC
    }) // 로깅
    .build()

6. 정리

• 공통 기능은 Interceptor에 몰아넣어 코드 중복을 줄이자.
• 로깅은 개발 환경에서는 적극 활용하되, 운영 환경에서는 민감정보 보호를 주의하자.
• 401/403 에러 처리, 토큰 갱신 로직을 Interceptor에 넣으면 관리가 수월하다.

---

마무리: OkHttp Interceptor는 네트워크 계층의 관문(Gateway) 역할을 합니다. 이 단계에서 로깅, 인증, 에러 처리를 표준화하면 앱 전체의 안정성이 크게 향상됩니다. 다음 글에서는 Jetpack Compose와 네트워크 계층 연결 (상태 관리 & UI 반영)을 다뤄보겠습니다.