模拟服务器

模拟服务器运行在 Mac 的某个端口上，像 API 一样应答。前端、App 和测试可以在 API 还不存在时，或真实 API 停机时使用它。模拟服务器的应答有两个来源，可单独使用，也可一起使用：

• 手动创建的路由：一个方法、一个路径，以及它应答的 JSON、XML 或文本。正文可以包含每次请求都会变化的示例数据（{{$randomFullName}}、{{$randomEmail}}），也可以引用请求的各个部分（{{request.params.id}}）。无需规范。参见路由和示例数据。
• OpenAPI 规范：每个操作都用规范记录的响应、示例，或根据其 Schema 生成的正文来应答。违反规范的请求会得到一个说明原因的 400，因此客户端发送了错误内容时，模拟服务器也会告诉你。

如果应答需要代码或状态，模拟服务器还可以使用 JavaScript 路由。

在边栏的模块切换器中选择模拟服务器，或按 ⌘4，即可打开该页面。

创建模拟服务器Copy Anchor Link

点按边栏模拟服务器标题中的 +，或使用空页面上的按钮：

• 新建模拟服务器创建一个由路由构成的模拟服务器。它自带一个路由 GET /users，应答五个示例用户，因此你可以直接启动它，看看正文能做什么。可以修改它，或添加你自己的路由；参见路由和示例数据。
• 规范的模拟服务器（在 + 菜单中，或空页面上的规范的模拟服务器）为工作区中的一个规范创建模拟服务器，例如 Alpenglow demo shop 的模拟服务器。

新的模拟服务器使用从 4010 起的下一个空闲端口。它的设置和路由是工作区 mocks 文件夹中的一个文件，因此团队可以通过 Git 共享模拟服务器。

由路由构成的模拟服务器也可以根据规范提供服务，而规范的模拟服务器也可以有路由：设置卡片中的根据规范提供服务会添加一个规范，更改 › 停止根据规范提供服务则去掉它。

启动和停止Copy Anchor Link

点按开始（⌘R）。顶部的栏会显示模拟服务器的地址，例如 http://127.0.0.1:4010。如果模拟服务器提供服务的规范的服务器 URL 带有路径（https://demo.echolot.dev/v1），地址会以该路径结尾（http://127.0.0.1:4010/v1），模拟服务器也在该路径下应答；请求也可以省略该路径。地址旁边的拷贝按钮会拷贝地址。

在“终端”中试试：

curl http://127.0.0.1:4010/users

停止会停止它。边栏会显示哪些模拟服务器正在运行：一个绿点，以及规范标题旁的端口或路由数量（Alpenglow demo shop · :4010、3 routes · stopped）。右键点按模拟服务器可选择开始或停止以及删除…。删除前会先询问；设置文件会移到废纸篓，规范则保留。

模拟服务器在其工作区窗口打开期间运行。运行中的模拟服务器会在不停止的情况下采用对路由、规范和设置的更改。已被其他程序占用的端口无法使用：Echolot 会告知这一点，请另选一个端口。

向模拟服务器发送请求Copy Anchor Link

• 路由卡片中的创建请求会创建一个文件夹，其中的请求调用模拟服务器的路由，{{baseUrl}} 设为模拟服务器的地址。参见从路由创建请求。
• 在环境中使用（模拟服务器运行时）会创建一个名为 Mock: <name> 的环境，其 {{baseUrl}} 为模拟服务器的地址，并将其设为当前环境。以 {{baseUrl}} 开头的请求，例如生成请求根据规范生成的那些，随后会发往模拟服务器，直到你选择其他环境。参见环境。

设置Copy Anchor Link

请求得到哪个响应Copy Anchor Link

请求会交给下面第一个对其方法和路径有应答的来源：

1. 模拟服务器的 JavaScript 路由。什么都不设置的路由会把请求传给下一个来源。
2. 它的手动创建的路由。一个路由可以有多个响应；请求可以按名称或状态要求其中一个，请求上的规则会选择其他的，否则由路由的默认响应应答。
3. 规范的操作，见下文。

字面路径段优先于参数，因此无论是路由还是操作，/pets/mine 都会先于 /pets/{id} 被选中。

对于规范的某个操作，模拟服务器按以下顺序选择响应：

1. 请求所要求的：Prefer: code=404, example=empty 标头，或 Postman 的 x-mock-response-code 和 x-mock-response-name 标头。
2. 在规范中的响应卡片中为该操作选定的响应。
3. 该操作的第一个成功响应。

规范中的响应卡片以菜单列出每个操作：第一个成功响应，或某个已记录的状态；若某个状态有多个示例，则还可选择示例。这一选择随模拟服务器一起存储。

正文是响应中具名的示例（所要求的那个，或第一个）、它唯一的 example，否则是根据其 Schema 生成的正文：符合每个字段的类型、格式和名称的示例数据（格式为 email 的字段会得到电子邮件地址），在 Schema 的限制之内，每次请求都会重新生成。与路径参数同名的字段会重复该参数的值。如果规范记录了多种媒体类型，则由请求的 Accept 标头选择其一。已记录的标头和内容类型也会一并发送。204、304 以及对 HEAD 的应答没有正文。

模拟服务器给出的其他应答：

浏览器可能从另一个端口上的页面调用模拟服务器：它会应答预检请求并发送 CORS 标头。

日志Copy Anchor Link

页面底部列出所选模拟服务器应答过的请求，最新的在前：时间、状态、方法和路径、所用的响应（路由的响应名称、规范示例的名称，或正文由 Schema 生成时的 generated），以及耗时。问题显示在请求下方的行中：它在哪里违反了规范，或路由正文中无法生成的示例值。将指针停留在请求上，可查看响应正文、请求正文和内容类型；拷贝响应会拷贝正文。清除会清空日志。

如果 Apple 的设备端模型可用，清除旁边的按钮会为日志生成摘要。

把示例存入规范Copy Anchor Link

对于规范的操作，规范是模拟服务器应答内容的唯一来源，因此你得到的真实响应要作为示例存储在规范中：在历史记录中，右键点按遵循该规范的请求的某次交换，选择存储为模拟示例…。为它起个名字，例如 two tents，然后点按存储。

该响应会成为请求所遵循的规范中对应操作的响应的一个具名示例。可以在规范中的响应卡片中选择它，或用 Prefer: example=two tents 来要求它。

对于规范中没有的路径，或没有规范的模拟服务器，请创建一个路由并粘贴正文。

在网络上共享Copy Anchor Link

打开应答网络上的其他设备，即可从手机、平板电脑或容器访问模拟服务器。其他设备使用你的 Mac 在本地网络上的地址，加上模拟服务器的端口。

第一次使用时，macOS 可能会询问是否允许 Echolot 查找本地网络上的设备并与其连接。请选择允许，否则其他设备无法访问模拟服务器。之后可以在系统设置 › 隐私与安全性 › 本地网络中更改这个选择。

网络上的任何人随后都可以调用该模拟服务器。不需要时请关闭共享。

通过命令行Copy Anchor Link

echolot mock alpenglow.yaml 提供规范文件的服务，echolot mock -w <workspace> <mock> 则提供工作区中某个模拟服务器的服务，带着它的设置和路由，无论有没有规范，适用于 CI 或容器。参见 echolot mock。echolot fake 根据相同的模板生成示例数据，用于测试夹具和种子数据。

智能体可以通过 Echolot 的 MCP 服务器启动模拟服务器并读取它们的日志；当模拟服务器工具集开启时，还可以创建模拟服务器、添加和更改路由、生成示例数据，并根据路由创建请求。参见智能体。