使用 API-First 方法构建 RestfulAPI（二）—— Mock

Panpan

2023-04-12

原文标题：Designing Restful APIs using an API-First Approach — Mocking
原文链接：https://dev.to/ntakashi/designing-restful-apis-using-an-api-first-approach-mocking-146f
作者：Nicolas Takashi

本系列共有三篇，阅读之前请确保你已阅读过该系列的前一篇文章：

本章我将介绍如何使用 OpenAPI 文档构建 Mock 服务器以改善开发人员的工作体验。

😎 Mock 概念

在我们使用 OpenAPI 文档深入研究 Mock 技术之前，应该先了解 Mock 的含义。

在面向对象的编程中， Mock 对象是以可控方式 Mock 真实对象的行为，通常作为软件测试计划的一部分。程序员通常会创建一个 Mock 对象来测试其他一些对象的行为，这与汽车设计师使用碰撞测试假人来模拟人类在车辆撞击中的动态行为的方式大致相同。该技术也适用于泛型编程。——维基百科

💡HTTP 级别 Mock

在 API 中， Mock 的概念与上面描述的相同，但不是使用框架来 Mock 对象，例如 Moq 和 RinoMock，而是使用 Mock 服务器来完成。

Mock 服务器将对预期的端点作出响应，对于不存在的端点，通常会提供验证错误的返回信息。

Mock 服务器替代方案

有几种创建 Mock 服务器的替代方案，每一种都有其特点，你可以在下面选项列表中点击查看详情。

上面列出的每个选项都是很优秀的 Mock 工具，绝对可以满足你的预期。而这篇文章的目的是展示如何使用 OpenAPI 文档构建 Mock 服务器，所以我们这里选择讲解 Prism ，它为我们提供了与 Open-API 的内置集成来创建 Mock 服务器，因此我们不需要编写任何代码来执行此操作。

Prism 简介

Prism 是一个命令行界面，聚合了一组使用 OpenAPI 文档进行 API Mocking 的包，这是使用 JavaScript 和 NodeJS 开发的，在 Github Repository 上有一个庞大的社区和许多赞同。

初步认识

在上一篇文章中，我使用了 Github 存储库和 Post 系列的代码，现在让我们在此基础上继续努力并改进解决方案。使用下面的一些命令将 Prism 添加到项目中。

yarn add @stoplight/prism-cli
# or
npm install --save @stoplight/prism-cli

Prism 的 HTTP Mock 服务器通过提供 API 描述文档中描述的端点和验证规则来 Mock 真实的 Web API，就像任何 HTTP 解决方案一样，它围绕 Request Messages 和 Response Messages 工作。

响应生成

Prism 会尝试将可用的信息返回有意义的响应，你可以使用任何 OpenAPI 文档，当然，良好的文档会提供更好的结果。

响应生成策略

Prism 有两种响应生成策略，静态生成策略和动态生成策略，接下来我们将了解这两者之间的一些差异。

静态生成策略

默认情况下，Prism 将使用静态生成策略来创建响应消息，你可以运行以下命令使用它，：

prism mock <path-to-openapi>

如果提供的 OpenAPI 文档有响应主体示例，那么它将使用该示例，否则，Prism 将通过查看整个模式对象来创建响应主体以创建虚拟响应。

动态生成策略

如果你要构建一个稳健的 API ，那么就不应该用相同的数据重复地对 API 进行测试，在现实世界中，数据是动态的，我们必须能够正确处理它，你可以运行以下命令：

prism mock <path-to-openapi> -d

动态模式通过根据所有属性的类型和其他信息（如格式）生成一个随机值来解决这个问题，这意味着你的 API 描述性越强，Prism 在创建 Mock 响应方面就会做得越好。

请求验证

基于 API 描述文档，Prism 可以考虑 request body、headers、query parameters 的各种验证规则，使用诸如type、format、maxLength之类的关键字。

配置 Prism

现在，你已经了解 Prism 基础知识及其工作原理，让我们在 API 项目中配置它并启动一个新的 Mock 服务器。

首先，我们需要将 package.json 更改为如下例所示，其中包含两个新命令 mock 和 premock。

{
  "name": "todoapi-spec",
  "version": "1.0.0",
  "description": "OpenAPI specification for TodoAPI",
  "main": "index.js",
  "author": "Nicolas Takashi",
  "license": "MIT",
  "scripts": {
    "premock": "yarn bundle",
    "mock": "prism mock ./bin/api.yaml -d",
    "bundle": "swagger-cli bundle specs/api.yaml -o ./bin/api.yaml -t yaml",
    "prelint": "yarn bundle",
    "lint": "spectral lint ./bin/api.yaml --ignore-unknown-format"
  },
  "dependencies": {
    "@openapitools/openapi-generator-cli": "^1.0.15-4.3.1",
    "@stoplight/prism-cli": "^4.0.0",
    "@stoplight/spectral": "^5.5.0",
    "swagger-cli": "^4.0.4"
  }
}

接下来只需运行以下命令即可启动 Prism，然后查看控制台以查看输出。

yarn mock

如果我们查看控制台的输出信息，会发现有一个 Mock 服务器正在运行localhost:4010，从现在开始，我们可以对该 Prism 服务器进行 API 调用。

使用 Swagger UI 调用 API

让我们通过 Swagger UI 调用 API ，在此之前，需要更改 api.yaml 并添加服务器部分，如下所示：

openapi: 3.0.0
info:
  title: Todo App API
  description: Todo App API.
  version: v1
  contact:
    email: 'nicolas.tcs@hotmail.com'
    name: 'Nicolas Takashi'
servers:
  - url: http://127.0.0.1:4010
    description: Mock Server
tags:
  - name: Tasks
paths:
  '/tasks':
    $ref: './components/paths/tasks/task.yaml'
  '/tasks/{id}':
    $ref: './components/paths/tasks/task-by-id.yaml'
components:
  schemas:
    Task:
      $ref: 'components/schemas/task.yaml#/components/schemas/Task'
    PagedTask:
      $ref: 'components/schemas/pagedTask.yaml#/components/schemas/PagedTask'
    ProblemDetails:
      $ref: 'components/schemas/problemDetails.yaml#/components/schemas/ProblemDetails'

现在，如果我们查看 Swagger UI，我们会注意到一个新的下拉列表，其中包含可用服务器列表，如下图所示。

最后，让我们尝试创建一个任务，调用POST /tasks并查看输出。

成功请求

由于我们已经发送了name这个必需的参数，因此请求返回的 HTTP Created 201 将包含 location header ，如下图所示：

非法请求

在尝试创建没有name 参数的任务后，将会返回 HTTP Bad Request，如 OpenAPI 文档中所述。

使用 Apifox 进行 Mock

当然，不得不提到 Apifox 的 Mock 功能，非常强大。Apifox 是集文档、Mock、自动化测试于一身的全能型 API 工具，Apifox 的 Mock 功能非常好用（主要是免费），具体操作可以查看该文章：《如何使用 Apifox 进行 Mock 以便轻松测试 API》。

结论

这就是本文的全部内容，现在你已经掌握了 Mock API 的基础知识，你需要继续学习，以了解每个功能以及如何利用此策略将其部署到你的客户端。API Mock 可以预测 API 使用和系统集成之间可能存在的许多问题。