블로그에 조회수 지표와 글쓴이 페이지를 동시에 완성한 이유

블로그에 조회수/지표 노출 + author 페이지를 한 번에 묶어서 작업했다. 작은 기능처럼 보이지만 실제로는 꽤 여러 레이어를 건드린 작업이었음.

왜 이게 하나의 커밋에 묶였나

처음엔 PostMetrics 컴포넌트만 만들려고 했다. 그런데 작업하다 보니 조회수를 기록/조회하는 API 엔드포인트(/api/metric)가 없으면 컴포넌트 자체가 의미 없고, API가 생기면 Article schema에서 author 필드가 애매하게 남는 문제가 눈에 들어왔다. 거기에 author 페이지(/author/money-team)가 없으면 포스트에 author 정보를 표시해도 링크가 죽어 있는 상태가 되니까 결국 한 덩어리로 묶었다.

팀에서 이런 작업을 리뷰할 때 자주 하는 말이 있다. "사용자가 실제로 눌렀을 때 죽는 링크를 PR에 올리지 말자"는 거다. 반쪽짜리 기능을 main에 머지하면 그 자체로 작은 장애고, 누군가 다음 스프린트에서 "이거 왜 안 되지?" 하고 디버깅하는 비용이 생긴다. 그래서 다소 커밋 범위가 넓어지더라도 릴리즈 가능한 단위로 묶는 편이다.

변경 파일별 역할

파일 수가 다섯 개로 적지 않은데, 크게 보면 컴포넌트 레이어 → 레이아웃 연결 → 라우트 처리 → API → 참조 페이지 순서로 각 레이어를 하나씩 건드린 구조다. 어느 한 파일이 빠지면 체인이 끊기는 형태라서 분리 커밋보다 묶는 게 맞다고 판단했다.

Article schema author 변경이 끼어든 이유

이게 약간 숨어 있는 포인트인데, author 페이지를 새로 만들면서 기존 Article schema의 author 필드가 단순 문자열로만 박혀 있던 게 문제였다. author 페이지로 라우팅하려면 slug나 식별 가능한 값이 필요한데 그냥 표시용 이름만 들어 있으면 링크를 동적으로 생성할 수가 없다.

// Before — author가 표시명 문자열 하나
author: z.string()

// After — author 페이지와 연결 가능한 구조로
author: z.object({
  name: z.string(),
  slug: z.string(),
})

schema를 바꾸면 기존 콘텐츠 파일들도 같이 수정해야 하는 번거로움이 있지만, 나중에 "author 필터링" 같은 기능을 붙일 때 다시 schema를 뜯어야 하는 비용을 생각하면 지금 한 번 정리하는 게 맞다. 이런 타이밍 판단이 팀장 포지션에서 자주 해야 하는 결정이기도 하다. 기술 부채를 지금 갚느냐, 다음에 갚느냐.

api/metric.ts — 간단하지만 설계는 명확하게

조회수 API는 크게 두 가지 동작이 필요했다.

• POST /api/metric — 포스트 진입 시 조회수 +1
• GET /api/metric?slug=... — 현재 조회수 조회

Astro의 API 라우트는 하나의 파일에서 HTTP 메서드로 분기할 수 있어서 metric.ts 하나로 처리했다. 단순한 구조지만 이런 엔드포인트도 "slug 없이 요청하면 어떻게 되나", "동시 요청이 몰리면?" 같은 엣지 케이스는 미리 정리해두는 게 나중에 팀원이 건드릴 때 혼란이 없다. 지금 당장 트래픽이 없어도 방어 코드는 작성 습관이다.

짧은 회고

PostMetrics 컴포넌트 자체는 UI 작업이라 금방이었는데, author schema 변경 + author 페이지 신규 작성 + 기존 콘텐츠 파일 업데이트가 예상보다 시간을 잡아먹었다. 이런 "작아 보이는 schema 변경"이 사실 변경 반경이 제일 넓다. 앞으로 schema를 바꿀 일이 있으면 콘텐츠 파일 수를 먼저 확인하는 습관을 들여야겠다는 걸 다시 한 번 확인한 작업이었음.

끝.

🛒 이 글과 어울리는 추천 상품

• 기계식키보드 쿠팡에서 보기 →
• 모니터암 쿠팡에서 보기 →
• 외장SSD 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.