Monday, March 5, 2018

안드로이드 RecyclerView IndexOutOfBoundsException: Inconsistency detected 오류 원인과 해결법
  /   No comments   

안드로이드 앱 개발 과정에서 RecyclerView는 거의 필수적으로 사용되는 핵심 컴포넌트입니다. 하지만 유연하고 강력한 만큼, 개발자를 괴롭히는 까다로운 예외 상황도 종종 발생시킵니다. 그 중 가장 악명 높은 오류 중 하나가 바로 java.lang.IndexOutOfBoundsException: Inconsistency detected. Invalid item position X(offset:Y).state:Z 일 것입니다. 이 오류는 많은 개발자들이 한 번쯤은 마주치고, 그 원인을 찾기 위해 많은 시간을 소요하게 만듭니다. 이 오류 메시지는 RecyclerView의 내부 상태와 어댑터(Adapter)가 제공하는 데이터 간에 불일치, 즉 '모순(Inconsistency)'이 발생했음을 의미합니다.

단순히 데이터를 업데이트하고 notifyDataSetChanged()를 호출하지 않아서 발생하는 경우도 있지만, 문제의 근원은 생각보다 깊고 복잡할 수 있습니다. 비동기 처리, 복잡한 데이터 조작, 잘못된 어댑터 업데이트 방식 등 다양한 시나리오에서 이 문제는 발생하며, 때로는 간헐적으로 나타나 디버깅을 더욱 어렵게 만듭니다. 이 글에서는 'Inconsistency detected' 오류가 발생하는 근본적인 원인을 깊이 있게 분석하고, 기본적인 해결 방법부터 DiffUtil과 ListAdapter를 활용한 최신 모범 사례까지, 체계적이고 실용적인 해결책을 종합적으로 제시합니다.

문제의 핵심: RecyclerView의 내부 상태와 데이터의 불일치

이 오류를 이해하기 위해서는 RecyclerView가 어떻게 아이템 뷰를 그리고 관리하는지 알아야 합니다. RecyclerView는 화면에 보이는 아이템만 뷰로 생성하고, 스크롤되어 화면 밖으로 나가는 뷰는 재활용(Recycle)하여 성능을 최적화합니다. 이 과정에서 RecyclerView는 내부적으로 아이템의 위치(position), 상태(state) 등의 정보를 정확하게 추적하고 관리합니다.

이때, 모든 정보의 '기준점' 또는 '진실의 원천(Source of Truth)'은 RecyclerView.Adapter가 가지고 있는 데이터입니다. 예를 들어, getItemCount() 메서드는 어댑터가 관리하는 데이터의 총 개수를 반환하며, RecyclerView는 이 값을 절대적으로 신뢰합니다.

'Inconsistency detected' 오류는 다음과 같은 시나리오에서 발생합니다:

  1. RecyclerView의 LayoutManager가 특정 위치(예: 5번 위치)의 뷰를 화면에 표시하기 위해 어댑터에 요청합니다.
  2. LayoutManager는 어댑터의 getItemCount()가 10이라고 알려주었기 때문에 5번 위치에 아이템이 당연히 있을 것이라고 예상합니다.
  3. 하지만 그 사이, 개발자의 코드 어딘가에서 어댑터가 사용하는 데이터 리스트가 3개의 아이템만 가진 새로운 리스트로 변경되었습니다. (이 변경 사실을 RecyclerView는 아직 모릅니다!)
  4. 어댑터는 5번 위치의 데이터를 실제로 가져오려고 시도하지만, 실제 데이터 리스트의 크기는 3이므로 IndexOutOfBoundsException이 발생합니다.
  5. RecyclerView는 이 예외를 감지하고, "데이터와 뷰의 상태가 일치하지 않는다"는 의미의 'Inconsistency detected'라는 더 구체적인 오류 메시지를 포함하여 앱을 강제 종료시킵니다.

결론적으로 이 오류는 "데이터는 바뀌었는데, 그 사실을 RecyclerView에게 제때, 그리고 올바르게 알려주지 않았을 때" 발생하는 문제입니다. 이제 어떤 상황들이 이런 위험한 불일치를 유발하는지 구체적인 원인들을 살펴보겠습니다.

'Inconsistency Detected' 오류를 유발하는 주요 원인들

1. 백그라운드 스레드에서의 데이터 업데이트 (가장 흔한 원인)

