stubby中文文档|stubby js中文教程|解析

npm npmdoc 2年前 (2021-12-28) 627次浏览

stubby中文文档|stubby js中文教程|解析

安装命令:npm i stubby

构建状态
NPM 版本

stubby4node

用于在开发期间模拟/存根外部系统的可配置服务器。

stubby采用 YAML 或 JSON 文件形式的端点描述符,告诉它如何响应传入的请求。对于每个传入请求,按顺序检查配置的端点,直到找到匹配项。

目录

安装

通过 npm

npm install -g stubby

这将stubby作为命令安装在您的PATH. -g如果您想在项目中使用 stubby 作为嵌入式模块,请不要使用标志。

通过来源

git clone https://github.com/mrak/stubby4node.git
cd stubby4node
npm start -- <stubby args>

支持的运行时

  • node.js – 最新和当前支持的 LTS 版本

开发在 x86-64 Linux 上进行。

启动服务器

某些系统要求您sudo在某些端口(如 80)上运行服务之前

[sudo] stubby

命令行开关

stubby [-a <port>] [-c <file>] [-d <file>] [-h] [-k <file>] [-l <hostname>] [-p <file>] [-q]
       [-s <port>] [-t <port>] [-v] [-w] [-H]

-a, --admin <port>             Port for admin portal. Defaults to 8889.
-c, --cert <file>              Certificate file. Use with --key.
-d, --data <file>              Data file to pre-load endoints. YAML or JSON format.
-h, --help                     This help text.
-k, --key <file>               Private key file. Use with --cert.
-l, --location <hostname>      Hostname at which to bind stubby.
-q, --quiet                    Prevent stubby from printing to the console.
-p, --pfx <file>               PFX file. Ignored if used with --key/--cert
-s, --stubs <port>             Port for stubs portal. Defaults to 8882.
-t, --tls <port>               Port for https stubs portal. Defaults to 7443.
-v, --version                  Prints stubby's version number.
-w, --watch                    Auto-reload data file when edits are made.
-H, --case-sensitive-headers   Do not normalize response headers to lower-case.

从命令行使用时,stubby响应SIGHUP信号以重新加载其配置。

端点配置

本节解释requestresponse对象上每个属性的用法、意图和行为

这是一个完全填充的、不切实际的端点:

-  request:
      url: ^/your/awesome/endpoint$
      method: POST
      query:
         exclamation: post requests can have query strings!
      headers:
         content-type: application/xml
      post: >
         <!xml blah="blah blah blah">
         <envelope>
            <unaryTag/>
         </envelope>
      file: tryMyFirst.xml
   response:
    - status: 200
      latency: 5000
      headers:
         content-type: application/xml
         server: stubbedServer/4.2
      body: >
         <!xml blah="blah blah blah">
         <responseXML>
            <content></content>
         </responseXML>
      file: responseData.xml
    - status: 200
      body: "Haha!"

要求

此对象用于将传入请求与已配置的可用端点进行匹配。

