복군의 뒷주머니

Fragment를 한 줄도 쓰지 않는 Compose 앱인데 Play Console이 androidx.fragment:fragment 1.1.0을 오래된 SDK로 지목한다면, 범인은 구글 자신의 라이브러리입니다. 광고·Firebase·인앱 리뷰가 공통으로 거치는 play-services-basement가 2019년판 fragment 1.1.0을 끌고 옵니다. 최신 basement로 올려도 그대로라서 앱에서 버전을 승격하는 것이 유일한 방법입니다. 앱 18개를 전수로 확인해 보니 12개가 이 상태였는데, 콘솔 경고는 3개에만 떠 있었습니다.

안드로이드 앱 여러 개를 운영하고 있습니다. 어느 날 한 앱의 Play Console에 SDK 문제로 이 라이브러리가 떴습니다.

androidx.fragment:fragment  1.1.0

당황스러웠습니다. 그 앱은 순수 Compose라 Fragment 클래스를 한 번도 import 한 적이 없고, build.gradle에도 fragment라는 글자가 없었습니다. 차단은 아니고 권고 수준의 경고였지만, 내가 선언하지 않은 것을 고치라니 어디서부터 봐야 할지 몰랐습니다.

누가 끌고 오는지 — dependencyInsight

Gradle에 물어보면 바로 나옵니다.

./gradlew :app:dependencyInsight \
    --configuration releaseRuntimeClasspath \
    --dependency androidx.fragment:fragment

경로를 따라 올라가면 끝에 이것이 있습니다(출력을 줄여 옮겼습니다).

androidx.fragment:fragment:1.1.0
\--- com.google.android.gms:play-services-basement:18.x
     +--- com.google.android.gms:play-services-ads-...
     +--- com.google.android.gms:play-services-measurement-...   (firebase-analytics)
     \--- com.google.android.play:review ...

play-services-basement는 구글 플레이 서비스 계열의 바닥 라이브러리라 애드몹, Firebase Analytics, 인앱 리뷰가 전부 이걸 거칩니다. 광고나 분석을 넣은 앱이면 거의 자동으로 생긴다고 보면 됩니다.

라이브러리를 최신으로 올리면 되지 않나 — 안 된다

제일 먼저 시도한 게 이것이었습니다. 그런데 Google Maven의 POM을 직접 열어 보면 답이 나옵니다.

curl -s https://dl.google.com/android/maven2/com/google/android/gms/play-services-basement/18.11.0/play-services-basement-18.11.0.pom

최신판도 fragment 1.1.0을 그대로 선언하고 있습니다. 기다려도, SDK를 올려도 안 사라집니다. 앱 쪽에서 더 높은 버전을 요구해 Gradle의 충돌 해소가 높은 쪽을 고르게 하는 수밖에 없습니다.

해결 — 앱에서 버전을 승격한다

방법 A: constraints로 바닥값만 올린다 (권장)

# gradle/libs.versions.toml
[versions]
fragment = "1.8.9"

[libraries]
androidx-fragment = { group = "androidx.fragment", name = "fragment", version.ref = "fragment" }

// app/build.gradle.kts
dependencies {
    constraints {
        implementation(libs.androidx.fragment) {
            because("play-services-basement 가 끌어오는 fragment 1.1.0 을 Play 가 경고한다")
        }
    }
    ...
}

constraints는 의존성을 추가하지 않습니다. 누군가 fragment를 끌고 올 때만 "최소 이 버전"을 걸어 줍니다. 안 쓰는 Fragment를 내가 선언해 들고 있는 모양이 안 되고, 나중에 basement가 알아서 최신을 끌고 오게 되면 이 줄은 아무 일도 안 합니다.

방법 B: implementation으로 직접 선언한다

// Fragment 버전 강제 업그레이드 (play-services-basement 가 1.1.0 을 끌고 온다)
implementation(libs.androidx.fragment)

더 단순하고 확실합니다. 다른 앱들은 이렇게 고쳤습니다. 다만 아래 두 가지를 조심하세요.

확인 — 소스가 아니라 빌드 결과물로

의존성 트리는 "그렇게 될 것"이지 실제로 들어간 것이 아닙니다. Play가 읽는 것은 결과물이니 결과물에서 확인합니다.

# APK 안에 들어간 버전 파일 — 한 줄이면 끝난다
unzip -p app-release.apk META-INF/androidx.fragment_fragment.version
1.8.9

AAB로 올린다면 번들 안의 의존성 메타데이터(BUNDLE-METADATA/com.android.tools.build.libraries/dependencies.pb)가 Play가 SDK 색인에 쓰는 자료입니다. 바이너리라 눈으로 읽기는 어렵고, 같은 빌드로 만든 APK에서 버전 파일을 보는 편이 빠릅니다.

경고가 뜬 앱만 아픈 게 아니다

이 글을 쓰게 된 진짜 이유입니다. 경고는 최근에 업로드한 앱에만 뜹니다. 저는 처음에 경고가 뜬 앱 셋만 고쳤는데, 나중에 18개 앱을 전부 APK로 확인해 보니 12개가 여전히 1.1.0이었습니다.

더 뼈아팠던 건 따로 있었습니다. 이미 앱 네 개를 주석까지 달아 고쳐 두었는데, 그 뒤에 새로 만든 앱 다섯 개에 그 한 줄이 옮겨지지 않았습니다. 새 앱을 만들 때 기존 앱의 build.gradle을 참고하긴 했지만, "이 줄은 왜 있지?"로 읽히는 줄은 빠지기 쉽습니다. 특히 이 줄은 앱의 기능과 아무 관계가 없어 보이는 줄이라 더 그렇습니다.

정리

• Fragment를 안 써도 광고·Firebase·인앱 리뷰가 있으면 play-services-basement를 통해 fragment 1.1.0이 들어옵니다.
• 최신 basement(18.11.0)도 1.1.0을 선언합니다. SDK를 올려서는 안 사라집니다.
• 앱에서 constraints(권장) 또는 implementation으로 버전을 승격합니다.
• Java 앱은 fragment(non-ktx)를, 버전은 Kotlin 요구 수준을 확인하고 고릅니다.
• 확인은 APK의 META-INF/androidx.fragment_fragment.version으로 합니다.
• 경고는 최근 업로드한 앱에만 뜹니다. 여러 앱이면 전부 확인하고, 새 앱 템플릿에도 넣으세요.

자주 묻는 것

이 경고를 무시하면 앱이 내려가나요?

제가 받은 것은 차단이 아닌 권고 수준이었고, 업로드와 출시는 그대로 됐습니다. 다만 Play의 SDK 색인 경고는 SDK 제공자가 등급을 올리면 나중에 업로드를 막는 쪽으로 바뀔 수 있습니다. 한 줄로 끝나는 일이라 미뤄 둘 이유가 없습니다.

fragment를 올리면 광고나 Firebase가 깨지지 않나요?

AndroidX는 같은 메이저 버전(1.x) 안에서 하위 호환을 지키는 것이 원칙이라, 1.1.0에서 1.8.x로 올리는 것은 그 범위 안입니다. 저는 광고·인앱 리뷰·Firebase Analytics가 든 앱들에 적용해 배포했고 빌드와 실행에 문제가 없었습니다. 그래도 불안하면 광고가 뜨는 화면과 동의(UMP) 팝업을 실기기에서 한 번씩 띄워 보세요.

constraints를 넣었는데 버전이 안 바뀌어요.

constraints는 같은 설정(configuration)에 걸려야 합니다. implementation 블록 안에 넣었는지, 다른 곳에서 strictly나 force로 낮은 버전을 박아 두지 않았는지 dependencyInsight로 확인하세요. 출력에 "By constraint"라는 사유가 붙어 있으면 제대로 걸린 것입니다.

Firebase Remote Config에서 값을 바꿨는데 앱이 반응하지 않을 때, fetchAndActivate가 성공했다는 로그만 보고 넘어가면 원인을 못 찾습니다. 조회는 템플릿이 비어 있어도 성공하기 때문에, 성공 여부만으로는 원격값을 받았는지 인앱 기본값으로 돌고 있는지가 구분되지 않습니다. 하필 기본값과 원격값이 같은 숫자라면 구분이 원리적으로 불가능해집니다. 앱 16개에 원격 설정을 붙이면서 겪은 것을 바탕으로, 값이 어디서 왔는지 확인하는 법과 반영이 늦는 세 가지 이유를 정리합니다.

광고 클릭 차단 시간 같은 값을 앱 재배포 없이 바꾸고 싶어서 Remote Config를 붙였습니다. 코드는 문서대로 짰습니다.

val rc = FirebaseRemoteConfig.getInstance()
rc.setDefaultsAsync(mapOf("bok_config" to """{"click_block_expiry_min":1440}"""))
rc.fetchAndActivate().addOnCompleteListener { task ->
    Log.i(TAG, "fetch ok=${task.isSuccessful}")
    apply(rc.getString("bok_config"))
}

실기기에서 돌리니 fetch ok=true가 찍혔고, 차단 시간도 1440분(24시간)으로 적용돼 있었습니다. 성공으로 보였습니다.

그런데 콘솔에는 아무 값도 올린 적이 없었다

그 시점에 Remote Config 템플릿은 비어 있었습니다. 원격에 값을 올리는 스크립트를 아직 안 돌렸기 때문입니다. 즉 앱이 쓰던 1440은 원격값이 아니라 setDefaultsAsync로 심어 둔 인앱 기본값이었습니다.

제 경우는 더 나빴습니다. 첫 원격값을 일부러 인앱 기본값과 같은 1440으로 올릴 계획이었거든요. 동작은 안 바꾸고 연결만 확인하려는 의도였는데, 그러면 적용됐는지를 값으로는 영영 알 수 없습니다. 대조군이 없는 초록불입니다.

해결 — 값의 출처(source)를 같이 찍는다

getValue(key)가 돌려주는 FirebaseRemoteConfigValue에는 그 값이 어디서 왔는지가 들어 있습니다.

val source = when (rc.getValue("bok_config").source) {
    FirebaseRemoteConfig.VALUE_SOURCE_REMOTE  -> "remote"   // 2
    FirebaseRemoteConfig.VALUE_SOURCE_DEFAULT -> "default"  // 1
    FirebaseRemoteConfig.VALUE_SOURCE_STATIC  -> "static"   // 0
    else -> "unknown"
}
Log.i(TAG, "fetch ok=${task.isSuccessful} source=$source value=...")

로그를 바꾸고 다시 봤습니다.

원격 템플릿 비어 있음  →  fetch ok=true source=default applied=expiryMs=86400000
bok_config 발행 후     →  fetch ok=true source=remote  applied=expiryMs=86400000