현대 안드로이드 앱에서 네트워크 통신이나 데이터베이스 접근은 필수적입니다. 이러한 작업은 UI 스레드(메인 스레드)를 차단하지 않기 위해 반드시 백그라운드 스레드에서 수행되어야 합니다. 많은 개발자들이 Kotlin Coroutines, RxJava, 또는 전통적인 Thread를 사용하여 비동기 작업을 처리합니다. 문제는 여기서 시작됩니다.

네트워크 요청으로 새로운 데이터 목록을 받아온 뒤, 그 결과를 받은 백그라운드 스레드에서 직접 어댑터의 데이터 리스트를 수정하고 notify...() 메서드를 호출하는 경우가 이 오류의 가장 대표적인 원인입니다. 안드로이드의 UI 툴킷은 스레드에 안전하지 않도록 설계되었습니다. UI 객체(View, RecyclerView, Adapter 등)에 대한 모든 접근은 반드시 UI 스레드에서 이루어져야 합니다.

백그라운드 스레드에서 어댑터 데이터를 변경하는 순간, UI 스레드에서는 RecyclerView가 레이아웃을 계산하거나 애니메이션을 처리하는 중일 수 있습니다. 이 두 작업이 동시에 진행되면 데이터 상태에 대한 경합 상태(Race Condition)가 발생하여 데이터 불일치로 이어지고 결국 크래시가 발생합니다.

잘못된 예시 (Kotlin Coroutines)


// ViewModel 또는 Repository
fun fetchData() {
    viewModelScope.launch(Dispatchers.IO) { // IO 스레드에서 작업 시작
        val newData = api.fetchItems() // 네트워크 호출
        
        // !!! 위험: IO 스레드에서 직접 어댑터 데이터를 변경 !!!
        myAdapter.updateList(newData)
    }
}

// Adapter
fun updateList(newList: List<Item>) {
    this.items.clear()
    this.items.addAll(newList)
    notifyDataSetChanged() // 이 호출도 백그라운드 스레드에서 실행되어 위험하다.
}

위 코드는 Dispatchers.IO 컨텍스트에서 네트워크 작업을 수행한 후, 같은 IO 스레드에서 어댑터의 리스트를 직접 수정하고 있습니다. 이는 'Inconsistency detected' 오류를 유발할 완벽한 조건입니다.

2. 어댑터 데이터 리스트의 잘못된 참조 관리

어댑터가 사용하는 데이터 리스트의 참조(reference)를 올바르게 관리하지 않는 것도 주요 원인 중 하나입니다. 많은 개발자들이 다음과 같이 리스트 객체 자체를 새로운 객체로 교체하는 실수를 합니다.


class MyAdapter(private var items: List<Item>) : RecyclerView.Adapter<MyViewHolder>() {

    fun updateList(newList: List<Item>) {
        // 잘못된 방식: 리스트 객체의 참조를 통째로 교체
        this.items = newList 
        notifyDataSetChanged()
    }
    
    override fun getItemCount(): Int {
        return items.size
    }
    // ...
}

이 방식이 당장은 문제없이 동작하는 것처럼 보일 수 있습니다. 하지만 이 어댑터를 생성할 때 넘겨준 초기 리스트(items)와 updateList를 통해 새로 할당된 리스트(newList)는 완전히 다른 메모리 주소를 가진 객체입니다. 만약 Activity나 Fragment에서 어댑터 외부의 다른 변수가 초기 리스트를 참조하고 있고, 그 변수를 통해 리스트를 수정한다면 어댑터는 그 변경을 전혀 감지하지 못합니다. 이런 구조는 데이터 흐름을 복잡하게 만들고, 예측하지 못한 시점에 데이터 불일치를 일으킬 수 있습니다.

가장 안전한 방법은 어댑터가 내부적으로 관리하는 리스트의 참조는 그대로 유지하면서, 리스트의 내용물만 변경하는 것입니다. 즉, `list.clear()` 와 `list.addAll(newData)`를 사용하는 것이 좋습니다.

3. 부정확하거나 순서가 잘못된 notify...() 호출

성능을 위해 notifyDataSetChanged() 대신 더 세분화된 notifyItemInserted(), notifyItemRemoved() 등을 사용할 때, 데이터 변경과 알림 호출의 순서가 맞지 않으면 오류가 발생할 수 있습니다.

잘못된 순서의 예시


