插件开发

插件脚手架及辅助工具：https://github.com/avwo/lack

为了满足一些特定业务场景的需要，whistle提供了插件扩展能力，通过插件可以新增whistle的协议实现更复杂的操作、也可以用来存储或监控指定请求、集成业务本地开发调试环境等等，基本上可以做任何你想做的事情，且开发、发布及安装whistle插件也都很简单。

先了解下如何安装使用插件：

可以先看下一个mock server插件的实现：whistle.vase

安装插件

whistle的插件就是一个Node模块，名字必须为 whistle.your-plugin-name 或 @org/whistle.your-plugin-name，其中 your-plugin-name 为插件名称，只能包含 小写字母(a-z)、数字(0-9)、_、- 四种字符，安装插件直接全局npm安装即可：

  1. npm i -g whistle.your-plugin-name
  2. # 或
  3. npm i -g @org/whistle.your-plugin-name

Mac或Linux安装时如果报权限错误，则需要加上sudo，如：sudo npm i -g whistle.your-plugin-name国内可以用cnpm或公司内部自己的镜像安装

全局安装后，可以在whistle的界面上看到所有已安装的插件列表(whistle定时搜索npm的全局目录，并自动加载或卸载插件，无需重启whistle)。

要更新插件的时候，重新安装即可

安装成功后可以在whistle的插件列表看到新安装的插件：插件列表

使用插件

插件安装后，whistle会新增两个协议，分别为 whistle.your-plugin-name 和 your-pluign-name，用户通过配置：

  1. pattern whistle.your-plugin-name://xxx
  2. # 或
  3. pattern your-plugin-name://xxx

匹配到上述规则的请求会自动请求插件相应的server，上述两种配置有些差异，后面再详细说下，下面我们先了解下插件基本原理，并快速开发一个whistle插件的项目。

实现原理

whistle的插件是一个独立运行的进程，这样是为了确保插件不会影响到whistle主进程的稳定性，并通过暴露一些http server的方式实现与whistle的交互，whistle会在特定阶段请求特定的server，具体看下面的原理图：

http请求http请求插件过程

图一：表示http(s)、WebSocket请求涉及到的插件内置server

tunnel请求tunnel请求插件过程

图二：表示tunnel请求涉及到的插件内置server，tunnel请求如上图指没有开启https捕获，或代理到whistle的Socket请求

从上面几个图可以知，whistle插件会设计以下7种server：

  1. statsServer：统计请求信息的服务
  2. resStatsServer：统计响应信息的服务
  3. rulesServer：设置请求规则的服务(支持http/https/websocket请求)
  4. resRulesServer：设置响应规则的服务(支持http/https/websocket请求)
  5. tunnelRulesServer：设置tunnel请求规则的服务
  6. server：whistle会把指定请求转发到该server
  7. uiServer: whistle插件的界面，可以通过特定的url访问

插件就是通过上述中的0-N个server实现相应的功能，并通过配置规则将请求转发到插件的各个server：

  1. pattern whistle.your-plugin-name://xxx
  2. # 或
  3. pattern your-plugin-name://xxx

只要匹配pattern的请求才会转到插件的各个server，上述两种配置的区别是：

  1. pattern whistle.your-plugin-name://xxx：请求默认不会走到插件里面的 server 服务whistle.xxx规则

    可以通过在rulesServer里面重新设置 pattern your-plugin-name://xxx 把请求转发到 server 里面

  2. pattern your-plugin-name://xxx：默认会经历所有server

除了用户手动配置，插件也可以自动规则，只需在插件模块的根目录新建一个 rules.txt 文件，里面可以设置所有whistle规则，包括当前插件的添加的新协议，这个文件的规则是公共的，相当于在：

  1. # rules.txt
  2. www.test.com/cgi-bin whistle.your-plugin-name://xxx

如果规则是跟具体请求无关，也可以在 rules.txt 里面设置定时从插件、或远程、或本地更新规则：

  1. @whistle.your-plugin-name/cgi-bin/xxx

这样whistle会定时请求插件 whistle.your-plugin-name uiServer里面的 /cgi-bin/xxx 的接口。

上述配置表示所有 www.test.com/cgi-bin 路径下的请求都会转到插件来。

