MockResponse插件

模拟响应。

命令提示符的屏幕截图,其中开发人员代理模拟了对 GitHub API 的请求的响应。

配置示例

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v4.0.0/rc.schema.json",
  "plugins": [
    {
      "name": "MockResponsePlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/DevProxy.Plugins.dll",
      "configSection": "mocksPlugin"
    }
  ],
  "mocksPlugin": {
    "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v4.0.0/mockresponseplugin.schema.json",
    "mocksFile": "mocks.json"
  }
}

配置属性

资产 DESCRIPTION 违约
mocksFile 包含模拟响应的文件的路径 mocks.json
blockUnmockedRequests 返回 502 Bad Gateway 未模拟的请求的响应 false

命令行选项

名称 DESCRIPTION 违约
-n, --no-mocks 禁用加载模拟请求 false
--mocks-file 包含模拟响应的文件的路径 -

模拟文件示例

Tip

若要从具有原始 HTTP 响应的文件创建模拟文件,请使用 mocks from-http-responses 该命令。

下面是模拟对象的示例。

使用正文进行响应

使用 200 正常响应和 JSON 正文响应请求的响应。

文件: mocks.json

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v4.0.0/mockresponseplugin.mocksfile.schema.json",
  "mocks": [
    {
      "request": {
        "url": "https://graph.microsoft.com/v1.0/me",
        "method": "GET"
      },
      "response": {
        "body": {
          "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity",
          "businessPhones": ["+1 412 555 0109"],
          "displayName": "Megan Bowen",
          "givenName": "Megan",
          "jobTitle": "Auditor",
          "mail": "MeganB@M365x214355.onmicrosoft.com",
          "mobilePhone": null,
          "officeLocation": "12/1110",
          "preferredLanguage": "en-US",
          "surname": "Bowen",
          "userPrincipalName": "MeganB@M365x214355.onmicrosoft.com",
          "id": "48d31887-5fad-4d73-a9f5-3c356e68a038"
        },
        "headers": [
          {
            "name": "content-type",
            "value": "application/json; odata.metadata=minimal"
          }
        ]
      }
    }
  ]
}

响应并显示错误

使用 404 未找到的响应响应响应请求。

文件: mocks.json

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v4.0.0/mockresponseplugin.mocksfile.schema.json",
  "mocks": [
    {
      "request": {
        "url": "https://graph.microsoft.com/v1.0/me/photo",
        "method": "GET"
      },
      "response": {
        "statusCode": 404
      }
    }
  ]
}

使用二进制数据进行响应

使用从磁盘上的文件加载的二进制映像响应请求。

文件: mocks.json

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v4.0.0/mockresponseplugin.mocksfile.schema.json",
  "mocks": [
    {
      "request": {
        "url": "https://graph.microsoft.com/v1.0/users/*/photo/$value",
        "method": "GET"
      },
      "response": {
        "body": "@picture.jpg",
        "headers": [
          {
            "name": "content-type",
            "value": "image/jpeg"
          }
        ]
      }
    }
  ]
}

根据 nth 请求做出响应

仅响应第二个匹配请求。 开发代理将其他请求传递给 API。

文件: mocks.json

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v4.0.0/mockresponseplugin.mocksfile.schema.json",
  "mocks": [
    {
      "request": {
        "url": "https://graph.microsoft.com/v1.0/external/connections/*/operations/*",
        "method": "GET",
        "nth": 2
      },
      "response": {
        "statusCode": 200,
        "body": {
          "id": "1.neu.0278337E599FC8DBF5607ED12CF463E4.6410CCF8F6DB8758539FB58EB56BF8DC",
          "status": "completed",
          "error": null
        }
      }
    }
  ]
}

响应与请求正文匹配

响应正文中包含特定字符串的请求。

文件: mocks.json

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v4.0.0/mockresponseplugin.mocksfile.schema.json",
  "mocks": [
    {
      "request": {
        "url": "https://login.microsoftonline.com/fa15d692-e9c7-4460-a743-29f29522229/oauth2/v2.0/token",
        "method": "POST",
        "bodyFragment": "scope=https%3A%2F%2Fapi.contoso.com%2FDocuments.Read"
      },
      "response": {
        "headers": [
          {
            "name": "Content-Type",
            "value": "application/json; charset=utf-8"
          }
        ],
        "body": {
          "token_type": "Bearer",
          "expires_in": 3599,
          "ext_expires_in": 3599,
          "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSU..."
        }
      }
    }
  ]
}

响应中的镜像请求数据

使用 @request.body.* 占位符对请求正文中的值进行响应。

文件: mocks.json

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v4.0.0/mockresponseplugin.mocksfile.schema.json",
  "mocks": [
    {
      "request": {
        "url": "https://graph.microsoft.com/v1.0/users",
        "method": "POST"
      },
      "response": {
        "statusCode": 201,
        "body": {
          "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity",
          "id": "12345678-1234-1234-1234-123456789abc",
          "businessPhones": "@request.body.businessPhones",
          "displayName": "@request.body.displayName",
          "givenName": "@request.body.givenName",
          "jobTitle": "@request.body.jobTitle",
          "mail": "@request.body.mail",
          "userPrincipalName": "@request.body.userPrincipalName",
          "accountEnabled": "@request.body.accountEnabled",
          "createdDateTime": "2024-01-15T10:30:00Z"
        },
        "headers": [
          {
            "name": "Content-Type",
            "value": "application/json; odata.metadata=minimal"
          },
          {
            "name": "Location",
            "value": "https://graph.microsoft.com/v1.0/users/12345678-1234-1234-1234-123456789abc"
          }
        ]
      }
    }
  ]
}

