简介

whistle是基于Node实现的跨平台web调试代理工具，同类型的工具有Fiddler和Charles，主要用于查看、修改HTTP、HTTPS、Websocket的请求、响应，也可以作为HTTP代理服务器使用。

在使用了Fiddler、Charles以及whistle这三款代理工具之后，总结出来的whistle的优势有以下几点：

  1. 配置简单：whistle的配置类似于系统hosts的配置，一切操作都可以通过配置实现，支持域名、路径、正则表达式、通配符、通配路径等多种匹配方式。
  2. 支持扩展：whistle提供了插件扩展能力，通过插件可以新增whistle的协议实现更复杂的操作、也可以用来存储或监控指定请求、集成业务本地开发调试环境等等，基本上可以做任何你想做的事情，且开发、发布及安装whistle插件也都很简单。
  3. 内置weinre：通过weinre可以修改调试移动端DOM结构、捕获页面异常等。
  4. 界面简单易懂：从界面来看，whistle的功能划分为了network（网络）、rules（规则）、values（数据）、pulgins（插件）四大模块，通过tab页签进行切换。
  5. 文档全面：whistle官网提供了详细的说明文档，工作中遇到的情况只要查阅文档都能解决。

下图是whistle支持的功能:
whistle功能

本文将结合本人在使用whistle过程中遇到的问题，对whisle的安装启动、配置及基础知识做下梳理。在介绍安装、配置等步骤时，有时会杂糅一些遇到的问题，没有遇到的话可以直接跳过。另外需要说明的是，由于是结合使用体验做的梳理，许多平时用不到或使用频率较低的内容，会写的很简略，如果本文解决不了你的问题的话，还请到whsitle官网去查看文档。

安装启动

安装Node

由于whistle是基于Node的，自然需要先安装Node环境，这里不再多做说明。下面是whistle官网对Node版本的建议：

whistle支持v0.10.0以上版本的Node，为获取更好的性能，推荐安装最新版本的Node。

安装whistle

Node安装完成后，执行如下命令安装whistle：

1
$ npm install -g whistle

查看版本：

1
whisle -V

如果能正确输出whistle的版本信息，就表示安装成功了。之后可通过help命令查看帮助信息：

1
whistle help

启动whistle

whistle支持三种等价的命令whistle、w2、wproxy，本文使用w2命令。下面是常用的命令：

启动whistle:

1
w2 start

whistle的默认端口是8899，如果要指定端口号，执行下面的命令：

1
w2 start -p 8888

重启whistle（也支持指定端口）:

1
w2 restart

停止whistle:

1
w2 stop

配置代理

配置代理时有两个关键的参数：服务器IP和端口号。端口号比较简单，对应w2 start命令启动好的端口号即可。服务器IP的话需要分两种情况：一种是本地，对应127.0.0.1即可，另一种是远程，这时候需要填服务器的IP。配置所需要的信息在启动whistle时控制台会告诉我们，见下图：

whistle启动界面

从上面的图片可以看出，端口号为8899，IP有127.0.0.1、10.1.2.30、192.168.137.1和192.168.191.1这四个，如果是本地代理的话，这四个IP都可以（如果不想每次IP更换都要重新配置，选127.0.0.1呀），如果是远程代理，除了127.0.0.1之外，其他都可以的（仍然不建议填10.1.2.30这个IP，理由同上）。

下面来说下配置代理的几种方式：

浏览器代理

浏览器代理的话要使用浏览器的代理插件，这里介绍chrome和firefox两种：

  1. chrome：使用SwitchOmega插件。
  2. firefox：地址栏输入访问 about:preferences，找到 Network Proxy，选择 手动代理配置(Manual proxy configuration)，输入代理服务器地址、端口，保存即可。

全局代理

  1. Windows: 菜单 > 设置 > 网络和Internet > 代理

Windows全局代理

  1. Mac: 系统偏好设置 > 网络 > 高级 > 代理 > 网页代理(HTTP) 和 安全网页代理(HTTPS)

Mac全局代理

  1. Linux: 工作中没有用过，此处略过。详见whistle官网

手机代理

手机端要配置代理的话，需要保证所连wifi和启动了代理的主机处在同一网络。以IOS为例：

  1. 连接网络（公司手机和电脑连接的不是同一网络，这个网络为电脑开的热点）：
    连接wifi

  2. 点击配置代理，修改为手动：
    配置代理

访问whistle控制台

配置完代理后，我们需要先验证下代理是否配置成功。不同于Fiddler和Charles，whistle需要用浏览器访问配置页面（即whistle控制台），有以下两种方式：

  1. 域名访问：http://local.whistlejs.com/
  2. IP + 端口访问： 如http:192.168.191.1:8888

因为我们是要验证刚才配置的代理是否生效，所以访问控制台的IP应该和配置代理的IP保持一致。

如果配置正确，我们就可以看到whistle的控制台了，如下图：
whistle页