除了 rules.txt 外，根目录还可以建插件私有规则：

  1. _rules.txt：whistle规则，相当于 rulesServer 返回的规则
  2. _values.txt：json对象，相当于 rulesServer 返回的Values

也可以在rules里面设置Values：操作值

为了方便各个server直接的通讯及初始化插件配置，可以在插件根目录创建一个 initial.js 的文件，插件首先加载该文件，另外还可以通过插件直接获取抓包数据等，具体插件API及如何开发插件参见：插件开发Demo

调试插件

插件脚手架及辅助工具：https://github.com/avwo/lack

  1. 开启whistle的调试模式：
    1.  w2 stop
    2.  w2 run

    这样可以在控制台看到插件console输出的日志及错误

  2. 修改插件代码后，需要触发插件项目的 package.json 修改才会重新加载该插件，比如添加或删除一个空格。

抓包调试protobuf等自定义协议

whistle v1.13.0版本开始支持通过插件自定义长连接数据的解析器，并通过 Network/Frames 进行显示发送接收数据，及监听状态变化、获取构造请求数据等，具体参考：https://github.com/whistle-plugins/whistle.custom-parser

API

插件的上述各个server里面每个请求的 (req, res) 对象内置了一些属性及方法，用来获取请求配置信息，以及抓包数据。

  1. initial.js: 项目根目录文件，可选，插件在加载所有server之前加载
    1.  module.exports = (options) => {
    2.    // options里有storage对象及Storage类，以及一些自定义请求头字段的名称
    3.    options = {
    4.    name: plugin.moduleName,
    5.    script: PLUGIN_MAIN,
    6.    value: plugin.path,
    7.    REQ_FROM_HEADER: REQ_FROM_HEADER,
    8.    RULE_VALUE_HEADER: RULE_VALUE_HEADER,
    9.    MAX_AGE_HEADER: MAX_AGE_HEADER,
    10.    ETAG_HEADER: ETAG_HEADER,
    11.    FULL_URL_HEADER: FULL_URL_HEADER,
    12.    REAL_URL_HEADER: REAL_URL_HEADER,
    13.    REQ_ID_HEADER: REQ_ID_HEADER,
    14.    CUSTOM_PARSER_HEADER: CUSTOM_PARSER_HEADER,
    15.    STATUS_CODE_HEADER: STATUS_CODE_HEADER,
    16.    LOCAL_HOST_HEADER: LOCAL_HOST_HEADER,
    17.    HOST_VALUE_HEADER: LOCAL_HOST_HEADER,
    18.    PROXY_VALUE_HEADER: PROXY_VALUE_HEADER,
    19.    PAC_VALUE_HEADER: PAC_VALUE_HEADER,
    20.    METHOD_HEADER: METHOD_HEADER,
    21.    CLIENT_IP_HEADER: config.CLIENT_IP_HEAD,
    22.    CLIENT_PORT_HEAD: CLIENT_PORT_HEAD,
    23.    GLOBAL_VALUE_HEAD: GLOBAL_VALUE_HEAD,
    24.    HOST_IP_HEADER: HOST_IP_HEADER,
    25.    debugMode: config.debugMode,
    26.    config: conf
    27.  }
    28.  };

  2. statsServer：统计请求信息的服务

    1.  exports.statsServer = (server, options) => {
    2.    // options 同上，initial.js的options是同一个对象
    3.    server.on('request', (req, res) => {
    4.      const oReq = req.originalReq;
    5.      const oRes = req.originalRes;
    7.      req.clientIp: 请求的客户端IP，注意：挂在req里面
    9.      oReq.id: 请求的ID，每个请求对应一个唯一的ID
    10.      oReq.headers: 请求的原始headers，而req.headers包含了一些插件自定义字段
    11.      oReq.ruleValue: 配置的规则值， 如：whistle.xxx://ruleValue
    12.      oReq.url: 请求的完整url
    13.      oReq.realUrl: 请求的真实url，一般为空
    14.      oReq.method: 请求方法
    15.      oReq.clientPort: 请求的客户端端口
    16.      oReq.globalValue: pattern @globalValue
    17.      oReq.proxyValue: 配置的代理规则，一般为空
    18.      oReq.pacValue: 配置的pac规则，一般为空
    20.      oRes.serverIp: 服务端IP，只有在server或resServer、resStatsServer才能获取到
    21.      oRes.statusCode: 响应状态码，同 oRes.serverIp
    23.      // 获取抓包数据，不需要等待响应完成
    24.      req.getReqSession((s) => {
    25.        // 如果设置了 enable://hide 会获取到空数据
    26.        if (!s) {
    27.          return;
    28.        }
    29.        // do sth
    30.      }):
    31.      // 获取完整的抓包数据，要等待响应完成
    32.      req.getSession((s) => {
    33.        // 如果设置了 enable://hide 会获取到空数据
    34.        if (!s) {
    35.          return;
    36.        }
    37.        // do sth
    38.      }):
    39.      // 获取WebSocket或Socket请求的帧数据列表
    40.      // 返回 1~16 个帧数据
    41.      req.getFrames((list) => {
    42.        // 如果为空表示该长连接已断开
    43.        if (!list) {
    44.          return;
    45.        }
    46.        // do sth
    47.      }):
    48.    });
    49.  };

  3. resStatsServer：统计响应信息的服务

    1.  exports.resStatsServer = (server, options) => {
    2.    // options 同上，initial.js的options是同一个对象
    3.    server.on('request', (req, res) => {
    4.      const oReq = req.originalReq;
    5.      const oRes = req.originalRes;
    7.      req.clientIp: 请求的客户端IP，注意：挂在req里面
    9.      oReq.id: 请求的ID，每个请求对应一个唯一的ID
    10.      oReq.headers: 请求的原始headers，而req.headers包含了一些插件自定义字段
    11.      oReq.ruleValue: 配置的规则值， 如：whistle.xxx://ruleValue
    12.      oReq.url: 请求的完整url
    13.      oReq.realUrl: 请求的真实url，一般为空
    14.      oReq.method: 请求方法
    15.      oReq.clientPort: 请求的客户端端口
    16.      oReq.globalValue: pattern @globalValue
    17.      oReq.proxyValue: 配置的代理规则，一般为空
    18.      oReq.pacValue: 配置的pac规则，一般为空
    20.      oRes.serverIp: 服务端IP，只有在server或resServer、resStatsServer才能获取到
    21.      oRes.statusCode: 响应状态码，同 oRes.serverIp
    23.      // 获取抓包数据，不需要等待响应完成
    24.      req.getReqSession((s) => {
    25.        // 如果设置了 enable://hide 会获取到空数据
    26.        if (!s) {
    27.          return;
    28.        }
    29.        // do sth
    30.      }):
    31.      // 获取完整的抓包数据，要等待响应完成
    32.      req.getSession((s) => {
    33.        // 如果设置了 enable://hide 会获取到空数据
    34.        if (!s) {
    35.          return;
    36.        }
    37.        // do sth
    38.      }):
    39.      // 获取WebSocket或Socket请求的帧数据列表
    40.      // 返回 1~16 个帧数据
    41.      req.getFrames((list) => {
    42.        // 如果为空表示该长连接已断开
    43.        if (!list) {
    44.          return;
    45.        }
    46.        // do sth
    47.      }):
    48.    });
    49.  };

  4. rulesServer：设置请求规则的服务(支持http/https/websocket请求)

    1.  exports.rulesServer = (server, options) => {
    2.    // options 同上，initial.js的options是同一个对象
    3.    server.on('request', (req, res) => {
    4.      const oReq = req.originalReq;
    5.      const oRes = req.originalRes;
    7.      req.clientIp: 请求的客户端IP，注意：挂在req里面
    9.      oReq.id: 请求的ID，每个请求对应一个唯一的ID
    10.      oReq.headers: 请求的原始headers，而req.headers包含了一些插件自定义字段
    11.      oReq.ruleValue: 配置的规则值， 如：whistle.xxx://ruleValue
    12.      oReq.url: 请求的完整url
    13.      oReq.realUrl: 请求的真实url，一般为空
    14.      oReq.method: 请求方法
    15.      oReq.clientPort: 请求的客户端端口
    16.      oReq.globalValue: pattern @globalValue
    17.      oReq.proxyValue: 配置的代理规则，一般为空
    18.      oReq.pacValue: 配置的pac规则，一般为空
    20.      oRes.serverIp: 服务端IP，只有在server或resServer、resStatsServer才能获取到
    21.      oRes.statusCode: 响应状态码，同 oRes.serverIp
    23.      // 获取抓包数据，不需要等待响应完成
    24.      // 这里unsafe主要是提醒不要在回调里面返回规则
    25.      // 如果这样不会触发响应
    26.      req.unsafe_getReqSession((s) => {
    27.        // 如果设置了 enable://hide 会获取到空数据
    28.        if (!s) {
    29.          return;
    30.        }
    31.        // do sth
    32.      }):
    33.      // 获取完整的抓包数据，要等待响应完成
    34.      // 这里unsafe主要是提醒不要在回调里面返回规则
    35.      // 如果这样不会触发响应
    36.      req.unsafe_getSession((s) => {
    37.        // 如果设置了 enable://hide 会获取到空数据
    38.        if (!s) {
    39.          return;
    40.        }
    41.        // do sth
    42.      }):
    43.      // 获取WebSocket或Socket请求的帧数据列表
    44.      // 返回 1~16 个帧数据
    45.      // 这里unsafe主要是提醒不要在回调里面返回规则
    46.      // 如果这样不会触发响应
    47.      req.unsafe_getFrames((list) => {
    48.        // 如果为空表示该长连接已断开
    49.        if (!list) {
    50.          return;
    51.        }
    52.        // do sth
    53.      }):
    54.    });
    55.  };

  5. resRulesServer：设置响应规则的服务(支持http/https/websocket请求)

    1.  exports.resRulesServer = (server, options) => {
    2.    // options 同上，initial.js的options是同一个对象
    3.    server.on('request', (req, res) => {
    4.      const oReq = req.originalReq;
    5.      const oRes = req.originalRes;
    7.      req.clientIp: 请求的客户端IP，注意：挂在req里面
    9.      oReq.id: 请求的ID，每个请求对应一个唯一的ID
    10.      oReq.headers: 请求的原始headers，而req.headers包含了一些插件自定义字段
    11.      oReq.ruleValue: 配置的规则值， 如：whistle.xxx://ruleValue
    12.      oReq.url: 请求的完整url
    13.      oReq.realUrl: 请求的真实url，一般为空
    14.      oReq.method: 请求方法
    15.      oReq.clientPort: 请求的客户端端口
    16.      oReq.globalValue: pattern @globalValue
    17.      oReq.proxyValue: 配置的代理规则，一般为空
    18.      oReq.pacValue: 配置的pac规则，一般为空
    20.      oRes.serverIp: 服务端IP，只有在server或resServer、resStatsServer才能获取到
    21.      oRes.statusCode: 响应状态码，同 oRes.serverIp
    23.      // 获取抓包数据，不需要等待响应完成
    24.      req.getReqSession((s) => {
    25.        // 如果设置了 enable://hide 会获取到空数据
    26.        if (!s) {
    27.          return;
    28.        }
    29.        // do sth
    30.      }):
    31.      // 获取完整的抓包数据，要等待响应完成
    32.      // 这里unsafe主要是提醒不要在回调里面返回规则
    33.      // 如果这样不会触发响应
    34.      req.unsafe_getSession((s) => {
    35.        // 如果设置了 enable://hide 会获取到空数据
    36.        if (!s) {
    37.          return;
    38.        }
    39.        // do sth
    40.      }):
    41.      // 获取WebSocket或Socket请求的帧数据列表
    42.      // 返回 1~16 个帧数据
    43.      // 这里unsafe主要是提醒不要在回调里面返回规则
    44.      // 如果这样不会触发响应
    45.      req.unsafe_getFrames((list) => {
    46.        // 如果为空表示该长连接已断开
    47.        if (!list) {
    48.          return;
    49.        }
    50.        // do sth
    51.      }):
    52.    });
    53.  };

  6. tunnelRulesServer：设置tunnel请求规则的服务

    1.  exports.tunnelRulesServer = (server, options) => {
    2.    // options 同上，initial.js的options是同一个对象
    3.    server.on('request', (req, res) => {
    4.      const oReq = req.originalReq;
    5.      const oRes = req.originalRes;
    7.      req.clientIp: 请求的客户端IP，注意：挂在req里面
    9.      oReq.id: 请求的ID，每个请求对应一个唯一的ID
    10.      oReq.headers: 请求的原始headers，而req.headers包含了一些插件自定义字段
    11.      oReq.ruleValue: 配置的规则值， 如：whistle.xxx://ruleValue
    12.      oReq.url: 请求的完整url
    13.      oReq.realUrl: 请求的真实url，一般为空
    14.      oReq.method: 请求方法
    15.      oReq.clientPort: 请求的客户端端口
    16.      oReq.globalValue: pattern @globalValue
    17.      oReq.proxyValue: 配置的代理规则，一般为空
    18.      oReq.pacValue: 配置的pac规则，一般为空
    20.      oRes.serverIp: 服务端IP，只有在server或resServer、resStatsServer才能获取到
    21.      oRes.statusCode: 响应状态码，同 oRes.serverIp
    23.      // 获取抓包数据，不需要等待响应完成
    24.      // 这里unsafe主要是提醒不要在回调里面返回规则
    25.      // 如果这样不会触发响应
    26.      req.unsafe_getReqSession((s) => {
    27.        // 如果设置了 enable://hide 会获取到空数据
    28.        if (!s) {
    29.          return;
    30.        }
    31.        // do sth
    32.      }):
    33.      // 获取完整的抓包数据，要等待响应完成
    34.      // 这里unsafe主要是提醒不要在回调里面返回规则
    35.      // 如果这样不会触发响应
    36.      req.unsafe_getSession((s) => {
    37.        // 如果设置了 enable://hide 会获取到空数据
    38.        if (!s) {
    39.          return;
    40.        }
    41.        // do sth
    42.      }):
    43.      // 获取WebSocket或Socket请求的帧数据列表
    44.      // 返回 1~16 个帧数据
    45.      // 这里unsafe主要是提醒不要在回调里面返回规则
    46.      // 如果这样不会触发响应
    47.      req.unsafe_getFrames((list) => {
    48.        // 如果为空表示该长连接已断开
    49.        if (!list) {
    50.          return;
    51.        }
    52.        // do sth
    53.      }):
    54.    });
    55.  };

  7. server：whistle会把指定请求转发到该server

    1.  exports.statsServer = (server, options) => {
    2.    // options 同上，initial.js的options是同一个对象
    3.    server.on('request', (req, res) => {
    4.      const oReq = req.originalReq;
    5.      const oRes = req.originalRes;
    7.      req.clientIp: 请求的客户端IP，注意：挂在req里面
    9.      oReq.id: 请求的ID，每个请求对应一个唯一的ID
    10.      oReq.headers: 请求的原始headers，而req.headers包含了一些插件自定义字段
    11.      oReq.ruleValue: 配置的规则值， 如：whistle.xxx://ruleValue
    12.      oReq.url: 请求的完整url
    13.      oReq.realUrl: 请求的真实url，一般为空
    14.      oReq.method: 请求方法
    15.      oReq.clientPort: 请求的客户端端口
    16.      oReq.globalValue: pattern @globalValue
    17.      oReq.proxyValue: 配置的代理规则，一般为空
    18.      oReq.pacValue: 配置的pac规则，一般为空
    20.      oRes.serverIp: 服务端IP，只有在server或resServer、resStatsServer才能获取到
    21.      oRes.statusCode: 响应状态码，同 oRes.serverIp
    23.      // 获取抓包数据，不需要等待响应完成
    24.      req.getReqSession((s) => {
    25.        // 如果设置了 enable://hide 会获取到空数据
    26.        if (!s) {
    27.          return;
    28.        }
    29.        // do sth
    30.      }):
    31.      // 获取完整的抓包数据，要等待响应完成
    32.      // 这里unsafe主要是提醒不要在回调里面返回规则
    33.      // 如果这样不会触发响应
    34.      req.unsafe_getSession((s) => {
    35.        // 如果设置了 enable://hide 会获取到空数据
    36.        if (!s) {
    37.          return;
    38.        }
    39.        // do sth
    40.      }):
    41.      // 获取WebSocket或Socket请求的帧数据列表
    42.      // 返回 1~16 个帧数据
    43.      // 这里unsafe主要是提醒不要在回调里面返回规则
    44.      // 如果这样不会触发响应
    45.      req.unsafe_getFrames((list) => {
    46.        // 如果为空表示该长连接已断开
    47.        if (!list) {
    48.          return;
    49.        }
    50.        // do sth
    51.      }):
    52.    });
    53.  };

更多例子参考：

  1. https://github.com/whistle-plugins/whistle.script
  2. https://github.com/whistle-plugins