To do a good job, he must sharpen his tools.

I have been mainly engaged in the development of mobile terminal pages. The development of mobile terminal pages often requires real machine development and debugging by proxy. During this period, I have used Fiddler, SwitchHosts, Charles, Whistle and other proxy tools, and found that Whistle is the most efficient to use. The text-based configuration is simpler and more convenient than the GUi-based configuration of Charles. Besides, the plug-in expansion ability based on Whistle can realize more customized functions, improve development efficiency and improve development experience. It is very suitable for students to develop.

🏆 introduction

Whistle is an open source cross-platform Web debugging agent based on Node. It is mainly used to view and modify HTTP, HTTPS, Websocket requests and responses. It can also be used as an HTTP proxy server. Whistle uses the same method as hosts. You can configure everything in whistle. It supports multiple matching methods such as domain names, paths, regular expressions, wildcards, and wildcard paths.

#Mac Check the system hosts configuration 
$ sudo vi /etc/hosts 
Copy the code

The principle of

Whistle starts a proxy server. All requests go through Whistle and then forward to the real server, so when Whistle intercepts a request, it can do a lot of customization for the request. For details, see HTTP Proxy principles and implementation.

🚀 Quick start

The installation

To install Whistle, you need to install Node first. For better performance, you are advised to install the latest version of Node.

#Whistle installation, non-root users on Mac or Linux need to prefix the command line with sudo 
$ npm install -g whistle 
Copy the code

The latest version of Whistle supports three equivalent commands, whistle, w2, and wProxy, and w2 is used in this article.

#Check the version 
$ w2 -V 

#Viewing Help Information 
$ w2 help 
Copy the code

If the version information of Whistle is displayed, the installation is successful. You can run the help command to view the help information.

Start the

The common commands for whistle are as follows. For more command line parameters, see the command line parameters.

#Start the 
$ w2 start 
 
#restart 
$ w2 restart 
 
#stop 
$ w2 stop 
Copy the code

After Whistle is started, you can use the Whistle Console to configure proxies and capture packets. For details about the functions of the console, see the interface list.

Configure the agent

PC Proxy Configuration

The global agent

The global agent is a direct configuration of the system agent, after which all network requests are forwarded by Whistle. The global agent is required for development and debugging using the simulator.

  • Windows
  • Mac: System Preferences -> Network -> Advanced -> Proxy -> Web Proxy (HTTP)& Secure Web Proxy (HTTPS)

The default port number is 8899. Enter the corresponding port number if you specified it when starting Whistle.

Browser proxy

The browser proxy requires the plug-in of the browser. After the proxy is configured, the network requests of the browser are processed, and the networks of other browsers or software are not affected.

  • Chrome: Install the SwitchyOmega plugin.

Mobile proxy configuration

To configure the agent on the mobile terminal, you need to ensure that the WIFI of the mobile phone and PC are on the same network. The following takes iOS as an example, and Android is similar.

The server IP address and port can be clicked in the upper right corner of the Whistle consoleOnlineLook at it.

Install the certificate

After the proxy configuration is complete, you can go to the console to capture packets and verify whether the packet is successfully captured. Then you will find that only HTTP requests can be captured. To capture HTTPS requests, you need to install the Whistle certificatewhistle HTTPS. After the certificate is installed, enable the HTTPS and Websocket interception functions. Enabling HTTPS, Websocket interception, and installing and trusting certificates are both necessary.You can use Whistle for agent development and debugging.

🛠 ️ function

Whistle provides almost everything that a packet capture debugging tool can do. The following figure summarizes the features commonly used in WhistleAgreement list.

configuration

All whistle operations can be implemented using the following configuration mode. The configuration mode is extended to the hosts configuration mode (IP domain or combination mode IP domain1 domain2 domainN), providing richer matching modes and more flexible configuration modes. The matching sequence of Whistle is from left to right, which is different from the traditional configuration of Hosts from right to left. However, whistle can be switched in most cases to be compatible with the traditional configuration of Hosts. Pattern operatorURI is equivalent to operatorURI Pattern.

For easy reading, you are advised to write pattern operatorURI from left to right.

