理解proto3协议

服务和方法

Service 结尾的API成为服务,比如 ServerService,每个服务下有很多方法,比如:

createServer
updateServerBasic
updateServerGroupIds
在通过HTTP协议调用API时,你需要组合服务和方法,作为方法的地址:
API接口地址/服务名/方法名
比如:
http://192.168.2.100/ServerService/createServer

接口参数解读

假设我们看到以下的接口参数定义:

// 创建服务
message CreateServerRequest {
	int64 userId = 1;
	int64 adminId = 2;
	string type = 3;
	string name = 4;
	string description = 5;

	// 配置相关
	bytes serverNamesJON = 8;
	bytes httpJSON = 9;
	bytes httpsJSON = 10;
	bytes tcpJSON = 11;
	bytes tlsJSON = 12;
	bytes unixJSON = 13;
	bytes udpJSON = 14;
	int64 webId = 15;
	bytes reverseProxyJSON = 16;
	repeated int64 serverGroupIds = 17;
	int64 userPlanId = 18;
}

其中:

  • 每个字段定义都至少由三部分组成,最简单的定义为 字段类型 字段名 = 字段编号
  • int64string 等都是字段数据类型,目前支持以下常用的数据类型:
    • int64 - 64位整型
    • int32 - 32位整型
    • uint64 - 无符号的64位整型
    • uint32 - 无符号的32位整型
    • double - 双精度浮点数字
    • float - 单精度浮点数字
    • string - 字符串
    • bool - 布尔值,在JSON中为 true 或者 false
    • bytes - 二进制字节数组,通过JSON调用时,你需要先将数据转换为Base64格式,再传递到接口,比如:
    • 一个字符串的内容为Hello, World,那么传递到 bytes 类型字段的时候就需要传递 base64_encode('Hello, World'),最终值应该为 SGVsbG8sIFdvcmxk
    • 一个JSON数据的内容为{ "name": "goedge.cn", "type": "domain"},那么传递到 bytes 类型字段的时候就需要传递 base64_encode('{ "name": "goedge.cn", "type": "domain"}'),最终值应该为 eyAibmFtZSI6ICJnb2VkZ2UuY24iLCAidHlwZSI6ICJkb21haW4ifQ==
    • 一个文件内容的二进制内容同样也需要Base64编码处理
    • 反之,对于接口返回的响应数据来说,你需要Base64 Decode处理才能得到原始数据
  • repeated 字段类型 字段名 = 字段编号 表示一个数组,字段类型 部分表示字段值数组中的元素的类型,比如:
    • repeated int64 serverGroupIds 表示 serverGroupIds 是一个数组,通过JSON调用时需要传递[ 1, 2, 3 ]这样格式的数据,其中 int64 规定了数组中的每一项必须是一个整型;
    • repeated string types 表示 types 的值为 [ "type1", "type2" ] 这样的数组
    • repeated ServerGroup serverGroups 表示 serverGroups 的只为 [ serverGroup1, serverGroup2, serverGroup3 ] 这样的数组,因为ServerGroup也是一个对象,所以我们可以展开来,最终的JSON为:[ { "id":1, "name": "分组1" }, { "id":2, "name": "分组2" }, { "id":3, "name": "分组3" } ]
  • 数字1232等为字段编号,并 不是 字段值,对调用者来说,并没有实际意义;编号不一定是按顺序的,也不一定是连续的;

整体转换为JSON

通过JSON调用API时,需要将proto3协议的数据转换为JSON。对于这个示例中,和JSON的对应关系为:

{
  "userId": 35,
  "adminId": 1,
  "type": "httpProxy",
  "name": "My site",
  "description": "This is my site",

  "serverNamesJON": "ewogICJuYW1lIjogImdvZWRnZS5jbiIKfQ==",
  "httpJSON": "...",
  "httpsJSON": "...",
  "tcpJSON": "...",
  "tlsJSON": "...",
  "unixJSON": "...",
  "udpJSON": "...",
  "webId": "...",
  "reverseProxyJSON": "...",
  "serverGroupIds": [1, 3, 5],
  "userPlanId": 12
}

空参数

有些接口参数定义为:

message NotifyServersChangeRequest {

}
像这样的接口需要传递的JSON为:
{}
即可。

字符集

GoEdge所有API都只支持UTF-8。

GoEdge文档