WorkManager unique work는 같은 이름의 백그라운드 작업이 중복으로 쌓이지 않게 제어하는 방식입니다. 여기서 KEEP, REPLACE, APPEND는 단순 옵션이 아니라 앱의 데이터 동기화 정책을 결정합니다.
핵심은 이미 같은 이름의 작업이 대기 중일 때 새 요청을 어떻게 처리할 것인가입니다. 같은 업로드, 같은 동기화, 같은 로그 전송을 여러 번 예약할 수 있다면 unique work 정책을 먼저 봐야 합니다.
WorkManager unique work가 필요한 상황
사용자가 화면을 여러 번 열거나, 네트워크가 끊겼다가 다시 연결되거나, 앱 시작 시마다 동기화를 예약하면 같은 작업이 반복해서 쌓일 수 있습니다. 단순히 WorkRequest를 매번 enqueue하면 앱은 의도보다 많은 백그라운드 작업을 실행할 수 있습니다.
- 프로필 동기화를 앱 시작 때마다 예약한다
- 오프라인 작성 글 업로드를 저장 버튼마다 예약한다
- 서버 로그 전송 작업이 짧은 시간에 여러 번 들어온다
- 재시도 중인 작업이 있는데 사용자가 같은 동작을 다시 누른다
KEEP은 언제 맞을까
KEEP은 같은 unique name의 pending work가 있으면 새 작업을 넣지 않습니다. 이미 예약된 작업이 최신 요청을 대표할 수 있을 때 적합합니다.
예를 들어 전체 사용자 설정 동기화처럼 ‘한 번만 실행되면 충분한 작업’은 KEEP이 자연스럽습니다. 사용자가 설정 화면을 여러 번 열었다고 해서 같은 sync를 여러 번 쌓을 필요는 없습니다.
WorkManager.getInstance(context).enqueueUniqueWork(
"sync-user-settings",
ExistingWorkPolicy.KEEP,
syncRequest
)REPLACE는 언제 맞을까
REPLACE는 기존 pending work를 취소하고 새 작업으로 바꿉니다. 새 요청이 이전 요청보다 더 정확하거나 최신 상태를 담고 있을 때 씁니다.
검색 인덱스 재생성, 임시 파일 정리, 마지막 상태 기준 업로드처럼 ‘이전 작업보다 최신 작업이 중요하다’면 REPLACE가 더 안전합니다.
WorkManager.getInstance(context).enqueueUniqueWork(
"refresh-feed-cache",
ExistingWorkPolicy.REPLACE,
refreshRequest
)APPEND는 언제 맞을까
APPEND는 기존 unique work 체인의 끝에 새 작업을 붙입니다. 순서가 의미 있고, 앞 작업이 끝난 뒤 다음 작업을 이어야 할 때 선택합니다.
다만 앞 작업이 실패하거나 취소되면 뒤에 붙은 작업도 영향을 받을 수 있습니다. 그래서 APPEND는 로그 전송처럼 무조건 쌓는 용도보다, 순서 있는 작업 체인을 의도할 때 더 신중하게 써야 합니다.
정책 선택 기준
- 같은 작업이 이미 있으면 새 요청을 버려도 된다: KEEP
- 새 요청이 이전 요청을 대체해야 한다: REPLACE
- 작업 순서가 중요해서 뒤에 이어야 한다: APPEND
- 서로 독립적인 작업이면 unique name을 분리한다
- 사용자별, 파일별, 계정별로 unique name 범위를 다르게 잡는다
실무에서 자주 생기는 실수
가장 흔한 실수는 unique name을 너무 넓게 잡는 것입니다. 예를 들어 모든 업로드를 upload라는 하나의 이름으로 묶으면 서로 다른 파일 업로드가 의도치 않게 취소되거나 무시될 수 있습니다.
// 파일별로 독립적인 업로드가 필요하다면 이름도 분리한다.
val uniqueName = "upload-file-$fileId"
WorkManager.getInstance(context).enqueueUniqueWork(
uniqueName,
ExistingWorkPolicy.REPLACE,
uploadRequest
)정리
WorkManager unique work는 중복 실행을 막는 기능이지만, 실제로는 백그라운드 작업의 의미를 정하는 설계 도구입니다. KEEP은 기존 작업 유지, REPLACE는 최신 요청 우선, APPEND는 순서 있는 체인에 맞습니다.
공식 정의는 Android ExistingWorkPolicy 문서에서 확인할 수 있습니다. 앱 구조 관점은 Offline-first Android 앱 구조 글과 함께 보면 연결이 좋습니다.
