# 모의 서버 (/ko/docs/mocks)

모의 서버(mock)는 Mac의 포트에서 API처럼 응답하는 서버입니다. 프런트엔드, 앱, 테스트는 API가 만들어지기 전이나 실제 API가 멈춰 있는
동안에도 모의 서버를 사용할 수 있습니다. 모의 서버는 두 가지 출처에서 응답하며, 하나만 쓰거나 함께 쓸 수 있습니다.

- **직접 만든 경로**: 메서드, 경로, 그리고 응답할 JSON, XML, 텍스트. 본문에는 요청마다 달라지는 가짜 데이터
  (`{{$randomFullName}}`, `{{$randomEmail}}`)와 요청의 일부(`{{request.params.id}}`)를 넣을 수 있습니다. 명세는 필요 없습니다.
  [경로와 가짜 데이터](/docs/mocks/routes)를 참고하세요.
- **OpenAPI 명세**: 모든 작업이 명세에 문서화된 응답, 예제, 또는 스키마로 만든 본문으로 응답합니다. 명세를 위반하는 요청에는
  이유를 알려 주는 `400`이 돌아가므로, 클라이언트가 잘못된 것을 보내면 모의 서버가 알려 주기도 합니다.

코드나 상태가 필요한 응답에는 모의 서버에 [JavaScript 경로](/docs/mocks/scripted-routes)도 둘 수 있습니다.

사이드바의 모듈 전환기에서 **모의 서버**를 선택하거나 <kbd>⌘</kbd><kbd>4</kbd>를 눌러 페이지를 엽니다.

<Shot id="mocks-running" alt="실행 중인 Alpenglow 데모 쇼핑몰 모의 서버: 위쪽에 주소와 환경에서 사용, 중단 버튼, 명세가 표시된 설정 카드, 직접 만든 경로 두 개가 있는 경로 카드, 아래쪽에 경로와 명세가 응답한 요청의 로그가 보입니다" />

## 모의 서버 만들기 [#creating-a-mock]

사이드바의 <strong>모의 서버</strong> 헤더에서 <strong>+</strong>를 클릭하거나, 빈 페이지의 버튼을 사용하세요.

- **새로운 모의 서버**는 경로로 이루어진 모의 서버를 만듭니다. 처음에는 가짜 사용자 다섯 명으로 응답하는 `GET /users` 경로
  하나가 들어 있어서, 시작해 보면 본문으로 무엇을 할 수 있는지 바로 볼 수 있습니다. 바꾸거나 직접 경로를 추가하세요.
  [경로와 가짜 데이터](/docs/mocks/routes)를 참고하세요.
- **명세의 모의 서버**(**+** 메뉴, 또는 빈 페이지의 **명세의 모의 서버**)는 작업 공간에 있는 명세로 모의 서버를 만듭니다.
  예: **Alpenglow demo shop의 모의 서버**.

새 모의 서버는 `4010`부터 비어 있는 다음 포트를 사용합니다. 설정과 경로는 작업 공간의 `mocks` 폴더에 파일로 저장되므로, 팀은
Git으로 모의 서버를 공유합니다.

경로로 이루어진 모의 서버가 명세를 함께 제공할 수도 있고, 명세로 만든 모의 서버에 경로를 둘 수도 있습니다. **설정** 카드의
**명세 제공**으로 명세를 추가하고, **변경** › **명세 제공 중단**으로 뺍니다.

## 시작과 중단 [#starting-and-stopping]

**시작**(<kbd>⌘</kbd><kbd>R</kbd>)을 클릭합니다. 위쪽 막대에 `http://127.0.0.1:4010` 같은 모의 서버의 주소가 표시됩니다. 모의 서버가
제공하는 명세의 서버 URL에 경로가 있으면(`https://demo.echolot.dev/v1`) 주소도 그 경로로 끝나고(`http://127.0.0.1:4010/v1`)
모의 서버는 그 경로 아래에서 응답합니다. 요청에서 그 경로를 생략해도 됩니다. 주소 옆의 복사 버튼은 주소를 복사합니다.

터미널에서 시험해 보세요.

```sh
curl http://127.0.0.1:4010/users
```

**중단**을 누르면 멈춥니다. 사이드바에서 어떤 모의 서버가 실행 중인지 볼 수 있습니다. 초록색 점이 표시되고, 명세 제목 옆에는 포트,
경로로 만든 모의 서버에는 경로 수가 표시됩니다(`Alpenglow demo shop · :4010`, `3 routes · stopped`). 모의 서버를 오른쪽 클릭하면
<strong>시작</strong> 또는 <strong>중단</strong>과 <strong>삭제…</strong>가 나타납니다. 삭제하기 전에 확인을 요청하며, 설정 파일은 휴지통으로 이동하고 명세는 그대로
남습니다.