给定以下请求:

POST https://graph.microsoft.com/v1.0/users
Content-Type: application/json

{
  "displayName": "Megan Bowen",
  "userPrincipalName": "MeganB@M365x214355.onmicrosoft.com",
  "accountEnabled": true,
  "givenName": "Megan",
  "surname": "Bowen",
  "jobTitle": "Product Manager"
}

响应为:

HTTP/1.1 200 Connection Established
Content-Length: 0

HTTP/1.1 201 Created
Cache-Control: no-store
x-ms-ags-diagnostic: 
Strict-Transport-Security: 
request-id: 12345678-1234-1234-1234-123456789abc
client-request-id: 12345678-1234-1234-1234-123456789abc
Date: 9/10/2025 10:28:35 AM
Content-Type: application/json; odata.metadata=minimal
Location: https://graph.microsoft.com/v1.0/users/12345678-1234-1234-1234-123456789abc
OData-Version: 4.0
Content-Length: 648

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity",
  "id": "12345678-1234-1234-1234-123456789abc",
  "businessPhones": null,
  "displayName": "Megan Bowen",
  "givenName": "Megan",
  "jobTitle": "Product Manager",
  "mail": null,
  "mobilePhone": null,
  "officeLocation": null,
  "preferredLanguage": null,
  "surname": "Bowen",
  "userPrincipalName": "MeganB@M365x214355.onmicrosoft.com",
  "accountEnabled": true,
  "createdDateTime": "2024-01-15T10:30:00Z",
  "department": null,
  "companyName": null,
  "city": null,
  "country": null,
  "postalCode": null,
  "state": null,
  "streetAddress": null,
  "usageLocation": null
}

模拟文件属性

资产 DESCRIPTION 必选
request 定义 要响应的请求的请求对象 是的
response 定义要返回的响应的响应对象 是的

请求对象

每个请求具有以下属性:

资产 DESCRIPTION 必选 默认值 示例值
url 用于响应的 API 终结点的绝对 URL 是的 https://jsonplaceholder.typicode.com/posts
method 用于匹配请求的 HTTP 谓词 url 否 GET GET
nth 仅响应与模拟匹配的第 methodn 个截获请求, url并且 bodyFragment 否 2
bodyFragment 请求正文中应存在的字符串 否 foo

注解

如果要匹配 URL 中的任何一系列字符,请使用*属性中的星号 (url)。 例如,https://jsonplaceholder.typicode.com/* 匹配 https://jsonplaceholder.typicode.com/posts 和 https://jsonplaceholder.typicode.com/comments。 在运行时,开发代理将每个 * 函数转换为正则表达式 .*。

与请求 URL 匹配 url 属性时,开发人员代理将忽略大小写。 例如,匹配 https://jsonplaceholder.typicode.com/Posts 请求的 https://jsonplaceholder.typicode.com/posts模拟。 如果为同一方法定义了多个模拟,其中 URL 仅在大小写上不同,则开发代理将使用第一个匹配的模拟。

定义模拟时,首先放置最具体的模拟。 例如,如果有两个模拟,一个用于 https://jsonplaceholder.typicode.com/posts 一个, https://jsonplaceholder.typicode.com/*第一个模拟放在第一个模拟。 否则,开发代理首先匹配第二个模拟,并返回所有请求的 https://jsonplaceholder.typicode.com/* 响应。

nth如果需要将不同的响应发送到同一请求 URL,请使用该属性。 例如,使用它来模拟长时间运行的作。 首次调用 API 时,它会返回包含消息的 inprogress 响应。 第二次调用 API 时,它会返回包含消息的 completed 响应。 开发代理对与模拟methodurl匹配的每个截获请求进行计数,无论bodyFragment它是否为其返回模拟响应。 不需要对同一 URL 使用回退模拟:如果没有模拟应用于请求,开发人员代理会将其传递给 API。 有关属性 nth 的详细信息,请参阅 Mock nth 请求。

使用此属性 bodyFragment ,可以根据正文内容匹配请求。 例如,如果要匹配正文中包含字符串的请求 foo ,请将 bodyFragment 属性设置为 foo。 开发代理 bodyFragment 仅用于除其他请求外 GET的请求。

响应对象

每个响应具有以下属性:

资产 DESCRIPTION 必选 默认值 示例值
body 作为请求响应发送的正文 否 空 { "foo": "bar" }
statusCode 响应 HTTP 状态代码 否 200 404
headers 要包含在响应中的标头数组 否 空 [{ name: "content-type", "value": "application/json" }]

注解

如果将属性设置为 body JSON 对象或数组,则开发代理将其序列化为 JSON。 如果将字符串设置为字符串,则 Dev Proxy 将发送字符串 as-is,而不用周围引号。 使用字符串正文返回纯文本、HTML、XML 或其他非 JSON 内容。 由于开发代理默认为 content-type 标头 application/json,因此还设置 content-type 标头以匹配内容,例如 text/plain。

如果要返回二进制数据,请将 body 属性设置为字符串值,该值以 @ 后跟文件路径相对于 mocks 文件。 例如, @picture.jpg 返回存储在文件与 picture.jpg mocks 文件相同的目录中的图像。

若要镜像响应中的请求数据,请在响应正文中使用 @request.body.* 占位符。 例如, @request.body.displayName 从请求正文返回属性的值 displayName 。 此功能适用于嵌套对象和数组,使你可以创建反映传入请求数据的动态响应。 占位符替换支持各种 JSON 值类型,包括字符串、数字、布尔值和复杂对象。

后续步骤