csxj2026/junhong_cmp_fiber
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 网关限流接口文档补充操作、类别与状态枚举
Some checks failed
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Failing after 15m23s
Details

Browse Source 
- 限流组与错误分类的操作数组元素改为具名类型 GatewayOperation，接口文档按元素给出可选值
- 匹配方式、错误类别、状态字段补充 enum 标签；高优先级操作说明补充取值与必填条件
This commit is contained in:
邹进
2026-10-24 15:22:17 +09:00
parent 42e881576d
commit 78220deb0e
2 changed files with 45 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

56
internal/model/dto/gateway_rate_limit_dto.go
View File

@@ -8,26 +8,34 @@ type RateLimitGroupListRequest struct {
PageSize int `json:"page_size" query:"page_size" validate:"omitempty,min=1,max=100" minimum:"1" maximum:"100" description:"每页数量"`
CarrierID *uint `json:"carrier_id" query:"carrier_id" validate:"omitempty" description:"运营商账户ID筛选"`
OnlyGlobal bool `json:"only_global" query:"only_global" description:"只看全局组"`
Status *int `json:"status" query:"status" validate:"omitempty,oneof=0 1" description:"状态 (0:停用, 1:启用)"`
Status *int `json:"status" query:"status" validate:"omitempty,oneof=0 1" enum:"0,1" description:"状态 (0:停用, 1:启用)"`
}
// GatewayOperation 卡网关操作（query_flow:查流量, query_status:查状态, query_realname:查实名, stop:停机, start:复机）
type GatewayOperation string
// Enum 返回卡网关操作的全部取值，供接口文档生成数组元素枚举。
func (GatewayOperation) Enum() []interface{} {
return []interface{}{"query_flow", "query_status", "query_realname", "stop", "start"}
}
// SaveRateLimitGroupRequest 新建或修改网关限流组请求
type SaveRateLimitGroupRequest struct {
ID uint `json:"-" description:"限流组ID"`
CarrierID *uint `json:"carrier_id" validate:"omitempty" description:"运营商账户ID，为空表示全局组"`
GroupCode string `json:"group_code" validate:"required,max=50" required:"true" maxLength:"50" description:"组标识，同一账户内唯一"`
GroupName string `json:"group_name" validate:"required,max=100" required:"true" maxLength:"100" description:"组名称"`
MaxQPS int `json:"max_qps" validate:"required,min=1,max=10000" required:"true" minimum:"1" maximum:"10000" description:"每秒请求上限"`
Operations []string `json:"operations" validate:"required,min=1,dive,oneof=query_flow query_status query_realname stop start" required:"true" description:"组内操作 (query_flow:查流量, query_status:查状态, query_realname:查实名, stop:停机, start:复机)"`
HighPriorityOperations []string `json:"high_priority_operations" validate:"omitempty,dive,oneof=query_flow query_status query_realname stop start" description:"高优先级操作，必须属于组内操作"`
ReservedQPS int `json:"reserved_qps" validate:"min=0" minimum:"0" description:"预留给高优先级操作的额度，须小于每秒请求上限"`
Status *int `json:"status" validate:"omitempty,oneof=0 1" description:"状态 (0:停用, 1:启用)，新建默认启用"`
ID uint `json:"-" description:"限流组ID"`
CarrierID *uint `json:"carrier_id" validate:"omitempty" description:"运营商账户ID，为空表示全局组"`
GroupCode string `json:"group_code" validate:"required,max=50" required:"true" maxLength:"50" description:"组标识，同一账户内唯一"`
GroupName string `json:"group_name" validate:"required,max=100" required:"true" maxLength:"100" description:"组名称"`
MaxQPS int `json:"max_qps" validate:"required,min=1,max=10000" required:"true" minimum:"1" maximum:"10000" description:"每秒请求上限"`
Operations []GatewayOperation `json:"operations" validate:"required,min=1,dive,oneof=query_flow query_status query_realname stop start" required:"true" minItems:"1" description:"组内操作 (query_flow:查流量, query_status:查状态, query_realname:查实名, stop:停机, start:复机)"`
HighPriorityOperations []GatewayOperation `json:"high_priority_operations" validate:"omitempty,dive,oneof=query_flow query_status query_realname stop start" description:"高优先级操作，必须属于组内操作，设置预留额度时必填 (query_flow:查流量, query_status:查状态, query_realname:查实名, stop:停机, start:复机)"`
ReservedQPS int `json:"reserved_qps" validate:"min=0" minimum:"0" description:"预留给高优先级操作的额度，须小于每秒请求上限"`
Status *int `json:"status" validate:"omitempty,oneof=0 1" enum:"0,1" description:"状态 (0:停用, 1:启用)，新建默认启用"`
}
// UpdateRateLimitGroupStatusRequest 启停网关限流组请求
type UpdateRateLimitGroupStatusRequest struct {
ID uint `json:"-" path:"id" description:"限流组ID"`
Status *int `json:"status" validate:"required,oneof=0 1" required:"true" description:"状态 (0:停用, 1:启用)；停用后组内操作回落为默认每秒请求上限"`
Status *int `json:"status" validate:"required,oneof=0 1" required:"true" enum:"0,1" description:"状态 (0:停用, 1:启用)；停用后组内操作回落为默认每秒请求上限"`
}
// RateLimitGroupResponse 网关限流组响应
@@ -59,28 +67,28 @@ type RateLimitGroupPageResult struct {
type GatewayErrorRuleListRequest struct {
Page int `json:"page" query:"page" validate:"omitempty,min=1" minimum:"1" description:"页码"`
PageSize int `json:"page_size" query:"page_size" validate:"omitempty,min=1,max=100" minimum:"1" maximum:"100" description:"每页数量"`
Category string `json:"category" query:"category" validate:"omitempty,oneof=rate_limited_upstream terminal already_target transient business account_config" description:"类别筛选 (rate_limited_upstream:上游频率限制, terminal:终态不可操作, already_target:已是目标状态, transient:临时故障, business:业务错误, account_config:账户配置错误)"`
Status *int `json:"status" query:"status" validate:"omitempty,oneof=0 1" description:"状态 (0:停用, 1:启用)"`
Category string `json:"category" query:"category" validate:"omitempty,oneof=rate_limited_upstream terminal already_target transient business account_config" enum:"rate_limited_upstream,terminal,already_target,transient,business,account_config" description:"类别筛选 (rate_limited_upstream:上游频率限制, terminal:终态不可操作, already_target:已是目标状态, transient:临时故障, business:业务错误, account_config:账户配置错误)"`
Status *int `json:"status" query:"status" validate:"omitempty,oneof=0 1" enum:"0,1" description:"状态 (0:停用, 1:启用)"`
Keyword string `json:"keyword" query:"keyword" validate:"omitempty,max=100" maxLength:"100" description:"关键字模糊搜索"`
}
// SaveGatewayErrorRuleRequest 新建或修改上游错误分类规则请求
type SaveGatewayErrorRuleRequest struct {
ID uint `json:"-" description:"规则ID"`
Keyword string `json:"keyword" validate:"required,max=200" required:"true" maxLength:"200" description:"匹配关键字或正则"`
MatchType string `json:"match_type" validate:"required,oneof=contains prefix regex" required:"true" description:"匹配方式 (contains:包含, prefix:前缀, regex:正则)"`
Category string `json:"category" validate:"required,oneof=rate_limited_upstream terminal already_target transient business account_config" required:"true" description:"类别 (rate_limited_upstream:上游频率限制, terminal:终态不可操作, already_target:已是目标状态, transient:临时故障, business:业务错误, account_config:账户配置错误)"`
Operations []string `json:"operations" validate:"omitempty,dive,oneof=query_flow query_status query_realname stop start" description:"适用操作，为空表示全部"`
Priority int `json:"priority" validate:"min=1,max=10000" minimum:"1" maximum:"10000" description:"匹配优先级，越小越先匹配"`
MaybeAccepted bool `json:"maybe_accepted" description:"上游可能已受理（如返回含调用成功、操作进行中、请求被合并）"`
Status *int `json:"status" validate:"omitempty,oneof=0 1" description:"状态 (0:停用, 1:启用)，新建默认启用"`
Remark string `json:"remark" validate:"omitempty,max=500" maxLength:"500" description:"备注"`
ID uint `json:"-" description:"规则ID"`
Keyword string `json:"keyword" validate:"required,max=200" required:"true" maxLength:"200" description:"匹配关键字或正则"`
MatchType string `json:"match_type" validate:"required,oneof=contains prefix regex" required:"true" enum:"contains,prefix,regex" description:"匹配方式 (contains:包含, prefix:前缀, regex:正则)"`
Category string `json:"category" validate:"required,oneof=rate_limited_upstream terminal already_target transient business account_config" required:"true" enum:"rate_limited_upstream,terminal,already_target,transient,business,account_config" description:"类别 (rate_limited_upstream:上游频率限制, terminal:终态不可操作, already_target:已是目标状态, transient:临时故障, business:业务错误, account_config:账户配置错误)"`
Operations []GatewayOperation `json:"operations" validate:"omitempty,dive,oneof=query_flow query_status query_realname stop start" description:"适用操作，为空表示全部"`
Priority int `json:"priority" validate:"min=1,max=10000" minimum:"1" maximum:"10000" description:"匹配优先级，越小越先匹配"`
MaybeAccepted bool `json:"maybe_accepted" description:"上游可能已受理（如返回含调用成功、操作进行中、请求被合并）"`
Status *int `json:"status" validate:"omitempty,oneof=0 1" enum:"0,1" description:"状态 (0:停用, 1:启用)，新建默认启用"`
Remark string `json:"remark" validate:"omitempty,max=500" maxLength:"500" description:"备注"`
}
// UpdateGatewayErrorRuleStatusRequest 启停上游错误分类规则请求
type UpdateGatewayErrorRuleStatusRequest struct {
ID uint `json:"-" path:"id" description:"规则ID"`
Status *int `json:"status" validate:"required,oneof=0 1" required:"true" description:"状态 (0:停用, 1:启用)"`
Status *int `json:"status" validate:"required,oneof=0 1" required:"true" enum:"0,1" description:"状态 (0:停用, 1:启用)"`
}
// GatewayErrorRuleResponse 上游错误分类规则响应
@@ -109,7 +117,7 @@ type GatewayErrorRulePageResult struct {
// TestGatewayErrorRuleRequest 测试上游错误分类请求
type TestGatewayErrorRuleRequest struct {
Operation string `json:"operation" validate:"required,oneof=query_flow query_status query_realname stop start" required:"true" description:"操作 (query_flow:查流量, query_status:查状态, query_realname:查实名, stop:停机, start:复机)"`
Operation string `json:"operation" validate:"required,oneof=query_flow query_status query_realname stop start" required:"true" enum:"query_flow,query_status,query_realname,stop,start" description:"操作 (query_flow:查流量, query_status:查状态, query_realname:查实名, stop:停机, start:复机)"`
Message string `json:"message" validate:"required,max=1000" required:"true" maxLength:"1000" description:"上游返回信息"`
Draft *SaveGatewayErrorRuleRequest `json:"draft" description:"未保存的规则草稿，传入时与已启用规则一起参与匹配（草稿按自身优先级排序）"`
}

18
internal/service/polling/gateway_rate_limit_service.go
View File

@@ -240,12 +240,12 @@ func (s *GatewayRateLimitService) validateGroup(ctx context.Context, req *dto.Sa
if req.ReservedQPS >= req.MaxQPS {
return errors.New(errors.CodeInvalidParam, "预留额度必须小于每秒请求上限")
}
ops := uniqueStrings(req.Operations)
ops := uniqueStrings(operationStrings(req.Operations))
opSet := map[string]bool{}
for _, op := range ops {
opSet[op] = true
}
for _, op := range req.HighPriorityOperations {
for _, op := range operationStrings(req.HighPriorityOperations) {
if !opSet[op] {
return errors.New(errors.CodeInvalidParam, "高优先级操作必须属于组内操作："+constants.GatewayOperationName(op))
}
@@ -304,8 +304,8 @@ func applyGroupRequest(row *model.CarrierRateLimitGroup, req *dto.SaveRateLimitG
row.GroupName = strings.TrimSpace(req.GroupName)
row.MaxQPS = req.MaxQPS
row.ReservedQPS = req.ReservedQPS
row.Operations = encodeStrings(uniqueStrings(req.Operations))
row.HighPriorityOperations = encodeStrings(uniqueStrings(req.HighPriorityOperations))
row.Operations = encodeStrings(uniqueStrings(operationStrings(req.Operations)))
row.HighPriorityOperations = encodeStrings(uniqueStrings(operationStrings(req.HighPriorityOperations)))
if req.Status != nil {
row.Status = *req.Status
}
@@ -522,7 +522,7 @@ func applyRuleRequest(row *model.GatewayErrorClassification, req *dto.SaveGatewa
row.Keyword = strings.TrimSpace(req.Keyword)
row.MatchType = req.MatchType
row.Category = req.Category
row.Operations = encodeStrings(uniqueStrings(req.Operations))
row.Operations = encodeStrings(uniqueStrings(operationStrings(req.Operations)))
row.Priority = req.Priority
if row.Priority == 0 {
row.Priority = 100
@@ -594,6 +594,14 @@ func uniqueStrings(values []string) []string {
return out
}
func operationStrings(values []dto.GatewayOperation) []string {
out := make([]string, 0, len(values))
for _, value := range values {
out = append(out, string(value))
}
return out
}
func encodeStrings(values []string) datatypes.JSON {
if values == nil {
values = []string{}