값은 똑같이 86400000인데 출처만 바뀌었습니다. 이게 보이고 나서야 "원격에서 앱까지 사슬이 이어졌다"를 확정할 수 있었습니다.

값을 바꿨는데 반영이 늦는 세 가지 이유

① 최소 조회 간격 기본값이 12시간이다

minimumFetchIntervalInSeconds의 기본값은 43200초(12시간)입니다. 그 사이에 fetch를 불러도 SDK가 캐시된 값을 돌려주고 서버에 가지 않습니다. 오류도 아니라서 조용히 옛 값이 유지됩니다.

rc.setConfigSettingsAsync(
    FirebaseRemoteConfigSettings.Builder()
        .setMinimumFetchIntervalInSeconds(3600)   // 1시간
        .build()
)

저는 1시간으로 줄였습니다. 사고가 났을 때 켜는 스위치(광고 끄기)가 반나절 뒤에 닿으면 뜻이 없어서입니다. 다만 개발 중처럼 0으로 두고 배포하면 안 됩니다. 기기당 요청이 스로틀에 걸리면 FirebaseRemoteConfigFetchThrottledException이 나면서 오히려 더 늦게 반영됩니다.

테스트할 때 캐시를 바로 버리려면 앱 데이터를 지웁니다.

adb shell pm clear 내.패키지.이름

② fetchAndActivate는 비동기다 — 첫 화면에 늦는다

완료까지 1초 안팎 걸립니다. 그 사이에 첫 화면은 이미 그려집니다. 실기기에서 시각을 찍어 보니 이랬습니다.

13.565  배너를 띄울지 판정 (아직 기본값)
14.291  배너 생성
14.381  원격값 도착         ← 이미 늦었다

Compose에서 배너를 remember로 한 번만 만들면 나중에 다시 판정하지 않으므로, 늦게 온 값이 그 배너에는 영영 닿지 않습니다. 대처는 두 가지입니다.

• 직전에 활성화된 값을 먼저 읽는다. fetchAndActivate를 부르기 전에 getString으로 한 번 적용합니다. 디스크에 남은 지난번 값이 동기로 읽히므로 두 번째 실행부터는 화면보다 먼저 적용됩니다. 설치 직후 첫 실행은 원리적으로 못 막습니다.
• 값이 꼭 필요한 판단은 도착한 뒤에 한다. 업데이트 안내처럼 원격값을 보고 사용자에게 뭔가를 띄우는 코드를 앱 시작 직후에 두면, 첫 실행에서는 거의 항상 "값 없음"으로 읽혀 영영 안 뜹니다. 코드를 읽으면 정상으로 보이는 종류입니다.

③ 의존성이 없으면 조용히 기본값으로 돈다

공통 라이브러리에서 Remote Config를 쓰면서 SDK를 compileOnly로 두었는데, 앱 쪽에 firebase-config 의존성을 안 넣으면 빌드는 되고 런타임에 클래스가 없습니다. 앱이 죽지 않게 감싸 두면, 그 앱만 원격 설정이 통째로 꺼진 채 기본값으로 돕니다. "원격으로 껐는데 그 앱만 안 꺼진다"를 겪고 나서야 알게 되는 구조입니다.

runCatching {
    FirebaseRemoteConfig.getInstance()
    ...
}.onFailure { e ->
    // NoClassDefFoundError 까지 여기서 걸린다 — 조용히 넘기지 말고 기록한다
    Log.w(TAG, "원격 설정을 쓸 수 없다(firebase-config 의존성 누락?): ${e.javaClass.simpleName}")
}

firebase-analytics는 모든 앱에 이미 있어서 베끼는 과정에서 안 빠지는데, firebase-config는 0개에서 시작한 의존성이라 새 앱을 만들 때 빠지기 쉽습니다.

기본값은 "안전한 쪽"으로

원격값은 늦게 오거나 안 올 수 있으니, 앱은 상당 시간 기본값으로 돈다고 생각해야 합니다. 그래서 기본값을 정할 때 "평소에 쓸 값"이 아니라 "조회가 실패한 사용자에게 무슨 일이 생기나"로 정합니다.

정리

• fetchAndActivate 성공은 원격값을 받았다는 뜻이 아닙니다. 빈 템플릿에서도 성공합니다.
• getValue(key).source로 remote / default / static을 같이 찍으세요. 값이 같아도 출처는 갈립니다.
• 최소 조회 간격 기본값은 12시간입니다. 너무 짧게 두면 스로틀에 걸립니다.
• 원격값은 첫 화면에 늦습니다. 직전 값을 먼저 적용하고, 값이 필요한 판단은 도착 뒤에 합니다.
• SDK를 compileOnly로 쓰는 구조라면 의존성 누락이 조용히 기본값이 됩니다. 실패를 기록하세요.

자주 묻는 것

fetchAndActivate가 false를 돌려주는데 실패인가요?

아닙니다. Task<Boolean>의 결과값 false는 이번 호출에서 새로 활성화한 값이 없다는 뜻입니다. 이미 활성화된 값과 같거나 캐시에서 돌려준 경우입니다. 실패 여부는 task.isSuccessful로 봅니다. 결과값과 성공 여부를 섞어 읽으면 정상 동작을 실패로 오판합니다.

콘솔에서 게시했는데 source가 계속 default예요.

세 가지를 확인하세요. 키 이름이 코드와 정확히 같은지(대소문자 포함), 조건(앱 버전·국가 등)에 걸려 이 기기에 값이 안 내려오는지, 그리고 최소 조회 간격 때문에 아직 서버에 안 간 것인지입니다. 마지막은 adb shell pm clear로 캐시를 지우고 다시 켜면 바로 갈립니다.

값을 바꾸면 앱이 켜진 채로 바로 반영되게 할 수 있나요?

실시간 업데이트 리스너(addOnConfigUpdateListener)를 쓰면 게시 직후 켜져 있는 앱에 변경이 전달됩니다. 다만 받은 뒤 activate()를 불러야 적용되고, 이미 그려진 화면이 다시 판정하지 않는 문제는 그대로 남습니다. 저는 사고 대응용 스위치라 1시간 간격 조회로 충분하다고 보고 붙이지 않았습니다.

OkHttp에 재시도 인터셉터를 달아 뒀는데 네트워크 실패가 전혀 줄지 않는다면, 재시도 조건이 실제 예외를 못 잡고 있을 가능성이 큽니다. 연결이 응답 도중 끊기면 OkHttp는 SocketException이 아니라 평범한 IOException에 unexpected end of stream이라는 문구를 실어 던지고, 읽기 타임아웃의 문구는 timeout이 아니라 Read timed out입니다. 제 앱은 두 구멍에 차례로 빠져 있었고, 실사용자 실패 9건의 재시도 기록이 9건 전부 "한 번에 포기"였습니다. 재시도 코드는 멀쩡히 붙어 있었는데 한 번도 돈 적이 없었던 것입니다.

공공데이터 API를 쓰는 앱이었습니다. 정부 서버가 가끔 연결을 끊어서, 몇 년 전에 재시도를 붙여 둔 코드가 있었습니다.

fun isRetryable(e: IOException): Boolean =
    e is SSLException ||
    e is SocketException ||
    e.message?.contains("Connection reset") == true ||
    e.message?.contains("timeout") == true

읽어 보면 그럴듯합니다. SSL 오류, 소켓 오류, 연결 리셋, 타임아웃. 흔한 네트워크 실패는 다 들어 있는 것처럼 보입니다. 파일 맨 위 주석에도 "서버의 Connection reset에 대비한 재시도"라고 적혀 있었습니다.

첫 번째 구멍 — unexpected end of stream

이 람다를 별도 클래스로 꺼내서 테스트를 붙였더니 첫 실행에서 바로 빨간불이 났습니다. 테스트는 MockWebServer로 서버가 연결을 진짜로 끊게 만든 것이었습니다.

server.enqueue(MockResponse().setSocketPolicy(SocketPolicy.DISCONNECT_AT_START))
server.enqueue(MockResponse().setBody("ok"))

client.newCall(request).execute().use { assertEquals(200, it.code) }

첫 요청은 끊기고 두 번째는 성공하니, 재시도가 돌면 통과해야 합니다. 그런데 첫 요청에서 예외가 그대로 밖으로 나왔습니다. 찍힌 예외는 이랬습니다.

java.io.IOException: unexpected end of stream on http://127.0.0.1:2114/...

SocketException이 아닙니다. 그냥 IOException이고, 문구에 "Connection reset"도 "timeout"도 없습니다. 네 조건 어디에도 걸리지 않으니 재시도 없이 즉시 포기했습니다. "서버가 연결을 끊는 상황"에 대비한 코드가 정작 그 상황의 상당 부분을 놓치고 있었습니다.

같이 터진 것 — android.util.Log는 JVM 테스트에서 예외를 던진다

처음 돌린 테스트 네 개가 전부 다른 이유로 깨지기도 했습니다. 재시도 경로의 catch 블록 안에 Log.w(...)가 있었는데, 로컬 유닛테스트에서 android.util.Log는 호출만 해도 RuntimeException: Method w in android.util.Log not mocked를 던집니다. 재시도 경로가 통째로 폭발한 것입니다.

unitTests.isReturnDefaultValues = true를 켜면 사라지긴 합니다. 저는 켜지 않았습니다. 그 옵션은 안드로이드 API 전부를 조용한 기본값으로 바꿔서, 언젠가 다른 곳의 진짜 실패까지 초록불로 덮기 때문입니다. 대신 로그를 생성자 파라미터로 뺐습니다.

internal class RetryInterceptor(
    private val maxAttempts: Int = 3,
    private val sleep: (Long) -> Unit = { Thread.sleep(it) },
    private val logWarn: (String) -> Unit = { Log.w(TAG, it) },   // 테스트에서는 {} 를 넘긴다
) : Interceptor

두 번째 구멍 — "timeout"과 "timed out"은 다른 문자열이다

unexpected end of stream을 조건에 추가해서 배포했습니다. 닷새 뒤, 실사용자 기기 세 종류에서 첫 실행 데이터 로딩 실패가 6건 올라왔습니다. 실패 사유는 timeout으로 정확히 분류돼 있었습니다. 그런데 같은 시간대의 재시도 결말 기록을 보니 이상했습니다.

실패 9건, 포기 9건. 모든 실패에서 재시도가 0회였습니다. 원문을 열어 보니 이렇게 찍혀 있었습니다.

retry_skipped  detail=1/3 timeout Read timed out

