https://github.com/hiproxy/hiproxy-plugin-example
A hiproxy plugin example
https://github.com/hiproxy/hiproxy-plugin-example
Last synced: about 1 year ago
JSON representation
A hiproxy plugin example
- Host: GitHub
- URL: https://github.com/hiproxy/hiproxy-plugin-example
- Owner: hiproxy
- License: mit
- Created: 2017-06-10T15:14:49.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2017-06-14T03:26:59.000Z (about 9 years ago)
- Last Synced: 2025-02-05T13:48:36.997Z (over 1 year ago)
- Language: JavaScript
- Size: 114 KB
- Stars: 2
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# hiproxy-plugin-example
hiproxy插件示例。这个插件为hiproxy添加了一个Rewrite指令、一个CLI命令和一个页面路由。
* **名令**：`hello`，执行`hiproxy hello --name --age `
* **指令**：`add`，在rewrite文件中使用`add $add_value 1600 88;`
* **路由**：`test`，服务启动之后，访问`http://127.0.0.1:/test`
## 安装
```bash
npm install hiproxy/hiproxy-plugin-example -g
```
> **注意**：必须要把插件安装到全局。hiproxy CLI默认去全局查找插件，所以必须保证安装到`npm root -g`所在的目录中，才能被正确加载。
## 使用
安装完成后，hiproxy会自动加载所有安装的插件并注册插件定义的命令、指令和页面。
### 命令
安装好这个示例插件之后，执行`hiproxy --help`，可以看到如下信息，从中我们能发现，有了`hello`这个命令。
执行`hp hello --help`，可以看到`hello`命令的帮助信息。
### 页面
hiproxy-plugin-example为hiproxy添加了一个页面，url为`/test`，使用`hiproxy start --port 8888`启动服务之后，可以访问查看效果。
### 指令
hiproxy-plugin-example为hiproxy添加了一个rewrite指令`add`来做加法运算。指令的作用域为`[global, domain, location]`，这个指令接收三个参数：
* key：属性名称，用于把计算后得到的值赋值给当前作用于的props，比如：`$result`。
* num1：第一个加数，比如：`12`。
* num2：第二个加数，比如：`34`。
之后，我们可以使用这个计算出来的值，比如：`set_header Calc-Result $result`。
示例：
```bash
# rewrite rules
# need plugin `hiproxy-plugin-example`
set $gvar global-value;
domain test.hiproxy.io {
set $host test.hiproxy.io;
# hiproxy-plugin-example提供的指令
add $addresult 9999 90000;
location / {
proxy_pass http://127.0.0.1:8000/;
# hiproxy-plugin-example提供的指令
add $add_value 1600 88;
# 使用`add`计算的结果
set_header Add_Result $addresult;
set_header Test_Add_Value $add_value;
set_header Global_Var $gvar;
}
}
```
## 开发者
开发者开发新插件时，可以参考`hiproxy-plugin-example`。
### 插件结构
插件作为一个独立的模块安装，入口文件需要导出一个对象，包括三个属性：
* **commands**: ``，用来扩展`hiproxy`的CLI命令，数组中每个对象作为一个命令配置，具体配置见[命令配置](#command-config)。
* **directives**: ``，用来扩展`hiproxy`的rewrite指令，数组中每个对象作为一个指令配置，具体配置见[指令配置](#directive-config)。
* **routes**: ``，用来扩展`hiproxy`的页面路由，数组中每个对象作为一个路由配置，具体配置见[路由配置](#route-config)。
命令可以配置的内容为：`命令名称`、`描述`、`使用方法`、`处理函数`和`命令选项参数`。对应的字段为：
* 命令名称（command）：``，比如：`'hello'`。
* 描述信息（describe）：``，简单介绍命令的作用以及其他的信息，比如：`'A test command that say hello to you.'`。
* 使用方法（usage）：``，命令的使用方法提示信息，比如：`'hello [--name ] [-xodD]'`。
* 处理函数（fn）：``，执行命令时，调用的函数。函数调用时`this`值为命令行参数解析后的对象。
* 命令选项（option）：``，命令对应的选项，`key:value`形式。可以参考。
一个完整的命令示例如下：
```js
{
command: 'hello',
describe: 'A test command that say hello to you.',
usage: 'hello [--name ] [-xodD]',
fn: function () {
var cliArgs = this;
console.log('Hi, welcome to use hiproxy example plugin');
if (cliArgs.name ) {
console.log('your name is', cliArgs.name.green);
}
if (cliArgs.age ) {
console.log('your are', cliArgs.age.green, 'years old');
}
},
options: {
'name ': {
alias: 'n',
describe: 'your name'
},
'age': {
alias: 'a',
describe: 'your age'
}
}
}
```
### 指令配置
命令可以配置的内容为：`指令名称`、`作用域`和`处理函数`。对应的字段为：
* 指令名称（name）：``，比如：`'add'`。
* 作用域（scope）：``，指令对应的作用域，只有在这里指定的作用域里面才会执行。可选择的作用域为：`global`、`domain`、`location`、`request`和`response`。
* 处理函数（fn）：``，执行指令时，调用的函数。
一个完整的指令示例如下：
```js
{
name: 'add',
scope: ['global', 'domain', 'location'],
fn: function (key, a, b) {
var props = this.props;
var value = Number(a) + Number(b);
this.props[key] = value;
}
}
```
### 路由配置
路由可以配置的内容为：`路由规则`和`渲染函数`。对应的字段为：
* 路由规则（name）：``，比如：`'add'`。
* 渲染函数（render）：``，渲染页面，接收三个参数：`(route, request, response)`，`route`为url匹配后的对象，细节可以查看。
一个完整的指令示例如下：
```js
{
route: '/test(/:pageName)',
render: function (route, request, response) {
response.writeHead(200, {
'Content-Type': 'text/html',
'Powder-By': 'hiproxy-plugin-example'
});
var serverInfo = {
route: route,
pageID: route.pageName,
time: new Date(),
serverState: {
http_port: global.hiproxyServer.httpPort,
https_port: global.hiproxyServer.httpsPort,
cliArgs: global.args,
process_id: process.pid
}
};
response.end('
' + JSON.stringify(serverInfo, null, 4) + '
');
}
}
```