理解proto3协议

服务和方法

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

  1. createServer
  2. updateServerBasic
  3. updateServerGroupIds

在通过HTTP协议调用API时，你需要组合服务和方法，作为方法的地址：

  1. API接口地址/服务名/方法名

比如：

  1. http://192.168.2.100/ServerService/createServer

接口参数解读

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

  1. // 创建服务
  2. {
  3.     int64 userId;
  4.     int64 adminId;
  5.     string type;
  6.     string name;
  7.     string description;
  9.     // 配置相关
  10.     bytes serverNamesJON;
  11.     bytes httpJSON;
  12.     bytes httpsJSON;
  13.     bytes tcpJSON;
  14.     bytes tlsJSON;
  15.     bytes unixJSON;
  16.     bytes udpJSON;
  17.     int64 webId;
  18.     bytes reverseProxyJSON;
  19.     repeated int64 serverGroupIds;
  20.     int64 userPlanId;
  21. }

其中：

  • 每个字段定义都至少由两部分组成，最简单的定义为 字段类型 字段名，这里我们省略了字段编号；
  • int64和 string 等都是字段数据类型，目前支持以下常用的数据类型：
    • 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" } ]

整体转换为JSON

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

  1. {
  2.   "userId": 35,
  3.   "adminId": 1,
  4.   "type": "httpProxy",
  5.   "name": "My site",
  6.   "description": "This is my site",
  8.   "serverNamesJON": "ewogICJuYW1lIjogImdvZWRnZS5jbiIKfQ==",
  9.   "httpJSON": "...",
  10.   "httpsJSON": "...",
  11.   "tcpJSON": "...",
  12.   "tlsJSON": "...",
  13.   "unixJSON": "...",
  14.   "udpJSON": "...",
  15.   "webId": "...",
  16.   "reverseProxyJSON": "...",
  17.   "serverGroupIds": [1, 3, 5],
  18.   "userPlanId": 12
  19. }

空参数

有些接口参数定义为：

  1. {
  3. }

像这样的接口需要传递的JSON为：

  1. {}

即可。

字符集

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