조건은 contains("timeout")인데 메시지는 Read timed out입니다. "timeout"과 "timed out"은 다른 문자열이라 걸리지 않습니다. 타입 조건에도 안 걸렸습니다. SocketTimeoutException은 이름과 달리 SocketException의 자식이 아니라 InterruptedIOException의 자식입니다.

java.io.IOException
 ├─ java.net.SocketException            ← 조건이 본 것
 │    └─ ConnectException ...
 └─ java.io.InterruptedIOException
      └─ java.net.SocketTimeoutException ← 실제로 온 것

더 허무했던 건, 같은 앱에서 실패 사유를 분류하는 코드는 진작 is SocketTimeoutException으로 정확히 분류하고 있었다는 점입니다. 그래서 보고서에는 reason=timeout이 제대로 찍혔습니다. 분류는 타입으로, 재시도 판정만 문자열로 한 불일치가 원인이었습니다.

이 옛 테스트가 결함을 덮고 있었다

타임아웃 테스트가 없었던 게 아닙니다. 있었고, 초록불이었습니다.

assertTrue(isRetryable(IOException("read timeout")))   // ← 손으로 만든 예외

첫 번째 구멍에서 "손으로 만든 예외로 테스트하면 안 된다"를 배우고도, 바로 그 파일에 그 함정이 한 줄 남아 있었습니다. SocketPolicy.NO_RESPONSE로 서버가 응답을 영영 안 주게 만들어 진짜 읽기 타임아웃을 내는 테스트로 바꿨습니다.

server.enqueue(MockResponse().setSocketPolicy(SocketPolicy.NO_RESPONSE))
server.enqueue(MockResponse().setBody("ok"))
// client 는 readTimeout 을 짧게(예: 200ms) 잡아 둔다

해결 — 판정을 문자열이 아니라 타입으로

fun isRetryable(e: IOException): Boolean =
    e is SocketTimeoutException ||      // "Read timed out" / "timeout" 둘 다
    e is SSLException ||
    e is SocketException ||
    e.message?.contains("unexpected end of stream", ignoreCase = true) == true

unexpected end of stream은 전용 예외 타입이 없어서 문구로 남길 수밖에 없습니다. 나머지는 전부 타입입니다. 실제로 실기기에서 타임아웃을 재현해 보니 같은 SocketTimeoutException인데 메시지가 Read timed out이 아니라 timeout으로 나왔습니다. 어느 계층이 먼저 터지느냐로 문구가 갈립니다(Okio의 타임아웃이냐, 소켓의 SO_TIMEOUT이냐). 문자열 판정은 기기와 경로에 따라 되고 안 되고가 갈린다는 뜻입니다.

함께 막아야 하는 두 가지

① 취소는 실패가 아니다. 코루틴이 취소되면 Retrofit이 Call.cancel()을 부르고, OkHttp는 IOException("Canceled")를 던집니다. 실패처럼 생겨서 옵니다. 그대로 두면 사용자가 화면을 벗어난 횟수만큼 실패 통계가 쌓입니다. 문구가 아니라 call의 상태로 가릅니다.

} catch (e: IOException) {
    if (chain.call().isCanceled()) throw e   // 재시도도, 실패 기록도 하지 않는다
    ...

② 타임아웃은 시도 상한을 따로 낮춘다. 끊긴 연결은 즉시 예외가 오지만, 타임아웃은 한 번마다 readTimeout을 꼬박 태웁니다. 20초 타임아웃에 3회면 최악 60초인데, 제 경우 그 실패가 나는 자리가 하필 첫 실행 스플래시였습니다. 타임아웃만 2회로 줄였고, 실기기에서 43초에 끝나는 것을 확인했습니다.

private fun attemptLimit(e: IOException) =
    if (e is SocketTimeoutException) minOf(maxAttempts, 2) else maxAttempts

재시도가 실제로 도는지 밖에서 보는 법

이번 일의 진짜 교훈은 여기 있습니다. 재시도는 잘 돌아도 조용하고, 안 돌아도 조용합니다. 실패 건수만 보면 "네트워크가 원래 불안정하구나"로 읽힙니다. 그래서 재시도의 결말을 세 갈래로 나눠 기록합니다.

첫 시도 성공은 기록하지 않습니다. 재시도가 있었을 때만 남겨야 "살려낸 요청"이 잡음에 묻히지 않습니다. 실패 건수와 skipped 건수가 똑같이 움직이면, 그게 재시도가 한 번도 안 돌고 있다는 지문입니다.

정리

• 연결이 응답 도중 끊기면 OkHttp는 평범한 IOException("unexpected end of stream on …")을 던집니다. SocketException 조건에 안 걸립니다.
• 읽기 타임아웃의 문구는 Read timed out이라 contains("timeout")에 안 걸립니다. SocketTimeoutException은 SocketException의 자식도 아닙니다.
• 판정은 타입으로 합니다. 같은 예외라도 계층에 따라 문구가 달라집니다.
• 테스트는 MockWebServer의 SocketPolicy로 진짜 소켓을 끊어서 합니다. 손으로 만든 예외는 아무것도 검증하지 않습니다.
• 수정을 잠깐 되돌려서 새 테스트가 빨간불이 되는지 확인하세요. 초록불이 "검증됐다"인지 "조건에 못 닿았다"인지는 그렇게만 갈립니다.
• 재시도 결말(recovered·exhausted·skipped)을 기록하세요. 안 도는 재시도는 로그 없이는 안 보입니다.

자주 묻는 것

OkHttp의 retryOnConnectionFailure로는 안 되나요?

기본값이 true이고 일부 연결 실패는 알아서 다시 시도합니다. 하지만 대상이 좁습니다. 이미 요청을 보낸 뒤 응답 도중 끊긴 경우나 읽기 타임아웃은 다시 보내지 않는 경우가 많습니다. 서버 쪽에서 중복 처리돼도 문제없는 GET 요청이라면 인터셉터로 직접 재시도하는 편이 확실합니다.

POST도 이렇게 재시도해도 되나요?

조심해야 합니다. unexpected end of stream은 서버가 요청을 이미 처리한 뒤 응답만 못 보낸 경우에도 납니다. 결제·등록 같은 요청을 다시 보내면 두 번 처리될 수 있습니다. 저는 조회용 GET에만 이 인터셉터를 붙였습니다.

unexpected end of stream이 자꾸 나는 원인 자체는 뭔가요?

대개 서버나 중간 장비(로드밸런서·프록시)가 연결을 먼저 닫은 것입니다. 오래 놀던 keep-alive 연결을 재사용하려는 순간 서버는 이미 닫아 둔 경우가 흔합니다. 서버를 고칠 수 없는 공공 API라면 클라이언트에서 재시도로 받아내는 것이 현실적인 답입니다.

GA4에 커스텀 측정기준을 등록해 뒀는데 보고서를 열면 값이 하나도 안 담기고 (not set)만 나오는 경우가 있습니다. 대개는 수집이 안 되는 게 아니라 파라미터 타입 문제입니다. 측정기준은 문자열만 읽기 때문에, putLong으로 보낸 숫자는 등록해 둬도 값이 통째로 비어 있습니다. 제 앱 네 개가 전부 그 상태였고 30일치 1,209건이 남김없이 (not set)이었는데, 이벤트 수는 정확하게 나오는 탓에 한참 동안 눈치채지 못했습니다.

어쩌다 그렇게 됐는지부터 적겠습니다. 앱에 계측을 심었습니다. 목록 화면이 열릴 때 몇 건이 실렸는지 같이 보내도록 했습니다.

val params = Bundle().apply {
    putString("source", "cache")
    putLong("item_count", list.size.toLong())   // 몇 건 실렸나
}
FirebaseAnalytics.getInstance(context).logEvent("home_loaded", params)

GA4 관리 화면에서 item_count를 커스텀 측정기준으로 등록했습니다. 며칠 기다렸다가 탐색 보고서를 열었습니다.

item_count        이벤트 수
(not set)              1,209
─────────────────────────────
합계                    1,209

전량 (not set)이었습니다. 한 건도 값이 담기지 않았습니다. 이벤트 수 1,209는 정확했습니다. 즉 이벤트는 제대로 나가고 있었고, 값만 비어 있었습니다.

원인 — 측정기준은 문자열만 읽는다

GA4의 커스텀 측정기준(dimension)은 문자열 파라미터만 읽습니다. putLong·putDouble·putInt로 보낸 숫자는 측정기준으로 등록해 둬도 조회하면 전부 (not set)입니다.

GA4가 파라미터를 받는 창구는 두 개인데, 서로 통하지 않습니다.

등록 화면에서는 이 구분이 눈에 잘 안 들어옵니다. 파라미터 이름을 적는 칸이 똑같이 생겼고, 타입이 안 맞아도 등록은 그냥 됩니다. 경고도 없습니다.

진짜 무서운 것은 실패하는 방식이다

저는 이걸 한참 뒤에 알았습니다. 하필 item_count를 쓰던 검사가 "목록이 빈 채로 화면이 떴는가"를 잡는 것이었습니다. 예전에 목록이 통째로 비어 나가는 사고가 있었고, 그 재발을 감지하려고 심어 둔 계측이었습니다.

그런데 값이 전부 (not set)이니 item_count = 0인 건이 한 건도 잡히지 않습니다. 검사는 매번 "이상 없음"을 반환했습니다. 그 검사는 한 번도 돈 적이 없었던 셈입니다.

제 앱들을 전수로 훑어봤더니 item_count를 보내는 앱 네 개가 전부 같은 상태였습니다. 한 곳을 잘못 짠 게 아니라, 같은 코드를 베껴 쓰면서 같은 오해가 그대로 복사돼 있었습니다.

해결 — 숫자를 구간 문자열로 바꿔 보낸다

값별로 쪼개서 세고 싶다면 숫자를 구간으로 묶은 문자열로 보냅니다.

// ❌ 측정기준으로는 영영 안 읽힌다
putLong("item_count", list.size.toLong())

// ✅ 구간 문자열
putString("item_count", bucketOf(list.size))

private fun bucketOf(n: Int): String = when {
    n <= 0    -> "0"        // ← 이게 잡고 싶었던 값이다
    n < 10    -> "1_9"
    n < 50    -> "10_49"
    n < 100   -> "50_99"
    else      -> "100_plus"
}

구간을 나눌 때 가장 중요한 경계를 독립된 칸으로 두는 것이 핵심입니다. 저에게 필요했던 건 "0건"이었으므로 "0"을 따로 뺐습니다. "0_9"로 묶었다면 고쳐도 여전히 못 셌을 겁니다.

측정항목으로 등록하면 되는 것 아닌가

그것도 답이 아닙니다. 실제로 그렇게 해 봤는데, 커스텀 측정항목은 합계와 평균만 내줍니다. "총 3,400건"은 알려주지만 "0건이 몇 번이었나"는 못 셉니다. 제가 알고 싶었던 건 뒤쪽이었습니다.

둘 다 필요하면 둘 다 보내면 됩니다. 파라미터 이름만 다르게 해서 한 이벤트에 같이 싣습니다.

putString("item_count", bucketOf(n))   // 측정기준 — 구간별로 센다
putLong("item_total", n.toLong())      // 측정항목 — 합계·평균을 낸다

확인하는 법 — 코드를 읽지 말고 로그를 보세요

이 결함은 코드를 읽으면 정상으로 보입니다. 유닛테스트도 릴리스 빌드 확인도 잡아 주지 않습니다. 이벤트가 안 나가는 것도 아니고, 값이 틀린 것도 아니고, 타입이 안 맞을 뿐이기 때문입니다.

실기기에서 Firebase Analytics의 디버그 로그를 직접 보는 게 가장 확실합니다.

adb shell setprop log.tag.FA VERBOSE
adb shell setprop log.tag.FA-SVC VERBOSE
adb shell setprop debug.firebase.analytics.app 내.패키지.이름

adb logcat -d -s FA FA-SVC | findstr "Logging event"

파라미터가 타입까지 그대로 찍혀 나옵니다.

Logging event: origin=app, name=home_loaded,
  params=Bundle[{source(_o)=cache, item_count(_o)=3}]      ← 숫자로 나가는 중
  params=Bundle[{source(_o)=cache, item_count(_o)=1_9}]    ← 문자열로 고친 뒤

값이 따옴표 없이 3으로 찍히면 숫자, 1_9처럼 문자열 형태면 제대로 나가는 중입니다.

같은 계열의 함정 하나 더

실패 원인을 보낼 때 예외 클래스 이름을 그대로 싣는 코드도 같은 방식으로 조용히 망가집니다.

// ❌ 릴리스에서 이름이 뭉개진다
putString("reason", e::class.simpleName ?: "unknown")

릴리스는 isMinifyEnabled = true라 라이브러리와 우리 예외의 클래스 이름이 한 글자로 줄어듭니다. 저는 보고서에서 reason=X를 봤습니다. 그날 무엇이 실패했는지는 영영 못 읽습니다. JDK 내장 예외는 난독화를 피해 살아남기 때문에 되는 앱과 안 되는 앱이 갈려 더 헷갈립니다. 게다가 그 한 글자는 빌드마다 바뀌어서 집계 자체가 성립하지 않습니다.

is 타입 검사로 고정 키를 만들어 보내야 합니다.

fun reasonOf(e: Throwable): String = when (e) {
    is java.net.UnknownHostException -> "no_network"
    is java.net.SocketTimeoutException -> "timeout"
    is javax.net.ssl.SSLException -> "ssl"
    is java.io.IOException -> "io"
    else -> "unknown"
}

순서에 주의합니다. SocketTimeoutException은 IOException의 하위 타입이라 좁은 것을 먼저 놓지 않으면 전부 "io"로 뭉쳐집니다.

정리

• GA4 커스텀 측정기준은 문자열만 읽습니다. putLong으로 보낸 숫자는 등록해도 전부 (not set)입니다.
• 타입이 안 맞아도 등록은 되고 경고도 없습니다. 이벤트 수는 맞게 나와서 대시보드가 멀쩡해 보입니다.
• 값별로 세려면 구간 문자열로 보내고, 가장 중요한 경계는 독립된 칸으로 둡니다.
• 합계도 필요하면 측정항목용 숫자를 따로 하나 더 보냅니다.
• 검증은 실기기에서 adb logcat -s FA FA-SVC로 합니다. 코드를 읽어서는 안 보입니다.
• 계측을 심은 것과 밖에서 읽히는 것은 다릅니다. GA4에서 그 값을 실제로 꺼내 보는 데까지가 한 작업입니다.

자주 묻는 것

등록하고 얼마나 기다려야 값이 보이나요?

커스텀 측정기준은 등록한 이후에 수집된 데이터부터 적용됩니다. 소급되지 않습니다. 보고서에 반영되기까지 보통 24-48시간 걸리므로, 하루 이틀은 (not set)이 정상입니다. 이 글의 증상은 며칠이 지나도 100%가 (not set)인 경우입니다. 급하게 확인하려면 DebugView를 쓰면 실시간으로 보입니다.

이벤트당 파라미터 개수 제한이 있나요?

이벤트 하나에 파라미터 25개까지이고, 속성 단위로 커스텀 측정기준은 이벤트 범위 50개, 측정항목은 50개까지 등록할 수 있습니다. 실무에서는 개수보다 이름을 앱마다 다르게 쓰는 것이 먼저 문제가 됩니다. 같은 사건이 앱마다 다른 파라미터 이름으로 들어오면 한 화면에서 못 묶습니다.

등록할 때 표시 이름은 아무렇게나 지어도 되나요?

표시 이름에 괄호를 넣지 마세요. 여러 개를 한 번에 등록할 때 괄호가 들어간 것만 조용히 빠지는 일을 겪었습니다. 오류 메시지는 나오지 않고, 등록 목록에서 하나가 없을 뿐입니다. 등록 직후에 목록을 다시 읽어 개수를 세어 보는 것을 권합니다.

다른 버그를 잡다가 계측 테스트를 Android 10 실기기에서 돌렸습니다. 평소에는 최신 기기로만 돌리던 것이었습니다.

java.lang.SecurityException: Unknown permission
    android.permission.READ_MEDIA_IMAGES

갤러리 테스트 세 건이 전부 이걸로 죽었습니다. 테스트가 실패한 게 아니라 본문이 시작조차 못 한 것입니다.

범인은 이 줄이었습니다.

// ❌ API 33 전용 권한을 모든 기기에 요구한다
@get:Rule(order = 0)
val permissionRule: GrantPermissionRule = GrantPermissionRule.grant(
    Manifest.permission.CAMERA,
    Manifest.permission.ACCESS_FINE_LOCATION,
    Manifest.permission.READ_MEDIA_IMAGES,
)

원인 — 권한 이름이 API 33에서 갈린다

READ_MEDIA_IMAGES는 API 33(Android 13)에서 생긴 권한입니다. 그 미만 기기에는 그런 이름의 권한이 시스템에 아예 없습니다.

GrantPermissionRule은 테스트 본문 전에 이 권한들을 부여하려 하는데, 존재하지 않는 이름을 받으면 SecurityException을 던집니다. @Rule 단계에서 던지므로 @Before도 @Test도 실행되지 않습니다.

여기서 정신이 번쩍 들었던 건, 제 앱의 minSdk가 26이라는 사실이었습니다. 즉 갤러리 기능은 지원 범위의 상단 일부에서만 검증돼 왔습니다. 그 아래 구간은 테스트가 존재는 하는데 한 번도 돌아 본 적이 없었습니다.

고치는 법 — 매니페스트와 같은 경계로 가른다

@get:Rule(order = 0)
val permissionRule: GrantPermissionRule = GrantPermissionRule.grant(
    Manifest.permission.CAMERA,
    Manifest.permission.ACCESS_FINE_LOCATION,
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU)
        Manifest.permission.READ_MEDIA_IMAGES
    else
        Manifest.permission.READ_EXTERNAL_STORAGE
)

