백엔드 개발 흐름
백엔드 엔지니어가 작업 하나를 받아 프로덕션에 내보내기까지 거치는 과정을 설명합니다. 작업이 어디서 들어오는지는 우리는 이렇게 일합니다를 먼저 보세요. connectingServer를 기준으로 쓰며, connecting-matchmaker도 QA·프로덕션 배포 방식은 같습니다.
작업 쪼개기
- 맡은 작업을 서브태스크로 나누고, 서브태스크 하나에 PR 하나를 올리는 것이 기본입니다.
- PR은 추가·삭제 각각 250줄을 넘을 수 없습니다. 테스트, 마이그레이션, 문서, lock 파일 등은 세지 않습니다. 한도를 넘으면 PR 검사가 실패해 머지할 수 없으니, 처음부터 250줄 안에 들어오게 나눕니다.
- PR은 저장소마다 따로 올라가므로, 여러 저장소에 걸친 작업은 저장소별로 서브태스크를 나눕니다.
브랜치 만들고 구현하기
최신 main에서 티켓 키를 이름으로 브랜치를 만듭니다(예: BE-1234, Y26H1-974). main에 직접 커밋하지 않습니다.
모든 작업은 main 하나로 모이고, main은 언제 배포돼도 안전해야 합니다. 그래서 새 동작이나 동작 변경은 waffle 스위치로 감싸 기본값 꺼짐으로 머지합니다.
- 스위치는
common/constants.py의WaffleSwitchCategories에 정의하고, 환경별 어드민에서 켭니다. - 머지와 켜기는 따로 합니다. QA에서 확인하려면 QA 서버에 배포한 뒤 QA 환경의 스위치를 켭니다. 프로덕션은 배포가 끝난 뒤 켭니다.
- 스위치를 넣을 때 나중에 걷어낼 티켓도 함께 만듭니다.
- 앱과 맞물린 변경은 서버가 먼저 나가도 구버전 앱이 깨지지 않게 만듭니다.
- 오타, 로그, 순수 버그 수정처럼 되돌릴 동작이 없는 변경은 스위치 없이 머지합니다.
명령은 항상 uv run 또는 mise run으로 실행합니다. 로컬 환경 설정은 connectingServer README를 참고하되, README의 브랜치 설명(develop·release·master)과 pytest 직접 실행 안내는 예전 내용이니 이 문서를 따릅니다.
PR을 올리기 전에 아래 세 가지를 통과시킵니다. pre-commit은 스테이징한 파일만 검사하므로 git add를 먼저 합니다. mise run typecheck는 origin/main과 비교하므로 git fetch를 먼저 합니다. 테스트는 로컬 MySQL을 쓰므로 README대로 도커를 먼저 띄웁니다.
uv run pre-commit # 린터·포매터
mise run typecheck # mypy 오류 수 비교
mise run test # 전체 테스트
pre-commit에는 black, flake8, isort와 함께 저장소에서 만든 린터 세 개가 들어 있습니다. 세 린터는 파일 전체가 아니라 새로 쓰거나 고친 줄만 봅니다. 손대지 않은 기존 코드는 걸리지 않지만, 기존 위반이 있는 줄을 고치면 그 줄은 걸립니다. UCS004만 예외로, 메서드를 쓰는 쪽의 def 줄을 고치면 그보다 위에 있는 기존 메서드도 걸립니다. 에러 코드별 규칙과 고치는 법은 아래 문서에 있습니다.
| 린터 | 에러 코드 | 규칙 |
|---|---|---|
| FK 사용 검사 | FK001, FK002 | 외래 키 제약 |
| 타입 힌트 검사 | TYP001, TYP002, TYP003 | 타입 |
| UseCase 범위 검사 | UCS001, UCS002, UCS003, UCS004 | UseCase 하나가 맡는 범위 |
mypy 검사는 PR을 main에 합친 코드의 mypy 오류 수가 main보다 늘었으면 실패합니다. 전체 개수를 비교하므로, 다른 곳의 오류를 줄였으면 그만큼 상쇄됩니다. 새로 생긴 것으로 보이는 오류는 GitHub annotation으로 표시되고, 작업 로그 끝에 바뀌기 전후의 오류 수가 찍힙니다. mypy가 비정상 종료해도 실패합니다.
mypy 설정은 pyproject.toml의 [tool.mypy]에 있고, tests/와 migrations/는 검사하지 않습니다. mise run typecheck는 origin/main에서 갈라진 지점의 코드와 지금 작업 트리를 비교하므로, 커밋하지 않은 변경도 들어갑니다.
PR에서는 검사마다 실행되는 조건이 다릅니다.
- pre-commit과 테스트는 draft가 아닌 PR에서만 실행됩니다. pre-commit은 PR에서 바뀐 파일을 검사하고, 세 린터는 그중 PR이 바꾼 줄을 봅니다.
- UseCase 범위 검사와 mypy 검사는 draft를 포함한 모든 PR에서 실행됩니다.
uv run pre-commit install로 훅을 설치해 두면 커밋할 때마다 pre-commit이 실행됩니다. draft PR에서 UseCase 범위 검사가 실패했을 때 같은 검사를 로컬에서 돌리려면 mise run usecase-lint를 씁니다. origin/main 이후 커밋에서 추가한 줄을 봅니다.
세 린터의 검사를 특정 줄에서만 끄려면, 에러 메시지에 나온 줄 끝에 # noqa: TYP001처럼 코드를 적습니다. # noqa만 적으면 그 줄의 검사를 모두 넘어가고, flake8 검사도 함께 꺼집니다.
핵심 로직에는 테스트를 함께 작성합니다. 버그를 고칠 때는 그 버그를 재현하는 테스트를 씁니다. 커밋 메시지는 feat: 설명, fix: 설명처럼 타입을 앞에 붙입니다.
PR 올리기
- base는 항상
main이고, assignee는 본인입니다. - 제목은
[티켓 키] 타입: 설명형식입니다(예:[BE-610] feat: 사용자 임베딩 저장 기능 추가). 제목에 티켓 키가 없으면 PR 검사가 실패해 머지할 수 없습니다. - 본문은 저장소의 PR 템플릿을 채웁니다. 개요(기획서·테크 스펙·Jira 링크), 작업내용, Tests, 참고 순서입니다.
- 라벨은 하나 고릅니다.
🌱 feature,🐞 bug,🛠 refactor,DDL/migration(마이그레이션 포함),performance optimization중에서 고릅니다. - draft로 먼저 열어도 됩니다. 다만 draft 상태에서는 pre-commit과 테스트가 돌지 않고, 백엔드 팀에 리뷰 요청도 가지 않습니다. UseCase 범위 검사와 mypy 검사는 draft에서도 실행됩니다. 준비가 되면 Ready for review로 바꿉니다.
리뷰받고 머지하기
- Ready for review 상태가 되면 백엔드 팀에 리뷰 요청이 자동으로 갑니다. CodeRabbit은 draft일 때부터 자동으로 리뷰합니다. 특정 사람에게 리뷰받고 싶으면 리뷰어로 직접 추가합니다.
- 머지하려면 사람 1명과 CodeRabbit의 승인이 필요합니다. CodeRabbit이 변경을 요청하면 반영해서 푸시하고, CodeRabbit 댓글을 해결 처리하면 다시 검토해 승인합니다.
- 리뷰 대화를 모두 해결(Resolve conversation) 처리해야 머지할 수 있습니다.
- 테스트는 필수 검사가 아니어서 실패해도 머지 버튼이 눌립니다. 머지 전에 테스트가 통과했는지 직접 확인합니다.
- 머지는 작성자가 직접 하며 squash 머지만 됩니다. 머지하면 브랜치는 자동으로 지워지고, dev 서버에 자동으로 배포됩니다.
QA에 배포하기
QA 배포는 gh-deploy로 합니다. 처음 한 번만 설치합니다.
gh extension install yplabs-ltd/gh-deploy
저장소 폴더에서 gh deploy qa를 실행하면 아래를 차례로 묻습니다.
- 새 배포, 이미 올라간 버전의 재배포, 롤백 중 무엇인지
- 새 배포라면 버전을 얼마나 올릴지(minor, patch, major)
main에 새로 들어온 커밋 중 무엇을 넣을지(고른 커밋까지 전부, 또는 커밋을 하나씩 골라 체리픽)
확인하면 qa/X.Y.Z-rc.N 브랜치와 태그가 만들어지고 QA 서버에 배포됩니다. 같은 버전을 고쳐 다시 올리면 rc 번호가 하나씩 올라갑니다.
- QA 담당자는 스쿼드 에픽의 QA 작업으로 기능을 확인합니다. 버그를 찾으면 QA 프로젝트에 이슈를 만들어 작업자에게 배정합니다.
- 버그 수정 PR은 QA 이슈 키로 올립니다(예:
[QA-700] fix: ...). 머지한 뒤 버전을 올리지 않고 재배포로 다음 rc를 올립니다. - 이미 QA에 올라간 커밋을 빼야 하면 재배포에서 "커밋 빼기"를 고릅니다.
프로덕션에 배포하기
gh deploy prod를 실행하고 QA에서 확인을 마친 버전을 고르면, 그 rc의 커밋으로 release/X.Y.Z 브랜치가 만 들어집니다. 이 브랜치가 올라가면 전체 테스트가 돌고, 통과하면 vX.Y.Z 태그와 GitHub Release 생성, 프로덕션 배포(CodePipeline)가 함께 진행됩니다.
배포 담당은 따로 없고 팀원 누구나 올립니다. 핫픽스도 따로 가는 길이 없습니다. patch 버전으로 QA에 올려 확인한 뒤 같은 방법으로 내보냅니다. 새 버전은 가장 최근 QA 버전을 기준으로 올라가므로, QA에 아직 프로덕션에 나가지 않은 버전이 있으면 그 내용도 함께 나갑니다.
마이그레이션 적용하기
마이그레이션은 배포 파이프라인이 적용하지 않습니다. 작업자가 자기 로컬에서 환경별로 직접 적용합니다. 설정을 AWS Secrets Manager에서 읽으므로 AWS 자격 증명이 필요합니다.
mise run unapplied-migrations-prod # 적용 안 된 마이그레이션 먼저 확인
mise run migrate-prod # dev, qa도 같은 형식
migrate는 체크아웃한 코드에 있는 미적용 마이그레이션을 전부 적용합니다. 적용하기 전에 목록이 내 작업 것뿐인지 확인합니다.- 새 테이블이나 컬럼을 쓰는 코드라면, 그 코드가 배포되기 전에 해당 환경에 마이그레이션을 먼저 적용합니다.
- 컬럼을 지울 때는 반대입니다. 그 컬럼을 쓰지 않는 코드를 먼저 배포하고, 그다음에 컬럼을 지우는 마이그레이션을 적용합니다. NOT NULL 컬럼이면 nullable로 바꾸는 것부터 합니다.
- 마이그레이션이 있는 PR이 머지되기 전에는 다음 마이그레이션을 만들지 않습니다. 앞 PR이 머지되면
main을 받은 뒤에 만들어야 번호가 겹치지 않습니다.
배포 후 할 일
- QA·프로덕션 배포가 시작되거나 배포 워크플로가 실패하면 Slack으로 알림이 옵니다.
- 배포 내역은 QA팀이 Notion 배포 캘린더에 정리합니다. 한 버전에 실제로 들어간 커밋은
release/X.Y.Z브랜치에서 확인합니다. 체리픽으로 만든 버전은 GitHub Release의 변경 목록이 실제와 다를 수 있습니다. - waffle 스위치로 감싼 변경은 배포가 끝난 뒤 켭니다.
운영 이슈 정리하 기
백엔드 챕터는 월요일부터 금요일까지 요일마다 운영 이슈 당번이 정해져 있습니다. 당번은 퇴근 전에 그날 운영 이슈를 Notion 일일 운영이슈 DB에 한 페이지로 정리합니다. 정리 범위는 전날 저녁부터 오늘까지입니다.
- 평일 새벽에 그날 페이지가 자동으로 만들어지고, 당번 칸에는 그날 당번이 미리 들어가 있습니다. 새 페이지를 만들지 않고 자동으로 만들어진 페이지에 씁니다.
- 평일 오후 5시에 #dev-backend-private 채널에 그날 당번을 태그한 정리 요청 메시지가 올라옵니다.
- 이슈는 페이지의 섹션 중 맞는 곳에 적습니다. 섹션은 "고객 영향 가능", "인프라 · 배치", "앱 (Crashlytics)", "노이즈", "확인된 이슈" 다섯 개입니다.
- 전날 페이지에 이미 있던 이슈는 "확인된 이슈"에 적습니다.
- 이슈 하나는
[서비스] 제목 — N건, 시각한 줄로 쓰고, 그 아래에 원인, 조치, 출처 링크를 적습니다.
유저나 데이터에 영향을 준 이슈는 처리를 마친 사람이 바로 #cnt_production_notice 채널에 공지합니다. CX와 데이터 쪽에서 영향을 파악할 수 있어야 하기 때문입니다.
운영 이슈가 장애로 이어졌다면 회고는 장애가 나면에 따라 PMT 프로젝트에 남깁니다. 통화가 안 되거나 로그인이 아예 안 되는 이슈는 유저 경험에 큰 영향을 줍니다. 이런 이슈는 같은 원인으로 다시 생기 지 않도록 재발 방지 조치까지 하고, 필요하면 회고도 남깁니다.