Xu Shuaiwu is a front end engineer of Wemedical Cloud Service team. A front-end programmer who loves to do things on weekends
preface
Why do we need a proxy tool? How useful is a flexible agent tool for development?
A handy proxy tool that allows us to control our development environment at will. No! Directly cut a usable environment and follow my development. The process of validating the different data states of the page should also generate data? No! Direct agent to modify the data to go through the process, save effort. Specific models online problem scratching scratching cheeks do not know how to locate? The agent connects to the view element and remote log to easily locate the problem……
Using an agent will not solve all problems, but it will save us more than half the time in the process of solving problems, rather than having to wait for a restart when we encounter environmental problems
Whistle is introduced
The official quote about Whistle goes below
Whistle is a cross-platform Node-based web debugging proxy. Similar tools include Fiddler on Windows, It is used to view and modify HTTP, HTTPS, and Websocket requests and responses. It can also be used as an HTTP proxy server. Unlike Fiddler, which uses breakpoints to modify requests and responses, Whistle uses a similar configuration to the system hosts. All operations can be configured to support multiple matching modes, such as domain names, paths, regular expressions, wildcards, and wildcard paths. In addition, Node modules can be used to extend functions
Compared with Charles
Most people start out with one of the oldest proxy tools, Charles and Fiddler. I was Charles’s door. But after learning about The Whistle, he decided to embrace it. Here are some of the advantages I think Whistle has.
- Open source is free, and compared to Charles, open source Whistle is certainly more affordable to use.
- Easy to install, Whistle is based on Node, and the installation is to install the NPM package globally, which is certainly more front-end friendly.
- Configuration centralization is flexible. Whistle’s various features are centrally managed using a configuration file, which is more user-friendly and shareable to view and modify.
- Free programmable, when the built-in functions can not meet the needs, you can also use the Npm package to develop plug-ins, which is more user-friendly for JS developers.
How to use
Installation and use
For non-root Mac or Linux users, add sudo to the front of the command line, e.g. Sudo NPM install -g whistle.
#The installation
npm install -g whistle
#Start the
w2 start
#restart
w2 restart
#stop
w2 stop
Copy the codeAccessing the home screen
In general, direct accesshttp://localhost:8899/#networkThis address will do. If you do not use the default port, change to the enabled port number. The interface is as follows:
Configure the agent
Configuration information
Proxy server: 127.0.0.1 (If deployed on a remote server or VM, change the IP address of the corresponding server or VM)
Default port: 8899 (if the port is occupied, you can specify the new port at startup by using -p. For more information, you can run the w2 help command line (also available for v0.7.0 and later).)
Since Whistle cannot automatically set up a system agent, the content that requires a proxy needs to be configured manually
Agent system
This is not commonly used, each system to set the system agent in different ways, you can find the setting method
Browser proxy (Chrome as an example)
Chrome also allows you to set up proxies, but it’s recommendedSwitchyOmegaThe plug-in manages the proxy, and you can configure the ladder’s proxy rules at the same time, so that you will not be unable to access Google
Mobile agent
The mobile proxy requires both devices to be on the same WiFi (network connectivity). Configure the proxy for the current Wi-Fi in the Settings. For iOS: the proxy server is the IP of the Whistles device that started
The HTTPS certificate
Skip this section if you have configured or no HTTPS requirements.
By default, HTTPS cannot be used to view the content of the document. We need to install a custom root certificate to view the content of the HTTPS request. There is nothing special about this part of the document.
Download the root certificate and enable the capture of HTTPS requests:
Installing the Root Certificate
If there is a security alert after the certificate is installed, the main reason is that you have visited the page before, resulting in a long connection. You can wait for some time to visit, or reopen the browser, or restart Whistle: w2 restart
After downloading the root certificate, click the rootca. CRT file. The dialog box for installing the root certificate is displayed.
Windows:
Installing a root certificate on Windows
After downloading the certificate, double-click the certificate and install the certificate as instructed. During certificate installation, ensure that certificates are stored under a trusted root certification authority.
Mac:
After the Mac certificate is installed, you need to manually trust the certificate by performing the following steps:
Open the certificate management interface and find the certificate with the word whistle. If there are more than one certificate and you are not sure which one is the latest one, you can delete all the certificates and reinstall them
Double-click the certificate, click the left side of Trust to expand the option, the red part is Always Trust (Always Trust), click the upper left corner to close the current interface will require input password; After entering the password, you can see that the red icon X on the certificate is missing. This step indicates that the certificate installation is complete.
Firefox:
Menu > Preferences > Advanced > Certificates > Certificate Authorities > Import -> Select all Checkboxes -> OK
iOS
After setting up the agent on your phone, enter Rootca. pro in the address bar of Safari and install the certificate as prompted (or scan the QR code of the Whistle console to install the certificate. After iOS 10.3, you need to manually Trust the custom root Certificate. Set the path to Settings > General > About > Certificate Trust Testings. For details, see here
Android
- Scan the QR code to install the Whistle console, or install the browser address bar rootca.pro as prompted
- Some browsers do not automatically recognize CA certificates. You can install them using Android Chrome
- Some apps after Android 6.0 still fail to manually capture HTTPS connections after successfully installing certificates. It is possible that the app does not have the permission to trust the user’s customized certificates. Please confirm whether the app has the following configuration:
<base-config cleartextTrafficPermitted="true">
<trust-anchors>
<certificates src="system" />
<certificates src="user" />
</trust-anchors>
</base-config>
Copy the codeThis is mainly due to the change in the default configuration after Android 6.0. For more information, see the Android development documentation.
Enabling HTTPS interception
The dialog that opens in the figure has a checkbox:
1.Capture HTTPS CONNECTs: Enable HTTPS interception. Whistle can see HTTPS and Websocket requests only after checking the checkbox and installing the root certificate
Custom request certificate or root certificate
Whistle automatically generates a root certificate and dynamically generates HTTPS certificates for each request based on the root certificate. If a whistle needs a custom certificate or even a root certificate, it can use either of the following methods (only.crt certificates are supported) :
Match the ordinary certificate to (e.g. CRT and test.key, test2. CRT and test2.key, etc.) or the root certificate (the name must be root. CRT and root.key) in a directory such as /data/ SSL. W2 start -z /data/ SSL, WhistleAppData/custom_certs/.WhistleAppData/custom_certs/.WhistleAppData/custom_certs/
Priority -z dir > ~/.WhistleAppData/ > Built-in certificate
Match rule
There are many matching rules for Whistle. Here are some commonly used matching patterns that can cover 90% of the usage scenarios. Detailed rules can be viewed in [Matching Rules].
Note: Default matching rules are of the following form: Pattern operatorURI, matching rule on the left, operation rule on the right.
Domain name matching
#Matches all requests under the domain name www.test.com, including HTTP, HTTPS, WS, WSS, and tunnel
www.test.com operatorURI
#Matches all HTTP requests under the domain name www.test.com
http://www.test.com operatorURI
#Matches all HTTPS requests under the domain name www.test.com
https://www.test.com operatorURI
#The above matches can also qualify the port number of the domain namewww.test.com:8888 operatorURI # Port 8888 www.test.com/ operatorURI # HTTP for port 80, others for port 443Copy the codePath matching
#Limits the request protocol to match only HTTP requests
http://www.test.com/xxx operatorURI
http://www.test.com:8080/xxx operatorURI
#Matches all requests in the specified path
www.test.com/xxx operatorURI
www.test.com:8080/xxx operatorURI
Copy the codeWildcard match
Wildcard matching starts with ^. * is a wildcard. You can use 1, 1, and 9 to match the groups matched by the wildcard.
#Wildcard matches must begin with a ^
#Visit wy.guahao.com/abc/xyz/1.js will be mapped to/path/to/xyz / 1. Js
^wy.guahao.com/abc/*** /path/to/$1
#You can also end with a $limit
#Only the url at the end of index.js is forwarded
^wy.guahao.com/abc/***index.js$ /path/to/$1
Copy the code* means to stop when one/is matched, and *** means to match multiple
Domain name wildcard
* * * * * * * * * * * * * * * * * * * * * To apply to all subdomains, use ***.com operatorURI to match wx.wy.guahao.com
Regular match
For very flexible matching rules, you can use regular matching.
#Match all requests
/./ operatorURI
#Matches requests that have more than one keyword in the URL
/keyword/ operatorURI
#Matching by re, same thingThe $1~$9Capture grouping,$0Represents the entire URL
/(\d+).html/ operatorURI
Copy the codeCommonly used functions
Bind the Host
If the Host configuration is changed, it will not be cached and will take effect immediately
127.0.0.1 wy.guahao.com
Copy the codeReplace the request
Debug some domain name verification is difficult to find in the local problem (such as wechat authorization, wechat SDK call), can be online page proxy to the local development environment to troubleshoot the problem.
For some non-WebPack compiled resources can be used to replace online resources, to achieve direct debugging online effect. If the front and back ends of a project are not separated and the local environment is difficult to configure, you can debug the LOCAL JS and CSS files in the test environment.
#Local replacement line
127.0.0.1 wya.guahao.com
https://wy.guahao.com http://wya.guahao.com:8080
#Proxy replacement resource^ http://test.guahao-test.com/front/hps-h5-static/css/h5.min.css * * * http://127.0.0.1:9091/front/hps-h5-static/css/h5.css ^ http://test.guahao-test.com/front/hps-h5-static/js/h5.js * * * http://127.0.0.1:9091/front/hps-h5-static/js/h5.jsCopy the codeReplace returned content
The text class requests the append content and replaces the returned content
# description: append the content behind the request to http://guahao.com/style.css resAppend: / / {myAppend. CSS} # description: Completely replace request content http://guahao.com/style.css resBody: / / {myResBody. CSS}Copy the codeInjecting JS Script
We don’t normally enable debugging tools like vConsole and Eruda for online projects. It is difficult to view error reports and other information when a problem occurs. You can use an agent to inject the vConsole and Eruda into the page to see the problem.
#The htmlAppend operation is to inject the debugger variable at the end of the HTML section, and the contents of the variable are set in the "Value" panel
https://wy.guahao.com/ htmlAppend://{debugger}
Copy the codeContents of the debugger variable:
<script crossorigin="anonymous" integrity="sha384-ltIfi6+efoMR4xY0cwhn9a243JE/09cby6RJioKuqFKzs4un/eTmCLbAGaVM8xsJ" src="https://lib.baomitu.com/eruda/2.2.1/eruda.js"></script>
<script>eruda.init();</script>
Copy the code
Output from remote console. XXX
The pain point of mobile debugging is that you can’t view the log. Even if we use the above method to inject debugging tools such as Eruda into the page, it is inevitable that the two devices switch back and forth to view the content. Whistle has a remote Log platform similar to the browser Console. Using the corresponding rules, you can view the logs on other devices on the PC
#Wy.guahao.com domain name web site remote printlog
# wy.guahao.com log: / /
#Remote printlogSimultaneous injection of scripts
wy.guahao.com log://{injection-log}
#--------- Value section ------------
#Injection - the log contentThe console. The log (' -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- start -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- ') console. The log (' remote log) console. The log (' view a variable, window) console.log('-----------------end---------------------')Copy the code
Integrated Weinre remote debugging
Weinre is an Apache Infrastructure project, short for WEb INspector REmote. As the name suggests, it is similar to Firebug or a browser debugging tool, but enables you to run and debug web pages remotely. So if you’ve used firefox developer tools or Chrome’s debugging tools, getting started with Weinre is very easy and natural.
But the Weinre configuration is cumbersome, and Whistle automatically injects Weinre’s startup script into the page, making using Weinre a one-sentence affair.
Wy.guahao.com weinre://[key]Copy the code
summary
These are just a few of the functions I used during the development process, but Whistle is much more than that. If you’re interested, check out the Whistle documentation for more details. Below is a part of its protocol list, which is rich in features. And support plug-in writing, there are custom requirements can also write their own plug-in to achieve the required function.