더 나쁜 쪽 — 아무것도 검증하지 않으면서 늘 통과하던 테스트

위의 건은 그래도 빨간불이라 눈에 띕니다. 같은 날 발견한 다른 테스트가 훨씬 나빴습니다.

// ❌ "갤러리로 이동했는가"를 본다면서 빈 목록 문구를 확인한다
@Test
fun galleryContent_shown_afterOpeningGallery() {
    composeTestRule.onNodeWithContentDescription("갤러리").performClick()
    composeTestRule.onNodeWithText("저장된 사진이 없습니다").assertIsDisplayed()
}

이 테스트는 계속 통과하고 있었습니다. 이유가 문제입니다. 그 테스트 클래스는 사진 읽기 권한을 부여하지 않았고, 그래서 갤러리는 사진이 있든 없든 늘 비어 보였습니다.

즉 이 테스트는

• 화면 이동을 검증한다고 이름을 붙였지만
• 실제로는 목록이 비어 있는지를 보고 있었고
• 권한이 없어서 영원히 비어 있었습니다

실패할 수 없는 초록불이었습니다. 권한을 제대로 넣자마자 곧바로 빨간불이 됐습니다.

고친 방식은 관심사에 맞는 것을 보게 한 것입니다. 이동을 확인하고 싶으면 목록 내용이 아니라 탭이 선택됐는지를 봅니다.

@Test
fun galleryScreen_retainsStateAfterTabSwitch() {
    composeTestRule.onNodeWithText(str(R.string.tab_settings)).performClick()
    composeTestRule.waitForIdle()
    composeTestRule.onNodeWithText(str(R.string.tab_gallery)).performClick()
    composeTestRule.waitForIdle()
    // "무엇이 떴는가"가 아니라 "갤러리로 돌아왔는가"가 이 테스트의 관심사다
    composeTestRule.onNodeWithText(str(R.string.tab_gallery)).assertIsSelected()
}

"빈 상태"를 전제하는 테스트는 실패가 아니라 스킵이어야 한다

빈 목록 문구를 진짜로 확인하고 싶은 테스트도 물론 있습니다. 그건 기기에 사진이 없을 때만 성립하는 전제입니다. 사진이 있는 실기기에서 빨간불로 두면 진짜 회귀와 구분이 안 됩니다.

@Test
fun galleryScreen_showsEmptyMessageWhenNoPhotos() {
    assumeTrue("사진이 있는 기기에서는 빈 상태를 볼 수 없다", galleryIsEmpty())
    composeTestRule.onNodeWithText(str(R.string.gallery_empty)).assertIsDisplayed()
}

전제 판정은 화면과 같은 질의를 재사용한다

galleryIsEmpty()를 짤 때 경로를 테스트에 따로 적고 싶어집니다. 그러면 앱이 저장 폴더를 바꿨을 때 조용히 어긋납니다. 화면이 쓰는 질의 함수를 그대로 가져다 씁니다.

private fun galleryIsEmpty(): Boolean {
    val (selection, args) = galleryQuery(Build.VERSION.SDK_INT)   // 화면과 같은 질의
    val ctx = InstrumentationRegistry.getInstrumentation().targetContext
    val cursor = ctx.contentResolver.query(
        MediaStore.Images.Media.EXTERNAL_CONTENT_URI,
        arrayOf(MediaStore.Images.Media._ID), selection, args, null
    ) ?: return true
    cursor.use { return it.count == 0 }
}