pattern operatorURI 
Copy the code
  1. Pattern is an expression that matches the requested URL. The pattern can be a domain name, path, regular, or wildcard. For details, see Matching Mode.
 # domain name matching
 www.example.com 
 
 # Path matching, support with protocol, port
 www.example.com/test 
 
 # regular match/^https? ://www\.example\.com\/test/(.*)/ referer://http://www.test.com/The $1 
 
 # wildcard match
 ^www.example.com/test/*** referer://http://www.test.com/The $1 
Copy the code

Wildcard: domain name, path matching cannot satisfy some complicated situation, while regular matching can solve the problem of all matches, but the threshold is a little high, and relates to escape and set the starting position of the match, to offer some commonly used matching whistle more simple configuration, contain wildcard matching, wildcard domain, the path of wildcard match; The wildcard matching pattern must start with ^ (if you need to restrict the end position), ∗ is a wildcard, which supports pass), * is a wildcard, which supports pass), ∗ is a wildcard, which supports pass 0… 9 Gets the wildcard matching string, where $0 represents the entire request URL. See Matching Pattern – Wildcard Matching for more usage.

  1. The operatorURI is the corresponding operation and consists of the operation protocol and operation value.
operatorURI = operatorProtocol://operatorValue 
Copy the code
  • OperatorProtocol, which corresponds to a certain type of operation, for example:
# Local replacement, file protocol
pattern file://opValue
Copy the code
  • OperatorValue (operation value), corresponding to the parameter value of the operation, for example:
# Local replacement, file protocol
pattern file:///User/test/dirOrFile # or the pattern/User/test/dirOrFile
Copy the code
  1. Pattern and operatorURI support the combined mode. For details, see configuration mode.
# Traditional combination
# A pattern corresponds to multiple operations
pattern operatorURI1 operatorURI2 operatorURIN 
 
# If the pattern part is a path or domain name, and the operator URI is a domain name or path
# In this case, multiple patterns for one operation are also supported
operatorURI pattern1 pattern2 patternN 
Copy the code

Commonly used functions

The host forwarding

In local development, the request is forwarded to the local port, which can be used to remove the port number in the URL during development. After forwarding, the local page can be directly accessed using the online address, which can solve the relative path jump and cross-domain interface problems in local development. For more information, see the host protocol.

# Local port mapping
# online address: https://www.example.com/test
# development address: https://localhost:4000/
www.example.com 127.0.0.1:4000 
 
Page A will be forwarded to page B
It can be used to debug the embedded APP page. There is an entry link A in the APP, and the target page is B
www.example.com/a.html www.example.com/b.html 
Copy the code

Modify the request header

Modify request headers If the reqHeaders protocol is used, you can configure the swimlane of a back-end interface. The value in curly braces is the operation value.

www.example.com/api/xxx reqHeaders://{key}
Copy the code

Delayed response

Setting the delay response time (milliseconds) Using the resDelay protocol, you can use it to simulate an interface returning slowly.

Return after 5 seconds
www.example.com/api/xxx resDelay://5000 
Copy the code

Modify the response status code

Modify the response statusCode using the statusCode or replaceStatus protocol, which can be used to simulate an interface return error. ReplaceStatus indicates that the statusCode is changed after the request is responded. StatusCode does not send the request. After setting the statusCode, the request is returned.

The analog interface returned 500 errors
www.example.com/api/xxx statusCode://500 
Copy the code

Replace the response content

Use the resBody protocol, which can be used to mock data.

Replace the specified content with a local file
www.example.com/xxx resBody://filepath 
 
# Replace the specified content with the whistle value
www.example.com/xxx resBody://{key} 
Copy the code

Append response Content

Use the resAppend protocol to append the specified content to the response content. Use the resPrepend protocol to append the specified content to the response content. It can be used to inject some custom scripts, such as vConsole, etc.

Append the specified content to the response content
www.example.com/xxx resAppend://{key} 
 
# append the specified content to the response content
www.example.com/xxx resPrepend://{key} 
Copy the code

Cross domain

Modify the cORS of the response using the resCors protocol, which can be used to solve cross-domain problems.

# `*` 表示设置 access-control-allow-origin: * 
www.example.com resCors://* 
 
# `enable` 表示设置 access-control-allow-origin: http://originHost 
# and access - control - allow - credentials: true
www.example.com resCors://enable 
Copy the code

Mobile debugging

Mobile debugging mainly involves injecting vConsole, using Weinre to remotely view, modifying the DOM structure and style of the page, and using log to print log debug. For details, see Using Whistle to Debug a mobile page.

  • Injection vConsole
www.example.com jsAppend://{vConsole.js} 
Copy the code
  • weinre
# XXX is the corresponding Weinre ID, which is mainly used for page classification. The default is Anonymous
www.example.com weinre://xxx 
Copy the code
  • Print log
# XXX is the page classification, in order to facilitate simultaneous debugging of different pages
www.example.com log://xxx 
Copy the code

Set the packet capture style

Using the Style protocol, you can use it to highlight specific requests for easy viewing.

# color: The color of the font, the same as the CSS color attribute. Since '#' is the whistle annotation symbol, it can be replaced with '@'
# fontStyle: fontStyle can be set to normal, italic, oblique, etc
# bgColor: The background color of the row in the list, set to the same color
www.example.com/api/xxx style://color=@fff&fontStyle=italic&bgColor=red 
Copy the code

Filter configuration

The filtering configuration uses the excludeFilter and includeFilter protocols. ExcludeFilter excludes matching requests, and includeFilter reserves only matching requests.

# host Forwards requests from the back-end interface
www.example.com 127.0.0.1:4000 excludeFilter://*/aweme/ 
Copy the code