fun removeItem(position: Int) {
    // 실수 1: RecyclerView에 먼저 알리고, 데이터를 나중에 제거
    notifyItemRemoved(position) 
    items.removeAt(position) // 이 시점에는 이미 레이아웃이 갱신되려 할 수 있다.

    // 실수 2: 제거된 아이템 개수를 고려하지 않고 다른 알림 호출
    // 만약 position 이후의 아이템이 변경되었다면,
    // items.size가 줄었기 때문에 notifyItemChanged(position)은 올바른 아이템을 가리키지 못할 수 있다.
    if (items.isNotEmpty()) {
        notifyItemChanged(position) // 잘못된 위치를 가리킬 위험이 매우 높음
    }
}

규칙은 간단합니다: 항상 데이터를 먼저 변경하고, 그 후에 변경된 내용에 맞춰 notify...()를 호출해야 합니다. 데이터 리스트는 '진실'이고, `notify` 호출은 그 진실의 변경 사항을 RecyclerView에게 전달하는 '메신저' 역할을 합니다. 진실이 바뀌기도 전에 메신저가 출발해서는 안 됩니다.

4. 복잡한 UI 연산 (필터링, 정렬 등)

사용자 입력에 따라 실시간으로 목록을 필터링하거나 정렬하는 기능은 오류가 발생하기 쉬운 또 다른 지점입니다. 예를 들어, 사용자가 검색어 'A'를 입력했을 때 필터링이 시작되고, 결과가 적용되기 전에 사용자가 빠르게 'B'를 추가로 입력하는 경우를 생각해 봅시다. 두 개의 필터링 작업이 거의 동시에 실행되면서 어떤 결과가 먼저 어댑터에 적용될지 예측하기 어려워지며, 이는 경합 상태로 이어져 데이터 불일치를 일으킬 수 있습니다.

오류 해결 전략: 기본부터 최적화까지

이제 원인을 파악했으니, 단계별 해결책을 알아보겠습니다. 가장 간단한 방법부터 가장 권장되는 최신 방법까지 순서대로 설명합니다.

Level 1: 기본적이고 안전한 데이터 업데이트 (UI 스레드 + 안정적인 참조)

가장 먼저 지켜야 할 원칙입니다. 어떤 데이터 업데이트 로직을 사용하든 다음 두 가지는 반드시 지켜야 합니다.

  1. 모든 어댑터 관련 작업은 UI 스레드에서 수행하세요.
  2. 어댑터의 데이터 리스트 참조를 유지하며 내용만 수정하세요.

올바른 예시 (Kotlin Coroutines)

앞서 본 잘못된 예시를 올바르게 수정한 코드입니다.


// ViewModel 또는 Repository
fun fetchData() {
    viewModelScope.launch { // 기본적으로 Main 스레드에서 시작 (설정에 따라 다를 수 있음)
        val newData = withContext(Dispatchers.IO) { // 네트워크 작업만 IO 스레드로 전환
            api.fetchItems() 
        }
        // withContext 블록이 끝나면 다시 원래의 Main 스레드로 돌아옴
        myAdapter.updateList(newData) // 안전하게 Main 스레드에서 호출
    }
}

// Adapter
// 생성자에서 mutable list를 받아 내부에서만 사용하도록 캡슐화하는 것이 좋음
class MyAdapter : RecyclerView.Adapter<MyViewHolder>() {
    private val items = mutableListOf<Item>()

    fun updateList(newList: List<Item>) {
        // 1. 기존 리스트의 내용물을 지우고
        items.clear()
        // 2. 새로운 내용물을 추가 (참조는 그대로 유지됨)
        items.addAll(newList)
        // 3. UI 스레드에서 변경 사항을 알림
        notifyDataSetChanged()
    }
    
    override fun getItemCount(): Int {
        return items.size
    }
    // ...
}

이 코드는 withContext(Dispatchers.IO)를 사용해 네트워크 호출만 백그라운드에서 처리하고, 결과를 받아 어댑터를 업데이트하는 작업은 다시 UI 스레드(launch의 원래 컨텍스트)로 돌아와 안전하게 수행합니다. 또한 어댑터 내부에서 items.clear()와 items.addAll()을 사용하여 안정적으로 데이터를 교체합니다.

Level 2: 성능을 고려한 세분화된 notify...() 사용

notifyDataSetChanged()는 매우 편리하지만, 심각한 성능 문제를 야기할 수 있습니다. 이 메서드는 RecyclerView에게 "모든 것이 바뀌었으니, 처음부터 끝까지 모든 뷰를 다시 그리고 레이아웃을 계산하라"고 명령합니다. 이는 아이템 개수가 많을 때 버벅임을 유발하고, 깜빡임 현상(blinking)을 일으키며, 아이템 추가/삭제 시 부드러운 애니메이션 효과를 모두 무시합니다.

