프론트엔드와 백엔드 개발자 협업하기

TL;DR

• API SDK를 패키지로 배포하고 변경 추적을 보완해, 프론트엔드가 업데이트 시점을 선택하도록 했다.
• Bruno로 API 요청을 공유하고 인증을 자동화해 반복 작업을 줄였다.
• traceparent로 클라이언트와 백엔드의 트레이스를 연결해 VOC의 원인을 함께 추적하기 쉬워졌다.
• 변경 요청은 티켓과 PR으로 남겨 맥락과 처리 상태를 확인할 수 있게 했다.

회사에서 백엔드 개발자와 나란히 앉아서 개발하고 있다. 필요한 게 있으면 수시로 묻는다. 응답에 이 값을 추가할 수 있는지, 이 에러는 왜 나는지, 이 기능은 어떻게 구현하면 좋을지.

바로 물어볼 사람이 옆에 있다는 건 꽤 편하다. 그러다 보니 문서를 읽으면 알 수 있는 것도 물어보게 됐다. 너무 귀찮게 하는 것 같다는 생각도 한다. 일단 문서부터 읽어야겠다.

그래도 옆자리에서 도란도란 이야기하며 서비스를 만들어가는 건 즐겁다. 각자 개발하다가도 화면을 같이 보고, 애매한 부분은 바로 이야기할 수 있으니까.

그렇게 일하면서 조금씩 바꿔본 것들이 있다. 대화만으로는 남기기 어려운 내용을 기록하고, 반복하는 작업을 줄이고, 문제가 생겼을 때 함께 들여다볼 수 있게 만드는 일이다.

API SDK의 버전을 프론트엔드에서 선택하기

우리 회사는 종전부터 OpenAPI 명세를 SDK로 만들어 사용하고 있었다. 백엔드에 새 커밋이 올라오면 GitHub Actions가 SDK를 생성하고, 프론트엔드 저장소에 동기화 커밋을 남기는 방식이었다. 생성된 코드를 가져다 쓰면 되니 꽤 편했다.

다만 프론트엔드가 SDK 버전을 선택하기는 어려웠다. 백엔드의 변경이 곧바로 들어왔고, 타이밍이 맞지 않으면 새로 생성된 타입 때문에 빌드 오류가 나기도 했다. 웹만 관리할 때는 대체로 최신 API에 맞춰 배포했지만, 앱은 이미 배포된 버전과 다음 배포를 준비하는 버전이 함께 있다. 어떤 SDK를 사용할지 직접 정할 필요가 생겼다.

그래서 백엔드 저장소에서 SDK를 GitHub Packages에 패키지로 발행하도록 바꿨다. 프론트엔드에서는 필요한 버전을 의존성으로 설치한다.

물론 SDK 버전을 고정해도 요청을 받는 서버는 항상 최신이다. 구버전 앱과의 호환성은 여전히 백엔드와 함께 챙겨야 한다. 이번 변경만으로 운영상 문제가 해결됐다고 말할 만한 결과는 아직 없다.

지금 짚을 수 있는 변화는 브레이킹 체인지를 알아보기 쉬워졌다는 점이다. 백엔드 동료가 SDK를 업데이트하는 Actions에 관련 체크를 넣어뒀다. 버전 번호에 변경의 의미가 조금 더 담기고, 어떤 변경이 들어왔는지도 추적할 수 있게 됐다.

백엔드는 SDK를 발행하고, 프론트엔드는 변경 내용을 확인한 뒤 버전을 올린다. 메인 브랜치에서는 정식 배포 버전의 SDK를 사용하도록 필수 체크도 넣었다. 개발 중에 쓰던 버전이 그대로 들어가는 일을 막기 위해서다.

SDK 버전은 OpenTelemetry 기록에도 함께 남기고 있다. 어떤 SDK 버전에서 보낸 요청인지 확인할 수 있으니, 나중에 버전별 문제를 디버깅할 때 도움이 되지 않을까 기대하고 있다.

Bruno로 API를 확인하는 과정 줄이기

최근에는 Bruno를 알게 됐다. API 요청을 보내고 응답을 확인하는 도구인데, 요청 모음을 Git으로 공유하고 OpenAPI 명세를 가져올 수 있다는 점이 마음에 들었다.

이전에는 API를 직접 확인하려면 로그인부터 했다. 쿠키에서 토큰을 복사해 요청에 붙여 넣어야 했고, 만료되면 다시 같은 일을 했다.

Bruno에서는 인증 요청으로 토큰을 받아 저장하고, 환경변수를 통해 후속 요청에서 사용하도록 구성했다.