무엇을 놓쳤나

이 테스트들이 못 잡고 지나간 것이 실제로 있었습니다. 같은 앱에서 SQLiteException: no such column: relative_path로 갤러리를 여는 순간 앱이 죽는 버그가 API 28 이하에 있었습니다. MediaStore.RELATIVE_PATH가 API 29부터인데 minSdk가 26이었던 것입니다.

갤러리 화면을 여는 계측 테스트가 분명히 있었는데도 못 잡았습니다. 그 테스트가 API 33 이상에서만 돌고 있었기 때문입니다. 자세한 내용은 따로 정리했습니다 — (MediaStore relative_path 편).

일반화 — 초록불의 두 가지 뜻

이번 일을 한 문장으로 줄이면 이렇습니다.

초록불이 "검증됐다"는 뜻인지 "조건에 못 닿았다"는 뜻인지 갈라 봐야 합니다.

아래는 전부 결과 요약에서 통과처럼 보이는 것들입니다.

결과

권한 분기를 넣고 단정문을 바로잡은 뒤 두 환경에서 돌렸습니다.

실기기(Android 10) : 계측 42개 · 0 실패 · 2 스킵
에뮬레이터(전면 카메라 없음) : 계측 42개 · 0 실패 · 1 스킵

스킵 수가 환경마다 다른 것이 정상입니다. 그 차이가 곧 "이 환경에서는 어떤 전제가 성립하지 않았는가"를 말해 줍니다. 스킵이 0으로만 나오면 오히려 전제 처리를 안 한 것일 수 있습니다.

정리

• GrantPermissionRule에 API 33 전용 권한 이름을 그대로 넘기지 마세요. 33 미만에서 SecurityException으로 본문이 시작조차 못 합니다.
• 권한 목록의 경계는 매니페스트의 maxSdkVersion과 같게 맞춥니다.
• 권한을 안 준 테스트는 화면이 늘 비어 보여 아무거나 통과시킵니다.
• "빈 상태" 전제는 실패가 아니라 스킵(assumeTrue)으로 처리합니다.
• 전제 판정은 화면과 같은 질의를 재사용합니다.
• 테스트도 minSdk에서 한 번 돌리세요. 앱을 돌린 것과는 별개의 확인입니다.

자주 묻는 것

CI에서는 최신 API 에뮬레이터만 쓰는데요?

흔한 구성이고, 그래서 이 문제가 오래 숨습니다. 전체 스위트를 두 배로 돌릴 필요는 없습니다. 저장소·권한·미디어를 건드리는 테스트 클래스만 minSdk 에뮬레이터에서 한 번 더 돌려도 이 부류는 걸러집니다.

@SdkSuppress로 33 미만을 제외하면 안 되나요?

그건 "33 미만에서는 검증하지 않겠다"고 선언하는 것입니다. 기능 자체가 33+ 전용이면 옳은 선택이지만, 갤러리처럼 minSdk 전 구간에서 동작해야 하는 기능에 쓰면 문제를 감추는 쪽이 됩니다. 제 경우가 정확히 그랬습니다.

connectedAndroidTest로 돌리면 권한이 자꾸 초기화되는데요?

connectedAndroidTest는 앱을 설치하면서 권한 상태를 지웁니다. 저는 설치 → pm grant → am instrument 순서로 나눠 돌립니다. GrantPermissionRule과 별개로, 테스트 밖에서 미리 필요한 권한을 주고 시작하는 편이 결과가 안정적입니다.

카메라 화면에 로그를 심어 두고 며칠 뒤 이런 것을 봤습니다.

camera/bind_failed —
IllegalArgumentException: No available camera can be found lens=0

lens=0은 CameraSelector.LENS_FACING_FRONT, 즉 전면입니다. 전면 카메라가 없는 기기에서 전환 버튼을 누른 것입니다.

여기까지는 예상 가능한 범위입니다. 진짜 문제는 그 다음이었습니다. 실패한 것은 전면인데, 잘 나오던 후면 미리보기까지 검은 화면이 됩니다. 그리고 그 상태에서 빠져나올 방법이 없습니다. 크래시가 아니라서 아무 안내도 없고, 사용자는 이유 없는 검은 화면만 봅니다.

왜 후면까지 죽는가 — 순서 문제다

문제가 된 코드는 흔한 모양이었습니다.

// ❌ 떼고 나서 붙이는데, 붙이기가 실패하면 아무것도 안 남는다
LaunchedEffect(lensFacing) {
    val provider = ProcessCameraProvider.getInstance(context).get()
    val selector = CameraSelector.Builder().requireLensFacing(lensFacing).build()

    provider.unbindAll()
    provider.bindToLifecycle(lifecycleOwner, selector, preview, imageCapture)
}

unbindAll()이 먼저입니다. 이 줄을 지나는 순간 기존에 잘 붙어 있던 후면 바인딩이 사라집니다. 그리고 다음 줄에서 없는 렌즈로 붙이려다 예외가 납니다. 남는 상태는 "아무것도 안 붙은 상태"입니다.

즉 전환 한 번의 실패가 카메라 기능 전체를 끕니다.

게다가 재시도가 없다

LaunchedEffect(lensFacing)은 키가 바뀔 때만 다시 돕니다. 실패해도 lensFacing은 여전히 전면 값 그대로이므로, 이 블록은 다시 실행되지 않습니다. 복구 경로가 아예 없는 것입니다. 화면을 나갔다 들어와도 상태가 남아 있으면 그대로입니다.

고친 방식 — 떼기 전에 확인하고, 실패하면 되돌린다

세 겹으로 얽힌 문제라 세 군데를 고쳤습니다.

① 있는지 먼저 묻는다 — unbindAll()을 지나기 전에

val provider = ProcessCameraProvider.getInstance(context).get()

// 두 렌즈가 다 있을 때만 전환 버튼을 띄운다
canSwitch = provider.hasCamera(CameraSelector.DEFAULT_BACK_CAMERA) &&
            provider.hasCamera(CameraSelector.DEFAULT_FRONT_CAMERA)

val selector = CameraSelector.Builder().requireLensFacing(lensFacing).build()

// ⚠️없는 렌즈라면 unbindAll() 을 지나기 전에 돌아선다
if (!provider.hasCamera(selector)) {
    if (lensFacing != boundLens) {
        lensFacing = boundLens        // 전환 실패 — 되던 렌즈로 되돌린다
    } else if (!flippedOnce) {
        flippedOnce = true            // 처음 고른 렌즈가 없다 — 반대쪽을 한 번만
        lensFacing = otherLens(lensFacing)
    }
    return@LaunchedEffect
}

hasCamera(selector)가 핵심입니다. 떼기 전에 물어보면 잘 붙어 있던 것을 잃지 않습니다.

② 실패해도 되돌아갈 자리를 기억한다

// 마지막으로 **실제 바인딩에 성공한** 렌즈. 전환이 실패했을 때 되돌아갈 자리다.
var boundLens by remember { mutableIntStateOf(CameraSelector.LENS_FACING_BACK) }

// ... 바인딩 성공 직후에만 갱신한다
provider.unbindAll()
provider.bindToLifecycle(lifecycleOwner, selector, preview, imageCapture)
boundLens = lensFacing

lensFacing(가고 싶은 곳)과 boundLens(실제로 성공한 곳)를 따로 둡니다. 하나로 합쳐 두면 "되돌릴 자리"라는 정보 자체가 없습니다.

그리고 catch에서도 되돌립니다. 되돌리면 lensFacing이 바뀌므로 LaunchedEffect가 다시 돌아 미리보기가 살아납니다.

} catch (e: Exception) {
    // 기록만 하고 끝내면 재시도 자체가 없다 — 검은 화면이 그대로 남는다
    logIssue("camera", "bind_failed", "${e::class.simpleName}: ${e.message} lens=$lensFacing")
    if (lensFacing != boundLens) lensFacing = boundLens
}

③ 없는 렌즈로 가는 버튼을 아예 안 띄운다

if (canSwitch) {
    IconButton(onClick = { lensFacing = otherLens(lensFacing) }) { /* ... */ }
}

무한 왕복 빗장

flippedOnce가 왜 필요한지 짚고 갑니다. 처음 고른 렌즈가 없어서 반대쪽으로 넘겼는데 그쪽도 없으면, 다시 반대쪽으로 넘기면서 두 렌즈 사이를 무한히 왕복합니다. 카메라가 아예 없는 기기에서 실제로 그렇게 됩니다. 한 번만 넘겨 보고 멈추게 해야 합니다.

검증 — 실기기로는 이 버그를 못 잡는다

여기가 제가 얻은 가장 큰 교훈입니다. 제 테스트 폰은 전면과 후면이 다 있어서 문제의 분기에 아예 들어가지 않습니다. 몇 번을 눌러 봐도 정상입니다.

조건을 만들어야 합니다. 에뮬레이터를 전면 카메라 없이 띄웁니다.

emulator -avd Pixel_5_API_30 -camera-front none

제대로 걸렸는지 확인합니다.

adb shell dumpsys media.camera | findstr /C:"Number of camera devices" /C:"Facing"

Number of camera devices: 1
Facing: Back

음성 대조군을 반드시 확인하세요

테스트를 짜고 초록불이 떴다고 끝내면 안 됩니다. 수정 전 코드를 같은 에뮬레이터에 올려서 빨간불이 뜨는지 봐야 합니다. 저는 이렇게 확인했습니다.

전면=false 후면=true 인데 전환 버튼 1개  → 실패

이게 나와야 그 테스트가 실제로 이 버그를 잡는다는 게 증명됩니다. 대조군 없이 통과만 보면, 조건에 못 닿아서 초록불인 경우와 구분되지 않습니다.

정리

• unbindAll()은 돌아올 수 없는 지점입니다. 그 앞에서 hasCamera()로 확인하세요.
• "가고 싶은 렌즈"와 "실제로 성공한 렌즈"를 따로 들고, 실패하면 되돌려 LaunchedEffect를 다시 돌립니다.
• getInstance().get()을 try 안에 넣으세요. 일시적 점유에도 던집니다.
• 실패를 기록하세요. 크래시가 아닌 고장은 로그를 안 심으면 영영 모릅니다.
• 없는 렌즈로 가는 버튼 자체를 감추고, 무한 왕복 빗장을 겁니다.
• 검증은 -camera-front none 에뮬레이터 + 음성 대조군으로 합니다.

