밴드 플랫폼 서버 개발 일지 - 협업 툴로서 Postman 도입 및 작업 환경

프론트엔드와 협업을 위해 보통 스웨거가 많이 쓰인다.

하지만 스웨거는 컨트롤러 코드에 침투해 코드가 오염되는 단점이 있다.

그래서 포스트맨 워크스페이스를 활용해 스웨거를 대체해보려 한다.

협업 문서로서 포스트맨 도입 배경

스웨거 코드를 인터페이스로 분리할 수도 있고, 어노테이션으로도 공통 관심사를 뺄 수 있지만

애플리케이션 코드에 남겨야하는 부담이 있다. 즉, 스웨거가 잘못되었을 때 서버 재배포가 이루어져야 스웨거 수정이 가능하다.

AI를 활용해서 작성하면 귀찮음도 떨어지고 실수할 일도 없겠지만

스웨거 코드 고쳐서 배포하다가 서버 떨어질 아주 낮은 확률을 방지해보고자 하는 의도가 있었다.

그리고 사실 개인적으로 포스트맨을 잘 써보고 싶었다. 

(보통 스웨거가 편하기 때문에 협업 시작하면 다시 돌아갈 수도 있다. 프론트엔드 개발자를 설득할 자신은 없다.)

 

그렇다면 왜 포스트맨을 써보려 했나?

API 문서로도 활용이 가능하지만 궁극적으로 테스트 자동화까지 시도하고싶다.

코덱스에서 충분히 가능하지만, 컨트롤러 통합테스트를 언젠가 일일이 시도하기에는 시간도, 토큰도 많이 소모될 것이다.

'포스트맨을 잘 작성해놓고 MCP를 세팅한다면 로컬에서 테스트 편하게 가능하지 않을까?'라는 생각에서 출발했다.

결론적으로 테스트 자동화는 AI없이 Github action CI로 세팅하는게 더 편리하다고 한다.

개인 프로젝트에서는 Local 방식으로 MCP를 연동해 포스트맨 테스트 자동화가 가능하다.

하지만 협업시에는 모두 동일한 환경에서 진행하지 않기에 깃헙 액션을 활용함이 좋을 것 같다.

 

MCP 연동

https://github.com/postmanlabs/postman-mcp-server

https://learning.postman.com/docs/reference/postman-api/postman-mcp-server/overview

생각보다 문서가 친절하게 잘 작성되어있었다.

MCP를 연결할 때 2가지 방식이 있다.

Remote, Local 방식이 각각 존재한데 간단히 각각 알아보면,

 

Local MCP

로컬 방식은 내 맥북에서 mcp 서버를 띄워 더 여러 조작을 할 수 있다.

로컬에서 서버를 띄워 동작하다보니 내가 띄워놓은 스프링 서버에 직접 접근이 가능하다.

직접적으로 codex가 포스트맨으로 로컬 서버에 여러 요청을 찔러보고 실제 에러/응답 코드를 확인하여 변경할 수 있다.

환경 변수나 로컬 파일을 외부에 유출하지 않기 때문에 보안이 강화된다.

 

Remote MCP

Remote MCP는 포스트맨 쪽 클라우드 mcp 서버에 붙는 것이다.

공홈에 있듯 https://mcp.postman.com/minimal 이 Postman Cloud 쪽에서 작업이 이루어진다.

 

Local MCP가 직접적으로 포스트맨을 로컬 서버에 쏘면서 세팅이 가능하다는 장점이 있는데,

세팅도 조금 더 복잡하고 크게 와닿지 않아 간편한 Remote MCP를 사용해 세팅했다.

 

세팅

1. MCP 연동

간단하다.

codex mcp add postman --remote-url https://mcp.postman.com/minimal

나는 codex 경로가 달라서 몇가지 명령어 더 입력했는데,

명령어 입력하면 웹에서 로그인 진행하고 연동이 끝난다.

 

2. 작업 환경 세팅

작업 스레드(채팅)을 2개로 분리해서 각각 다른 워크트리에서 병렬로 작업을 돌렸다.

하지만 lazycodex ulw-plan 명령어로 계속 계획을 뽑아내며

서로 병렬로 돌릴 작업 분배하고 하다보니 스레드 분리가 필요하다고 생각했다.

 

따라서 4가지 스레드를 워크트리를 각각 나누어 작업을 생각했다.

계획, 작업1, 작업2, 포스트맨 작성 이렇게 4가지로 스레드를 분리했고 워크트리도 각각 분리했다.

작업은 이러한 순서로 진행된다.

1. 계획 스레드에서 ulw-plan을 사용해 병렬로 돌릴 작업을 선정하고 프롬프트까지 뽑는다.

2. 작업1, 작업2 스레드에서 1에서 세운 계획을 붙여넣고 ulw-plan을 사용해 구체적 작업 계획을 세운다.

3. ulw-start로 작업을 실행한다.

4. 작업 완료 이후에 포스트맨 스레드에서 API 명세를 작성한다.

생각보다 나쁘지 않은 것 같아서 당분간은 이렇게 할 예정이다.

 

실제 작업 진행

MCP 연동하고 codex한테 만들어달라하니 Collections를 잘 만들어준다.

우측 하단 Pull from Cloud 버튼 클릭하면 내 로컬 워크스페이스와 연동 잘 된다.

 

회원가입 API를 테스트로 만들어 봤는데 나쁘지 않았다.

애플리케이션 코드를 codex가 직접 확인해서 성공/실패 케이스 모두 요청해볼 수 있도록 만들어져있다.

하지만 아직 스웨거처럼 간편하게 api 연동에 필요한 정보들을 모두 얻기는 어렵다 판단된다.

프롬프팅해서 넣어보니 많이 괜찮아졌다. 요청 필드도 추가되었고 하단에 응답도 추가되었다.

하지만 아직 백엔드 기준으로 DTO 명이나 응답들이 써있어서 아쉽다.

이정도면 협업할 때 불편함 없이 사용해볼 수 있을 것 같다.

엔드포인트, 요청, 성공/에러 응답 모두 한 눈에 편하게 체크해 활용 가능해보인다.

로그인 이후부터는 스크립트 활용해서 access token 자동으로 들어가서 api 요청될 수 있도록 세팅해보려한다.

 

앞으로 불편함이 생길때마다 디벨롭하며 이 글에 추가해보려 한다.

개발자가 많아지면 스웨거 쓰는게 좋을 것 같은데,

적은 인원의 협업 환경(4명으로 알고있음)은 무료니까 한번 쯤 생각해보아도 나쁘지 않을 것 같다.