whistle规则系统深度解析

芮川琨Jack

801人浏览 · 2025-08-25 23:25:31

芮川琨Jack · 2025-08-25 23:25:31 发布

whistle规则系统深度解析

【免费下载链接】whistle HTTP, HTTP2, HTTPS, Websocket debugging proxy 项目地址: https://gitcode.com/gh_mirrors/wh/whistle

本文深入解析whistle规则系统的核心机制，涵盖规则语法结构、pattern匹配模式、operation操作指令分类以及过滤条件includeFilter/excludeFilter的高级应用。从基础格式到高级技巧，全面介绍如何利用whistle实现精准的网络请求控制和灵活处理，助力开发者构建高效的网络调试和模拟环境。

whistle规则语法结构与基本格式

whistle的规则系统采用简洁而强大的模式匹配语法，通过特定的格式结构来实现对网络请求的精确控制和灵活处理。掌握其语法结构与基本格式是高效使用whistle的关键基础。

基本规则格式

whistle规则的基本语法结构遵循以下格式：

pattern operation://value [filters...]

其中各组成部分的含义如下：

组件	描述	示例
`pattern`	匹配请求URL的模式表达式	`www.example.com/api/*`
`operation`	操作指令，定义要执行的动作	`file`、`proxy`、`reqHeaders`
`value`	操作的具体值或目标	`/path/to/file`、`http://proxy:8080`
`filters`	可选过滤器，进一步限定匹配条件	`method://POST`、`statusCode://200`

多规则配置格式

在实际使用中，通常需要配置多条规则，whistle支持多种配置格式：

单行单规则

www.example.com/api/users file:///data/users.json
api.service.com/v1/* proxy://http://internal-proxy:8080

多行规则组

# 用户相关API规则
www.example.com/api/users file:///data/users.json
www.example.com/api/profile reqHeaders://X-User-ID=123

# 服务代理规则  
api.service.com/v1/* proxy://http://internal-proxy:8080
api.service.com/v2/* proxy://http://internal-proxy:8080

注释使用

# 这是单行注释
www.example.com/api/users file:///data/users.json  # 行内注释

/*
多行注释
用于说明复杂的规则组
*/
api.service.com/v1/* proxy://http://internal-proxy:8080

模式匹配语法详解

whistle的模式匹配支持多种灵活的语法形式：

精确匹配

# 完全匹配特定URL
https://www.example.com/api/v1/users reqHeaders://X-Version=1.0

通配符匹配

# 匹配所有子域名
*.example.com/api/* proxy://http://internal:8080

# 多级子域名匹配  
**.example.com/data/** file:///mock/data/$2

正则表达式匹配

# 使用正则表达式精确匹配
/\.(js|css|png)$/i resHeaders://Cache-Control=max-age=3600

# 复杂正则匹配
/\/api\/v\d+\/users\/\d+/ reqHeaders://X-API-Version=$1

操作指令分类

whistle的操作指令分为多个类别，每类指令处理不同类型的网络操作：

请求重写类

www.example.com host://127.0.0.1:3000
api.service.com proxy://http://proxy-server:8080

头部操作类

www.example.com reqHeaders://X-Forwarded-For=192.168.1.1
api.service.com resHeaders://Access-Control-Allow-Origin=*

内容修改类

www.example.com/html/* htmlAppend://<div>Footer</div>
api.service.com/data/* resReplace://{"status":"mock"}

文件操作类

www.example.com/static/* file:///path/to/static/files
api.service.com/config/* rawfile:///config/app.json

过滤器语法

过滤器用于对匹配的请求进行进一步的条件筛选：

# 方法过滤器
www.example.com/api/* file:///mock/api.json method://POST

# 状态码过滤器
www.example.com/api/* resHeaders://X-Cache-Hit=true statusCode://200

# 组合过滤器
api.service.com/data/* proxy://internal:8080 method://GET statusCode://404

特殊语法特性

变量引用

# 使用通配符捕获组
^http://*.example.com/api/**/data file:///mock/$1/$2.json