모의 서버는 작업 공간 윈도우가 열려 있는 동안 실행됩니다. 실행 중인 모의 서버는 멈추지 않고도 경로, 명세, 설정의 변경을 반영합니다.
다른 프로그램이 사용 중인 포트는 쓸 수 없으며, Echolot이 그렇게 알려 주면 다른 포트를 고르세요.

### 모의 서버로 요청 보내기 [#sending-requests-to-the-mock]

- **경로** 카드의 **요청 생성**은 모의 서버의 경로를 호출하는 요청 폴더를 만들고, `{{baseUrl}}`을 모의 서버의 주소로 설정합니다.
  [경로에서 요청 만들기](/docs/mocks/routes#requests-from-routes)를 참고하세요.
- **환경에서 사용**(모의 서버가 실행 중일 때)은 `{{baseUrl}}`이 모의 서버의 주소인 `Mock: <name>`이라는 환경을 만들고 활성화합니다.
  명세로 [요청 생성](/docs/specs#requests-that-follow-the-spec)이 만든 요청처럼 `{{baseUrl}}`로 시작하는 요청은 다른 환경을 고를
  때까지 모의 서버로 갑니다. [환경](/docs/workspaces/environments)을 참고하세요.

## 설정 [#settings]

| 설정 | 하는 일 |
| --- | --- |
| **이름** | 사이드바에 표시되는 모의 서버의 이름. |
| **명세** | 제공하는 명세, 또는 **없음: 경로만 응답**. **열기**는 명세 페이지에서 명세를 열고, **명세 제공**과 **변경**은 명세를 고르거나 제공을 중단합니다. |
| **포트** | 수신 대기하는 포트(1~65535). |
| **네트워크의 다른 기기에 응답** | 모든 네트워크 인터페이스에서 수신 대기합니다. 휴대전화나 컨테이너에서 테스트할 때 사용합니다. 끄면 이 Mac에서만 접근할 수 있습니다. |
| **지연** | 응답하기 전에 기다릴 시간(밀리초, 최대 60,000). 느린 API를 시험할 때 사용합니다. |
| **실패** | 일부러 `500`을 반환할 요청의 비율. 클라이언트가 어떻게 대처하는지 시험할 때 사용합니다. |
| **검사** | 명세가 있을 때: **명세를 위반하는 요청 거부(이유와 함께 400 응답)**. 기본으로 켜져 있습니다. |

## 요청에 대한 응답이 정해지는 방식 [#which-response-a-request-gets]

요청은 다음 중에서 메서드와 경로에 맞는 응답이 있는 첫 번째로 갑니다.

1. 모의 서버의 [JavaScript 경로](/docs/mocks/scripted-routes). 아무것도 설정하지 않는 경로는 요청을 다음으로 넘깁니다.
2. [직접 만든 경로](/docs/mocks/routes). 경로에는 응답이 여러 개 있을 수 있습니다. 요청이 이름이나 상태로 응답 하나를 지정할 수
   있고, 요청에 대한 규칙이 다른 응답을 고르며, 그 외에는 경로의 기본 응답이 응답합니다.
3. 아래에 설명한 명세의 작업.

경로와 작업 모두에서 고정 경로 구간이 매개변수보다 우선하므로 `/pets/mine`이 `/pets/{id}`보다 먼저 선택됩니다.

명세의 작업에 대해서는 모의 서버가 다음 순서로 응답을 고릅니다.

1. 요청이 지정한 것: `Prefer: code=404, example=empty` 헤더, 또는 Postman의 `x-mock-response-code`와
   `x-mock-response-name` 헤더.
2. **명세 응답** 카드에서 작업에 대해 고른 응답.
3. 작업의 첫 번째 성공 응답.

**명세 응답** 카드는 모든 작업을 메뉴와 함께 나열합니다. **첫 번째 성공 응답**이나 문서화된 상태 중 하나를 고를 수 있고, 예제가
여러 개인 상태에서는 예제도 고릅니다. 선택은 모의 서버와 함께 저장됩니다.

본문은 응답의 이름이 있는 예제(요청이 지정한 것, 없으면 첫 번째), 단일 `example`, 또는 스키마로 만든 본문입니다. 스키마로 만들 때는
각 필드의 타입, 형식, 이름에 맞는 가짜 데이터(형식이 `email`인 필드에는 이메일 주소)를 스키마의 제한 안에서 요청마다 새로 만듭니다.
경로 매개변수와 이름이 같은 필드는 그 값을 그대로 반복합니다. 명세에 미디어 타입이 여러 개 문서화되어 있으면 요청의 `Accept` 헤더가
하나를 고릅니다. 문서화된 헤더와 콘텐츠 타입도 함께 전송됩니다. `204`, `304`, `HEAD`에 대한 응답에는 본문이 없습니다.

모의 서버가 주는 그 밖의 응답은 다음과 같습니다.

| 상태 | 시점 |
| --- | --- |
| `400` | 모의 서버가 명세를 제공하고, 검사가 켜져 있으며, 요청이 명세를 위반할 때: 경로, 쿼리, 헤더, 쿠키 매개변수가 없거나 타입이 틀렸을 때, 콘텐츠 타입이 틀렸을 때, 본문이 JSON 스키마와 맞지 않을 때. 본문에 모든 이유가 나열됩니다. |
| `404` | 그 경로를 가진 경로 또는 작업이 없을 때. |
| `405` | 경로는 있지만 이 메서드로는 없을 때. `Allow` 헤더에 경로와 명세를 합쳐 받을 수 있는 메서드가 나열됩니다. |
| `413` | 요청 본문이 32 MB보다 클 때. |
| `500` | 일부러 일으킨 실패(**실패** 참고). |
| `501` | 작업에 요청한 상태에 대한 응답이 문서화되어 있지 않을 때. |

브라우저가 다른 포트의 페이지에서 모의 서버를 호출할 수 있습니다. 모의 서버는 프리플라이트 요청에 응답하고 CORS 헤더를 보냅니다.

## 로그 [#the-log]

페이지 아래쪽에는 선택한 모의 서버가 응답한 요청이 최신 순으로 나열됩니다. 시간, 상태, 메서드와 경로, 사용한 응답(경로의 응답 이름,
명세 예제의 이름, 또는 본문이 스키마에서 만들어졌을 때의 `generated`), 걸린 시간이 표시됩니다. 문제는 요청 아래 줄에 표시됩니다.
요청이 명세를 위반한 곳이나 경로의 본문에서 만들 수 없었던 가짜 값입니다. 요청 위에 포인터를 올리면 응답 본문, 요청 본문, 콘텐츠
타입을 볼 수 있고, **응답 복사**는 본문을 복사합니다. **지우기**는 로그를 비웁니다.

Apple의 온디바이스 모델을 사용할 수 있는 환경에서는 **지우기** 옆의 버튼이 로그를 요약합니다.

## 명세에 예제 저장하기 [#saving-examples-into-the-spec]

명세의 작업에서는 명세가 모의 서버가 응답하는 내용의 유일한 출처이므로, 실제로 받은 응답은 명세에 예제로 저장합니다.
[기록](/docs/workspaces/history)에서 명세를 따르는 요청의 교환을 오른쪽 클릭하고 <strong>모의 서버 예제로 저장…</strong>을 선택하세요. `two tents`
같은 이름을 붙이고 **저장**을 클릭합니다.

응답은 요청이 따르는 명세에서 해당 작업의 응답에 대한 이름 있는 예제가 됩니다. **명세 응답** 카드에서 고르거나
`Prefer: example=two tents`로 지정할 수 있습니다.

명세에 없는 경로나 명세가 없는 모의 서버에는 [경로](/docs/mocks/routes)를 만들고 본문을 붙여 넣으세요.

## 네트워크에서 공유하기 [#sharing-on-the-network]

휴대전화, 태블릿, 컨테이너에서 모의 서버에 접근하려면 **네트워크의 다른 기기에 응답**을 켭니다. 다른 기기에서는 로컬 네트워크에서의
Mac 주소와 모의 서버의 포트를 사용합니다.

처음에는 macOS가 Echolot이 로컬 네트워크의 기기를 찾아 연결해도 되는지 물어볼 수 있습니다. 허용하지 않으면 다른 기기에서 모의
서버에 접근할 수 없습니다. 나중에 **시스템 설정 › 개인정보 보호 및 보안 › 로컬 네트워크**에서 답을 바꿀 수 있습니다.

켜 두면 네트워크의 누구나 모의 서버를 호출할 수 있습니다. 필요하지 않을 때는 공유를 끄세요.

## 명령줄에서 [#from-the-command-line]

`echolot mock alpenglow.yaml`은 명세 파일을 제공하고, `echolot mock -w <workspace> <mock>`은 작업 공간의 모의 서버를 설정과 경로
그대로(명세 유무와 관계없이) CI나 컨테이너에서 제공합니다. [echolot mock](/docs/cli/mock)을 참고하세요.
[`echolot fake`](/docs/cli/fake)는 같은 템플릿으로 가짜 데이터를 만들어 픽스처와 시드 데이터에 사용할 수 있게 합니다.

에이전트는 Echolot의 MCP 서버로 모의 서버를 시작하고 로그를 읽을 수 있으며, **모의 서버** 도구 모음이 켜져 있으면 모의 서버를 만들고,
경로를 추가하고 바꾸고, 가짜 데이터를 생성하고, 경로에서 요청을 만들 수 있습니다. [에이전트](/docs/ai/agents)를 참고하세요.