2nd/10_Wiki/Topics/Coding/Android_WorkManager_Patterns.md

id, title, category, status, source_trust_level, verification_status, created_at, updated_at, tags, tech_stack, applied_in, aliases

id	title	category	status	source_trust_level	verification_status	created_at	updated_at	tags	tech_stack	applied_in	aliases
android-workmanager-patterns	WorkManager — 신뢰성 있는 백그라운드 작업	Coding	draft	B	conceptual	2026-05-09	2026-05-09	android workmanager background vibe-coding	language applicable_to Kotlin / WorkManager 2.9+ Android		periodic work one-time work constraints deferred

WorkManager 패턴

"배터리 / 네트워크 / 충전" 조건 충족 시 OS 가 알아서 실행해주는 영속 작업 큐. process 죽어도 살아남음. 즉각 백그라운드 작업이 아닌 "결국 실행되어야 함" 인 작업에 적합.

📖 핵심 개념

• One-time vs Periodic (최소 15분).
• Constraints: 네트워크 / 충전 / idle / 배터리.
• Backoff: 실패 시 재시도 정책.
• Unique work: 같은 이름의 작업 중복 방지.

💻 코드 패턴

CoroutineWorker

@HiltWorker
class SyncWorker @AssistedInject constructor(
    @Assisted ctx: Context,
    @Assisted params: WorkerParameters,
    private val repo: SyncRepository,
) : CoroutineWorker(ctx, params) {

    override suspend fun doWork(): Result = try {
        val sinceMs = inputData.getLong("since", 0L)
        repo.pullChanges(sinceMs)
        Result.success(workDataOf("count" to 42))
    } catch (e: IOException) {
        if (runAttemptCount < 3) Result.retry() else Result.failure()
    } catch (e: Exception) {
        Result.failure()
    }
}

Enqueue with constraints

val req = OneTimeWorkRequestBuilder<SyncWorker>()
    .setConstraints(Constraints.Builder()
        .setRequiredNetworkType(NetworkType.UNMETERED)
        .setRequiresCharging(true)
        .build())
    .setInputData(workDataOf("since" to lastSyncMs))
    .setBackoffCriteria(BackoffPolicy.EXPONENTIAL, 30, TimeUnit.SECONDS)
    .build()

WorkManager.getInstance(context)
    .enqueueUniqueWork("sync-changes", ExistingWorkPolicy.KEEP, req)

Periodic

val req = PeriodicWorkRequestBuilder<SyncWorker>(1, TimeUnit.HOURS)
    .setConstraints(networkConstraints)
    .build()
WorkManager.getInstance(context)
    .enqueueUniquePeriodicWork("hourly-sync", ExistingPeriodicWorkPolicy.KEEP, req)

Foreground (긴 작업)

override suspend fun doWork(): Result {
    setForeground(createForegroundInfo()) // 알림 표시
    return processLongJob()
}

🤔 의사결정 기준

작업	도구
즉시 1회 (UI 동안)	viewModelScope
화면 닫혀도 계속 (5분 이내)	Service (foreground)
결국 실행돼야 함 (나중 OK)	WorkManager one-time
주기적 (≥15분)	WorkManager periodic
긴 다운로드 + 진행 표시	WorkManager + foreground info
특정 시각 alarm	AlarmManager (정확 시각) — WorkManager 는 시각 보장 X

❌ 안티패턴

• WorkManager 를 즉시 작업에: OS 가 지연 가능. 즉시 = Service 또는 coroutine.
• enqueue 대신 enqueueUnique 안 씀: 같은 작업 중복 큐잉.
• Result.failure() 인데 사용자 모름: 실패 알림 누락. observe + UI 표시.
• input/output Data 가 큼 (>10KB): Bundle 크기 한계. ID 만 전달, 본문은 DB/file.
• doWork 가 너무 오래 (>10분): OS 가 강제 종료. expedited work 또는 foreground.
• Hilt 통합 빠뜨림: 의존성 주입 안 됨. HiltWorker + WorkerFactory 등록.
• periodic 15분 미만: OS 가 무시.

🤖 LLM 활용 힌트

• 상황 분류 → 작업 도구 매트릭스 먼저 그리기.
• HiltWorker 통합 코드 같이.

🔗 관련 문서

• Android_Kotlin_Coroutines_Scopes
• Backpressure_Patterns