자주 묻는 것

전면 없는 기기가 요즘 있나요?

제 실사용자 중에는 없었습니다. 이 로그를 낸 것도 자동 검사 기기와 에뮬레이터였습니다. 그래도 고친 이유는 같은 코드 경로를 실사용자 상황이 공유하기 때문입니다. 다른 앱이 카메라를 점유한 순간 전환을 누르면 똑같이 검은 화면에 갇힙니다. 지표가 0인 것과 코드가 맞는 것은 다릅니다.

DEFAULT_FRONT_CAMERA로 바인딩하면 알아서 폴백되지 않나요?

requireLensFacing은 이름 그대로 필수 조건이라 없으면 예외입니다. 자동 폴백을 기대하고 짜면 이 글의 상황이 그대로 재현됩니다.

화면에 안내를 띄우는 게 낫지 않나요?

둘 다 하는 게 맞습니다. 다만 먼저 할 것은 미리보기를 살리는 것입니다. "전면 카메라가 없습니다"만 띄우고 검은 화면을 그대로 두면 사용자는 여전히 아무것도 못 합니다.

설정 화면에 텍스트 입력 칸을 하나 만들었습니다. 값은 DataStore에 저장하고, 화면은 그 값을 collectAsState()로 받아 씁니다. 교과서적인 단방향 데이터 흐름입니다.

영어로 hello를 칩니다. 잘 됩니다. 지우고 다시 칩니다. 잘 됩니다. 배포합니다.

그리고 며칠 뒤 한글로 "가나"를 쳐 봅니다.

입력한 것 : 가나
칸에 남은 것 : ㄱㅏㄴㅏ

자음과 모음이 합쳐지지 않고 낱개로 확정됩니다. 백스페이스도 자모 단위로 지워집니다. 저는 이 상태로 앱을 스토어에 내보냈고, 그 입력 칸은 앱의 핵심 기능이었습니다.

원인 — 한 글자마다 디스크를 한 바퀴 돈다

문제의 코드는 이렇게 생겼습니다.

// ❌ 값의 주인이 DataStore 다
val settings by settingsVm.settings.collectAsState()

OutlinedTextField(
    value = settings.customText,
    onValueChange = { settingsVm.setCustomText(it) },
)

한 글자를 칠 때마다 이 경로를 돕니다.

키 입력 → onValueChange → ViewModel → DataStore 쓰기(디스크)
       → Flow 방출 → collectAsState → 리컴포지션 → value 갱신

영어에서는 이 왕복이 늦어도 티가 안 납니다. h는 그냥 h이고, 늦게 돌아와도 h입니다.

한글은 다릅니다. 한글 입력은 "조합 중"이라는 중간 상태를 거칩니다. ㄱ → 가 → 간처럼 이미 화면에 있는 글자가 다음 입력으로 바뀌는 과정이고, 이 조합 상태는 IME가 입력 필드와 연결된 채로 들고 있습니다.

그런데 value가 비동기 저장소에서 돌아오는 값이면, 한 글자마다 필드의 값이 외부에서 통째로 교체됩니다. IME 입장에서는 자기가 조합하던 글자가 매번 발밑에서 사라지는 셈이라 조합 상태가 끊깁니다. 끊긴 조합은 ㄱ인 채로 확정되고, 다음 ㅏ도 따로 확정됩니다. 그래서 ㄱㅏㄴㅏ가 됩니다.

해결 — 입력값은 화면이 들고, 저장은 따로 내보낸다

고치는 원칙은 한 줄입니다. 입력 중인 값의 주인은 화면이어야 합니다. 저장은 그대로 나가되, 필드가 그 결과를 기다리지 않게 만듭니다.

// ✅ 입력값은 화면이 직접 들고 있는다
var customInput by rememberSaveable { mutableStateOf<String?>(null) }

OutlinedTextField(
    value = customInput ?: settings.customText,
    onValueChange = {
        customInput = it              // 화면이 즉시 반영 — IME 조합이 안 끊긴다
        settingsVm.setCustomText(it)  // 저장은 따로 나간다
    },
    singleLine = true,
)

String?과 null이 하는 일

null은 "아직 사용자가 아무것도 안 쳤다"는 뜻입니다.

빈 문자열("")로 초기화하면 안 되는 이유가 여기 있습니다. DataStore가 값을 늦게 내주는 첫 프레임에서 저장돼 있던 글자가 빈 칸으로 덮여 보입니다. 사용자에게는 설정이 날아간 것처럼 보입니다.

remember가 아니라 rememberSaveable

remember만 쓰면 화면 회전이나 시스템의 프로세스 정리에서 입력 중이던 값이 사라집니다. rememberSaveable은 Bundle에 실려 살아남습니다. 입력 칸에는 기본으로 이쪽을 씁니다.

같은 함정이 있는 자리들

DataStore만의 문제가 아닙니다. value가 비동기 왕복을 거쳐 돌아오면 전부 같습니다.

• Room — 입력할 때마다 DB에 쓰고 Flow로 다시 받는 구조
• 서버 저장 — 자동 저장 필드. 네트워크 지연이라 증상이 가장 심합니다
• ViewModel StateFlow — 저장소가 없어도 debounce·distinctUntilChanged·stateIn 같은 연산자가 중간에 끼면 같은 일이 벌어집니다
• 부모에서 내려주는 상태 호이스팅 — 값이 여러 단계를 거쳐 오면서 프레임이 밀리는 경우

확인하는 법

도구가 필요 없습니다. 앱을 켜고 텍스트 칸에 한글을 치면 끝입니다. 문제는 그걸 안 해 본다는 것입니다.

체크리스트로 두면 좋습니다.

• 입력 칸마다 "가나다"를 실제로 쳐 본다 — 붙여넣기 말고 자판으로. 붙여넣기는 조합 과정이 없어 통과합니다
• 중간 글자를 백스페이스로 지웠다가 다시 친다 — 조합 상태가 가장 잘 깨지는 지점입니다
• 빠르게 연타해 본다 — 저장이 느릴수록 증상이 선명합니다
• 화면을 회전시킨다 — rememberSaveable 여부가 여기서 드러납니다

UI 테스트로 잡으려는 시도는 권하지 않습니다. Compose 테스트의 텍스트 입력은 조합 과정을 거치지 않고 값을 밀어 넣는 방식이라, 사람이 손으로 치는 것과 경로가 다릅니다. 초록불이 나와도 손으로 치면 깨집니다.

정리

• Compose TextField의 value를 비동기 저장소 왕복에 맡기면 한글 자모가 흩어집니다.
• 원인은 성능이 아니라 IME 조합 상태가 매 글자 끊기는 것입니다.
• 입력값은 rememberSaveable로 화면이 들고, 저장은 따로 내보냅니다.
• null 초기값으로 "아직 안 침"과 "빈 값"을 구분합니다.
• 텍스트 입력 칸이 있으면 반드시 한글로 쳐 보세요. 영어 테스트는 이 버그를 절대 못 잡습니다.

자주 묻는 것

매 글자 저장하는 게 문제 아닌가요? debounce를 걸면 되지 않나요?

debounce는 저장 횟수를 줄일 뿐, value의 주인이 여전히 저장소면 조합은 똑같이 끊깁니다. 오히려 지연이 들쭉날쭉해져 증상이 불규칙해집니다. 두 가지는 별개의 개선이고, 먼저 고칠 것은 값의 주인입니다. 주인을 화면으로 옮긴 뒤에 저장 쪽에 debounce를 거는 것은 좋습니다.

TextFieldValue를 쓰면 해결되나요?

TextFieldValue는 커서 위치·선택 영역까지 같이 다루는 타입이라 관리할 상태가 늘어납니다. 원인이 "값이 외부에서 교체된다"는 것이므로, 타입을 바꾸는 게 아니라 주인을 바꿔야 풀립니다.

단방향 데이터 흐름 원칙에 어긋나는 것 아닌가요?

저장의 진실 공급원은 여전히 저장소 하나입니다. 달라진 것은 입력 중인 임시 상태를 화면이 들고 있다는 점뿐이고, 이건 IME처럼 프레임 단위로 이어져야 하는 상태에 대한 정상적인 처리입니다. 아키텍처를 지키다 글자가 깨지면 지킬 이유가 없습니다.

앱 안에서 내 앱이 저장한 사진만 골라 보여 주는 갤러리 화면이 있었습니다. 잘 돌아갔습니다. 실기기에서도, 에뮬레이터에서도, 스토어에 나간 뒤에도 아무 문제가 없었습니다.

그런데 로보 테스트를 한 번 돌렸더니 이게 나왔습니다.

android.database.sqlite.SQLiteException: no such column: relative_path (code 1)
  SELECT ... FROM images WHERE (relative_path LIKE ?)
→ Force finishing activity com.example.myapp/.MainActivity

갤러리 탭을 누르는 순간 앱이 강제 종료됩니다. 조건은 하나, Android 9 이하 기기입니다.

원인 — 컬럼에도 API 레벨이 있다

MediaStore.MediaColumns.RELATIVE_PATH는 API 29(Android 10)에서 생긴 컬럼입니다. Scoped Storage가 들어오면서 절대경로 대신 쓰라고 만들어진 것입니다.

문제는 이 상수를 쓰는 코드가 구형 기기에서도 컴파일도 되고 실행도 된다는 점입니다. RELATIVE_PATH는 그냥 "relative_path"라는 문자열 상수이고, 그 문자열은 어느 API 레벨에서든 멀쩡히 존재합니다. Lint도 조용합니다.

터지는 곳은 훨씬 뒤입니다. 그 문자열이 ContentResolver.query()의 selection에 실려 미디어 DB로 넘어가고, 그 DB에 해당 컬럼이 없어서 SQLite가 예외를 던집니다. 컴파일 타임 안전장치가 하나도 걸리지 않는 종류의 API 경계입니다.

왜 아무도 못 잡았나

이 크래시는 Play Console vitals에도 Crashlytics에도 0건이었습니다. 코드가 실제로 깨져 있는데도 그랬습니다. 이유는 단순합니다.

즉 지표가 깨끗한 것은 코드가 맞다는 뜻이 아니라, 아직 아무도 그 자리를 밟지 않았다는 뜻이었습니다. 내일 Android 9 사용자가 설치하면 그대로 깨집니다. minSdk를 26으로 선언해 뒀다는 것은 그 기기에서 동작한다고 스토어에 약속했다는 의미입니다.

고친 방식 — 질의를 SDK로 가르고, 함수로 뽑는다

조회 조건을 만드는 부분을 sdkInt를 인자로 받는 순수 함수로 분리했습니다.