# 正则表达式捕获组  
/api/v(\d+)/users/(\d+)/ reqHeaders://X-API-Version=$1&X-User-ID=$2

优先级控制

# 使用important提升优先级
www.example.com/api/users file:///data/users.json lineProps://important

# 默认规则（低优先级）
www.example.com/api/* proxy://http://default-proxy:8080

条件执行

# 仅对特定内容类型生效
www.example.com/api/* resReplace://{"mock":true} resType://json

# 基于请求体内容过滤
api.service.com/data/* file:///mock/data.json reqBody://"test":true

规则执行流程

whistle的规则执行遵循特定的优先级和匹配顺序：

mermaid

实用配置示例

开发环境模拟

# API接口模拟
api.example.com/v1/users file:///mocks/users.json
api.example.com/v1/products file:///mocks/products.json

# 静态资源代理
static.example.com/* file:///frontend/dist

# 跨域支持
api.example.com/* resHeaders://Access-Control-Allow-Origin=*

调试配置

# 请求日志记录
www.example.com/* log://请求到达时间: ${time}

# 性能测试
api.service.com/data/* reqDelay://2000
api.service.com/process/* resDelay://1000

# 错误模拟
www.example.com/api/error statusCode://500

安全测试

# SQL注入测试
www.example.com/search?q=* reqReplace://q=SELECT * FROM users

# XSS测试
www.example.com/comment resReplace://<script>alert('XSS')</script>

# 权限绕过
api.example.com/admin/* statusCode://200

掌握whistle规则的基本语法结构和格式，能够帮助开发者快速构建复杂的网络调试和模拟环境，提高开发和测试效率。

Pattern匹配模式详解与使用技巧

在Whistle的规则系统中，pattern匹配是整个代理调度的核心机制，它决定了哪些网络请求会被特定的规则所处理。掌握pattern的各种匹配模式和技巧，能够让你更精准地控制网络请求的拦截和处理。

Pattern匹配的基本结构

Whistle的规则采用 pattern operator://value 格式，其中pattern部分支持多种匹配方式：

// 基础语法格式
pattern operator://value

// 示例：匹配example.com域名的所有请求并设置代理
example.com proxy://127.0.0.1:8080

域名匹配模式

域名匹配是最基础也是最常用的匹配方式，支持多种格式：

匹配类型	语法示例	说明
基础域名	`example.com`	精确匹配指定域名
IP地址	`192.168.1.1`	匹配IP地址
带端口	`example.com:8080`	匹配特定端口的域名
无协议前缀	`//example.com`	忽略协议前缀的匹配

mermaid

通配符匹配的高级用法

Whistle提供了强大的通配符匹配能力，支持多级域名和路径的灵活匹配：

域名通配符

// 单级通配符 - 匹配任意单级子域名
*.example.com proxy://127.0.0.1:8080

// 多级通配符 - 匹配任意多级子域名
**.example.com proxy://127.0.0.1:8080

// 混合通配符 - 固定前缀 + 多级通配
test.abc**.com proxy://127.0.0.1:8080

// 协议通配符 - 匹配多种协议
http*://example.com proxy://127.0.0.1:8080

// 特殊规则 - 同时匹配根域名和多级子域名
***.example.com proxy://127.0.0.1:8080

路径通配符

路径通配符需要在表达式前加 ^ 显式声明：

// 单级路径通配符
^example.com/api/*/users file:///local/data/$1