网址(必填)

  • 是一个成熟的正则表达式
  • 这是端点唯一必需的属性。
  • 在基本主机和端口之后(即在 之后localhost:8882表示 url
  • 任何查询参数都被剥离(所以不要包括它们,这就是query目的)。

    • /url?some=value&another=value 变成 /url
  • 不检查 URI 编码的合规性。

    • 如果它无效,它将永远不会触发匹配。

这是您可以获得的最简单的方法:

-  request:
      url: /

使用正则表达式的演示:

-  request:
      url: ^/has/to/begin/with/this/

-  request:
      url: /has/to/end/with/this/$

-  request:
      url: ^/must/be/this/exactly/with/optional/trailing/slash/?$

方法

  • 默认为GET.
  • 不区分大小写。
  • 可以是以下任何一种:

    • 得到
    • 邮政
    • 删除
    • 等等。
-  request:
      url: /anything
      method: GET
  • 它也可以是一个值数组。
-  request:
      url: /anything
      method: [GET, HEAD]

-  request:
     url: ^/yonder
     method:
       -  GET
       -  HEAD
       -  POST

询问

  • 值是成熟的正则表达式

  • 如果省略,stubby 将忽略给定 url 的查询参数。

  • 变量/值对的 yaml 哈希图。

  • 允许查询参数以任意顺序出现在 uri 中

  • 以下将匹配其中任何一个:

    • /with/parameters?search=search+terms&filter=month
    • /with/parameters?filter=month&search=search+terms
-  request:
     url: ^/with/parameters$
     query:
       search: search terms
       filter: month

注意:重复的查询字符串键(通常是数组表示)会将它们的值转换为逗号分隔的列表。

/url?array=one&array=two

将匹配:

- request:
    url: ^/url$
    query:
      array: one,two

邮政

  • 是一个成熟的正则表达式
  • 如果省略,则忽略任何发布数据。
  • 服务器请求的正文内容,例如表单数据。
-  request:
      url: ^/post/form/data$
      post: name=John&email=john@example.com

文件

  • 如果提供,则替换post为本地给定文件的内容。

    • 路径是相对于--data文件所在的位置
  • 如果在发出请求时未找到文件,则回退到post匹配。
  • 允许您在多个文件中拆分存根数据
-  request:
      url: ^/match/against/file$
      file: postedData.json
      post: '{"fallback":"data"}'

发布数据.json

{"fileContents":"match against this if the file is here"}
  • 如果postedData.json/match/against/file请求时文件系统上不存在,则 stubby 将根据{"fallback":"data"}(from post)匹配帖子内容

json

  • 如果存在postfile存在则不使用
  • 将被解析为一个 JavaScript 对象。
  • 允许您指定将与 JSON 请求进行深度比较的 JSON 字符串

虽然不是必需的,但建议还指定application/json标题要求。

-  request:
      url: ^/match/against/jsonString$
      headers:
         content-type: application/json
      json: '{"key1":"value1","key2":"value2"}'

JSON 字符串可以包含"key": "value"任意顺序的对:{"key1":"value1", "key2":"value2"}相当于{"key2":"value2", "key1":"value1"}

标题

  • 值是成熟的正则表达式
  • 如果省略,stubby 将忽略给定 url 的标头。
  • 标题名称不区分大小写匹配。
  • 类似于 的标头/值对的哈希图query

以下端点仅接受具有application/jsonpost 值的请求

-  request:
      url: /post/json
      method: post
      headers:
         content-type: application/json

回复

假设已针对给定request对象进行匹配response则使用来自的数据构建回存到客户端的存根响应。

另外:response属性也可以是一个 yaml 响应序列,在每个请求发出时循环。

另外:response属性也可以是 url(字符串)或对象/url 序列。该 url 将用于记录要在调用 stubby 时使用的响应对象。当以这种方式使用时,来自request端点部分的数据将用于将请求组装到作为response.

- request:
    url: /single/object
  response:
    status: 204

- request:
    url: /single/url/to/record
  response: http://example.com

- request:
    url: /object/and/url/in/sequence
  response:
  - http://google.com
  - status: 200
    body: 'second hit'

地位

  • 响应的 HTTP 状态代码。
  • 整数或类似整数的字符串。
  • 默认为200.
-  request:
      url: ^/im/a/teapot$
      method: POST
   response:
      status: 420

身体

  • 响应体的内容
  • 默认为空内容正文
-  request:
      url: ^/give/me/a/smile$
   response:
      body: ':)'

文件

  • 类似于request.file,但文件的内容用作body.
-  request:
      url: /
   response:
      file: extremelyLongJsonFile.json

标题

  • 类似于,request.headers除了这些被发送回客户端。
-  request:
      url: ^/give/me/some/json$
   response:
      headers:
         content-type: application/json
      body: >
         [{
            "name":"John",
            "email":"john@example.com"
         },{
            "name":"Jane",
            "email":"jane@example.com"
         }]

潜伏

  • 在发回响应之前等待的时间,以毫秒为单位
  • 适合测试超时或慢速连接
-  request:
      url: ^/hello/to/jupiter$
   response:
      latency: 800000
      body: Hello, World!

动态令牌插值

stubby根据配置的端点匹配请求数据时,它会保留所有正则表达式捕获组的散列。这些捕获组可以在response数据中引用这是一个例子

-  request:
      method: [GET]
      url: ^/account/(\d{5})/category/([a-zA-Z]+)
      query:
         date: "([a-zA-Z]+)"
      headers:
         custom-header: "[0-9]+"

   response:
      status: 200
      body: Returned invoice number# <% url[1] %> in category '<% url[2] %>' on the date '<% query.date[1] %>', using header custom-header <% headers.custom-header[0] %>

url正则表达式^/account/(\d{5})/category/([a-zA-Z]+)有两个定义捕获组:(\d{5})([a-zA-Z]+)query正则表达式具有一个限定的捕获组:([a-zA-Z]+)

尽管headers没有明确定义捕获组(括号内没有正则表达式部分),但仍然可以在模板中访问各个标头的完全匹配值(请参阅捕获组 ID)。

模板bodyfile

response.body可以有以下的格式标记插值< %PROPERTY_NAME[CAPTURING_GROUP_ID] %>如果它是对应headersquery成员匹配的令牌,则令牌结构将是`<% HEADERS_OR_QUERY.[KEY_NAME][CAPTURING_GROUP_ID] %>。

  response:
    body: The "content-type" header value was <% headers.content-type[0] %>.

注意:如果您file在响应中使用该属性,请记住文件内容都是内插的。换句话说,<% ... %>将出现在文件的内容中以及配置中具有response.file

捕获组 ID

CAPTURING_GROUP_ID是通过使用正则表达式来确定。的索引0将是与正则表达式匹配的全文。

捕获组从索引开始1并对应于括号的使用。

让我们用上面的例子来演示:

- request:
    url: ^/account/(\d{5})/category/([a-zA-Z]+)

如果传入的url/account/54/category/users,则以下将是捕获组:

<% url[0] %> -> /account/54/categroy/users
<% url[1] %> -> 54
<% url[2] %> -> users

让我们举一个更复杂的例子,将子组作为捕获:

- request:
    url: ^/resource/(([a-z]{3})-([0-9]{3}))$

如果传入的url/resource/abc-123,则捕获组将是:

<% url[0] %> -> /resource/abc-123
<% url[1] %> -> abc-123
<% url[2] %> -> abc
<% url[3] %> -> 123

故障排除

  • 确保您在 stubby 配置中使用的正则表达式实际上做了它应该做的。在 stubby 中使用它之前,通过节点 REPL(或类似的)验证它是否有效
  • 确保正则表达式具有您想要作为标记值捕获的正则表达式部分的捕获组。换句话说,如果您的令牌 ID 开始于,请确保您没有忘记正则表达式中的括号1
  • 当想要使用完整的正则表达式匹配作为令牌值时,请确保使用令牌 ID 零
  • 确保您在模板中使用的令牌名称正确:检查属性名称是否正确、捕获组 ID、完全匹配的令牌 ID <%%>

管理门户

管理门户是一个 RESTful(ish) 端点,运行在localhost:8889. 或者您通过 stubby 的选项描述的任何地方。

为 Stubby 提供端点

向 提交POST请求localhost:8889PUTlocalhost:8889/:id*提交请求,或为每个端点加载具有以下结构的数据文件 (-d):

  • request: 描述客户端对服务器的调用

    • method: GET/POST/PUT/DELETE/等。
    • url: URI 正则表达式字符串。
    • query:请求中包含的查询字符串参数的键/值映射
    • headers:服务器应响应的标头的键/值映射
    • post:匹配响应正文的字符串。
    • file: 如果指定,则返回给定文件的内容作为请求帖子。如果在请求时找不到文件,则使用post代替
  • response: 描述服务器对客户端的响应

    • headers:服务器应在其响应中使用的标头的键/值映射
    • latency:服务器在响应之前应等待的时间(以毫秒为单位)。用于测试超时和延迟
    • file: 如果指定,则返回给定文件的内容作为响应正文。如果在请求时找不到文件,则使用正文代替
    • body: 服务器对客户端的响应的正文
    • status:数字 HTTP 状态代码(200 表示正常,404 表示未找到等)

YAML

-  request:
      url: ^/path/to/something$
      method: POST
      headers:
         authorization: "Basic usernamez:passwordinBase64"
      post: this is some post data in textual format
   response:
      headers:
         Content-Type: application/json
      latency: 1000
      status: 200
      body: Your request was successfully processed!

-  request:
      url: ^/path/to/anotherThing
      query:
         a: anything
         b: more
      method: GET
      headers:
         Content-Type: application/json
      post:
   response:
      headers:
         Content-Type: application/json
         Access-Control-Allow-Origin: "*"
      status: 204
      file: path/to/page.html

-  request:
      url: ^/path/to/thing$
      method: POST
      headers:
         Content-Type: application/json
      post: this is some post data in textual format
   response:
      headers:
         Content-Type: application/json
      status: 304

JSON

[
  {
    "request": {
      "url": "^/path/to/something$",
      "post": "this is some post data in textual format",
      "headers": {
         "authorization": "Basic usernamez:passwordinBase64"
      },
      "method": "POST"
    },
    "response": {
      "status": 200,
      "headers": {
        "Content-Type": "application/json"
      },
      "latency": 1000,
      "body": "Your request was successfully processed!"
    }
  },
  {
    "request": {
      "url": "^/path/to/anotherThing",
      "query": {
         "a": "anything",
         "b": "more"
      },
      "headers": {
        "Content-Type": "application/json"
      },
      "post": null,
      "method": "GET"
    },
    "response": {
      "status": 204,
      "headers": {
        "Content-Type": "application/json",
        "Access-Control-Allow-Origin": "*"
      },
      "file": "path/to/page.html"
    }
  },
  {
    "request": {
      "url": "^/path/to/thing$",
      "headers": {
        "Content-Type": "application/json"
      },
      "post": "this is some post data in textual format",
      "method": "POST"
    },
    "response": {
      "status": 304,
      "headers": {
        "Content-Type": "application/json"
      }
    }
  }
]

如果您想通过文件加载多个端点,请使用 JSON 数组或 YAML 列表 (-) 语法。成功后,响应将包含Location在带有新创建资源位置的标头中

获取已加载端点的 ID

Stubby 将响应头添加X-Stubby-Resource-ID到传出响应中。此 ID 可被引用以与管理门户一起使用。

获取存根端点的当前列表

执行GET请求localhost:8889将返回所有当前保存的响应的 JSON 数组。204 : No Content如果没有保存,它会回复

执行GET请求localhost:8889/<id>将返回 JSON 对象,该对象表示具有提供的 id 的响应。

状态页面

您还可以通过转到查看当前配置的端点 localhost:8889/status

更改现有端点

PUT以与 using 相同的格式执行请求POST,只是这次在路径中提供 id。例如,为了更新ID 4的反应,你会PUTlocalhost:8889/4

删除端点

发送DELETE请求至localhost:8889/<id>

存根门户

发送到任何网址localhost:8882(或您告诉 stubby 运行的任何地方)的请求将搜索可用的端点,如果找到匹配项,则使用该端点的response数据进行响应

端点如何匹配

对于给定的端点,stubby 只关心匹配已在 YAML 中定义的请求的属性。此规则的例外是method如果省略,则默认为GET

例如,以下将匹配POST对根 url 的任何请求:

-  request:
      url: /
      method: POST
   response: {}

请求可以有任何标题和它想要的任何帖子正文。它将匹配上述内容。

伪代码:

for each <endpoint> of stored endpoints {

   for each <property> of <endpoint> {
      if <endpoint>.<property> != <incoming request>.<property>
         next endpoint
   }

   return <endpoint>
}

编程API

粗短模块

stubby在项目目录中作为模块添加

    npm install stubby

然后在您的项目文件中,您可以执行以下操作:

    var Stubby = require('stubby').Stubby;
    var mockService = new Stubby();

    mockService.start();

你问我能用它做什么?继续阅读!

开始(选项,[回调])

  • options: 一个包含参数的对象,用于启动这个 stubby。参数与命令行中使用的全名标志一起使用。

    • stubs: 运行存根门户的端口号
    • admin: 运行管理门户的端口号
    • tls: 通过 https 运行存根门户的端口号
    • data:包含端点数据的 JavaScript 对象/数组
    • location: 运行 stubby 的地址/主机名。
    • key: 密钥文件内容(PEM 格式)
    • cert: 证书文件内容(PEM 格式)
    • pfx: pfx 文件内容(与密钥/证书选项互斥)
    • watch: 文件名以在发生更改时作为存根数据进行监控和加载
    • quiet: 默认为true. 传入false以获得控制台输出(如果可用)
    • _httpsOptions:传递给底层 tls 服务器的附加选项
    • caseSensitiveHeaders: 如果为 false(默认值),所有响应头都是小写的。
  • callback: 接受一个参数:错误信息(如果有),否则未定义

开始([回调])

与之前的签名相同,只有所有选项都被假定为默认值。

停止([回调])

关闭 stubby 的存根和管理门户正在使用的连接和端口。callback之后执行

获取(ID,回调)

模拟对管理门户的 GET 请求,回调接收结果数据。

  • id:要检索的端点的 id。如果省略,所有注册端点的数组将传递给回调。
  • callback(err, endpoint):err如果不存在具有给定 id 的端点,则定义。否则,endpoint人口稠密。

获取(回调)

模拟对管理门户的 GET 请求,回调接收结果数据。

  • id:要检索的端点的 id。如果省略,所有注册端点的数组将传递给回调。
  • callback(endpoints): 接受一个包含返回结果数组的参数。如果没有注册端点,则为空

发布(数据,[回调])

  • data: 要存储在 stubby 中的端点对象
  • callback(err, endpoint): 如果一切顺利,将使用创建的端点执行。如果出现错误,则使用错误消息调用。

放置(ID,数据,[回调])

  • id: 要更新的端点的 id。
  • data:用于替换端点的数据。
  • callback(err): 如果成功,则不传递参数执行。否则,传递错误消息。

删除([id],回调)

  • id: 要销毁的端点的 id。如果省略,则从 stubby 中清除所有端点。
  • callback(): 在端点被移除后调用

例子

var Stubby = require('stubby').Stubby;

var stubby1 = new Stubby();
var stubby2 = new Stubby();

stubby1.start({
  stubs: 80,
  admin: 81,
  location: 'localhost',
  data: [{
    request: { url: "/anywhere" }
  },{
    request: { url: "/but/here" }
  }]
});

stubby2.start({
  stubs: 82,
  admin: 83,
  location: '127.0.0.2'
});

也可以看看

去做

不间断更改

  • 允许多值字段(数组和映射)作为查询/发布参数

重大变化

  • /以正则表达式开头和结尾的解释配置值,否则视为精确的字符串匹配

    • 如果/包围的值没有编译为正则表达式,则在添加时将错误记录到控制台/响应

笔记

  • 版权所有2015 Eric Mrak, Alexander Zagniotov
  • 许可证Apache v2.0
项目贡献人员列表:


极客公园 , 版权所有丨如未注明 , 均为原创丨本网站采用BY-NC-SA协议进行授权
转载请注明原文链接:stubby中文文档|stubby js中文教程|解析
喜欢 (0)
.excerpt .focus {display:none}