# rpc-frontend

**Repository Path**: CloudGuan/rpc-frontend

## Basic Information

- **Project Name**: rpc-frontend
- **Description**: IDL文件生成前端
- **Primary Language**: C++
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 6
- **Created**: 2020-11-10
- **Last Updated**: 2023-02-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## IDL转换工具
将IDL文件转换为通用JSON中间格式，方便使用任何支持JSON访问的语言用来生成RPC框架代码

### 使用步骤
1. 定义IDL文件
2. 导出为JSON文件

### IDL文件规则


```
#import "test.idl"

// I'm a single line comment
/*
 * I'm a multi-line comment
 */

struct Data {
    i32 field1
    string field2
    seq<string> field3
    set<string> field4
    dict<i64,string> field5
    bool field6
    float field7
    double field8    
}

service Service {
    void method1(Data,string)
    string method2(i8,set<string>,ui64)        
}

```
如上所示IDL文件支持struct和service, struct是纯数据结构，不支持定义方法，service为接口定义，接口内可以包含若干方法，struct内可以嵌套定义struct，例如：

```
strutct A {
    struct B {
        ...
    }    
}
```
所有定义的struct都为全局作用域，不论是否定义在任何一个struct内部，service内部也可以定义struct，struct内部不能定义service，struct支持多种数据类型，包含基础数据类型和容器，所有数据类型如下:
|  数据类型   |  描述   |
| --- | --- |
| i8    |  8位有符号整数   |
| i16    | 16位有符号整数    |
| i32    | 32位有符号整数    |
| i64    | 64位有符号整数    |
| ui8    | 8位无符号整数    |
| ui16    |16位无符号整数     |
| ui32    |32位无符号整数     |
| ui64    |64位无符号整数     |
| string    |字符串     |
| bool | 布尔 |
| float | 单精度浮点数 |
| double | 双精度浮点数 |
| dict | 字典 |
| set | 集合 |
| seq | 序列（数组）|

当有多个IDL文件时，可以将struct和service组织在不同的文件内，将要使用的文件通过#import来导入到入口文件，被导入的文件都会被工具在运行时合并到一起并输出。当工具检测到错误时会给出错误现场.

## 服务类型

1. 单件
   同一时刻工厂只会创建一个实例
2. 多实例
   同时可以有多个实例存在
3. 可重入
   单个实例但可以被同时调用
4. 静态，动态
   服务器是否可以被动态加载


```
// 做多可以生成16个实例
service Service multiple=16 {
}

// 单件，只能有一个实例
service Service single {
}

// 单件，只能有一个实例，但可以被并发调用
service Service reentrant {
}

// 单件，只能有一个实例，但可以被并发调用，同时是动态加载
service dynamic Service reentrant {
}
```

## 方法类型
1. 双工
   代理调用后会等待返回（不论方法是否有返回值）
2. 单工
   代理调用后不会等待返回，也不关心调用成功或者失败，相当于通知

```
service Service multiple=16 {
    // 单工
    oneway void method1(Data,string)
}
```

## 方法超时和重试
1. 双工服务方法默认有5秒的超时时间，默认不重试
2. 超时时间和重试次数是可以配置的

```
service Service multiple=16 {
    // 单工
    void method1(Data,string) timeout=2000 retry=3
}
```
以上的配置为超时2秒，最多重试3次

## 生成JSON文件

frontend是一个命令行工具，运行help可以得到使用方法

![输入图片说明](https://images.gitee.com/uploads/images/2019/1212/190826_5e4267b7_467198.png "屏幕截图.png")

运行命令后可以得到对应类型的JSON文件，后续开发这可以使用这个JSON文件来生成自己的RPC框架代码，生成的构成已经进行对IDL做了语法检查和错误校验。

![输入图片说明](https://images.gitee.com/uploads/images/2019/1212/165343_8536f197_467198.png "屏幕截图.png")

可以通过 -i 或者--include 添加 你自己的import文件搜索路径 例子如下

```shell
./frontend -f test1.idl -t cpp -i ../example
```

上面的例子所生成的JSON文件如下:

```
./frontend -f test1.idl -t cpp
```

```
{
	"serviceNames" : 
	[
		"Service"
	],
	"services" : 
	[
		{
			"methods" : 
			[
				{
					"arguments" : 
					[
						{
							"isStruct" : true,
							"type" : "Data"
						},
						{
							"type" : "std::string"
						}
					],
					"name" : "method1",
					"retType" : 
					{
						"type" : "void"
					}
				},
				{
					"arguments" : 
					[
						{
							"type" : "std::int8_t"
						},
						{
							"key" : 
							{
								"type" : "std::string"
							},
							"type" : "std::unordered_set"
						},
						{
							"type" : "std::uint64_t"
						}
					],
					"name" : "method2",
					"retType" : 
					{
						"type" : "std::string"
					}
				}
			],
			"name" : "Service"
		}
	],
	"structNames" : 
	[
		"Data"
	],
	"structs" : 
	[
		{
			"fields" : 
			[
				{
					"name" : "field1",
					"type" : "std::int32_t"
				},
				{
					"name" : "field2",
					"type" : "std::string"
				},
				{
					"key" : 
					{
						"type" : "std::string"
					},
					"name" : "field3",
					"type" : "std::vector"
				},
				{
					"key" : 
					{
						"type" : "std::string"
					},
					"name" : "field4",
					"type" : "std::unordered_set"
				},
				{
					"key" : 
					{
						"type" : "std::int64_t"
					},
					"name" : "field5",
					"type" : "std::unordered_map",
					"value" : 
					{
						"type" : "std::string"
					}
				},
				{
					"name" : "field6",
					"type" : "bool"
				},
				{
					"name" : "field7",
					"type" : "float"
				},
				{
					"name" : "field8",
					"type" : "double"
				}
			],
			"name" : "Data"
		}
	]
}

```