협업 속도를 높이는 의존성 분리와 안정적인 API 버저닝, 그리고 경계 세우기
최근 팀 프로젝트를 하면서 개발 속도는 올리되 시스템 안정성은 지키는 방법을 오래 고민했습니다. 내 기능만 돌아가게 만드는 단계를 넘어 다른 팀원의 작업과 어떻게 맞물릴지, 변경에는 얼마나 유연하게 대응할지 고민한 과정을 TIL로 정리합니다.
1. 구현체 없이 먼저 달리기: 인터페이스와 가짜 객체 활용
협업을 하다 보면 모든 기능이 동시에 완성되지는 않습니다. 내가 만드는 기능이 다른 팀원의 작업에 의존할 때, 상대방이 개발을 끝낼 때까지 기다리면 흐름이 끊기고 병렬 작업도 못 합니다.
이 문제를 풀려고 우리는 인터페이스를 먼저 정의하고 임시로 동작하는 스텁(Stub)이나 페이크(Fake) 구현체를 붙여서 개발을 시작했습니다. 이렇게 하니 이런 이점이 있었습니다.
- 실제 구현체가 없어도 의존하는 기능을 막힘없이 개발합니다.
- 팀원 간 작업 병렬성이 크게 좋아집니다.
- 실제 구현체가 완성되면 인터페이스 뒤쪽 구현체만 갈아 끼우면 됩니다.
- 테스트할 때 아직 완성되지 않은 의존성이나 외부 시스템을 대체하기 쉽습니다.
다만 스텁이나 페이크 객체는 임시 방편이라 실제 비즈니스 정책과 다르게 작동할 수 있습니다. 코드에 임시 구현체라는 사실을 명확히 남기고 실제 구현체로 교체하는 시점을 꼼꼼히 챙겨야 합니다.
2. API 버저닝: 클라이언트와 맺는 안전한 계약
API 경로에 /v1이나 /v2를 붙이는 일은 단순한 형식이 아닙니다. 서비스를 배포하고 운영하다 보면 응답 필드가 바뀌거나 요청 구조가 바뀌는 일이 흔합니다. 기존 API를 그대로 수정하면 이미 개발해 둔 클라이언트가 멈춰 버립니다.
API 버저닝은 기존 사용자와 맺은 약속을 지키는 핵심 장치입니다. 버저닝을 도입하면 이런 효과를 볼 수 있습니다.
- 기존 클라이언트 호환성 유지
- 변경에 따른 영향 범위 분산
- 신규 버전으로 점진적인 마이그레이션
- 운영 중인 서비스의 안정성 확보
버저닝이 변경을 안전하게 받아들이고 비즈니스를 지키는 실무 장치라는 걸 배웠습니다.
3. 요구사항 분석: 기능 목록 작성을 넘어 정책과 경계 설정하기
요구사항을 단순히 기능을 만든다고만 보고 접근하면 한계에 부딪힙니다. 요구사항에 담긴 정책이 무엇인지, 그 책임의 경계를 어디에 둘지 정의하는 과정이 중요합니다.
설계 과정에서 이런 질문을 거듭 던졌습니다.
- 검증 로직은 어느 계층에서 처리해야 하는가?
- 이 조건은 단순한 화면 정책인가, 비즈니스 정책인가?
- 이 API의 책임이 현재 도메인 영역에 속하는 것이 맞나?
- 다른 도메인과 경계가 모호하게 섞이고 있지는 않은가?
이런 판단은 기획 문서만 보고 바로 익힐 수 있는 게 아니었습니다. 다양한 구현과 협업, 운영 경험이 쌓여야 자연스럽게 몸에 익습니다.
우리가 마주하는 설계 고민은 대부분 앞선 서비스에 답이 있습니다. 커머스, 주문, 결제, 회원, 알림 같은 도메인은 이미 자리 잡은 서비스의 레퍼런스가 풍부합니다. 기존 서비스가 정책과 도메인 경계를 어떻게 나눴는지 참고하면 의사결정이 훨씬 수월합니다. 다만 그대로 베끼기보다는 팀 규모와 프로젝트 복잡도에 맞게 덜어내고 덧붙이는 조율이 필요합니다.
배운 점 정리
- 협업에서는 내 기능을 만드는 데 그치지 않고 시스템 전체에서 각 기능이 어떻게 연결될지 먼저 고민해야 합니다.
- 인터페이스를 먼저 정의하면 작업 병렬성은 높아지지만, 가짜 구현체를 실제 객체로 교체하는 일정을 철저히 관리해야 합니다.
- API 버저닝은 안전하게 변경을 수용하는 계약 관리 방식입니다.
- 요구사항 분석은 기능 목록을 쪼개는 작업이 아니라, 정책의 도메인 경계와 책임 소재를 정하는 과정입니다.