백엔드 동료도 꽤 좋아했다. 특히 토큰을 복사하고 붙여 넣는 일이 사라진 게 좋다고 했다. env 파일로 환경 설정을 남겨둘 수 있다는 점도 편하다고 했다. 지금은 무료 체험까지 신청해서 쓰고 있다. 소개한 보람이 있다.

요청 모음을 함께 관리하니 어떤 요청을 보냈는지도 같이 확인할 수 있다. 말로 설명하는 것보다 요청 하나를 같이 보는 편이 빠를 때가 많다.

다만 내가 사용하려던 OpenAPI 명세 동기화 기능은 무료 사용이 5회로 제한돼 있었다. 동료도 반복 작업이 줄어드는 걸 좋아하는 모습을 보니, 우리에게 필요한 기능을 Electron으로 직접 만들어보고 싶다는 생각이 더 커졌다. 일단은 생각 중이다.

traceparent로 클라이언트부터 요청 따라가기

회사에서는 로그와 트레이스를 확인하는 데 SigNoz를 쓰고 있다. 백엔드에는 관련 인프라가 구축돼 있었지만, 프론트엔드에서는 활용하지 않고 있었다.

서버의 기록만으로는 프론트엔드에서 어떤 과정을 거쳐 요청을 보냈는지 알기 어려웠다. 나도 클라이언트에서 시작한 요청이 서버에서 어떻게 처리됐는지 이어서 보고 싶었다.

그래서 프론트엔드에서도 기록을 남길 수 있도록 SDK를 만들고, 요청에 traceparent를 붙여 백엔드의 추적 인프라와 연결하기 시작했다.

이렇게 하니 백엔드에서도 프론트엔드가 어떻게 요청을 보냈는지 함께 살펴볼 수 있게 됐다. 동료도 디버깅이 조금 수월해진 것 같았고, 나도 그랬다. 프론트엔드와 백엔드 로그를 따로 열고 비슷한 시간대의 요청을 대조하던 수고가 줄었다.

VOC를 확인할 때도 같은 요청을 따라가며 어느 구간에서 문제가 생겼는지 함께 볼 수 있다는 점이 좋았다. 문제가 생겼을 때 동료에게 전달할 내용도 이전보다 구체적이 됐다.

지금은 앱 버전과 런타임 버전 같은 메타데이터도 남기고 있다. 특정 버전에서 문제가 집중되는지 살펴보는 데 활용할 생각이다.

SigNoz MCP도 연결해봤다. VOC를 주면 에이전트가 관련 기록을 찾아 분석하도록 할 수 있었다. 분석이 맞는지는 확인해야 하지만, 흩어진 기록을 찾는 수고는 덜 수 있었다.

변경 요청은 티켓과 PR로 남기기

변경이 필요한 부분은 Jira 티켓과 PR도 적극적으로 사용하고 있다.

옆에 앉아 있으니 말로 요청하기 쉽다. 메시지로 남기는 것도 간단하다. 그런데 그 순간에는 서로 이해했더라도, 다른 일을 하다 보면 잊기 쉽다. 요청한 사람은 기다리고 있는데, 받은 사람은 다른 작업에 밀려 놓칠 수도 있다.

나중에는 이 이야기를 어디서 했는지부터 찾아야 한다. 처리됐는지 확인하려고 다시 물어보기도 한다.

티켓으로 남기면 요청한 내용과 이유, 진행 상태를 함께 확인할 수 있다. PR에서는 실제 변경을 보며 이야기할 수 있다. 왜 이런 변경이 필요했는지 맥락이 남는 것도 좋다.

사내 메신저로 알림도 자동 전송되게 되어 있어서, 변경 사항을 계속 직접 찾아보지 않아도 흐름을 따라가기 편해졌다.

옆자리에서 먼저 이야기하고, 결정된 내용을 티켓이나 PR에 남기는 식으로 일하고 있다. 대화하면서 빨리 정리할 수 있는 부분도 있고, 기록으로 남겨야 서로 편한 부분도 있다.

앞으로도 궁금한 게 생기면 옆자리의 백엔드 개발자에게 물어볼 것 같다. 같이 화면을 보다가 생각하지 못한 방법을 찾기도 하고, 이야기를 나누는 동안 애매했던 요구사항이 정리되기도 하니까.

다만 문서에 있는 건 먼저 읽고, 이야기해서 정한 건 잘 남겨야겠다. 편하게 물어볼 수 있는 동료가 있다는 이유로 그 사람의 기억에 너무 기대지는 않도록.