whistle使用實踐（配置與基礎篇）

簡介

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過程中遇到的問題，對whisle的安裝啟動、配置及基礎知識做下梳理。在介紹安裝、配置等步驟時，有時會雜糅一些遇到的問題，沒有遇到的話可以直接跳過。另外需要說明的是，由於是結合使用體驗做的梳理，許多平時用不到或使用頻率較低的內容，會寫的很簡略，如果本文解決不了你的問題的話，還請到whsitle官網去查看文檔。

安裝啟動

安裝Node

由於whistle是基於Node的，自然需要先安裝Node環境，這里不再多做說明。下面是whistle官網對Node版本的建議：

whistle支持v0.10.0以上版本的Node，為獲取更好的性能，推薦安裝最新版本的Node。

安裝whistle

Node安裝完成后，執行如下命令安裝whistle：

$ npm install -g whistle

查看版本：

whisle -V 

如果能正確輸出whistle的版本信息，就表示安裝成功了。之后可通過help命令查看幫助信息：

whistle help

啟動whistle

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

啟動whistle:

w2 start

whistle的默認端口是8899，如果要指定端口號，執行下面的命令：

w2 start -p 8888

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

w2 restart

停止whistle:

w2 stop

配置代理

配置代理時有兩個關鍵的參數：服務器IP和端口號。端口號比較簡單，對應w2 start命令啟動好的端口號即可。服務器IP的話需要分兩種情況：一種是本地，對應127.0.0.1即可，另一種是遠程，這時候需要填服務器的IP。配置所需要的信息在啟動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 > 代理

2. Mac: 系統偏好設置 > 網絡 > 高級 > 代理 > 網頁代理(HTTP) 和 安全網頁代理(HTTPS)

3. Linux: 工作中沒有用過，此處略過。詳見whistle官網

手機代理

手機端要配置代理的話，需要保證所連wifi和啟動了代理的主機處在同一網絡。以IOS為例：

1. 連接網絡（公司手機和電腦連接的不是同一網絡，這個網絡為電腦開的熱點）：
   

2. 點擊配置代理，修改為手動：
   

訪問whistle控制台

配置完代理后，我們需要先驗證下代理是否配置成功。不同於Fiddler和Charles，whistle需要用瀏覽器訪問配置頁面（即whistle控制台），有以下兩種方式：

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

因為我們是要驗證剛才配置的代理是否生效，所以訪問控制台的IP應該和配置代理的IP保持一致。

如果配置正確，我們就可以看到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 或者掃二維碼下載
   

安裝證書

證書的安裝是不依賴於代理工具的，也就是說我們無論用的是whistle還是Fiddler或者是Charles，步驟都是一樣的。我把安裝步驟單獨做了匯總，詳見【安裝證書】

開啟攔截https

安裝好證書之后，必須開啟https攔截功能之后，whistle才能看到HTTPS、Websocket的請求。開啟https攔截和安裝並信任證書，這兩個條件缺一不可。
我們需要通過下面的步驟開啟https攔截：在啟動了whistle的機器上用瀏覽器打開配置頁面，點擊https，會彈出一個帶二維碼的界面，在這個界面勾選Capture HTTPS CONNECTs選項（是不是很熟悉，在下載證書的第2種方法里我們見過的）

上面的配置完成之后，如果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對應的操作：

pattern operatorURI

pattern和operatorURI也可以左右互換（在這里），為了行文的清晰，不造成新的混淆，這里只介紹我常用的配置方式，我認為只掌握一種就夠了。

我們配置hosts時，如果一個IP要對應多個域名，會這樣子寫：

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

和系統hosts一樣，如果一個pattern要對應多個操作，whsitle也支持組合方式的配置。使用組合方式時，whistle會按照從左到右的順序執行operatorURI。

pattern operatorURI1 operatorURI2 operatorURIN

在簡單了解了配置方式之后，我們就可以按照pattern operatorURI的模式為whsitle添加規則了。
還是再回到whsitle控制台的界面，選中Rules。我們可以像使用SwitchHosts軟件管理hosts一樣對規則進行分組管理。默認情況下，whistle只有一個Default的分組，如下：

我們可以點擊Create按鈕添加一個單品頁的分組，在這個分組里可以加上所有與單品頁相關的配置（如果要禁用某個配置，可以使用Ctrl + /的快捷鍵，或者直接在前面加#）