더 나은 방법은 변경된 부분만 정확히 알려주는 것입니다.

세분화된 알림 예시


// Adapter 내부에 아래와 같은 메서드를 구현
fun addItem(item: Item) {
    items.add(0, item) // 리스트의 맨 앞에 아이템 추가
    notifyItemInserted(0) // 0번 위치에 아이템이 삽입되었음을 알림
}

fun removeItem(position: Int) {
    if (position >= 0 && position < items.size) {
        items.removeAt(position) // 해당 위치의 아이템 제거
        notifyItemRemoved(position) // 해당 위치의 아이템이 제거되었음을 알림
    }
}

fun updateItem(position: Int, updatedItem: Item) {
    if (position >= 0 && position < items.size) {
        items[position] = updatedItem // 해당 위치의 아이템 교체
        notifyItemChanged(position) // 해당 위치의 아이템 내용이 변경되었음을 알림
    }
}

이 방식은 RecyclerView가 최소한의 작업만 하도록 유도하여 성능을 크게 향상시키고, 자연스러운 기본 애니메이션(Cross-fade, Slide 등)을 활성화합니다. 하지만 개발자가 직접 이전 리스트와 새 리스트를 비교하여 어떤 아이템이 추가/삭제/변경되었는지 계산하는 로직을 구현해야 하는 부담이 있습니다.

Level 3: 궁극의 솔루션, DiffUtil과 ListAdapter

이전 리스트와 새 리스트의 차이점을 계산하는 복잡한 작업을 개발자 대신 자동으로, 그것도 효율적으로 처리해주는 강력한 도구가 바로 DiffUtil입니다. 그리고 DiffUtil의 사용을 극도로 단순화하고 모범 사례를 강제하는 것이 ListAdapter입니다.

새로운 프로젝트를 시작하거나 기존 코드를 리팩토링한다면, RecyclerView와 함께 ListAdapter를 사용하는 것을 강력히 권장합니다.

DiffUtil의 작동 원리

DiffUtil은 유진 마이어스(Eugene Myers)의 차분(difference) 알고리즘을 기반으로 두 리스트 간의 차이점을 계산합니다. 이를 통해 다음과 같은 최소한의 업데이트 목록을 생성합니다.

  • 어떤 아이템이 추가되었는가? (→ notifyItemInserted)
  • 어떤 아이템이 삭제되었는가? (→ notifyItemRemoved)
  • 어떤 아이템의 위치가 바뀌었는가? (→ notifyItemMoved)
  • 어떤 아이템의 내용이 바뀌었는가? (→ notifyItemChanged)

ListAdapter 구현하기

ListAdapter를 사용하면 이 모든 과정이 거의 자동으로 처리됩니다.

1. ItemCallback 구현
먼저 DiffUtil.ItemCallback을 구현하여 두 아이템이 동일한 객체인지(areItemsTheSame), 그리고 내용까지 동일한지(areContentsTheSame)를 판단하는 로직을 정의해야 합니다.


// data class를 사용하면 equals()가 자동으로 구현되어 편리하다.
data class User(val id: Long, val name: String, val profileImageUrl: String)

class UserDiffCallback : DiffUtil.ItemCallback<User>() {
    // 두 아이템이 동일한 항목을 나타내는지 확인 (보통 고유 ID로 비교)
    // 이 메서드가 true를 반환해야 areContentsTheSame이 호출됨
    override fun areItemsTheSame(oldItem: User, newItem: User): Boolean {
        return oldItem.id == newItem.id
    }

    // 두 아이템의 데이터 내용이 같은지 확인
    // areItemsTheSame이 true일 때만 호출됨
    // 내용이 다르면 RecyclerView가 아이템 뷰를 갱신 (애니메이션 적용)
    override fun areContentsTheSame(oldItem: User, newItem: User): Boolean {
        // data class는 자동으로 equals를 구현해주므로 간단하게 비교 가능
        return oldItem == newItem 
    }
}

areItemsTheSame은 아이템의 고유성을, areContentsTheSame은 내용의 동일성을 비교합니다. 예를 들어, 사용자의 이름만 바뀌었다면 `id`는 같으므로 areItemsTheSame은 true, `name`이 다르므로 areContentsTheSame은 false를 반환하게 됩니다. 그 결과 RecyclerView는 뷰를 새로 만드는 대신 해당 아이템에 대해 변경 애니메이션(cross-fade)만 적용합니다.