/** 사진이 저장되는 자리. 조회와 저장이 같은 값을 봐야 하므로 한 곳에 둔다. */
const val EVIDSNAP_DIR = "DCIM/EvidSnap"

internal fun galleryQuery(sdkInt: Int): Pair<String, Array<String>> =
    if (sdkInt >= Build.VERSION_CODES.Q) {
        "${MediaStore.Images.Media.RELATIVE_PATH} LIKE ?" to arrayOf("$EVIDSNAP_DIR/%")
    } else {
        @Suppress("DEPRECATION")
        "${MediaStore.Images.Media.DATA} LIKE ?" to arrayOf("%/$EVIDSNAP_DIR/%")
    }

호출부는 이렇게 됩니다.

val (selection, selectionArgs) = galleryQuery(Build.VERSION.SDK_INT)
contentResolver.query(
    MediaStore.Images.Media.EXTERNAL_CONTENT_URI,
    projection, selection, selectionArgs, sortOrder
)?.use { cursor -> /* ... */ }

여기서 걸리기 쉬운 세 가지

저장 쪽도 대칭으로 갈라야 한다

읽기만 고치면 절반입니다. 저장 쪽은 이렇게 갈랐습니다.

• API 29 이상: RELATIVE_PATH + IS_PENDING을 그대로 사용
• API 28 이하: Environment.getExternalStoragePublicDirectory로 폴더를 잡고 mkdirs()로 직접 만든 뒤 MediaColumns.DATA에 절대경로를 넣습니다. 미디어스토어가 폴더를 만들어 주지 않습니다.

참고로 바로 옆의 IS_PENDING은 원래부터 >= Q로 막혀 있었고, 매니페스트에도 WRITE_EXTERNAL_STORAGE에 maxSdkVersion="28"이 붙어 있었습니다. 즉 pre-Q를 지원할 의도는 있었는데 구현만 빠진 것이었습니다. "SDK 분기를 한 군데 했으면 다 했겠지"는 근거가 안 됩니다.

경계값은 테스트로 못 박는다

sdkInt를 인자로 뺀 진짜 이유가 이것입니다. Build.VERSION.SDK_INT는 프레임워크 상수라 유닛 테스트 런타임에서 바꿀 수 없습니다. 인자로 받으면 경계 양쪽을 그냥 호출해서 확인할 수 있습니다.

@Test
fun `pre-Q 는 DATA 절대경로로 조회한다`() {
    val (selection, args) = galleryQuery(28)
    assertTrue(selection.startsWith("_data"))
    assertTrue(args[0].startsWith("%/"))   // 절대경로라 앞에 % 가 있어야 한다
}

@Test
fun `Q 이상은 RELATIVE_PATH 로 조회한다`() {
    val (selection, _) = galleryQuery(29)
    assertTrue(selection.startsWith("relative_path"))
}

28과 29를 둘 다 확인하는 게 요점입니다. 한쪽만 두면 경계가 어디인지를 검증하지 못합니다.

덧 — 테스트는 이걸 왜 못 잡았나

같은 앱의 계측 테스트가 갤러리 화면을 열고 있었는데도 이 크래시를 못 잡았습니다. 나중에 보니 그 테스트 자신이 minSdk에서 안 돌고 있었습니다. 권한 @Rule에 API 33+ 전용 권한 이름을 못박아 둬서, 그 미만 기기에서는 본문이 시작조차 못 하고 있었습니다.

같은 계열의 다른 사고라 따로 정리해 두었습니다 — (계측 테스트가 minSdk에서 안 돌고 있었다 편). 이 글이 "앱이 왜 죽었나"라면, 그쪽은 "검증이 왜 초록불이었나"입니다.

정리

• RELATIVE_PATH는 API 29부터입니다. 문자열 상수라 컴파일·Lint가 안 잡아 줍니다.
• 조회는 죽고, 저장은 조용히 어긋납니다. 둘 다 갈라야 합니다.
• 실사용자 분포가 크래시를 가려 줍니다. 지표 0건은 안전의 근거가 아닙니다.
• SDK 분기는 인자 받는 함수로 뽑아 경계 양쪽을 테스트로 고정하세요.

자주 묻는 것

minSdk를 29로 올려 버리면 안 되나요?

가능한 선택이고, 그 편이 코드는 훨씬 단순해집니다. 다만 그건 버리는 사용자층을 알고 내리는 결정이어야 합니다. 26으로 두고 구현을 안 하는 것이 문제였지, 26 자체가 문제는 아닙니다.

Android 9 에뮬레이터에서도 사진이 안 보이는데요?

저장 쪽 분기를 안 고쳤다면 사진이 다른 폴더에 떨어져 있습니다. 조회를 고쳐도 없는 곳을 찾는 셈이라 계속 비어 보입니다. 저장 분기의 mkdirs()까지 확인하세요.

DATA를 쓰면 정책 위반 아닌가요?

deprecated는 "쓰지 말라"가 아니라 "새 코드에서는 다른 것을 쓰라"입니다. API 28 이하 분기 안에서만 쓰는 것이라 Scoped Storage 정책과 충돌하지 않습니다. 29 이상에서 쓰지 않도록 분기를 확실히 갈라 두는 게 중요합니다.

위젯을 붙인 앱에서 Crashlytics에 이런 것이 올라옵니다.

FATAL EXCEPTION: main
java.lang.RuntimeException: Unable to start activity
    ComponentInfo{...androidx.glance.appwidget.action.InvisibleActionTrampolineActivity}
Caused by: java.lang.IllegalArgumentException:
    List adapter activity trampoline invoked without specifying target intent.
    at androidx.glance.appwidget.action.ActionTrampolineKt
        .launchTrampolineAction(ActionTrampoline.kt:93)

내 폰에서 위젯을 아무리 눌러도 재현되지 않습니다. 에뮬레이터에서도 멀쩡합니다. 그런데 사용자에게는 계속 납니다. 스택 트레이스에 내가 쓴 코드가 한 줄도 없어서 어디서부터 봐야 할지도 막막합니다.

제 앱에서는 이걸 두 번 겪었습니다. 한 번은 원인을 찾아 막았는데, 8일 뒤 같은 예외가 그대로 다시 났습니다. 막아야 할 컴포넌트가 하나가 아니었기 때문입니다.

이 액티비티는 내가 만든 게 아니다

InvisibleActionTrampolineActivity는 androidx.glance:glance-appwidget이 자기 매니페스트에 선언해 넣는 컴포넌트입니다. 매니페스트 병합 결과물에는 들어 있지만 내 프로젝트 소스 어디를 뒤져도 나오지 않습니다.

하는 일은 이름 그대로 중계(트램폴린)입니다. 시작할 때 받은 인텐트에서 목적지 인텐트를 꺼내 그쪽으로 넘기고 자신은 사라집니다. 문제는 그 목적지 정보가 없을 때입니다. 그러면 위 IllegalArgumentException을 던지고, 액티비티 시작 중 발생한 예외라 앱이 그대로 죽습니다.

핵심 — 트램폴린은 두 개다

여기가 제가 8일을 날린 지점입니다. glance-appwidget 1.1.1은 이름이 비슷한 트램폴린 액티비티를 두 개 넣습니다.

저는 처음에 로그에 찍힌 Invisible 쪽만 끄고 배포했습니다. 그리고 8일 뒤, 형제 쪽으로 FATAL 5건이 사용자 4명에게 났습니다. Crashlytics에서는 예외 메시지도 발생 줄 번호도 같아서, 처음에는 수정이 반영이 안 된 줄 알았습니다. 컴포넌트 이름을 대조하고서야 절반만 막혀 있었다는 걸 알았습니다.

해결 — 매니페스트에서 둘 다 끈다

<application> 안에 두 블록을 나란히 넣습니다.

<activity
    android:name="androidx.glance.appwidget.action.InvisibleActionTrampolineActivity"
    android:enabled="false"
    tools:node="merge"
    tools:replace="android:enabled" />

<activity
    android:name="androidx.glance.appwidget.action.ActionTrampolineActivity"
    android:enabled="false"
    tools:node="merge"
    tools:replace="android:enabled" />

<manifest> 태그에 tools 네임스페이스가 없으면 같이 넣어야 합니다.

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

속성 두 개가 왜 필요한가

꺼도 되는 근거 — 정상 클릭은 이 경로를 안 탄다

남의 라이브러리 컴포넌트를 끄는 것이라, 무엇을 잃는지 확인하고 넣어야 합니다. glance-appwidget 1.1.1 기준으로 확인한 내용입니다.

• 트램폴린 인텐트를 심는 applyTrampolineIntent는 getFillInIntentForAction 안에서만 호출됩니다. 이 함수는 Lazy 컬렉션 경로(LazyColumn 등의 항목 클릭)에서 쓰입니다.
• actionRunCallback은 브로드캐스트로 갑니다.
• actionStartActivity는 PendingIntent.getActivity로 갑니다.

즉 위젯에 Lazy 컬렉션이 없다면 일반 버튼과 클릭은 이 액티비티를 거치지 않고, 꺼도 동작이 달라지지 않습니다. 제 위젯 세 개가 그 조건이라 껐고, 끈 뒤 위젯 클릭은 그대로 동작합니다.

막혔는지 확인하는 법

배포 전에 직접 찔러 볼 수 있습니다. 다만 일반 셸에서는 확인이 안 됩니다. 이 액티비티들은 exported="false"라, 셸 사용자(uid 2000)로 실행하면 컴포넌트가 켜져 있든 꺼져 있든 SecurityException이 먼저 뜹니다.

그래서 루팅된 에뮬레이터에서 확인합니다.

adb root
adb shell am start -n com.example.myapp/androidx.glance.appwidget.action.InvisibleActionTrampolineActivity

저는 이 방법으로 수정 전 상태에서 크래시를 한 건 재현한 뒤 블록을 넣었습니다. 재현을 못 해 본 채로 "이걸 끄면 아마 될 것"으로 배포하는 것과는 확신의 크기가 다릅니다. 컴포넌트 이름만 바꿔서 형제 쪽도 같이 확인하세요.

정직하게 남겨 둘 것 — 무엇이 이걸 시작하는지는 모른다

글을 이렇게 끝내고 싶지만, 확인 못 한 부분을 확인한 것처럼 쓰면 다음에 이걸 읽는 사람이 저처럼 헛다리를 짚습니다.

어떤 주체가 이 트램폴린을 목적지 인텐트 없이 시작하는지는 끝내 특정하지 못했습니다. 저는 스토어 업로드마다 도는 자동 검사가 am start로 컴포넌트를 훑는 것이라 짐작했는데, 실기기에서 재 보니 셸은 exported="false"에 막혀 SecurityException을 받습니다. 그 경로가 아니라는 것만 확인된 셈입니다.