Clear the cache

You can Disable the current page cache using Chrome by opening the Developer tool and selecting the Disable Cache option in the Network menu. Mobile devices do not support this method. You need to use a whistle agent to whistle.

  1. Disable page 304 and cache headers: disable://cache
  2. Add the random parameter resReplace to the long cached static resource link in the page via re replacement
No caching is used for requests that pass through the proxy and are matched, including strong caching and negotiated caching
www.example.com disable://cache 
 
# add timestamp parameter to js/CSS request address in the page
# ``` assetsURL 
# /\.(js|css)(['"])/g: .$1? time=${now}$2
# ` ` `
www.example.com/index.html disable://cache resReplace://`{assetsURL}` 
Copy the code

🔌 plug-in

To meet the needs of specific business scenarios, Whistle provides plug-in extensibility capabilities that allow you to add more complex operations to whistle’s protocols, store or monitor specific requests, integrate with a business local development and debugging environment, and do pretty much anything you want. Each Whistle plug-in is a normal NPM package, so developing, publishing, and installing a Whistle plug-in is simple; Whistle’s plug-in is a standalone process that does not affect the stability of the whistle main process. See whistle-plugins for more plug-ins.

Common plug-in

inspect

Mobile terminal page development often need to inject vConsole on the page for debugging, the general practice is to introduce vConsole in HTML, open the development environment, formal environment annotation or delete, easy to accidentally release online; Another problem is that online pages can’t be debugged using vConsole. Using the whistle.inspect plugin, you can inject vConsole without intruding into the page code, as well as online pages.

#Install the inspect plug-in 
$ w2 i whistle.inspect 
Copy the code

Configure the page to be injected:

www.example.com whistle.inspect://vConsole 
Copy the code

🌰 Project practice

It is recommended to use the global agent, which does not affect other software networks and is convenient for mobile terminal development using the simulator.

Notice After restarting the Mac, you need to start Whistle before you can access the network.

  • Both global proxy and browser proxy can be used on PC.
  • It is recommended to use Whistle global agent + simulator development for mobile terminal, which is very efficient.

Rule profile

When initializing the project, add the.whistle.js rule configuration file in the root directory. Other students can add this configuration by running w2 add or w2 use in the root directory of the project. You can also use features like Charles to import and export configurations.

// .whistle.js 
const pkg = require('./package.json'); 
 
exports.name = ` [${pkg.name}] Local environment configuration '; 
exports.rules = 3000 ` ` 127.0.0.1: www.example.com; // Multi-line rules are separated by \n
Copy the code
Add rule configuration
$ w2 add 
Copy the code

Reference documentation

  • Whistle Official Document
  • Whistle tools introduction to the whole – tencent Web front-end IMWeb team community | | blog blog
  • Principle and realization of (a) | HTTP proxy JerryQu station