# RPC通道
## 数据包
UBot的所有RPC数据包均使用[JSON-RPC 2.0](http://wiki.geekdream.com/Specification/json-rpc_2.0.html)进行编码
>[warning] UBot只能处理标准JSON，注释等扩展内容将导致解析失败！
数据包示例：
```json
// Request
// 存在id字段（即使为null）表示常规请求
// 不存在id字段表示通知模式，服务端只会处理请求，不会给予回应
{
"json-rpc":"2.0",
"id":55,
"method":"get_user_name",
"params":[
"Account1",
"123456789"
]
}
// Response
{
"id":55,
"jsonrpc":"2.0",
"result":"UBotTest"
}
```
## 命名规范
所有RPC操作的方法名、参数名均使用蛇形命名法(Snake Case)
示例：
```
hello_world
get_token
```
所有RPC参数，如非特别声明，均按位置调用
```json
{params:["hello","world"]} //按位置调用
{params:{"a":"hello","b":"world"}} //按名称调用
```
## 通讯协议
UBot的所有RPC都是 全双工类型 的RPC，即Router可以调用客户端的函数，客户端也可以调用Router的函数
从`JSON-RPC 2.0`规范的角度来讲，无论是传输层的服务端还是客户端，都同时是`JSON-RPC 2.0`中所讲的Server和Client
RPC支持以下几种连接方式
>[warning] 尽管可以同时使用多种方式（同时存在多个连接），但**极度不推荐**这么做
### Websocket 模式
所有的UBot RPC都支持且推荐使用Websocket协议连接
- 全双工模式：直接连接
>[info] 任何情况下，都应该首选该模式
- Server-Client模式：在URL中加入参数`norequest=1`，此时客户端可以向Router发送请求，但Router不会向客户端发送任何请求（如 触发事件），Router只会回应客户端的请求
>[info] 此模式往往用于难以实现Peer模式的平台，通过建立两个Websocket连接，一个负责向Router发送请求，另一个负责接收来自Router的请求
### HTTP Post 模式
通过向RPC连接发送POST请求，提交内容为请求信息(`application/json`)，返回内容为响应信息(`application/json`)或空（对于`JSON-RPC`中定义的通知而言，不作任何响应）
该模式只能向Router发送请求，无法接收请求
请求示例：
```
// Request
POST /api/app?id=Echo&token=Ciq-h4_7TV26egu0aPBi1A HTTP/1.1
Content-Length: 130
Content-Type: application/json
Host: localhost:5000
{
"json-rpc":"2.0",
"id":0,
"method":"get_user_name",
"params":[
"Account",
"1234"
]
}
// Response
HTTP/1.1 200 OK
Content-Length: 46
Content-Type: application/json; charset=utf-8
{"id":0,"jsonrpc":"2.0","result":"HelloWorld"}
```
### Webhook 模式
通过注册Webhook，在Router向客户端发出请求时，自动Post某个网址，并将返回结果作为JSON-RPC的响应对象
该模式只能接收Router的请求，无法**主动**向Router发出任何请求
如果您接收到的是请求对象，您必须返回JSON-RPC的响应对象，除非您接收到的是通知
您可以通过返回一个同时包含响应对象和请求对象的数组来**被动**地向Router发出请求（这些请求的响应结果又会作为数据以webhook的形式调度给您，您可以继续回复请求对象向Router继续发送请求。如果您不需要回应，则可以使用`JSON-RPC`中定义的通知模式发出请求）
#### Webhook 管理
请参考API列表Webhook控制器部分
## RPC库
JSON-RPC 2.0是使用较广泛的一种协议，全双工模式（即Peer模式，部分库只支持Server-Client模式）也是较常见的一种实现方式，大部分平台都可以找到支持over Websocket的库
- Golang平台：[wsrpc](https://github.com/1354092549/wsrpc)
- .NET平台：[microsoft/vs-streamjsonrpc](https://github.com/microsoft/vs-streamjsonrpc)
- Node.js平台：[json-rpc-peer](https://github.com/JsCommunity/json-rpc-peer)
- Dart平台：[dart-lang/json_rpc_2](https://github.com/dart-lang/json_rpc_2)
>[info] 以上RPC库并非由本人维护，若遇到问题请咨询对应作者
