PostmanAI 코딩 도구로 마이크로서비스를 만드는 일은 이제 일상이 됐습니다. 문제는 속도가 아니라 일관성입니다. AI는 보통 하나의 엔드포인트를 잘 만들지만, 여러 요청이 데이터를 주고받는 흐름과 그 흐름이 지켜야 할 계약(contract) 은 놓치기 쉽습니다.
이때 필요한 것이 API의 단일 진실 공급원(SSOT, Single Source of Truth) 입니다. 이 글에서는 Postman 컬렉션을 SSOT로 두고, AI가 생성한 코드를 그 기준에 맞춰 검증하는 방법을 실제 주문 처리(Order Processing) 데모를 예로 설명합니다.
AI 코드의 함정: 단편적인 요청
AI에게 "주문 API를 만들어줘"라고 하면 보통 POST /orders, GET /orders/{id} 같은 개별 엔드포인트를 그럴듯하게 생성합니다. 하지만 실제 업무는 한 번의 요청으로 끝나지 않습니다.
- 주문을 생성하고(
POST), 그 order_id로 상세를 조회하고(GET), - 상태에 따라 다른 후속 처리를 하고(
PUT), 필요하면 취소(DELETE)합니다.
요청과 요청 사이에 흐르는 데이터(주문 ID, 금액, 상태)가 일관되게 유지되는지는 개별 엔드포인트 테스트만으로는 알 수 없습니다.
컬렉션 하나가 명세이자 테스트이자 문서
Postman 컬렉션은 단순한 "요청 모음"이 아닙니다. 하나의 컬렉션에 다음이 모두 담깁니다.
- 요청/응답 스키마 — 각 요청의 본문과 예시 응답(Example Response)
- 검증 로직 —
pm.test(...)테스트 스크립트 - 문서 — 각 요청에 붙는 마크다운 설명
즉 컬렉션이 곧 API 명세이고, 실행 가능한 테스트이며, 사람이 읽는 문서입니다. 이것을 Git Sync로 GitHub 레포지토리와 동기화하면, 컬렉션이 코드처럼 버전 관리되고 팀 전체가 같은 기준을 공유합니다.
GitHub 레포 (postman/collections/*.json)
↕ Git Sync
Postman 워크스페이스 (팀 협업)
변수 체이닝으로 "흐름"을 검증한다
AI가 만든 코드가 단일 요청만이 아니라 데이터 흐름을 지키는지 보려면, 요청 간에 값을 넘기며 검증해야 합니다. Postman에서는 컬렉션 변수로 이를 표현합니다.
// Step 1 — POST /orders 응답에서 값 추출
const response = pm.response.json();
if (response.order_id) {
pm.collectionVariables.set('order_id', response.order_id);
pm.collectionVariables.set('expected_total', response.total_amount);
} else {
pm.execution.setNextRequest(null); // 실패 시 워크플로 중단
}
이 단계 연결(
setNextRequest)은 Collection Runner·Newman·Postman CLI에서 순차 실행될 때 동작합니다. 요청을 개별 Send로 보내면 흐름 제어가 적용되지 않습니다.
// Step 2 — GET /orders/{{order_id}} 에서 일관성 검증
pm.test('[REQ] 생성한 주문 ID와 조회 결과가 일치', function () {
pm.expect(pm.response.json().order_id).to.equal(pm.collectionVariables.get('order_id'));
});
이렇게 order_id → 조회 → 상태 업데이트 → 취소로 이어지는 4단계를 하나의 워크플로로 묶으면, AI가 생성한 API가 요청 사이의 계약을 지키는지 한 번에 확인할 수 있습니다. 상태에 따라 분기하는 조건부 검증도 가능합니다.
// Step 3 — 상태별 분기
const status = pm.collectionVariables.get('current_status');
if (status === 'shipped') {
pm.test('[REQ] 배송된 주문은 추적 번호가 있어야 한다', function () {
pm.expect(pm.collectionVariables.get('tracking_number')).to.not.be.empty;
});
}
Mock으로 "명세 우선" 개발
Postman은 컬렉션의 예시 응답을 기반으로 Mock 서버를 즉시 만들어 줍니다. 실제 백엔드가 없어도 명세대로 응답하는 가짜 엔드포인트가 생기는 것입니다.
이는 세 가지 역할을 동시에 합니다.
- 명세 문서 — 요청/응답 형태를 코드로 고정
- 개발 지원 — 프론트엔드·모바일이 백엔드 완성을 기다리지 않고 병렬 개발
- 테스트 더블 — Collection Runner가 일관된 데이터로 검증
AI에게는 이 명세(마크다운 설명 + 예시 JSON)를 입력으로 주고 구현을 생성하게 한 뒤, 같은 컬렉션으로 그 구현을 검증합니다. 명세와 구현이 어긋나면 테스트가 바로 잡아냅니다.
정리
AI는 코드를 빠르게 만들지만, "이 코드가 우리 API 계약을 지키는가"는 보장하지 않습니다. Postman 컬렉션을 SSOT로 두면,
- 명세·테스트·문서가 한곳에 모이고,
- Git Sync로 팀 전체가 같은 기준을 공유하며,
- 변수 체이닝과 Mock으로 AI가 만든 코드의 흐름과 계약을 검증할 수 있습니다.
엔터프라이즈 규모에서 이를 어떻게 통제하는지는 다음 글에서 다룹니다.