멀티스레드 + 큐 + dataclass 리팩토링 삽질기~

🧩 배경

오늘 드디어 리팩토링 할 수 있는 틈새시간이 주어진 날!!

최근 코드 리팩토링 과정에서 반복되는 로직(주석으로 미리 표시해놨지롱)을 정리하고 사용하고 있는 멀티스레딩으로 문서 적재를 병렬 처리하는 구조를 좀 다듬으려고 했다

 

우선 내 삽질 기록 전에 내가 하고 있는 과업에 대해 간단히 설명

1. 문서(html)를 청크(seq)로 쪼개서 적재하기 때문에, response는 문서 단위로 성공/실패/미분류된 문서 청킹 아이디 를 모아주어야 한다.

1-1. 단순히 스레드가 몇 개 성공했는지가 중요한 게 아니라: 

A문서는 총 3개의 청크중 1개 성공, 2개 실패
B문서는 총 15개의 청크중 15개 성공, 0개 실패

이렇게 문서 청크 단위로 상태를 집계해야 나중에 통계/로직강화 등에 쓰일 수 있다!

 

2. 여기서, 스레드별로 처리되는 문서에 대한 성공/실패/미분류된 문서 청킹 아이디를 따로 모아야 했고, 이를 다시 한번 합쳐서 API response 포맷에 맞춰 반환해야 했다.

3. 내가 원하는 포맷은 이거:

{
  "docLoadResult": {
    "processResults": [
      {
        "docId": "DOC123",
        "successList": ["DOC123_1"],
        "failureList": ["DOC123_2"],
        "unknownList": [],
        "docListCnt": 2
      },
      {
        "docId": "DOC456",
        "successList": ["DOC456_1"],
        "failureList": [],
        "unknownList": ["DOC456_2", "DOC456_3"],
        "docListCnt": 3
      }
    ]
  }
}

 

 

💭 고민의 내용

처음에는 단순 리스트 묶음으로 관리했는데 점점 코드가 지저분해져서 dataclass를 도입해 구조화하기로 했다.

요렇게:

from dataclasses import dataclass, field

@dataclass
class ResultDoc:
    docSuccessList: list = field(default_factory=list)
    docFailureList: list = field(default_factory=list)
    docUnknownList: list = field(default_factory=list)
    docListCnt: int = 0

 

1. 각 스레드는 ResultDoc 객체를 채운다

2. queue.put(resultDoc)로 결과를 push 해준다

3. 모든 스레드가 끝난 뒤, queue.get()으로 푸쉬해놓은 결과들을 모아 최종 response를 만들어 최종 return!

 

 

그러나

문제는 결과 집계를 다루는 과정에서 발생했다:

• 스레드별로 ResultDoc 객체를 만들어 큐에 넣었는데 successList에 값이 안 들어감 💢(맹새코 분명 디버깅했을 땐 잘 갖고 왔던 값들이었다 ㅜㅜ)
• count값(각문서별 문서 청크 데이터 카운트)은 잘 찍히는데 왜 리스트는 비어있는 거지? 대체 어디서 데이터가 날아간 건지,,
• 특히 디버깅 모드에선 리스트 안 값이 보이는데!!! 왜 response로 만들어 내보내면 하염없이 []만 나오는 것이냐 대체 왜..

이 과정에서 나는

'멀티 스레딩이라 값이 꼬였나?'

'전역변수 문제인가?' (괜히 의심)

같은 불안감이 커졌고 원인을 한참 못 잡으니 너무너무 답답했다.

 

 

🛠️ 해결을 위한 시도들

오늘 하루 종일 구글과 GPT를 옆구리에 끼고 살았다.

 

1. deepcopy 적용

찾아보니, mutable 객체(list) 참조 문제 일 수 있다고 하더라.

queue.put(copy.deepcopy(resultDoc)) 을 했다

 

2. dataclass 기본값 확인

혹시 모르니 dataclass 기본값을 field(default_factory=list) 로 해주었는지 다시 확인했다(list = []과 같은 코드를 썼을까 봐)

 

3. 큐에 값을 넣기 직전/직후 디버깅

큐에 넣기 직전 값 → 큐에서 꺼낸 직후 값 → response에 append 직후 값을 더듬더듬 읽었다. 근데 값을 잘 들고 나왔는데..

 

4. 여러 가설 세우기: 멀티스레드 race condition, 전역 공유 문제?

 

근데 문제는 전혀 다른 곳에 있었다.

 

 

바로 오타 😂 😂 😂 .

ㅋㅋㅋㅋㅋㅋㅋㅋㅋㅋㅋㅋㅋㅋㅋㅋㅋㅋㅋㅋㅋㅋㅋㅋ

쓰고도 어이없다.

 

그 문제의 코드 정확히 가져오겠다:

final_result.append({
    "successList": list(r.docSuccessList),
    "failureList": list(r.docFailureList),
    "successList": list(r.docUnknownList),  # <- 잘못된 키 중복
    "docListCnt": r.docListCnt
})

바로보이나요..?

전 안 보여서 반나절을 날렸습니다,,ㅋㅋㅋ

 

dict 생성 코드에 같은 key를 두 번 썼고 결국 successList에 unkownList 값이 담긴 것이다.

그러니 원하는 값이 들어가지 않았던 것.

문제의 본질은 멀티스레드도, 큐도, dataclass도 아니었다.

결국 오타 문제였다.

 

 

📈 변화

1. 가장 큰 변화는 이번 경험으로 인해 “가장 단순한 원인부터 확인하라”는 교훈을 얻은 것이 되겠다.

2. 오타 수정해서 원하는 API 응답 형태를 만들었다

 

 

📌 회고 & 다음 목표

• 복잡한 문제를 의심하기 전에 단순한 실수를 먼저 체크하자
• 이번 경우는 멀티스레딩, 큐 자체의 문제와는 무관했는데.. 괜히 깊은 곳만 파다가 시간을 날린것이니.. 그래도 이게 나한테 도움이 될 거라 믿는다. 저런 날도 있으면 이런 날도 있는 거지
• 그렇게 되면 dataclass + queue + 멀티스레딩 구조 자체는 꽤 깔끔하게 맞았다는 거겠지? 앞으로 스레드 처리할 때 큰 도움이 되겠다..
• 다음에는 이런 경험을 바탕으로, 로깅/테스트 코드를 강화해 “단순한 실수”가 이렇게 큰 삽질로 이어지지 않게 하고 싶다.