Skip to content

自定义插件

Jump to bottom Edit New page
avenwu.wwb edited this page May 23, 2016 · 20 revisions

插件名称不能与内置的协议名称重复，否则会被忽略，如不能命名为：whistle.req 等，插件列表：https://github.com/whistle-plugins

v0.8.0 及以后的whistle版本提供了更加方便的协议扩展机制，用户通过编写正常的node模块处理whistle转发过来的数据，只需node模块的名称要按约定命名，形如 whistle.xxx 或 @org/whistle.xxx，即可实现扩展whistle的功能。

如果想先看下whistle插件的效果，可以参考：https://github.com/whistle-plugins/whistle.helloworld

插件用途

  1. 自定义静态服务器

    每个公司对前端静态资源的构建方式，对应的本地调试服务器也不一样，各个公司或部门可以把自己的静态服务器经过简单包装集成在whistle上，一般只需做个转发，可以参考：https://github.com/whistle-plugins/whistle.tianma

  2. 提供构造数据服务及数据包共享

    whistle会提供一个比较通用的构造数据的插件vase，具体参考：https://github.com/whistle-plugins/whistle.vase。

    用户也可以根据需要自定义适合自己的打桩模块，或者直接是数据包，可以通过以下四种方式实现打桩或者其它功能的共享：

    • 通过模块提供的导入导出功能
    • 通过npm的publish和install实现共享
    • 通过设置代理，或者是chrome的代理插件直接指向对应whistle，或者是通过whistle的proxy协议指定请求代理到对应的其它whistle代理服务实现共享其它whistle的配置（可以把whistle部署在公共的机器上）

  3. 编写可以共享的前端demo使用

    试验一些前端功能的例子，比如websocket、bigpipe、cors等，可以通过上述的三种方式实现共享，可以参考例子： https://github.com/whistle-plugins/whistle.helloworld

  4. 自带全局规则

    在插件package.json同级目录添加文件rules.txt，whistle会自动加载该文件配置的规则

    rules.txt:

     www.aliexpress.com 127.0.0.1
 /./ helloworld://test #把所有请求转发到helloworld插件上

  5. 自定义私有规则

    在插件package.json同级目录添加文件_rules.txt，如果请求匹配该插件，则whistle会匹配私有文件配置的规则

    _rules.txt:

     www.aliexpress.com 127.0.0.1 filter://rule # 请求不要转发到插件
 /./ filter://rule #由交由rulesServer输出的rule处理

  6. 动态规则

    在插件里面新增一个rulesServer，详情参考: https://github.com/whistle-plugins/whistle.helloworld

  7. 其它你能想到的各种用途

插件结构

同正常的node模块，只是命名有有约定：whistle.protocol 或 @myorg/whistle.protocol（protocol为用户自定义的名称，只能为数字、小写英文字母、下划线、横线，即：az09_-）

package.json

{
	"name": "whistle.helloworld",
	"version": "0.0.1",
	"description": "xxxx",
	"homepage": "https://github.com/whistle-plugins/whistle.helloworld#whistlehelloworld",
	//others
}

Note: 建议设置homepage，主要方便用户通过点击whistle的about对话框，直接查看插件的使用帮助

详细内容可以参考例子：https://github.com/whistle-plugins/whistle.helloworld

编写插件

支持http、https、websocket，其中https需要开启whistle的https拦截。

whistle的插件就是一个正常的node模块，其原理是：当请求经过whistle时，whistle通过配置拦截相应的请求到协议对应的插件，如果插件还没开启，whistle会自动创建两个http server对象传给对应插件模块exports出来的如下两个方法：

//【必须存在，否则无法启动插件】出来拦截到请求的server
module.exports = function(server, options) {
	//通过server处理whistle转发过来的请求
};

//【可选，可以不设置】插件自身的ui配置服务uiServer（module.exports不能写成exports）
       
module.exports.uiServer = function(server, options) {
	//通过server处理内部配置页面的请求
};

//【可选，可以不设置】用于动态设置规则，把新规则响应给请求（module.exports不能写成exports）
       
module.exports.rulesServer = function(server, options) {
	//通过server处理内部配置页面的请求
};

options里面有两个有用的字段，用于在头部获取在whistle配置的ruleValue和判断是否是https、wss请求：

{
	FULL_URL_HEADER: //完整的请求url,
	METHOD_HEADER: //请求方法,
	RULE_VALUE_HEADER: //ruleValue存放的头部字段名称
	SSL_FLAG_HEADER: //判断是否是安全请求的头部字段名称,
	config: //whistle的配置
}

插件模块可以通过监听 server 的 request 事件处理whistle转发过来的http请求，且可以利用socket.io或ws来处理websocket请求。

如何编写插件、获取请求的url及配置的ruleValue，具体详细内容可以参考例子：https://github.com/whistle-plugins/whistle.helloworld

Note: 要让插件支持https或wss，需要开启https拦截及安装根证书，whistle会自动把https或wss转化http或ws请求转发给插件，插件无需关心关心证书问题

调试插件

把本地node模块link到全局目录：

$ npm link
或 sudo npm link

这样whistle就可以识别到本地的插件，如果用户代码有修改，只需给package.json加个空格，改变package.json的 修改时间 即可实现插件重新加载，无需重启whistle。

卸载本地插件：

npm unlink
# 或 sudo npm unlink
	
# 如果npm link不是在模块所在根目录执行，可以采用下面这种方式卸载本地开发的全局模块
npm unlink whistle.xxx -g
# 或 sudo npm unlink whistle.xxx -g

发布插件

同发布正常的node模块，模块编写完毕，可以通过以下几种方式发布：

  1. 公共的node模块，直接上传到npm仓库：

     # 登陆npm login后，在模块的根目录(package.json所在目录)执行
 npm publish

  2. 自建的npm仓库，有些公司会自建自己的仓库

     xnpm publish

安装插件

同安装全局的node模块，只需直接通过npm安装，需要安装到全局

npm install -g whistle.protocol
# 或
xnpm install -g whistle.protocol
# 或
xnpm install -g @org/whistle.protocol

Note: 如果whistle不是全局安装，只是本地clone代码下来执行，这种情况全局安装不生效，要在whistle目录下使用npm install whistle.xxx安装，相当于安装whistle的依赖

更新插件

可以通过直接重复上述安装插件的方式强制更新，直接通过npm更新:

npm update -g whistle.protocol
# 或
xnpm update -g whistle.protocol
# 或
xnpm update -g @org/whistle.protocol

卸载插件

npm uninstall -g whistle.protocol
# 或
xnpm uninstall -g whistle.protocol
# 或
xnpm uninstall -g @org/whistle.protocol

使用插件

安装完插件，直接可以在whistle中配置

pattern   protocol://ruleValue
                
配置完以后whistle会自动把匹配到的请求转发到对应protocol的插件whistle.protocol上，并把ruleValue传给插件服务器

更多内容可以参考：

  1. https://github.com/whistle-plugins/whistle.helloworld

  2. https://github.com/whistle-plugins

Add a custom footer
Add a custom sidebar
Clone this wiki locally