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

# WorkManager 패턴

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

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

## 💻 코드 패턴

### CoroutineWorker
```kotlin
@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
```kotlin
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
```kotlin
val req = PeriodicWorkRequestBuilder<SyncWorker>(1, TimeUnit.HOURS)
    .setConstraints(networkConstraints)
    .build()
WorkManager.getInstance(context)
    .enqueueUniquePeriodicWork("hourly-sync", ExistingPeriodicWorkPolicy.KEEP, req)
```

### Foreground (긴 작업)
```kotlin
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]]