📚 Android Paging3 + Jetpack Compose: LoadState 처리 공통화하기

🚀 Paging 이란???

Android 앱 개발을 하다 보면
서버로부터 한 번에 모든 데이터를 가져오기 어려운 경우가 많습니다.

이럴 때 사용하는 대표적인 기술이 바로
👉 Paging 입니다.

---

📦 Paging3 + Jetpack Compose

특히 Paging3 + Jetpack Compose 조합은
방대한 데이터를 리스트 형태로 자연스럽게, 끊김 없이 보여줄 수 있어
실무에서 널리 활용됩니다.

---

🎨 UX는 왜 중요할까?

저는 개발하면서 사용자 경험(UX)을 무엇보다 중요하게 생각합니다.

데이터가 로드되는 동안 화면이 텅 비어 있으면,
사용자는 불안하게 생각합니다.
"앱이 멈춘 건가?" 하는 의문을 갖게 되죠.

---

✨ Skeleton Loading 도입

그래서 저는 로딩 상태에서 단순 스피너 대신
👉 Skeleton Loading(스켈레톤 로딩)을 적용합니다.

💡 스켈레톤 로딩은 실제 콘텐츠의 레이아웃을 회색 블록 등으로 미리 그려 보여주어
사용자가 "곧 데이터가 나타나겠구나" 라는 심리적 안정감을 느낄 수 있게 하는 방식입니다.

---

🌀 Paging3의 LoadState란?

LazyPagingItems를 쓰면 데이터 로딩 상태를 알 수 있는 loadState가 제공됩니다.

• refresh → 초기 로딩 / 새로고침
• append → 리스트 하단 추가 로딩

각각 Loading, Error, NotLoading 상태를 가집니다.

즉, 우리가 해야 할 일은 간단합니다:

• ⏳ Loading → 스켈레톤 or 로딩 UI 보여주기
• ❌ Error → 에러 UI + 재시도 버튼

---

❌ LoadState 직접 처리(공통화 전)

Paging3를 Compose에서 사용할 때 가장 흔한 패턴은
각 화면에서 loadState를 직접 분기 처리하는 방식입니다.

LazyColumn(
    modifier = Modifier
        .fillMaxSize()
        .padding(top = 8.dp),
    state = scrollState,
    verticalArrangement = Arrangement.spacedBy(12.dp)
) {
    items(
        key = bookListPagingItems.itemKey { it.isbn },
        count = bookListPagingItems.itemCount
    ) { index ->
        /**
         * PagingItem에 대한 Composable
         */
    }

    val loadState = bookListPagingItems.loadState

    when {
        loadState.refresh is LoadState.Loading -> {
            item {
                /**
                 * 새로고침 상태(초기 로딩) 로딩 UI (예: Skeleton)
                 */
            }
        }

        loadState.refresh is LoadState.Error -> {
            val error = loadState.refresh as LoadState.Error
            item {
                /**
                 * 새로고침 상태 에러 UI (error를 받아 재시도 제공)
                 */
            }
        }

        loadState.append is LoadState.Loading -> {
            item {
                /**
                 * 추가 로딩 상태 로딩 UI (예: 하단 Progress)
                 */
            }
        }

        loadState.append is LoadState.Error -> {
            val error = loadState.append as LoadState.Error
            item {
                /**
                 * 추가 로딩 상태 에러 UI (error를 받아 재시도 제공)
                 */
            }
        }
    }
}

⚠️ 문제점

• 중복 코드: 화면마다 동일한 when(loadState) 블록을 작성해야 함
• 유지보수 비용 증가: 로딩/에러 UI가 바뀌면 모든 화면을 수정해야 함
• UX 불일관성: 화면별로 구현이 조금씩 달라지면서 사용자 경험에 차이가 생길 수 있음
• 가독성 저하: 리스트 아이템 로직과 로딩/에러 처리가 뒤섞여 코드가 복잡해짐

---

✅ LoadState 공통화: pagingLoadStateHandler

앞에서 본 것처럼 LoadState를 직접 처리하면
중복 코드, 유지보수 비용, UX 불일관성 등 여러 문제가 발생합니다.

저는 이를 해결하기 위해 LazyListScope에 확장 함수를 만들어
LoadState 처리를 공통화했습니다.

/**
 * 페이징 상태에 따른 UI 처리를 위한 LazyListScope 확장 함수.
 *
 * @param pagingItems LazyPagingItems 인스턴스.
 * @param loadStateRefreshLoading 새로고침 상태(초기 로딩)에서 로딩 UI를 표시하는 컴포저블.
 * @param loadStateRefreshError 새로고침 상태에서 에러 UI를 표시하는 컴포저블. LoadState.Error 객체를 파라미터로 받음.
 * @param loadStateAppendLoading 추가 로딩 상태에서 로딩 UI를 표시하는 컴포저블.
 * @param loadStateAppendError 추가 로딩 상태에서 에러 UI를 표시하는 컴포저블. LoadState.Error 객체를 파라미터로 받음.
 */
fun LazyListScope.pagingLoadStateHandler(
    pagingItems: LazyPagingItems<*>,
    loadStateRefreshLoading: @Composable LazyItemScope.() -> Unit = {},
    loadStateRefreshError: @Composable LazyItemScope.(LoadState.Error) -> Unit = {},
    loadStateAppendLoading: @Composable LazyItemScope.() -> Unit = {},
    loadStateAppendError: @Composable LazyItemScope.(LoadState.Error) -> Unit = {}
) {
    val loadState = pagingItems.loadState

    when {
        loadState.refresh is LoadState.Loading -> {
            item {
                loadStateRefreshLoading()
            }
        }

        loadState.refresh is LoadState.Error -> {
            val error = loadState.refresh as LoadState.Error
            item {
                loadStateRefreshError(error)
            }
        }

        loadState.append is LoadState.Loading -> {
            item {
                loadStateAppendLoading()
            }
        }

        loadState.append is LoadState.Error -> {
            val error = loadState.append as LoadState.Error
            item {
                loadStateAppendError(error)
            }
        }
    }
}

