Mock Server (선택적 프록시)

Free Rider는 로컬 HTTP 서버에서 선택한 엔드포인트만 OpenAPI 기반 목 응답으로 대체하고, 나머지 요청은 실제 Upstream 서버로 전달합니다.

시작하기

1. 컬렉션에서 상단 Mock 버튼을 누릅니다.
2. Upstream URL은 현재 선택한 환경의 이 기본값입니다. 필요하면 다른 HTTP(S) URL을 입력해 덮어쓰고, 비워두면 Proxy 전달을 끌 수 있습니다.
3. Endpoint Rules에서 목킹할 요청을 Mock으로 전환하고 나머지는 Proxy로 둡니다.
4. 스키마 생성, OpenAPI 예시, 직접 작성 중 응답 모드를 정하고 미리보기에서 검증합니다.
5. 시작을 누르고 프론트엔드 API base URL을 http://127.0.0.1:4010 으로 바꿉니다.
6. 앱의 저장 버튼으로 Mock 규칙과 로컬 설정을 저장합니다.

GET /users를 Mock으로, POST /orders를 Proxy로 지정하면 첫 번째는 가짜 JSON, 두 번째는 실제 API 응답을 돌려줍니다. 규칙이 없는 경로도 기본 Proxy입니다. 선택 환경을 바꾸면 실행 중인 Mock 서버의 Upstream도 새 환경의 baseUrl에 맞게 갱신됩니다. 명시적으로 입력한 Upstream 주소는 유지됩니다. baseUrl이 없거나 Mock/MCP 서버 자신의 주소를 가리키면 설정 오류로 시작 또는 갱신이 차단됩니다.

엔드포인트에서 바로 Mocking

REST 요청 탭의 상단 Mocking 버튼을 누르면 해당 엔드포인트에 기본 Mock 규칙을 만들고 Mock 서버 화면의 해당 경로로 바로 이동합니다. 기존에 Mock 규칙이 있다면 새로 중복 생성하지 않고 기존 규칙을 열며, Proxy로 설정된 기본 규칙은 Mock으로 변경합니다. 조건별 응답 및 이름 있는 시나리오 규칙은 유지됩니다.

OpenAPI JSON 응답 스키마가 있다면 자동으로 스키마 생성 모드로 시작합니다. 스키마가 없다면 직접 작성 모드로 시작합니다. 요청에 저장하지 않은 수정사항이 있으면 먼저 해당 요청을 저장합니다. Mock 규칙 변경 후에는 워크스페이스도 저장해야 합니다. 실행 중인 동일 컬렉션의 Mock 서버에는 즉시 변경사항 반영을 시도합니다.

Mock 서버의 Endpoint Rules / Scenario Rules 상단 검색 입력은 HTTP 메서드, 경로, 요청 이름, 폴더로 목록을 필터링합니다. 검색 결과 개수를 표시하며, 지우기로 전체 목록을 다시 표시할 수 있습니다. 검색은 설정을 변경하지 않습니다.

응답 동작

• OpenAPI 응답 status, content-type, schema를 사용합니다.
• 스키마 생성은 필수 필드, 타입, enum, 값의 범위와 길이, 배열, 조합 조건 등을 검사합니다.
• OpenAPI 예시가 있는 경우 해당 JSON을 반환할 수 있습니다.
• 직접 작성한 JSON도 스키마가 있다면 검증하며, 위반 시 성공 응답 대신 오류를 반환합니다.
• 사용자 정의 경로는 OpenAPI 없이 직접 JSON을 반환하도록 등록할 수 있습니다.
• 순환 참조나 생성할 수 없는 제약은 오류로 처리합니다.

Network 기록

외부 프론트엔드의 Mock/Proxy 트래픽이 Network 탭에 구분됩니다. 인증/쿠키 헤더, 비밀번호·토큰 등의 JSON 필드는 마스킹하고 비 JSON 본문은 보관하지 않습니다.

제한과 보안

