여러 기능을 한 배포에 담으며 배운 것들
목차
한 번에 6개 기능이 나갔다. 졸업, 퀵팩트, freshness, 필터, 모바일, 라이크. 각자 다른 요청에서 비롯한 일들이지만, 결국 한 마이그레이션과 한 번의 문서 정비로 수렴했다. 단순히 기능들을 코드로 마무리하는 것과 "이걸 어떻게 체계적으로 기록할 것인가" 는 다른 차원의 문제였다.
문서가 코드를 앞선다
CLAUDE.md 수정이 먼저였다. 팀에게 "이 기능들을 어떤 기준으로 개발하고 리뷰할 건가" 를 알려야 했다.
코드 없이 문서만 있으면 작동하지 않지만, 코드 없이 문서가 없으면 다음 기능을 만들 때 같은 질문을 반복한다. "라이크 기능에서 권한 체크를 어디서 해야 하나요?" "freshness를 어떤 주기로 업데이트하나요?" 같은 것들이다. 구두로만 전하면 사람이 바뀔 때마다 정보가 손실된다.
이번 문서 정비에서 기록한 항목들:
- 졸업 상태 전이의 규칙 (언제, 어떤 조건, 누가)
- freshness와 퀵팩트의 차이 및 캐싱 전략
- 필터와 모바일 환경에서의 쿼리 최적화 기준
- 라이크 기능의 권한 체크 위치
이런 것들을 글로 남기면, 새로운 팀원이 온라보딩할 때나 코드 리뷰 시간이 눈에 띄게 줄어든다.
MySQL 8.4 호환성을 맞추는 일
2026-06-22-grad-freshness.sql 마이그레이션은 단순히 새 컬럼을 추가하는 일만 아니었다. 이 과정에서 기존 마이그레이션들의 호환성 문제를 정정했다.
데이터베이스 호환성이 어긋나면, 같은 쿼리가 환경마다 다르게 동작한다. 로컬 개발 환경에선 잘 돌아도 프로덕션에선 실패하고, 외부 시스템이 다른 MySQL 버전을 쓸 때 예상 밖의 결과가 나온다. 마이그레이션이 누적될수록 레거시 스타일의 타입 정의가 섞여서, "왜 이 컬럼은 이렇게 정의된 거지?" 같은 질문에 대답할 수 없게 된다.
이번 정정에서 정리한 것들:
- 새 컬럼들의 타입 정의 (NOT NULL, DEFAULT, CHARSET, COLLATE)
- freshness나 라이크 같이 검색·정렬이 빈번한 컬럼의 인덱스 전략
- 졸업 상태 업데이트와 라이크 카운트 변경의 트랜잭션 패턴
한 번 정산하면 "다음 마이그레이션은 이 기준을 따르자" 라는 통일된 스타일이 생긴다. 기술 부채를 방치하지 않고 정기적으로 정리하는 것의 가치가 여기다.
왜 6개 기능을 한 마이그레이션에 넣었나?
여러 기능이 동시에 나올 때, 항상 묻는 질문이 있다: "기능별로 따로 마이그레이션을 쓰면 안 되나?"
우리의 판단:
- 데이터 독립성 — 각 기능의 DB 변경이 서로 영향을 주지 않는다. 라이크 카운트와 졸업 상태는 완전히 별개 컬럼.
- 배포 타이밍 — 모든 기능이 같은 시점에 프로덕션으로 반영된다. 이 경우 마이그레이션 여러 개를 순차 실행하는 것보다 한 번에 처리하는 게 실패율이 훨씬 낮다.
- 추적 가능성 — 나중에 "라이크 기능 이후로 뭐가 바뀌었지?" 하고 찾을 때, 마이그레이션 파일이 하나면 답이 명확하다.
물론 예외는 있다. 만약 한 기능이 아직 불확실하거나 테스트 중이라면, 그 부분은 빼고 별도 마이그레이션으로 연기한다. "한 마이그레이션은 한 번의 배포를 상징해야 한다" 는 원칙이 있는데, 이게 나중에 롤백이나 장애 분석할 때 정말 중요하다.
코드와 문서, 그리고 마이그레이션 전략이 모두 맞아떨어질 때, 비로소 새로운 기능들이 깔끔한 형태로 팀의 자산이 된다.
🛒 이 글과 어울리는 추천 상품
*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.
댓글 0
첫 댓글 달아줘.