MockDeck

静态示例的优势

保持正确的文档

当开发人员阅读您的API参考时，他们会寻找清晰的请求和响应对。OpenAPI示例为他们提供了这种对，且没有任何动态部分。您可以直接将JSON复制到curl命令中，并查看服务器应该返回的内容。由于示例存在于规范内，因此当您更改模式时，它会自动更新，工具如Redoc可以直接在文档中渲染它。

审查和合同讨论

在API设计审查期间，利益相关者经常对有效载荷的形状发表评论。拥有一个具体的示例可以更容易地发现缺失的字段或错误类型。您可以指向规范中的示例并说“这是我们同意的”。此次对话无需运行服务器。

SDK生成

模拟服务器添加价值时

前端集成

当UI团队开始进行真正的HTTP请求时，他们需要一个可以响应的服务器。模拟服务器监听一个端口，匹配请求路径和方法，并返回响应。这使得前端可以独立于后端时间表工作。你可以模拟延迟、错误代码或部分数据，而无需等待真正的服务。

演示环境

当你向潜在客户展示产品时，你希望UI感觉活跃。用真实数据填充的模拟服务器可以给人一种系统正在工作的印象。你可以使用功能标志开启或关闭模拟服务器，并且即使真正的后端由于维护而下线，演示环境也会保持稳定。

测试边缘情况

漂移检测和契约测试

为什么示例会默默漂移

一个示例只是文本的一段。如果开发人员改变了模式但忘记更新示例，规范在人类读者看来仍然正确。没有什么能执行这个示例，所以错误一直隐藏，直到有人尝试使用生成的客户端并看到不匹配。

为什么模拟会大声漂移

一个与真实API偏离的模拟将导致请求失败。前端将接收到意外的状态码或形状，测试将立即失败。这种响亮的失败使问题早早可见，提示团队更新模拟或契约。

在CI中使用契约测试

我们在每个拉取请求上运行一个契约测试套件。该套件启动模拟，发送OpenAPI文件中定义的请求，并检查响应是否与示例和模式匹配。如果开发人员向模式添加了一个新字段但忘记将其添加到模拟中，测试将失败，CI构建将停止。这给我们提供了快速的反馈，并保持模拟的诚实。

从 OpenAPI 设置模拟服务器

选择一个可以直接读取文件的工具

我更喜欢能够以 OpenAPI JSON 或 YAML 作为输入并生成模拟服务器的工具。例如 Prism、Mockoon 和 Stoplight Studio 的内置模拟模式。这些工具解析路径、方法、参数和响应，然后启动一个匹配规范的本地 HTTP 服务器。

从示例或模式生成响应

当工具遇到响应定义时，它首先查找示例。如果存在示例，则返回该确切的有效载荷。如果没有示例，则回退到模式并创建一个虚拟值：字符串变为“示例”，数字变为 0，布尔值变为 false，数组获得一个项，对象获得所有必需属性。这意味着您可以从模式开始并仍然获得可用的模拟。

使用覆盖自定义行为

有时您需要特定的状态代码或延迟响应用于特定的测试。大多数模拟服务器允许您添加覆盖规则。您编写一个小的 JSON 文件，匹配路径和方法，并告诉服务器返回不同的状态、不同的正文或等待一段时间（以毫秒为单位）后再响应。这保持了从规范生成的核心模拟，同时允许您注入特定于测试的逻辑。

在开发和 CI 中运行模拟

在本地开发中，我使用一个命令启动模拟并在工作于前端时将其保持运行。在 CI 中，我将模拟作为后台服务启动，运行契约测试，然后将其关闭。在两个地方使用相同的命令，这减少了环境之间的差异。

保持示例与模式同步

将示例视为合同的一部分

我在审查每个模式更改时使用一个清单：模式更改是否添加、删除或重命名了一个属性？如果是，我会打开相应的示例并进行相同的编辑。这一习惯可以防止之前描述的无声漂移。

使用一个检查示例的 lint 工具

我添加一个 lint 步骤，运行 spectral 并使用一个规则集来标记缺失的示例或无法通过模式验证的示例。lint 步骤在每次推送时运行，如果它失败，构建将停止。规则集很简单：对于定义模式的每个响应，必须至少有一个示例，并且该示例必须能够成功解析模式。

为重复结构自动生成示例