• 기본 OFF. 앱 재시작 시 자동 실행하지 않습니다. 주소는 127.0.0.1로 고정합니다.
• 기본 포트 4010. 포트 변경이나 다른 컬렉션 실행은 먼저 중지 후 진행합니다.
• Upstream은 명시적인 HTTP/HTTPS 서버만 허용하며 자기 자신과 MCP 서버로의 반복 호출을 차단합니다.
• 요청/응답 본문 최대 8MB, 히스토리 본문 최대 512KB.
• 현재 SSE/WebSocket 프록시, HTTPS MITM, 시스템 트래픽 가로채기, 상태 기반 가상 데이터베이스를 지원하지 않습니다.
• CORS는 localhost 기반 프론트엔드 개발을 대상으로 합니다. 원격 웹사이트 사용 용도가 아닙니다.
• 쿠키의 Domain/Secure/SameSite 제약으로 HTTPS·교차 도메인 로그인 동작은 실제 환경과 다를 수 있습니다.
• 압축 응답은 전달 과정에서 풀릴 수 있어 큰 바이너리/스트리밍 API에는 적합하지 않습니다.
• Mock 규칙은 컬렉션 Git 내보내기에 포함될 수 있으므로 개인정보와 실제 토큰을 입력하지 마세요.

코스 및 MCP 시나리오 연동은 후속 작업입니다.

Network 응답을 Mock 규칙으로 전환

1. Free Rider에서 API를 실행하거나 로컬 Mock Proxy의 요청을 발생시킵니다.
2. 상단 Network 탭에서 JSON 응답을 선택하고 Mock this response를 누릅니다.
3. 대상 컬렉션을 선택합니다. OpenAPI 요청과 매칭되면 실제 URL (예: /users/42) 대신 템플릿 경로 (예: /users/{id})를 사용합니다.
4. 자동으로 마스킹된 JSON을 확인하고 필요한 값을 직접 수정합니다. 토큰·비밀번호 등의 필드는 [redacted]로 대체되며, 다른 개인정보는 수동 확인이 필요합니다.
5. DTO 검증을 눌러 응답 스키마와 일치하는지 확인합니다. 기존 Mock 규칙이 있으면 덮어쓰기 확인란을 선택해야 합니다.
6. Mock 규칙 추가를 누른 뒤, 상단 저장 버튼으로 워크스페이스에 보관합니다. 실행 중인 동일 컬렉션의 서버에는 즉시 규칙 반영을 시도합니다.

본문이 잘린 응답, 비 JSON 응답, 응답 본문이 없는 HTTP 상태, 잘못된 JSON은 자동 전환하지 않습니다. Network에서 가져온 자료는 편집 가능한 초안이며 원본 기록은 변경하지 않습니다. URL의 쿼리 문자열은 규칙에 포함하지 않습니다.

조건별 응답과 장애 시뮬레이션

같은 HTTP 메서드·경로에 조건부 응답을 여러 개 등록할 수 있습니다. Mock 화면에서 엔드포인트의 + 조건 추가를 누른 뒤 Match JSON에 조건을 입력합니다.

{
  "query": { "scenario": "unavailable" },
  "headers": { "X-Debug": "yes" },
  "body": { "user": { "type": "test" } }
}

• query는 쿼리 파라미터 값이 정확히 일치해야 합니다. 같은 키가 여러 번 포함된 경우 그중 하나가 일치하면 됩니다.
• headers는 이름의 대소문자를 구분하지 않지만 값은 정확히 비교합니다.
• body는 JSON 객체의 부분 일치를 지원합니다. 중첩된 지정 필드는 모두 일치해야 하며, 배열은 정확히 일치해야 합니다.
• 세 종류의 조건을 함께 입력하면 모두 일치해야 합니다(AND).
• 동일한 경로에서는 조건이 많은 규칙이 먼저 선택됩니다. 단, 정적 경로가 경로 파라미터보다 우선합니다. 동일한 우선순위이면 컬렉션에 저장한 순서를 따릅니다.
• 조건부 규칙에 일치하는 것이 없다면 엔드포인트의 기본 Mock/Proxy 규칙을 실행하며, 그마저 없으면 Upstream으로 프록시합니다.
• 기존 조건 없는 Mock 규칙은 이전과 똑같이 동작합니다. Network → Mock은 조건부 응답을 덮어쓰지 않고 기본 규칙만 추가하거나 교체합니다.