그래도 막는 이유는, 정상 동작에서는 어차피 안 불리는 경로라 끄는 쪽의 손해가 없기 때문입니다. 원인 경로를 안다고 가정하고 하나만 껐던 것이 애초의 실수였습니다.

정리

• 스택에 내 코드가 없는 크래시라도 매니페스트 병합 결과물에는 범인이 있을 수 있습니다.
• Glance를 쓰면 InvisibleActionTrampolineActivity와 ActionTrampolineActivity 둘 다 끕니다.
• 끌 때는 tools:node="merge" + tools:replace="android:enabled"를 같이 씁니다.
• 위젯에 Lazy 컬렉션이 없을 때만 안전합니다. 넣게 되면 그때 걷어내세요.

자주 묻는 것

Crashlytics에 안 잡히는데 괜찮은 건가요?

위젯을 쓰는 앱이고 Glance 버전이 같다면 소지는 있습니다. 저는 한 앱에서 사용자 2명이 겪은 걸 보고 같은 구조의 다른 앱에도 선제로 넣었습니다. 지표가 깨끗한 것과 코드가 맞는 것은 다릅니다.

Glance를 올리면 해결되나요?

제가 확인한 건 1.1.1 기준입니다. 상위 버전에서 동작이 바뀌었는지는 검증하지 않았으니, 올린다면 위 adb root 확인을 다시 해 보고 판단하세요.

액티비티를 지우면(tools:node="remove") 안 되나요?

enabled="false"는 선언은 남기고 시작만 막는 쪽이라 라이브러리 다른 코드가 이 컴포넌트를 참조해도 병합이 깨지지 않습니다. 저는 remove는 시도하지 않았습니다.

윈도우에서 클로드 코드(Claude Code)를 쓰다 보면 한글이 세 군데에서 각각 다르게 깨집니다.

// ① 터미널 출력
?????? ??? ???

// ② 파이썬 실행
UnicodeEncodeError: 'cp949' codec can't encode character '✓'

// ③ 만들어 준 PowerShell 스크립트 실행
+ Write-Output "?��?��"
              ~~~~~~
문자열에 종료 기호가 없습니다.

세 증상 모두 AI 도구의 버그가 아닙니다. 윈도우의 기본 문자 인코딩이 UTF-8이 아니라 CP949(euc-kr 계열)이기 때문에 생기는 오래된 문제이고, 도구가 한글을 많이 다루게 되면서 한꺼번에 드러난 것입니다.

깨지는 지점이 셋이므로, 고치는 곳도 셋입니다. 하나만 고치고 "왜 아직도 깨지지"를 반복하는 경우가 대부분입니다.

① 터미널 출력이 ?로 나올 때

콘솔의 코드페이지를 UTF-8(65001)로 바꿉니다. 임시로는 이 한 줄이면 됩니다.

chcp 65001

PowerShell이라면 출력·입력 인코딩까지 함께 지정하는 편이 확실합니다.

# PowerShell 프로필에 넣어두면 매번 적용된다
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
[Console]::InputEncoding  = [System.Text.Encoding]::UTF8
$OutputEncoding = [System.Text.Encoding]::UTF8

프로필 파일 위치는 이렇게 확인하고, 없으면 만들면 됩니다.

echo $PROFILE
# 없으면
New-Item -ItemType File -Path $PROFILE -Force

근본 해결 — 시스템 로캘을 UTF-8로

매번 설정하기 싫다면 윈도우 전체를 UTF-8로 돌릴 수 있습니다.

설정 → 시간 및 언어 → 언어 및 지역 → 시스템 로캘 변경 → "세계 언어 지원을 위한 Beta: 유니코드 UTF-8 사용" 체크 → 재부팅

② UnicodeEncodeError: 'cp949' — 파이썬

파이썬이 print()로 한글이나 특수문자(✓, →, 이모지)를 출력할 때 터집니다. 스크립트 안의 한글은 멀쩡한데 출력하는 순간 죽는 것이 특징입니다.

방법 A — 환경 변수 (가장 간단)

# 현재 세션만
$env:PYTHONIOENCODING = "utf-8"

# 영구 적용
[Environment]::SetEnvironmentVariable(
    "PYTHONIOENCODING", "utf-8", "User")

방법 B — 스크립트 자체가 스스로 해결하게 (권장)

다른 PC나 자동화(작업 스케줄러)에서도 돌아가야 한다면, 환경 변수에 기대지 말고 스크립트 상단에서 표준 출력을 UTF-8로 다시 감싸는 편이 안전합니다.

# -*- coding: utf-8 -*-
import sys, io
sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8")

파일 읽기·쓰기도 마찬가지

# ❌ 윈도우에서는 기본이 cp949 라 깨진다
open("data.txt").read()

# ✅ 항상 명시
open("data.txt", encoding="utf-8").read()
open("out.txt", "w", encoding="utf-8").write(text)

③ 스크립트가 실행조차 안 될 때 — BOM 문제

여기가 가장 안 알려져 있고, 가장 오래 헤매는 지점입니다. AI가 만들어 준 .ps1 파일을 실행했더니 문법 오류가 나고, 열어보면 코드는 멀쩡합니다.

Write-Output "발행 완료"
# → 문자열에 종료 기호가 없습니다.

Windows PowerShell 5.1은 BOM이 없는 파일을 CP949로 읽습니다. UTF-8로 저장된 한글이 CP949로 해석되면서 따옴표 짝이 깨진 것처럼 보이는 것입니다. 코드가 아니라 파일이 저장된 방식이 문제입니다.

# BOM 포함으로 다시 저장
$content = Get-Content .\script.ps1 -Raw -Encoding UTF8
[System.IO.File]::WriteAllText(
    "$PWD\script.ps1", $content,
    [System.Text.UTF8Encoding]::new($true))   # $true = BOM 포함

에디터에서라면 VS Code 오른쪽 아래 인코딩 표시를 눌러 Save with Encoding → UTF-8 with BOM을 고르면 됩니다.

Set-Content로 파일을 만들 때

# ❌ PowerShell 5.1의 Set-Content 기본값은 시스템 ANSI(CP949)
Set-Content out.txt $text

# ✅ 명시
Set-Content out.txt $text -Encoding utf8

AI 도구에 아예 규칙으로 박아두기

매번 "한글 안 깨지게 저장해 줘"라고 말하는 대신, 프로젝트 규칙 파일(CLAUDE.md 등)에 적어두면 계속 적용됩니다. 실제로 효과가 큰 부분입니다.

# 인코딩 규칙 (윈도우 환경)

- 모든 텍스트 파일은 UTF-8 로 저장한다.
- .ps1 파일은 반드시 UTF-8 **BOM 포함** 으로 저장한다.
  (BOM 이 없으면 PowerShell 5.1 이 CP949 로 읽어 파싱이 깨진다)
- 파이썬 스크립트는 상단에 표준 출력 UTF-8 래핑을 넣는다.
- open() 과 Set-Content 에는 인코딩을 항상 명시한다.

터미널에서 한글 입력이 이상할 때

출력이 아니라 입력 쪽 증상도 있습니다. 한글을 치는 도중 글자가 커서와 어긋나게 그려지거나, 문장 중간을 수정하면 조합이 흐트러지는 현상입니다.

이것은 코드페이지가 아니라 터미널의 IME 처리 문제라 설정으로 해결되지 않습니다. 대응은 두 가지입니다.

• 도구를 최신 버전으로 업데이트 — 한국어·중국어·일본어 조합 입력 처리는 개선이 이어지는 영역입니다.
• 긴 한글 프롬프트는 다른 곳에서 작성해 붙여넣기 — 조합 중 렌더링 문제라, 완성된 문자열을 붙여넣으면 영향을 받지 않습니다.

점검 순서

자주 묻는 질문

Q. chcp 65001을 했는데도 깨집니다.

깨지는 지점이 출력이 아니라 파일 저장일 가능성이 큽니다. 그 파일을 VS Code로 열어 오른쪽 아래 인코딩 표시를 확인하세요. CP949로 저장돼 있다면 코드페이지를 아무리 바꿔도 그대로입니다.

Q. 손으로 실행하면 되는데 작업 스케줄러에서만 깨집니다.

실행 계정이 달라 환경 변수가 적용되지 않은 것입니다. 환경 변수 대신 스크립트 자체가 인코딩을 지정하도록 바꾸면 실행 주체와 무관해집니다.

Q. UTF-8 BOM을 넣으면 다른 데서 문제 되지 않나요?

.ps1은 BOM이 있어야 안전하고, 반대로 셸 스크립트(.sh)·JSON·YAML은 BOM이 있으면 안 됩니다. 파일 종류에 따라 다르므로 일괄로 BOM을 붙이지 마세요.

Q. PowerShell 7을 쓰면 해결되나요?

많이 나아집니다. 기본 인코딩이 UTF-8이라 BOM 문제에서 자유롭습니다. 다만 윈도우에 기본 설치된 5.1도 함께 남아 있으므로, 스크립트가 어느 쪽으로 실행되는지는 여전히 확인해야 합니다.

Q. AI가 만든 코드의 한글 주석만 깨집니다.

파일 저장 인코딩 문제입니다. 소스 파일을 UTF-8로 저장하고, 자바 계열이라면 컴파일 옵션에 -encoding UTF-8이 들어가 있는지도 확인하세요.

정리

윈도우에서 한글이 깨질 때 가장 먼저 할 일은 고치는 게 아니라 어디서 깨졌는지 가르는 것입니다. 화면에서 깨진 것인지, 파일에 잘못 저장된 것인지, 파일은 멀쩡한데 읽는 쪽이 잘못 해석한 것인지에 따라 답이 완전히 다릅니다.

그리고 한 번 고쳤으면 규칙으로 남기세요. 인코딩 문제는 잊을 만하면 다른 얼굴로 돌아오고, 그때마다 같은 시간을 다시 씁니다.

최근 정리한 개발 트러블슈팅

• Glance 위젯 트램폴린 크래시 — 액티비티는 두 개다
• no such column: relative_path — minSdk 경계에서 죽는 갤러리
• Compose TextField 한글 자모 분리 — 값의 주인이 누구인가
• No available camera can be found — 전환 실패가 후면까지 끈다
• Unknown permission — 테스트가 minSdk에서 안 돌고 있었다
• GA4 커스텀 측정기준이 전부 (not set) — 숫자 파라미터는 디멘션으로 읽히지 않는다