如果要配置的分組生效，需要雙擊左側單品頁的tab，出現對號就表示生效了，沒有在使用的分組是沒有對號的，也可以同時使用多個分組。

匹配模式pattern

whistle的匹配模式分為以下幾種：

1. 域名匹配：域名匹配不僅支持匹配某個域名，也可以限定端口號、協議

// 匹配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

2. 路徑匹配：指定匹配某個路徑，也可以限定端口號、協議

// 匹配www.domain.com:81/path路徑及其子路徑（如www.domain.com:81/path/child）的請求
www.domain.com:81/path operatorURI

3. 精確匹配：與上面的路徑匹配不同，路徑匹配不僅匹配對應的路徑，而且還會匹配該路徑下面的子路徑，而精確匹配只能指定的路徑，只要在路徑前面加$即可變成精確匹配

// 匹配www.domain.com:81/path的路徑，不包含子路徑
$www.domain.com:81/path operatorURI

4. 正則匹配：正則的語法及寫法跟js的正則表達式一致，支持兩種模式：/reg/、/reg/i 忽略大小寫，支持子匹配，但不支持/reg/g，且可以通過正則的子匹配把請求url里面的部分字符串傳給operatorURI

// 匹配所有請求
* operatorURI

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

// 利用子匹配把url里面的參數帶到匹配的操作uri
// 下面正則將把請求里面的文件名稱，帶到匹配的操作uri
// 最多支持10個子匹配 $0...9，其中$0表示整個請求url，其它跟正則的子匹配一樣
/[^?#]\/([^\/]+)\.html/ protocol://...$1...

5. 通配符匹配：通常，域名匹配和路徑匹配可以滿足我們大部分的需要，不滿足的部分也可以用正則匹配來補充，但正則對大部分人來說還是有門檻的，whistle
   很貼心的為我們提供了更簡單的通配符匹配方式。目前我還沒用過通配符匹配，這里依然簡單介紹下，完整通配符匹配：在這里

• 通配符匹配

// 以 ^ 開頭
^www.example.com/test/*** protocol://...$1...

// 限定結束位置
^www.example.com/test/***test$ protocol://...$1...

如果請求url為 https://www.example.com/test/abc?123test，這第一個配置 $1 = abc?123&test，第二個配置 $1 = abc?123，而 https://www.example.com/test/abc?123test2 只能匹配第一個。

• 通配域名匹配

// 匹配以 .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...

• 通配路徑匹配

// 對所有域名對應的路徑 protocol://a.b.c/xxx[/yyy]都生效
*/ 127.0.0.1

操作值operatorURI

whistle官網將whsitle的操作值分為字符串和JSON對象兩種。本文按照配置方式的不同，將whislte的操作值分為兩種：帶空格的和不帶空格的。

• 帶空格：帶空格的字符串和保留縮進格式的JSON對象
• 不帶空格：不帶空格的字符串和序列化了的不帶空格的JSON對象

不帶空格的操作值可以直接在operatorURI中寫入，模式為pattern opProtocol://(strValue)，注意字符串必須要用括號包裹：

// 將符合pattern的url的返回內容用helloworld代替
pattern resBody://(helloworld)

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

1. 保存在Values中
   在whsitle控制台中打開Values標簽，點擊Create，增加名稱為test.json的操作值，並在右側編輯test.json的內容，可按照pattern opProtocol://{valueName}來使用，注意value名稱是用打括號包裹的，如下：

// 將符合pattern的url的返回內容用test.json文件中的內容代替
pattern resBody://{test.json}

增加的操作值的名稱是按照自己的需求取的，后綴名也是非必填的。使用后綴名的話會按照對應的格式高亮展示，不使用的話默認文本格式展示

2. 保存在本地文件中
   首先我們先在本地新建一個test1.json的文件，然后在whsitle控制台中點擊Files標簽
   

按照步驟選中創建的test1.json文件，whsitle會生成一個path，我們可以按照這個路徑來使用

// 將符合pattern的url的返回內容用test.json文件中的內容代替
pattern resBody:///$whistle/test1.json

原文地址：https://yolkpie.net/2020/12/22/whistle使用實踐（配置與基礎篇）/