API 文档与接口参考

入门指南

理解 proto3 协议

结合 WAFGO 的接口定义，了解字段类型、数组、Base64 和 JSON 请求的对应关系。示例用于说明数据格式，实际调用前请按目标接口替换资源 ID 和配置。

接口参数解读

接口详情中的 message 定义描述请求或响应字段。阅读时先识别字段类型和字段名，再结合注释理解用途。部分说明文档使用“字段类型字段名”的简写，并省略字段编号；这种简写不是可直接编译的 proto3 源码。

真正的 proto3 字段还包含唯一编号，例如 int64 userId = 1;。数组使用 repeated，而不是 [] 前缀。下面截取当前 CreateServerRequest 中的字段，编号与现有定义一致。

旧版简写示例中出现的 unixJSON 不在当前 CreateServerRequest 定义内；实际提交字段应以当前方法详情为准。

参数简写示意（非 proto3 源文件）

{
  int64 userId;
  int64 adminId;
  string type;
  string name;
  string description;
  bytes serverNamesJSON;
  bytes httpJSON;
  bytes httpsJSON;
  bytes tcpJSON;
  bytes tlsJSON;
  bytes udpJSON;
  int64 webId;
  bytes reverseProxyJSON;
  []int64 serverGroupIds;
  int64 userPlanId;
}

对应的 proto3 字段写法（节选）

syntax = "proto3";

message CreateServerRequest {
  int64 userId = 1;
  int64 adminId = 2;
  string type = 3;
  string name = 4;
  string description = 5;
  bytes serverNamesJSON = 8;
  bytes httpJSON = 9;
  bytes httpsJSON = 10;
  bytes tcpJSON = 11;
  bytes tlsJSON = 12;
  bytes udpJSON = 14;
  int64 webId = 15;
  bytes reverseProxyJSON = 16;
  repeated int64 serverGroupIds = 17;
  int64 userPlanId = 18;
}

查看完整 CreateServerRequest

常用字段类型

官方 ProtoJSON 对 int64、uint64 等 64 位整数使用十进制字符串作为规范输出，以避免 JavaScript 数值精度丢失。本文 HTTP 示例沿用接口说明中的小整数数字形式；不要据此假定所有 HTTP 适配层都具有完整 ProtoJSON 行为。涉及大整数时，应确认实际接口接受的表示方式，并避免先转换成可能丢失精度的 JavaScript Number。

int64: 有符号 64 位整数。
int32: 有符号 32 位整数。
uint64: 无符号 64 位整数，不能传入负数。
uint32: 无符号 32 位整数，不能传入负数。
double: 双精度浮点数。
float: 单精度浮点数。
string: 字符串，JSON 中使用双引号包围。
bool: 布尔值，JSON 中写为 true 或 false，不加引号。
bytes: 二进制字节数据，通过 JSON 传输时表示为 Base64 字符串。

Protocol Buffers 官方 ProtoJSON 类型映射

bytes 与 Base64

向 bytes 字段传递文本时，先把文本编码成 UTF-8 字节，再进行 Base64 编码；文件则直接对原始二进制字节进行 Base64 编码。接收到 bytes 字段的 JSON 响应时，需要先做 Base64 解码，再按数据实际格式读取。

例如，Hello, World 的 Base64 为 SGVsbG8sIFdvcmxk。对 JSON 配置编码时，编码对象是完整 JSON 文本，而不是其中某一个字段；空格和换行变化也会改变 Base64 结果。

下面的域名 JSON 与 Base64 根据当前站点域名 wafgo.com 成对生成，解码后会得到展示的同一份 UTF-8 JSON 文本。

原始文本与 Base64

Hello, World
SGVsbG8sIFdvcmxk

待编码的 JSON 文本

{"name":"wafgo.com","type":"domain"}

对应的 Base64 值

eyJuYW1lIjoid2FmZ28uY29tIiwidHlwZSI6ImRvbWFpbiJ9

数组与 repeated 字段

文档简写中的 []字段类型字段名表示数组，字段类型限定每个元素的类型。正式 proto3 使用 repeated；JSON 中对应方括号数组。元素是消息对象时，数组中的每一项都应按该消息的字段展开。

下面是三种独立字段的格式示例，并非某个接口的完整请求；实际请求只传递目标方法定义中存在的字段。

[]int64 serverGroupIds: 整数数组，例如 [1, 2, 3]；正式声明为 repeated int64 serverGroupIds = 字段编号;。
[]string types: 字符串数组，例如 ["type1", "type2"]。
[]ServerGroup serverGroups: ServerGroup 对象数组，每个元素按 ServerGroup 的定义提供字段。

JSON 数组格式

{
  "serverGroupIds": [1, 2, 3],
  "types": ["type1", "type2"],
  "serverGroups": [
    {"id": 1, "name": "分组1"},
    {"id": 2, "name": "分组2"},
    {"id": 3, "name": "分组3"}
  ]
}

整体转换为 JSON

HTTP 请求体使用 JSON 对象，以接口定义中的字段名作为键，并按字段类型填写值。serverNamesJSON 是 bytes 字段，所以它的值是域名配置 JSON 的 Base64 字符串，而不是直接嵌套的数组。

下面展示创建网站请求的格式对应关系。域名列表按当前站点配置生成；ID、网站名称、类型、分组和协议配置需要替换为实际数据。空字符串仅用于展示未设置 bytes 的表示，字段是否可空或可省略仍取决于对应接口的业务校验。

HTTP JSON 请求格式示例

{
  "userId": 35,
  "adminId": 1,
  "type": "httpProxy",
  "name": "My site",
  "description": "This is my site",
  "serverNamesJSON": "W3sibmFtZSI6IndhZmdvLmNvbSIsInR5cGUiOiJmdWxsIn1d",
  "httpJSON": "",
  "httpsJSON": "",
  "tcpJSON": "",
  "tlsJSON": "",
  "udpJSON": "",
  "webId": 0,
  "reverseProxyJSON": "",
  "serverGroupIds": [1, 3, 5],
  "userPlanId": 12
}

查看域名信息列表的定义

嵌套对象

当字段类型是另一个消息对象时，JSON 可以嵌套表示。下面以 addr 对象说明层级关系；可用字段应以目标接口的消息定义为准。

嵌套消息与 bytes 字段是两种不同类型：消息字段可以直接放入对象，bytes 字段则仍需要先序列化内容并做 Base64 编码。

嵌套 JSON 格式示例

{
  "name": "Site",
  "addr": {
    "protocol": "http",
    "host": "example.com",
    "portRange": "80"
  }
}

空参数

如果请求消息没有任何字段，按 HTTP 接口的 JSON 调用方式提交空对象 {} 即可，不要把空对象写成字符串 "{}"。

无字段的消息定义示意

message EmptyRequest {}

对应的请求体

{}

字符集

WAFGO API 使用 UTF-8。发送 JSON 文本和字符串时请统一采用 UTF-8；包含中文或其他非 ASCII 字符的内容，也应先取得 UTF-8 字节再进行 Base64 编码。

Base64 解码得到的是原始字节。文本按 UTF-8 解码，JSON 文本再进行 JSON 解析；文件数据则按二进制内容处理。

API 调用概述 Protocol Buffers 官方 proto3 语言指南