허브에 빠져 있던 두 개의 출처
저는 여러 프로젝트 상태를 한 화면에서 보려고 작은 파이썬 허브(hub.py)를 씁니다. 카드마다 출처가 하나씩 있고, 렌더 함수가 그 출처를 받아 화면에 그립니다.
2026-08-05에 이 허브에 카드 두 개를 추가했습니다. 하나는 운세 계열 앱의 계측 카드로, 앱 쪽 /admin/metrics 엔드포인트를 읽습니다. 다른 하나는 이 개발 블로그로 들어오는 유입을 보는 카드인데, 로컬 :8899 포트에서 뜨는 dev-inflow.html 페이지를 가리킵니다.
변경은 hub.py 한 파일에 11줄을 더한 것이 전부입니다. 그런데 그 11줄 안에 카드 두 개 말고 하나가 더 들어 있습니다. render_card의 note_only 분기입니다.
당신의 대시보드에서 카드 하나를 그리려면 반드시 숫자가 있어야 하나요, 아니면 "여기 가서 보세요"라는 메모만으로도 카드가 될 수 있나요?
왜 분기가 필요했나
분기 이름만 봐도 그 전 렌더러가 어떤 가정을 하고 있었는지 짐작할 수 있습니다. note_only라는 분기를 새로 만들어야 했다는 건, 그 전까지는 모든 카드가 값을 가진다고 보고 렌더러를 짰다는 뜻입니다. 숫자를 바로 꺼낼 수 없고 메모와 링크만 남기면 되는 출처는, 그 렌더러로는 카드 모양을 갖출 수 없었습니다.
흔한 함정입니다. 대시보드를 처음 만들 때는 숫자가 나오는 출처부터 붙이니, 렌더러도 자연스럽게 숫자를 전제로 굳어 버립니다. 그러다 숫자가 없는 출처가 생기면 선택지는 둘입니다. 가짜 값이나 빈 값을 넣어 억지로 맞추든가, 아예 허브에 올리지 않든가. 어느 쪽이든 허브는 실제로 보고 싶은 것보다 좁은 그림을 보여 주게 됩니다.
키는 코드 밖에
계측 카드에는 조건이 하나 더 있었습니다. 관리자 엔드포인트라 키가 필요합니다. 이번 커밋에서는 키를 코드에 적지 않고 SAJUDUO_ADMIN_KEY 환경변수에서 읽게 했습니다. 허브 코드는 저장소에 남고, 키는 실행 환경에만 있습니다.
당신이라면? 렌더러를 고쳐서 숫자 없는 카드를 받을지, 숫자 없는 출처는 허브에 올리지 않을지.
제가 고른 쪽
저는 렌더러를 고치는 쪽을 골랐습니다. render_card에 note_only 분기를 넣어, 값 없이 메모만 있는 카드도 정상적인 카드로 그리게 했습니다. 그리고 그 위에 계측 카드와 유입 카드를 함께 올렸습니다. 출처를 더하는 일과 렌더러가 받을 수 있는 카드 모양을 넓히는 일을 한 커밋에서 같이 했습니다.
자가진단 체크리스트
- 대시보드 렌더 함수가 "값이 없는 카드"를 정상 경로로 처리하나요, 아니면 예외나 빈칸으로 떨어지나요?
- 보고 싶지만 숫자를 바로 꺼낼 수 없다는 이유로 허브에 올리지 않은 출처가 있나요?
- 관리자 엔드포인트를 읽는 카드의 키가 코드가 아니라 환경변수에만 있나요?
솔직한 부분
이 글의 근거는 11줄짜리 커밋 하나뿐입니다. 커밋에는 두 카드 중 어느 쪽이 note_only로 그려지는지, 계측 카드가 실제로 어떤 숫자를 보여 주는지, 카드를 붙인 뒤 제가 무엇을 새로 알게 됐는지가 적혀 있지 않습니다. 그래서 "카드를 붙였더니 무엇이 보였다"는 이야기는 쓸 수 없습니다. 제가 말할 수 있는 건 이 정도입니다. 숫자를 전제로 짠 렌더러는 숫자 없는 출처를 조용히 밖으로 밀어내고, 그걸 바로잡는 데 큰 작업이 필요하지는 않았다는 것.