// 多级路径通配符  
^example.com/static/**/js/*.js reqDelay://1000

// 任意字符通配符
^example.com/data/***file reqHeaders://X-File-Type=special

mermaid

正则表达式匹配

对于复杂的匹配需求，Whistle支持完整的正则表达式语法：

// 基础正则匹配
/\.(js|css)$/i reqDelay://500

// 带标志的正则匹配
/\/api\/v\d+\/users\/\d+/ui reqHeaders://X-API-Version=latest

// 正则匹配示例 - 匹配版本化API
/\/api\/v(\d+)\/(users|products)\/(\d+)/ reqHeaders://X-API-Version=v$1&X-Resource-Type=$2&X-ID=$3

正则匹配支持以下标志：

i - 忽略大小写
u - Unicode支持
组合标志如 ui

子匹配传值技巧

Whistle的强大之处在于支持从pattern中提取子匹配内容并传递到操作值中：

通配符子匹配

// 提取域名部分
^http://*.example.com/api/** file:///data/$1/$2

// 匹配: http://dev.example.com/api/users/list
// 结果: $1 = "dev", $2 = "users/list"
// 文件路径: /data/dev/users/list

正则表达式子匹配

// 正则子匹配示例
/\/user\/(\w+)\/profile\/(avatar|info)/ reqHeaders://X-Username=$1&X-Profile-Type=$2

// 匹配: /user/john/profile/avatar
// 结果: $1 = "john", $2 = "avatar"
// 添加请求头: X-Username: john, X-Profile-Type: avatar

实用匹配技巧与最佳实践

1. 组合匹配策略

// 组合使用多种匹配模式
**.api.example.com reqDelay://200
^**.example.com/static/**/*.js reqSpeed://100kb
/\.(png|jpg|gif)$/i cache://3600

2. 性能优化匹配

// 精确匹配优先于通配符匹配
api.example.com/user/login reqDelay://0  // 精确匹配，高性能
**.example.com reqDelay://100            // 通配符匹配，较低性能

// 使用正则表达式缓存
var cachedRegex = /\.(js|css)$/i
cachedRegex reqDelay://300

3. 调试与测试模式

// 开发环境专用匹配
^localhost:3000/** log://
^127.0.0.1:8080/** reqHeaders://X-Debug-Mode=true

// 测试数据模拟
^test-api.example.com/users/* resBody://{"id": $1, "name": "Test User"}

4. 安全相关匹配

// 敏感接口保护
/\/admin\/.*/ reqHeaders://X-Secure-Access=true
^**.example.com/password/** log://secure

// API密钥验证
/\/api\/.*\?key=(\w+)/ reqHeaders://X-API-Key=$1

匹配优先级与冲突解决

Whistle的匹配遵循特定的优先级规则：

mermaid

当多个规则匹配同一个请求时，Whistle会按照以下顺序处理：

精确匹配的规则
通配符匹配的规则
正则表达式匹配的规则

常见问题与解决方案

匹配失效排查

// 1. 检查通配符语法
*.example.com    // 正确
* .example.com   // 错误：包含空格

// 2. 验证正则表达式
/\.js$/          // 正确
/\.js$/i         // 正确：忽略大小写
/\.js$           // 错误：缺少结束符

// 3. 路径通配符前缀
^example.com/*   // 正确：显式声明
example.com/*    // 错误：可能被当作字面星号

性能优化建议

// 避免过度使用通配符
**.example.com/**   // 性能较低
api.example.com     // 性能较高

// 使用更具体的匹配
^example.com/static/*.js   // 较好
^example.com/**/*.js       // 较差

// 正则表达式预编译
var userPattern = /\/user\/(\d+)/
userPattern reqHeaders://X-User-ID=$1

通过掌握这些pattern匹配模式和技巧，你能够构建出更加精确、高效和可维护的Whistle规则配置，从而更好地满足各种网络调试和代理需求。

operation操作指令分类与功能说明

在Whistle的规则系统中，operation操作指令是整个规则体系的核心执行部分，它定义了当请求匹配到特定模式时应执行的具体操作。操作指令采用统一的语法格式：protocol://[value]，其中protocol指定操作类型，value定义操作内容。

操作指令的核心分类体系

Whistle的操作指令按照功能领域可以分为八大类别，每个类别包含多个具体的操作协议：

mermaid

操作值的多种引用方式

Whistle支持灵活的操作值引用机制，满足不同场景下的配置需求：