如果页面打不开，则可能是whistle所在的电脑防火墙限制了远程访问whistle的端口，需要关闭防火墙或者设置白名单。

设置白名单的步骤如下：

  1. 控制面板 -> 系统和安全 -> Windows Defender防火墙 -> 高级设置 -> 入站规则 -> 新建规则
  2. 选择端口
    选择端口
  3. 输入wistle启动时设置的端口号
    输入端口号
  4. 选择允许连接
    允许连接
  5. 输入设置的规格名称
    输入规则名称
  6. 在入站规则列表中查看是否新建成功以及是否开启，开启之后whistle提供的服务就可以在局域网中访问了
    查看入栈规则

安装https证书

关闭防火墙或者给whsitle设置了白名单之后，如果whistle的设置页面可以正常打开，这表示说我们可以代理http请求了。

如果你的页面和接口全部是http请求，就可以忽略安装https证书的这一步了。但现实是除了本地或者预发环境，我们很难找到不是https的了（很多预发环境也是https的），因此还是建议提前把证书装上。
如果你的环境中出现了以下情况（当然，没有装好证书的话这些情况基本都会出现的），就是https证书没有安装或者没装好：

  1. whisle的配置页面可以打开，但是网页不能打开或者只加载了一部分页面
  2. 京东App数据更新不了或展示不全，或者扫码提示“无法获取信息”
  3. whistle配置页面中network中443端口的请求前面有小锁，或者抓不到请求
  4. 浏览器提示“您的连接不是私密连接”

下载证书

我们可以通过下面的方式下载证书：

  1. 在配置代理的设备上打开浏览器，在浏览器中输入rootca.pro即可下载，这种是最便捷的方式
  2. 在启动了whistle的机器上用浏览器打开配置页面，点击https，会弹出一个带二维码的界面，点击Download RootCA 或者扫二维码下载
    https证书

安装证书

证书的安装是不依赖于代理工具的，也就是说我们无论用的是whistle还是Fiddler或者是Charles，步骤都是一样的。我把安装步骤单独做了汇总，详见【安装证书】

开启拦截https

安装好证书之后，必须开启https拦截功能之后，whistle才能看到HTTPS、Websocket的请求。开启https拦截和安装并信任证书，这两个条件缺一不可。
我们需要通过下面的步骤开启https拦截：在启动了whistle的机器上用浏览器打开配置页面，点击https，会弹出一个带二维码的界面，在这个界面勾选Capture HTTPS CONNECTs选项（是不是很熟悉，在下载证书的第2种方法里我们见过的）
开启https拦截

上面的配置完成之后，如果https的请求还是不能正常访问或者还是出现安全提醒，可以重新打开浏览器访问或者重启下whistle。whistle官网给出的解释是如果之前访问过该页面，导致长链接已建立，所以我们之后的配置是不生效的。

基础

虽然在[whistle使用实践（实例篇）]中我会按照具体的使用场景来详细介绍whistle的使用方法，但是在此之前，我们有必要对whistle控制台的功能划分和whisle的配置方式做一下简单的了解。

控制台

whistle控制台的打开方式上文我们已经说过了，这里不再重复。
whistle控制台核心部分的分区如下（[whistle界面详细列表点这里]（http://wproxy.org/whistle/webui/））：
控制台划分

  1. NetWork: 查看请求响应的详细信息及请求列表的Timeline
  2. Rules: 匹配规则，whistle核心，详见下一节配置方式
  3. Values: 配置key-value的数据，在Rules里面配置可以通过{key}获取
  4. Plugins: 显示所有已安装的插件列表，开启关闭插件功能

配置方式

在文章的开头就说过，whistle的所有操作都可以通过配置实现，配置方式扩展于系统hosts配置方式(ip domain或组合方式ip domain1 domain2 domainN)，具有更丰富的匹配模式及更灵活的配置方式。

whistle默认的配置方式是将匹配模式(pattern)写在左边，操作uri(operatorURI)写在右边。这样，whistle会将请求的url与pattern进行匹配，如果匹配上就执行operatorURI对应的操作：

1
pattern operatorURI

pattern和operatorURI也可以左右互换（在这里），为了行文的清晰，不造成新的混淆，这里只介绍我常用的配置方式，我认为只掌握一种就够了。

我们配置hosts时，如果一个IP要对应多个域名，会这样子写：

1
127.0.0.1  www.domain1.com www.domain2.com www.domainN.com

和系统hosts一样，如果一个pattern要对应多个操作，whsitle也支持组合方式的配置。使用组合方式时，whistle会按照从左到右的顺序执行operatorURI。

1
pattern operatorURI1 operatorURI2 operatorURIN

在简单了解了配置方式之后，我们就可以按照pattern operatorURI的模式为whsitle添加规则了。
还是再回到whsitle控制台的界面，选中Rules。我们可以像使用SwitchHosts软件管理hosts一样对规则进行分组管理。默认情况下，whistle只有一个Default的分组，如下：
default分组

