주간 트랜드 14위

백엔드 코드 바꿨는데 왜 DOCS는 그대로일까: 휴먼 에러를 멸종시키는 법

성장하는 팀에서 파편화된 API 명세는 개발 속도를 늦추는 가장 큰 원인 중 하나입니다.

백엔드 코드는 수정되었는데 문서는 과거에 머물러 있거나, 에러 코드를 확인하기 위해 매번 소스 코드를 뒤져야 하는 상황은 팀 전체의 인지 부하를 높입니다.

저희 팀은 추가적인 서버 운용 비용을 들이지 않으면서도, 백엔드의 변경 사항을 자동으로 반영하고 누구나 쉽게 검색할 수 있는 사내 통합 API DOCS를 구축했습니다.

이 글에서는 Google Sheets를 데이터베이스로 활용하면서 발생하는 제약을 어떻게 기술적으로 해결했는지, 그리고 '쓰기 쉬운' 문서를 넘어 '자동으로 관리되는' 환경을 만든 과정을 소개합니다.

1. 데이터베이스 대신 선택한 Google Sheets와 ISR

보통 DOCS 사이트를 구축할 때 전용 DB와 서버를 고려하지만, 이는 관리 포인트가 늘어남을 의미합니다. 저희는 기획자나 운영자도 쉽게 내용을 수정할 수 있도록 Google Sheets를 데이터 저장소로 선택했습니다.

하지만 Google Sheets API에는 호출 횟수 제한(Quota)이 존재합니다. 사용자가 접속할 때마다 실시간으로 시트 데이터를 불러오게 되면 금세 제한에 걸려 사이트가 마비될 위험이 있죠. 이를 해결하기 위해 Next.js의 ISR(Incremental Static Regeneration) 전략을 활용했습니다.

• ISR 적용: 60초 주기로 시트의 최신 데이터를 가져와 정적 페이지를 업데이트합니다.
• 효과: 시트 API 호출은 최소화하면서, 작성자가 시트를 수정한 뒤 최대 1분 이내에 모든 팀원이 최신 문서를 볼 수 있는 실시간성을 확보했습니다.

2. 복잡한 비즈니스 로직을 담는 데이터 구조 설계

교육 서비스인 저희 팀은 선생님, 학생, 어드민이라는 세 가지 도메인을 운영하며, GraphQL 기반의 Query와 Mutation을 사용합니다. 이 복잡한 권한과 도메인을 시트 하나로 관리하기 위해 두 가지 명세 구조를 설계했습니다.

Operation: 권한과 식별자의 이진법 제어

단순히 "권한 있음/없음"을 텍스트로 적는 대신, 이진법(Bitmask) 기반의 권한 제어 방식을 도입했습니다. 관리자, 선생님, 학생 순으로 1과 0을 부여하고 이를 10진수로 변환하여 관리합니다.