引用方式	语法格式	适用场景	示例
内联值	`protocol://value`	简单值、无特殊字符	`reqHeaders://x-test=value`
内嵌值	`protocol://{key}`	多行内容、复杂配置	见下方代码示例
Values引用	`protocol://{values-key}`	跨规则共享配置	`file://{common-config}`
文件路径	`protocol:///path/to/file`	本地文件内容	`reqHeaders:///User/config.json`
远程URL	`protocol://https://example.com/config`	远程配置	`resHeaders://https://config.com/headers`

内嵌值配置示例

``` custom-headers
x-custom-header: Whistle-Proxy
authorization: Bearer token123
content-type: application/json; charset=utf-8
cache-control: no-cache, no-store
```

api.example.com/v1/* reqHeaders://{custom-headers}

模板字符串的动态能力

Whistle的模板字符串功能允许在操作值中动态引用请求上下文信息：

``` dynamic-config
request-id: ${reqId}
client-ip: ${clientIp}
request-time: ${now}
user-agent: ${reqHeaders.user-agent}
target-url: ${url}
query-param: ${query.search}
```

api.example.com/trace resHeaders://{dynamic-config}

数据对象格式支持

操作值支持多种数据格式，适应不同的配置需求：

JSON格式（结构化配置）

{
  "x-api-version": "1.0",
  "authorization": "Bearer ${randomUUID}",
  "cache-control": "max-age=300"
}

行格式（简洁配置）

x-api-version: 1.0
authorization: Bearer ${randomUUID}
cache-control: max-age=300

内联格式（URL参数风格）

x-api-version=1.0&authorization=Bearer${randomUUID}&cache-control=max-age=300

操作指令的执行优先级与组合使用

Whistle支持多个操作指令的组合使用，执行顺序遵循特定的优先级规则：

mermaid

常用操作指令功能对比表

操作协议	类别	主要功能	值格式	适用场景
`reqHeaders`	请求重写	修改请求头	键值对	API调试、身份验证
`resHeaders`	响应重写	修改响应头	键值对	CORS配置、缓存控制
`file`	Map Local	本地文件响应	文件内容	mock数据、本地开发
`host`	DNS欺骗	域名解析重定向	IP地址	环境切换、测试
`proxy`	代理转发	请求代理转发	代理地址	跨域访问、流量转发
`statusCode`	响应重写	修改状态码	状态码	错误测试、重定向
`weinre`	调试工具	远程调试	调试配置	移动端调试
`log`	日志记录	请求日志	日志格式	调试追踪

高级操作技巧

条件操作与过滤器组合

# 仅对POST请求添加特定头
api.example.com/user includeFilter://method=POST reqHeaders://x-request-type=api-call

# 排除静态资源请求
static.example.com/* excludeFilter://path=\\.(js|css|png)$ reqHeaders://x-debug=true

链式操作执行

# 先修改请求头，再代理转发
api.example.com/v1/* reqHeaders://x-version=2.0 proxy://backend-server:8080

# 先本地调试，再记录日志
test.example.com/file file://mock-data.json log://request-details

环境变量动态配置

# 使用环境变量区分配置
config.example.com reqHeaders://x-env=${env.NODE_ENV}

# 根据环境选择不同后端
api.example.com proxy://${env.BACKEND_URL:-localhost:3000}

Whistle的操作指令系统提供了极其灵活和强大的配置能力，通过合理的分类和组合使用，可以满足从简单调试到复杂业务场景的各种需求。掌握这些操作指令的分类和功能特点，是高效使用Whistle进行网络调试和开发的关键。

过滤条件includeFilter/excludeFilter应用

在whistle强大的规则系统中，includeFilter和excludeFilter是两个极其重要的过滤条件协议，它们为请求的精确匹配和排除提供了强大的控制能力。这两个协议允许开发者基于多种维度对请求进行精细化过滤，从而实现更加精准的规则匹配和调试控制。

过滤条件的基本语法

includeFilter和excludeFilter遵循统一的语法格式：

// 基本语法
includeFilter://{匹配条件}
excludeFilter://{匹配条件}

// 示例
includeFilter://host=example.com
excludeFilter://method=POST

支持的匹配维度

whistle提供了丰富的匹配维度，覆盖了HTTP请求的各个方面：

匹配维度	语法示例	说明
请求方法	`includeFilter://method=GET`	匹配GET请求
IP地址	`includeFilter://ip=192.168.1.1`	匹配指定IP
请求头	`includeFilter://reqH:content-type=application/json`	匹配请求头
响应头	`includeFilter://resH:content-type=text/html`	匹配响应头
环境变量	`includeFilter://env.NODE_ENV=production`	匹配环境变量
状态码	`includeFilter://statusCode=200`	匹配状态码
请求来源	`includeFilter://from=httpServer`	匹配请求来源
请求体	`includeFilter://b:pattern`	匹配请求体内容
客户端IP	`includeFilter://clientIp=192.168.1.100`	匹配客户端IP
服务器IP	`includeFilter://serverIp=10.0.0.1`	匹配服务器IP

高级匹配模式

除了基本的等值匹配，whistle还支持正则表达式匹配和复杂条件组合：

// 正则表达式匹配
includeFilter://reqH:user-agent=/Chrome/
excludeFilter://url=/\.(jpg|png|gif)$/

// 多条件组合
includeFilter://method=GET includeFilter://host=api.example.com
excludeFilter://statusCode=404 excludeFilter://statusCode=500

// 环境变量匹配
includeFilter://env.DEBUG=true
excludeFilter://env.ENVIRONMENT=production

过滤逻辑的工作原理

whistle的过滤系统采用以下逻辑规则：

mermaid

实际应用场景

1. 开发环境调试

// 只在开发环境下启用调试规则
includeFilter://env.NODE_ENV=development
www.example.com resBody://{console.log('Debug info')}

// 排除静态资源文件
excludeFilter://url=/\.(css|js|png|jpg|gif|ico)$/

2. API请求监控

// 监控特定API的请求
includeFilter://host=api.example.com includeFilter://method=POST
/api/** resBody://{console.log('API Request:', $url, $statusCode)}

// 排除健康检查请求
excludeFilter://url=/healthcheck/

3. 错误请求处理

// 捕获4xx和5xx错误
includeFilter://statusCode>=400
www.example.com resBody://{console.error('Error:', $statusCode, $url)}

// 但排除特定的错误类型
excludeFilter://statusCode=404

性能优化技巧

使用includeFilter和excludeFilter时，应注意以下性能优化点：

精确匹配优先：尽量使用精确匹配而非正则表达式
条件合并：将多个条件合并到一个过滤器中
缓存友好：避免在过滤条件中使用动态变化的内容
层级优化：先使用粗粒度过滤，再使用细粒度过滤

// 优化前（性能较差）
includeFilter://url=/api/.*/ includeFilter://method=POST includeFilter://reqH:content-type=application/json

// 优化后（性能更好）
includeFilter://host=api.example.com includeFilter://method=POST
/api/** resBody://{console.log('API Request')} reqHeaders://content-type=application/json

常见问题排查

当过滤条件不生效时，可以按照以下流程进行排查：

mermaid

通过合理运用includeFilter和excludeFilter，开发者可以构建出极其精确和高效的网络调试规则体系，大幅提升开发和调试效率。

总结

whistle规则系统通过简洁而强大的语法结构，提供了全方位的网络请求控制能力。从基础的pattern匹配到复杂的operation操作指令，再到精细的过滤条件应用，whistle展现出极高的灵活性和实用性。掌握这些核心机制，能够帮助开发者在各种场景下实现精准的网络调试、数据模拟和性能优化，显著提升开发和测试效率。通过合理的规则配置和优化，whistle成为现代Web开发中不可或缺的强大工具。

【免费下载链接】whistle HTTP, HTTP2, HTTPS, Websocket debugging proxy 项目地址: https://gitcode.com/gh_mirrors/wh/whistle