GitHub API 뜯어내기: 로컬 퍼스트 아키텍처 결정

사고 현장

개인 포털 v1에는 아주 “긱스러운” 설계가 있었습니다. 빌드 시점에 GitHub API에 요청해 사용자의 저장소와 스타 수를 페이지에 자동 동기화하는 것. 데이터는 항상 신선하고 수동 관리는 제로.

그러던 어느 날 api.github.com/users/min09577가 404를 반환하기 시작했습니다 — 계정이 플랫폼 리스크 관리에 걸린 것입니다. 빌드는 계속 돌았고, 데이터 소스는 사라졌고, 페이지의 작품 목록은 축소된 샘플 데이터로 떨어졌습니다.

회고: 이 설계에 숨어 있던 세 가지 가정

1. 계정은 영원히 접근 가능하리라는 가정 — 오답. 리스크 관리, 오판, 지역 문제. 그 어느 하나만으로도 404는 하늘에서 뚝 떨어집니다.
2. 빌드 머신의 네트워크는 믿을 만하리라는 가정 — 취약함. 빌드 산출물이 네트워크 요청 한 번의 성패에 의존하다니, 엔지니어링으로서 용납할 수 없습니다.
3. 데이터량이 실시간성에 걸맞으리라는 가정 — 오답. 작품 목록은 몇 달에 한 번 바뀝니다. 그걸 위해 런타임 의존을 들이는 건 위험과 수익이 전혀 맞지 않는 거래죠.

결정: 데이터 로컬화

데이터 소스를 뜯어냈습니다. 저장소와 통계는 전부 config.ts로 로컬 관리하고, 빌드 시점의 외부 요청은 제로가 되었습니다. 즉시 얻은 세 가지 이득:

• 결정론: npm run build의 결과는 저장소 내용만이 결정하고 GitHub의 기분은 결정하지 않습니다
• 속도: 빌드에서 네트워크 왕복이 사라져 CI에서 더 빠르고 더 안정적
• 감사 가능성: 페이지의 모든 숫자는 코드베이스에서 출처를 추적할 수 있습니다

단, 재접속 플러그는 남겨라

로컬화는 자동화의 영구 포기를 뜻하지 않습니다. 원래의 getGitHubData() 시그니처는 그대로 보존되어 있습니다. 나중에 계정이 복구되면 fetch 로직을 다시 꽂기만 하면 되고, 상위 컴포넌트는 한 줄도 바꿀 필요가 없습니다.

이번 회고의 가장 중요한 교훈입니다: 의존성을 뜯어낼 때는 인터페이스를 제자리에 남겨라. 데이터 소스는 바꿀 수 있어도 계약은 바꾸지 마라.

하나의 판단 기준

앞으로 “빌드 시점에 외부 서비스 요청”이라는 아이디어가 떠오르면, 먼저 이 체에 걸러봅니다:

이 데이터의 변화 빈도가, 끌어들이는 장애 위험에 걸맞는가?

월 단위로 변하는 콘텐츠에는 — 걸맞지 않습니다. 얌전하게 코드베이스에 들어가서, 역사는 git이 관리하게 하세요.