对于返回对象列表的端点，我有时使用一个小脚本，取模式的 items 定义并创建一个具有两个或三个变体条目的数组。脚本将生成的示例写回 OpenAPI 文件的适当响应中。这可以在不需要手动复制的情况下保持示例的真实性。

为团队记录该过程

我在存储库中保持一个简短的文件，概述了步骤：更新模式，运行 lint，修复任何标记的示例，提交。新团队成员可以遵循该文件并快速上手。

什么这不是

这不能保证模拟能够捕获前端和后端之间的所有可能不匹配。模拟只检查你编程它返回的内容，如果真实服务以你从未模拟的方式表现不同，差异仍将出现在生产中。

这不是说你可以完全跳过编写OpenAPI示例。即使你运行模拟，示例仍然对文档、SDK生成和合同讨论具有价值。

这不是承诺设置模拟服务器需要零时间。你需要安装工具，学习其覆盖语法，并将模拟启动/停止命令添加到你的脚本中。一旦你开始集成前端工作，投资就会得到回报，但这并不是免费的。

这不是断言模拟可以替代功能齐全的预发布环境。性能特征、身份验证集成和下游服务调用仍然最好在现实的预发布集群中进行测试。

操作员检查清单：Mock 服务器与 OpenAPI 示例

我会在每次发布时保留一份书面检查清单，用于检查这个主题。清单故意设计得很枯燥：命名所有者，命名证据文档，命名回滚计划。如果一个步骤不能产生文件、票据或日志记录，那么它不是一个步骤——它只是一个愿望。

在更改生产环境之前

- 冻结您要测量的分支或配置修订版。 - 记录当前的故障模式，包括一个具体的输入和一个具体的输出。 - 确认作业运行的身份，并检查该身份是否可以访问不应访问的数据。

在运行检查时

- 更喜欢一个可复现的路径，而不是十个轶事截图。 - 在触发工具或查询之前，写下预期的安全结果。 - 捕获正在测试的确切命令、提示、模式或正则表达式——而不是一个转述。 - 如果系统可以执行操作（发送、写入、删除、传输），则需要在同一路径中要求确认边界。

完成后

- 即使扫描结果干净，也要用所有者和日期记录残余风险。 - 不要将绿色检查转换为声称完整性的销售语言。 - 当模型、工具模式或验证规则发生变化时，重新运行相同的检查清单。

信号 | 记录内容 | 是否停止发货? 意外写入或发送 | 工具名称、参数、身份 | 是，直到被阻止 缺少对破坏性操作的确认 | 调用路径和绕过 | 是 不受信任的文本被视为指令 | 源表面和结果操作 | 是，适用于代理范围 扫描结果干净，判断开放 | 推迟的项目 + 所有者 | 仅当核心路径安全时

我如何向买家解释限制

当一个潜在客户问产品是否"涵盖一切"时，我会回答产品的边界：自动检查可以捕捉已知模式，但新的链式和政策判断仍需要审查。这份诚实可以降低支持负载，并保持博客与产品实际功能的一致性。

如果您需要第二种意见，请将此文与下面的参考资料和您自己的测试环境结合起来。不要仅仅因为模型写了自信的总结就跳过测试步骤。

参考资料

- OpenAPI 最佳实践 - Redoc - OpenAPI 规范 - 模式对象

常见问题

我们需要同时使用两个吗?

通常是的。文档示例和集成工作的模拟都需要。它们可以来自同一个规范。

示例可以替代模拟吗?

代码开始发送请求时，不行——示例不能回答。

MockDeck 是否运行模拟服务器?

不。它生成规范和示例响应；服务它们是一个单独的步骤。

我们如何防止模拟与真实 API 发生偏差?

在 CI 中验证真实流量与合同。没有人检查的模拟变成虚构。

示例响应是生产数据吗?

不。它们是生成的，类似真实数据，应该被视为测试数据。

我们应该从哪种格式开始?

如果你想要工具支持，使用 OpenAPI 3；如果你的团队已经在 Postman 中工作，使用 Postman；如果你只需要调用，使用原始路由。

参考资料

- OpenAPI 规范 - JSON 模式

尝试产品：MockDeck

2026-09-20 · 仅主来源 · 不包含虚构的流量指标 · 仅决策支持

相关文章

- 首先创建API模拟 - 探索完整的AI微SaaS主题矩阵 →