我们可以点击Create按钮添加一个单品页的分组，在这个分组里可以加上所有与单品页相关的配置（如果要禁用某个配置，可以使用Ctrl + /的快捷键，或者直接在前面加#）
添加分组

如果要配置的分组生效，需要双击左侧单品页的tab，出现对号就表示生效了，没有在使用的分组是没有对号的，也可以同时使用多个分组。
分组生效

匹配模式pattern

whistle的匹配模式分为以下几种：

  1. 域名匹配：域名匹配不仅支持匹配某个域名，也可以限定端口号、协议
1
2
3
4
5
6
7
8
9
// 匹配www.domain.com域名下的所有请求，包括http、https、ws、wss，tunnel
www.domain.com operatorURI

// 匹配www.domain.com域名下的http请求

http://www.domain.com operatorURI

// 匹配www.domain.com域名下81端口的请求(http请求默认为80端口，https请求默认为443端口)
www.domain.com:81 operatorURI

  1. 路径匹配：指定匹配某个路径，也可以限定端口号、协议

    1
    2
    // 匹配www.domain.com:81/path路径及其子路径（如www.domain.com:81/path/child）的请求
    www.domain.com:81/path operatorURI

  2. 精确匹配：与上面的路径匹配不同，路径匹配不仅匹配对应的路径，而且还会匹配该路径下面的子路径，而精确匹配只能指定的路径，只要在路径前面加$即可变成精确匹配

1
2
// 匹配www.domain.com:81/path的路径，不包含子路径
$www.domain.com:81/path operatorURI
  1. 正则匹配：正则的语法及写法跟js的正则表达式一致，支持两种模式：/reg/、/reg/i 忽略大小写，支持子匹配，但不支持/reg/g，且可以通过正则的子匹配把请求url里面的部分字符串传给operatorURI
1
2
3
4
5
6
7
8
9
10
// 匹配所有请求
* operatorURI

// 匹配url中包含keyword的请求，且忽略大小写
/keyword/i operatorURI

// 利用子匹配把url里面的参数带到匹配的操作uri
// 下面正则将把请求里面的文件名称，带到匹配的操作uri
// 最多支持10个子匹配 $0...9，其中$0表示整个请求url，其它跟正则的子匹配一样
/[^?#]\/([^\/]+)\.html/ protocol://...$1...
  1. 通配符匹配：通常，域名匹配和路径匹配可以满足我们大部分的需要，不满足的部分也可以用正则匹配来补充，但正则对大部分人来说还是有门槛的，whistle
    很贴心的为我们提供了更简单的通配符匹配方式。目前我还没用过通配符匹配，这里依然简单介绍下，完整通配符匹配：在这里
1
2
3
4
5
6
7
8
9
// 匹配以 .com 结尾的所有url，如: test.com, abc.com，但不包含 *.xxx.com
*.com protocol://...$1...
// 匹配 test.com 的子域名，不包括 test.com
// 也不包括诸如 *.xxx.test.com 的四级域名，只能包含: a.test.com，www.test.com 等test.com的三级域名
*.test.com protocol://...$1...

// 如果要配置所有子域名生效，可以使用 **
**.com protocol://...$1...

  • 通配路径匹配
1
2
// 对所有域名对应的路径 protocol://a.b.c/xxx[/yyy]都生效
*/ 127.0.0.1

操作值operatorURI

whistle官网将whsitle的操作值分为字符串和JSON对象两种。本文按照配置方式的不同，将whislte的操作值分为两种：带空格的和不带空格的。

  • 带空格：带空格的字符串和保留缩进格式的JSON对象
  • 不带空格：不带空格的字符串和序列化了的不带空格的JSON对象

不带空格的操作值可以直接在operatorURI中写入，模式为pattern opProtocol://(strValue)，注意字符串必须要用括号包裹：

1
2
// 将符合pattern的url的返回内容用helloworld代替
pattern resBody://(helloworld)

带空格的操作值需要将操作值保存在Values或者本地文件中。

  1. 保存在Values中
    在whsitle控制台中打开Values标签，点击Create，增加名称为test.json的操作值，并在右侧编辑test.json的内容，可按照pattern opProtocol://{valueName}来使用，注意value名称是用打括号包裹的，如下：

添加values

1
2
// 将符合pattern的url的返回内容用test.json文件中的内容代替
pattern resBody://{test.json}

增加的操作值的名称是按照自己的需求取的，后缀名也是非必填的。使用后缀名的话会按照对应的格式高亮展示，不使用的话默认文本格式展示

  1. 保存在本地文件中
    首先我们先在本地新建一个test1.json的文件，然后在whsitle控制台中点击Files标签
    点击Files

按照步骤选中创建的test1.json文件，whsitle会生成一个path，我们可以按照这个路径来使用
选中

1
2
// 将符合pattern的url的返回内容用test.json文件中的内容代替
pattern resBody:///$whistle/test1.json