增加API注释

2025-11-03 12:20:27 +08:00 · 2023-06-17 21:05:03 +08:00
parent 6a7af9e5cd
commit 7d54f3e165
10 changed files with 116 additions and 25 deletions
--- a/pkg/rpc/jsons/origin_refs.md
+++ b/pkg/rpc/jsons/origin_refs.md
@@ -0,0 +1,33 @@
+# 源站引用列表
+
+## 定义
+~~~json
+[
+  {
+	"isOn": "是否启用",
+	"originId": "源站ID 1"
+  },
+  {
+    "isOn": "是否启用",
+    "originId": "源站ID 2"
+  },
+  ...
+]
+~~~
+
+其中：
+* `originId` - 源站ID，可以通过 `/OriginService/createOrigin` 接口创建源站后获得
+
+## 示例
+~~~json
+[
+  {
+	"isOn": true,
+	"originId": 1
+  },
+  {
+    "isOn": true,
+    "originId": 2,
+  }
+]
+~~~
--- a/pkg/rpc/jsons/reverse_proxy_ref.md
+++ b/pkg/rpc/jsons/reverse_proxy_ref.md
@@ -0,0 +1,19 @@
+# 反向代理引用
+## 定义
+~~~json
+{
+  "isOn": "是否启用",
+  "isPrior": "是否覆盖上级配置，用于路由规则",
+  "reverseProxyId": "反向代理ID"
+}
+~~~
+其中：
+* `reverseProxyId` - 反向代理ID，可以通过 `/ReverseProxyService/createReverseProxy` 创建
+
+## 示例
+~~~json
+{
+  "isOn": true,
+  "reverseProxyId": 123
+}
+~~~
--- a/pkg/rpc/jsons/scheduling.md
+++ b/pkg/rpc/jsons/scheduling.md
@@ -0,0 +1,27 @@
+# 反向代理调度
+## 定义
+~~~json
+{
+	"code": "调度方法代号",
+    "options": "调度选项"
+}
+~~~
+
+其中：
+* `code` 调度方法代号
+  * `random` - 随机
+  * `roundRobin` - 轮询
+  * `hash` - Hash算法
+    * `key` - 自定义Key，可以使用请求变量，比如 `${remoteAddr}`
+  * `sticky` - Sticky算法
+    * `type` - 类型：cookie、header、argument
+    * `param` - 参数值
+
+
+## 示例
+~~~json
+{
+  "code": "random",
+  "options": null
+}
+~~~
--- a/pkg/rpc/pb/service_origin.pb.go
+++ b/pkg/rpc/pb/service_origin.pb.go
@@ -194,7 +194,7 @@ type CreateOriginResponse struct {
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields

-	OriginId int64 `protobuf:"varint,1,opt,name=originId,proto3" json:"originId,omitempty"`
+	OriginId int64 `protobuf:"varint,1,opt,name=originId,proto3" json:"originId,omitempty"` // 创建的源站ID
 }

 func (x *CreateOriginResponse) Reset() {
--- a/pkg/rpc/pb/service_reverse_proxy.pb.go
+++ b/pkg/rpc/pb/service_reverse_proxy.pb.go
@@ -35,9 +35,9 @@ type CreateReverseProxyRequest struct {
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields

-	SchedulingJSON     []byte `protobuf:"bytes,1,opt,name=schedulingJSON,proto3" json:"schedulingJSON,omitempty"`
-	PrimaryOriginsJSON []byte `protobuf:"bytes,2,opt,name=primaryOriginsJSON,proto3" json:"primaryOriginsJSON,omitempty"`
-	BackupOriginsJSON  []byte `protobuf:"bytes,3,opt,name=backupOriginsJSON,proto3" json:"backupOriginsJSON,omitempty"`
+	SchedulingJSON     []byte `protobuf:"bytes,1,opt,name=schedulingJSON,proto3" json:"schedulingJSON,omitempty"`         // 可选项，调度设置 @link json:scheduling
+	PrimaryOriginsJSON []byte `protobuf:"bytes,2,opt,name=primaryOriginsJSON,proto3" json:"primaryOriginsJSON,omitempty"` // 可选项，主要源站 @link json:origin_refs
+	BackupOriginsJSON  []byte `protobuf:"bytes,3,opt,name=backupOriginsJSON,proto3" json:"backupOriginsJSON,omitempty"`   // 可选项，备用源站 @link json:origin_refs
 }

 func (x *CreateReverseProxyRequest) Reset() {
--- a/pkg/rpc/pb/service_server.pb.go
+++ b/pkg/rpc/pb/service_server.pb.go
@@ -35,11 +35,11 @@ type CreateServerRequest struct {
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields

-	UserId      int64  `protobuf:"varint,1,opt,name=userId,proto3" json:"userId,omitempty"`          // 可选参数，用户ID，如果不想指定用户，此值可以为0
-	AdminId     int64  `protobuf:"varint,2,opt,name=adminId,proto3" json:"adminId,omitempty"`        // 可选参数，管理员ID
+	UserId      int64  `protobuf:"varint,1,opt,name=userId,proto3" json:"userId,omitempty"`          // 可选项，用户ID，如果不想指定用户，此值可以为0
+	AdminId     int64  `protobuf:"varint,2,opt,name=adminId,proto3" json:"adminId,omitempty"`        // 可选项，管理员ID
 	Type        string `protobuf:"bytes,3,opt,name=type,proto3" json:"type,omitempty"`               // 类型：httpProxy（HTTP反向代理，一般CDN服务都选这个）、httpWeb（静态文件服务，只会从服务器上读取文件内容，不会转发到源站）、tcpProxy（TCP反向代理）、udpProxy（UDP反向代理）
 	Name        string `protobuf:"bytes,4,opt,name=name,proto3" json:"name,omitempty"`               // 网站名称，通常可以是一个域名
-	Description string `protobuf:"bytes,5,opt,name=description,proto3" json:"description,omitempty"` // 可选参数，网站描述
+	Description string `protobuf:"bytes,5,opt,name=description,proto3" json:"description,omitempty"` // 可选项，网站描述
 	// 配置相关
 	ServerNamesJSON []byte `protobuf:"bytes,8,opt,name=serverNamesJSON,proto3" json:"serverNamesJSON,omitempty"` // 域名列表 @link json:server_names
 	// Deprecated: Do not use.
@@ -50,10 +50,10 @@ type CreateServerRequest struct {
 	TlsJSON          []byte  `protobuf:"bytes,12,opt,name=tlsJSON,proto3" json:"tlsJSON,omitempty"`                       // TLS协议，当type为tcpProxy时填写 @link json:tls_protocol
 	UnixJSON         []byte  `protobuf:"bytes,13,opt,name=unixJSON,proto3" json:"unixJSON,omitempty"`                     // 备用参数，不用填写
 	UdpJSON          []byte  `protobuf:"bytes,14,opt,name=udpJSON,proto3" json:"udpJSON,omitempty"`                       // UDP协议，当type为udpProxy时填写 @link json:udp_protocol
-	WebId            int64   `protobuf:"varint,15,opt,name=webId,proto3" json:"webId,omitempty"`                          // 可选参数，Web配置ID，当type为httpProxy或者httpWeb时填写，可以通过 /HTTPWebService/createHTTPWeb 接口创建；如果你需要配置缓存等信息时需要在 HTTPWebService 接口操作
-	ReverseProxyJSON []byte  `protobuf:"bytes,16,opt,name=reverseProxyJSON,proto3" json:"reverseProxyJSON,omitempty"`     // 反向代理（包含源站）设置
-	ServerGroupIds   []int64 `protobuf:"varint,17,rep,packed,name=serverGroupIds,proto3" json:"serverGroupIds,omitempty"` // 所属网站分组ID列表
-	UserPlanId       int64   `protobuf:"varint,18,opt,name=userPlanId,proto3" json:"userPlanId,omitempty"`                // 可选参数，套餐ID
+	WebId            int64   `protobuf:"varint,15,opt,name=webId,proto3" json:"webId,omitempty"`                          // 可选项，Web配置ID，当type为httpProxy或者httpWeb时填写，可以通过 /HTTPWebService/createHTTPWeb 接口创建；如果你需要配置缓存等信息时需要在 HTTPWebService 接口操作
+	ReverseProxyJSON []byte  `protobuf:"bytes,16,opt,name=reverseProxyJSON,proto3" json:"reverseProxyJSON,omitempty"`     // 反向代理（包含源站）配置引用，此项可以在创建网站后再设置 @link json:reverse_proxy_ref
+	ServerGroupIds   []int64 `protobuf:"varint,17,rep,packed,name=serverGroupIds,proto3" json:"serverGroupIds,omitempty"` // 可选项，所属网站分组ID列表
+	UserPlanId       int64   `protobuf:"varint,18,opt,name=userPlanId,proto3" json:"userPlanId,omitempty"`                // 可选项，套餐ID
 	NodeClusterId    int64   `protobuf:"varint,30,opt,name=nodeClusterId,proto3" json:"nodeClusterId,omitempty"`          // 所部署的集群ID
 	IncludeNodesJSON []byte  `protobuf:"bytes,31,opt,name=includeNodesJSON,proto3" json:"includeNodesJSON,omitempty"`     // 备用参数，不用填写
 	ExcludeNodesJSON []byte  `protobuf:"bytes,32,opt,name=excludeNodesJSON,proto3" json:"excludeNodesJSON,omitempty"`     // 备用参数，不用填写
--- a/pkg/rpc/protos/service_origin.proto
+++ b/pkg/rpc/protos/service_origin.proto
@@ -42,7 +42,7 @@ message CreateOriginRequest {
 }

 message CreateOriginResponse {
-	int64 originId = 1;
+	int64 originId = 1; // 创建的源站ID
 }

 // 修改源站
--- a/pkg/rpc/protos/service_reverse_proxy.proto
+++ b/pkg/rpc/protos/service_reverse_proxy.proto
@@ -32,9 +32,9 @@ service ReverseProxyService {

 // 创建反向代理
 message CreateReverseProxyRequest {
-	bytes schedulingJSON = 1;
-	bytes primaryOriginsJSON = 2;
-	bytes backupOriginsJSON = 3;
+	bytes schedulingJSON = 1; // 可选项，调度设置 @link json:scheduling
+	bytes primaryOriginsJSON = 2; // 可选项，主要源站 @link json:origin_refs
+	bytes backupOriginsJSON = 3; // 可选项，备用源站 @link json:origin_refs
 }

 message CreateReverseProxyResponse {
--- a/pkg/rpc/protos/service_server.proto
+++ b/pkg/rpc/protos/service_server.proto
@@ -179,11 +179,11 @@ service ServerService {

 // 创建网站
 message CreateServerRequest {
-	int64 userId = 1; // 可选参数，用户ID，如果不想指定用户，此值可以为0
-	int64 adminId = 2; // 可选参数，管理员ID
+	int64 userId = 1; // 可选项，用户ID，如果不想指定用户，此值可以为0
+	int64 adminId = 2; // 可选项，管理员ID
 	string type = 3; // 类型：httpProxy（HTTP反向代理，一般CDN服务都选这个）、httpWeb（静态文件服务，只会从服务器上读取文件内容，不会转发到源站）、tcpProxy（TCP反向代理）、udpProxy（UDP反向代理）
 	string name = 4; // 网站名称，通常可以是一个域名
-	string description = 5; // 可选参数，网站描述
+	string description = 5; // 可选项，网站描述

 	// 配置相关
 	bytes serverNamesJSON = 8; // 域名列表 @link json:server_names
@@ -194,10 +194,10 @@ message CreateServerRequest {
 	bytes tlsJSON = 12;  // TLS协议，当type为tcpProxy时填写 @link json:tls_protocol
 	bytes unixJSON = 13; // 备用参数，不用填写
 	bytes udpJSON = 14; // UDP协议，当type为udpProxy时填写 @link json:udp_protocol
-	int64 webId = 15; // 可选参数，Web配置ID，当type为httpProxy或者httpWeb时填写，可以通过 /HTTPWebService/createHTTPWeb 接口创建；如果你需要配置缓存等信息时需要在 HTTPWebService 接口操作
-	bytes reverseProxyJSON = 16; // 反向代理（包含源站）设置
-	repeated int64 serverGroupIds = 17; // 所属网站分组ID列表
-	int64 userPlanId = 18; // 可选参数，套餐ID
+	int64 webId = 15; // 可选项，Web配置ID，当type为httpProxy或者httpWeb时填写，可以通过 /HTTPWebService/createHTTPWeb 接口创建；如果你需要配置缓存等信息时需要在 HTTPWebService 接口操作
+	bytes reverseProxyJSON = 16; // 反向代理（包含源站）配置引用，此项可以在创建网站后再设置 @link json:reverse_proxy_ref
+	repeated int64 serverGroupIds = 17; // 可选项，所属网站分组ID列表
+	int64 userPlanId = 18; // 可选项，套餐ID

 	int64 nodeClusterId = 30; // 所部署的集群ID
 	bytes includeNodesJSON = 31; // 备用参数，不用填写