각 기본 Mock 또는 조건부 응답에서 **Delay (ms)**를 0~30,000ms로 설정할 수 있습니다. Failure simulation에서 다음 동작을 선택할 수 있습니다.

옵션	동작
Normal response	지정 상태 코드·JSON 본문을 반환합니다. HTTP 4xx/5xx를 입력하면 오류 응답을 테스트할 수 있습니다.
HTTP 504 timeout	설정한 지연 시간 후 JSON 형태의 HTTP 504를 반환합니다. 실제 소켓 타임아웃이 아니라 의도적인 모의 응답입니다.
Disconnect socket	지연 후 응답을 보내지 않고 연결을 끊습니다. 클라이언트에서 네트워크 예외 처리를 시험할 수 있습니다.

연결 끊김은 Network 기록에서 실패로 남습니다. 장애 모드일 때에는 일반 JSON 응답 스키마 검증을 우회하며, 정상 응답 모드에서는 기존 OpenAPI 계약 검증을 유지합니다. 외부에서 접근 가능한 서버나 공격용 트래픽 생성기가 아니며 localhost 개발 환경에서만 실행됩니다.

이름 있는 Mock 시나리오와 코스 연동

Mock 화면의 Scenario Profiles에서 프로필을 만들고 이름을 지정할 수 있습니다. 기본 규칙은 모든 시나리오에서 공통으로 적용되며, 특정 시나리오를 선택해 추가한 규칙은 그 시나리오가 활성화된 경우에만 적용됩니다. 같은 경로에서는 활성 시나리오 규칙이 기본 규칙보다 우선합니다.

1. 새 시나리오 이름을 입력하고 시나리오 생성을 누릅니다.
2. 편집기에서 대상 API에 Mock을 지정하고 응답 JSON·조건·지연 값을 설정합니다. 상속은 프로필의 기본 규칙을 그대로 따릅니다.
3. 실행 서버에 적용으로 실행 중인 서버에서 해당 시나리오를 테스트할 수 있습니다. 이 선택은 일시적이며 서버 재시작 시 기본 규칙으로 돌아갑니다.
4. Ride 화면에서 코스를 선택한 뒤 이 코스의 Mock 시나리오에 원하는 프로필을 연결합니다.
5. 저장 후 Ride를 실행하면 해당 시나리오로 응답을 선택하고, 실행 종료 후에는 이전 프로필로 복원합니다.

시나리오가 연결된 코스는 동일 컬렉션의 Mock 서버가 실행 중이어야 합니다. 다른 코스가 시나리오를 사용 중일 때에는 프로필 변경을 잠시 차단합니다. 서버가 중간에 중지되는 등 실행 환경이 바뀌면 코스 또는 서버 상태를 다시 확인해야 합니다.

MCP 도구

로컬 MCP 연결에서 다음 도구를 사용할 수 있습니다.

도구	기능
get_mock_server	Mock 서버 상태·시나리오 목록·규칙 개수 확인
list_mock_rules	본문과 조건 값을 노출하지 않는 규칙 요약 조회
start_mock_server / stop_mock_server	저장된 설정을 바탕으로 서버 시작/중지
select_mock_scenario	실행 중인 서버의 활성 프로필 변경 (빈 ID는 기본 규칙)
set_mock_scenario	새 프로필 생성 또는 이름 변경
set_mock_rule	새 규칙 추가 또는 index를 지정한 기존 규칙 교체
delete_mock_scenario / delete_mock_rule	시나리오와 연결된 코스 바인딩 또는 개별 규칙 삭제

코스의 set_course는 mockScenarioId를 받습니다. ride_course는 프로필을 자동 선택하며 종료 후 복원합니다.

MCP에서 변경을 저장하려면 먼저 워크스페이스를 저장해야 합니다. MCP의 서버 시작은 임의 원격 호스트를 선택하지 않고 해당 컬렉션에 이미 저장된 Upstream·포트만 사용합니다. 시나리오와 규칙이 변경되면 저장된 워크스페이스가 갱신됩니다. 주의: JSON 응답 본문에 개인정보·토큰을 직접 넣지 마세요.