2. ListAdapter 상속 및 사용
이제 RecyclerView.Adapter 대신 ListAdapter를 상속받고, 생성자에 위에서 만든 ItemCallback을 전달합니다.


// 생성자에 DiffUtil.ItemCallback을 전달
class UserAdapter : ListAdapter<User, UserViewHolder>(UserDiffCallback()) {

    override fun onCreateViewHolder(parent: ViewGroup, viewType: Int): UserViewHolder {
        // ViewHolder 생성 로직...
    }

    override fun onBindViewHolder(holder: UserViewHolder, position: Int) {
        // getItem() 메서드를 사용하여 특정 위치의 아이템에 접근
        val user = getItem(position)
        holder.bind(user)
    }
    
    // ListAdapter는 자체적으로 리스트를 관리하므로,
    // 데이터 리스트 필드를 직접 가질 필요가 없고 getItemCount()도 오버라이드할 필요가 없다!
}

3. 데이터 업데이트
마지막으로, Activity나 Fragment에서 새로운 리스트를 어댑터에 전달할 때는 submitList() 메서드를 사용합니다. 이 메서드가 ListAdapter의 핵심입니다.


// ViewModel
val userListLiveData = MutableLiveData<List<User>>()

fun fetchUsers() {
    viewModelScope.launch {
        val newUsers = withContext(Dispatchers.IO) { api.fetchUsers() }
        userListLiveData.value = newUsers
    }
}

// Fragment 또는 Activity
override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
    super.onViewCreated(view, savedInstanceState)
    
    val userAdapter = UserAdapter()
    recyclerView.adapter = userAdapter
    
    viewModel.userListLiveData.observe(viewLifecycleOwner) { userList ->
        // 새로운 리스트를 submitList에 전달하면 끝!
        // 내부적으로 DiffUtil이 비동기적으로 차이를 계산하고 UI를 업데이트한다.
        userAdapter.submitList(userList)
    }
}

submitList()는 놀라운 일들을 자동으로 처리합니다:

  • 내부적으로 백그라운드 스레드에서 DiffUtil을 실행하여 리스트 간의 차이를 계산합니다.
  • 계산이 완료되면 그 결과를 UI 스레드로 전달합니다.
  • 계산된 차이점(diff)을 기반으로 필요한 notify...() 메서드들을 정확하게 호출하여 RecyclerView를 최소한으로, 그리고 효율적으로 업데이트합니다.

결과적으로 개발자는 복잡한 스레드 관리나 수동적인 diff 계산 없이, 그저 submitList()에 새 리스트를 전달하기만 하면 됩니다. 'Inconsistency detected' 오류를 근본적으로 방지하고, 최적의 성능과 부드러운 UI를 모두 얻을 수 있는 가장 확실하고 현대적인 방법입니다.

결론: 안정적인 RecyclerView를 위한 최종 체크리스트

RecyclerView의 'Inconsistency detected' 오류는 당황스럽지만, 그 원인은 명확합니다: 데이터의 상태와 뷰의 상태 간의 불일치. 이 문제를 해결하고 안정적인 앱을 만들기 위해 다음 사항들을 항상 기억하세요.

  1. UI 스레드 원칙 준수: 어댑터의 데이터를 변경하거나 notify...()를 호출하는 모든 작업은 반드시 UI 스레드에서 수행해야 합니다. Coroutines의 withContext나 view.post 등을 적극 활용하세요.
  2. 안정적인 데이터 관리: 어댑터가 내부적으로 관리하는 리스트의 참조를 바꾸기보다, 내용물만 clear()와 addAll()로 교체하는 방식을 사용하세요.
  3. ListAdapter를 최우선으로 고려: 새로운 기능을 개발한다면 주저 없이 ListAdapter를 채택하세요. 스레드 문제, 복잡한 diff 계산, 성능 최적화를 한 번에 해결해주는 가장 강력한 솔루션입니다.
  4. 정확한 Notify: ListAdapter를 사용하지 않는 레거시 코드라면, 데이터 변경 후 반드시 해당 변경사항에 맞는 세분화된 notify...() 메서드를 정확하게 호출하여 성능을 확보하세요. notifyDataSetChanged()는 최후의 수단으로만 사용해야 합니다.

이 가이드에서 제시된 원인 분석과 단계별 해결책을 통해, 더 이상 'Inconsistency detected' 오류에 시달리지 않고 견고하고 부드러운 RecyclerView 구현에 자신감을 가지시길 바랍니다.


0 개의 댓글:

Post a Comment