📄 실제 적용 예제

이제 화면에서는 이렇게 단 한 줄만 추가하면 됩니다 👇

LazyColumn(
    modifier = Modifier
        .fillMaxSize()
        .padding(top = 8.dp),
    state = scrollState,
    verticalArrangement = Arrangement.spacedBy(12.dp)
) {
    items(
        key = bookListPagingItems.itemKey { it.isbn },
        count = bookListPagingItems.itemCount
    ) { index ->
        bookListPagingItems[index]?.let { book ->
            BookContent(bookModel = book)
        }
    }

    // ✅ LoadState 공통 처리
    pagingLoadStateHandler(
        pagingItems = bookListPagingItems,
        loadStateRefreshLoading = { SkeletonBookLoading() }, // 초기 로딩 → Skeleton UI
        loadStateRefreshError = { e -> LoadStateRefreshError(error = e) { onRetry() } },
        loadStateAppendLoading = { LoadStateAppendLoading() }, // 하단 추가 로딩 → Progress
        loadStateAppendError = { e -> LoadStateAppendError(error = e) { onRetry() } },
    )
}

---

🤔 써보니 아쉬운 점

이 방식(pagingLoadStateHandler 직접 호출)은 분명 편리해졌지만,
실제로 여러 화면에 적용하다 보니 조금 아쉬운 점이 있었습니다.

• 매번 loadStateRefreshLoading, loadStateRefreshError,
  loadStateAppendLoading, loadStateAppendError를 모두 넘겨줘야 함
• 사실 화면 입장에서 중요한 건 retry 이벤트만 넘겨주면 되는 경우가 대부분
• 로딩/에러 UI는 프로젝트 전역에서 동일하게 쓰는 패턴이 많음

즉, Loading UI는 로딩시에 항상 노출되어야하고 실제 화면에서는 받는 이벤트는 재시도 이벤트 뿐인데
불필요하게 코드가 길어지는 느낌이 있었습니다.

---

🔧 한 단계 더 단순화: handlePagingLoadState

그래서 저는 프로젝트에 맞게 한 단계 더 래핑한 함수를 만들었습니다.
이 함수 안에서 로딩/에러 UI를 고정해두고,
화면에서는 onRetry 하나만 넘겨주면 됩니다.

LazyColumn(
    modifier = Modifier
        .fillMaxSize()
        .padding(top = 8.dp),
    state = scrollState,
    verticalArrangement = Arrangement.spacedBy(12.dp)
) {
    items(
        key = bookListPagingItems.itemKey { it.isbn },
        count = bookListPagingItems.itemCount
    ) { index ->
        /**
         * PagingItem에 대한 Composable
         */
    }

    // ✅ LoadState 공통 처리 (onRetry만 넘겨주면 됨)
    handlePagingLoadState(
        bookListPagingItems = bookListPagingItems,
        onRetry = onRetry
    )
}

🔨 그리고 래퍼 함수는 이렇게 정의했습니다:

private fun LazyListScope.handlePagingLoadState(
    bookListPagingItems: LazyPagingItems<BookModel>,
    onRetry: () -> Unit,
) {
    pagingLoadStateHandler(
        pagingItems = bookListPagingItems,
        loadStateRefreshLoading = {
            LoadStateRefreshLoading()
        },
        loadStateRefreshError = { error ->
            LoadStateRefreshError(
                error = error,
                onClickRetry = onRetry
            )
        },
        loadStateAppendLoading = {
            LoadStateAppendLoading()
        },
        loadStateAppendError = { error ->
            LoadStateAppendError(
                error = error,
                onClickRetry = onRetry
            )
        },
    )
}

---

📊 비교: 세 가지 접근 방식

구분	LoadState 직접 처리	pagingLoadStateHandler (공통화)	handlePagingLoadState (단순화)
코드 길이	화면마다 길고 중복	한 줄로 줄어듦, 하지만 인자 많음	onRetry 하나만 넘기면 끝
유지보수	UI 바뀌면 모든 화면 수정	유틸 함수만 수정하면 전체 반영	래퍼 함수만 수정하면 전체 반영
UX 일관성	화면별로 다르게 구현될 수 있음	공통 처리로 어느 정도 보장	전역 UI 고정 → 완전 통일
가독성	리스트와 상태처리 뒤섞임	코드 분리가 되어 개선	가장 간결하고 깔끔

---

🎯 결론

• Paging3의 LoadState 처리는 반복적이고 실수하기 쉬운 작업입니다.
• pagingLoadStateHandler를 만들면 중복 제거 + 일관성을 얻을 수 있습니다.
• 더 나아가 handlePagingLoadState 같은 프로젝트 맞춤 래퍼로 단순화하면,
  화면에서는 onRetry만 넘기면 되므로 코드가 가장 깔끔해집니다.

👉 특히 저는 UX를 중요시하기 때문에 Skeleton Loading을 기본으로 적용해,
사용자에게 "앱이 멈춘 게 아니라 데이터를 불러오는 중이구나" 하는 안정감을 주도록 했습니다.

---

💬 여러분은 Paging3의 로딩 상태를 어떻게 처리하고 계신가요?

• 단순 스피너?
• Skeleton Loading?
• 아니면 저처럼 유틸을 만들어 공통화?

댓글로 공유해주시면 좋겠습니다 🚀