Files
junhong_cmp_fiber/internal/model/dto/gateway_rate_limit_dto.go
邹进 78220deb0e
Some checks failed
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Failing after 15m23s
docs: 网关限流接口文档补充操作、类别与状态枚举
- 限流组与错误分类的操作数组元素改为具名类型 GatewayOperation,接口文档按元素给出可选值
- 匹配方式、错误类别、状态字段补充 enum 标签;高优先级操作说明补充取值与必填条件
2026-10-24 15:22:17 +09:00

271 lines
20 KiB
Go
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
package dto
import "time"
// RateLimitGroupListRequest 网关限流组列表请求
type RateLimitGroupListRequest 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:"每页数量"`
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" 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 []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" enum:"0,1" description:"状态 (0:停用, 1:启用);停用后组内操作回落为默认每秒请求上限"`
}
// RateLimitGroupResponse 网关限流组响应
type RateLimitGroupResponse struct {
ID uint `json:"id" description:"限流组ID"`
CarrierID *uint `json:"carrier_id" description:"运营商账户ID,为空表示全局组"`
CarrierName string `json:"carrier_name" description:"运营商账户名称,全局组为空"`
GroupCode string `json:"group_code" description:"组标识"`
GroupName string `json:"group_name" description:"组名称"`
MaxQPS int `json:"max_qps" description:"每秒请求上限"`
Operations []string `json:"operations" description:"组内操作 (query_flow:查流量, query_status:查状态, query_realname:查实名, stop:停机, start:复机)"`
HighPriorityOperations []string `json:"high_priority_operations" description:"高优先级操作"`
ReservedQPS int `json:"reserved_qps" description:"预留给高优先级操作的额度"`
Status int `json:"status" description:"状态 (0:停用, 1:启用)"`
StatusName string `json:"status_name" description:"状态名称"`
CreatedAt time.Time `json:"created_at" description:"创建时间"`
UpdatedAt time.Time `json:"updated_at" description:"更新时间"`
}
// RateLimitGroupPageResult 网关限流组分页结果
type RateLimitGroupPageResult struct {
List []RateLimitGroupResponse `json:"items" description:"限流组列表"`
Total int64 `json:"total" description:"总数"`
Page int `json:"page" description:"当前页"`
PageSize int `json:"size" description:"每页数量"`
}
// GatewayErrorRuleListRequest 上游错误分类规则列表请求
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" 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" 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" enum:"0,1" description:"状态 (0:停用, 1:启用)"`
}
// GatewayErrorRuleResponse 上游错误分类规则响应
type GatewayErrorRuleResponse struct {
ID uint `json:"id" description:"规则ID"`
Keyword string `json:"keyword" description:"匹配关键字或正则"`
MatchType string `json:"match_type" description:"匹配方式 (contains:包含, prefix:前缀, regex:正则)"`
Category string `json:"category" description:"类别"`
CategoryName string `json:"category_name" description:"类别名称"`
Operations []string `json:"operations" description:"适用操作,为空表示全部"`
Priority int `json:"priority" description:"匹配优先级"`
MaybeAccepted bool `json:"maybe_accepted" description:"上游可能已受理"`
Status int `json:"status" description:"状态 (0:停用, 1:启用)"`
Remark string `json:"remark" description:"备注"`
CreatedAt time.Time `json:"created_at" description:"创建时间"`
UpdatedAt time.Time `json:"updated_at" description:"更新时间"`
}
// GatewayErrorRulePageResult 上游错误分类规则分页结果
type GatewayErrorRulePageResult struct {
List []GatewayErrorRuleResponse `json:"items" description:"规则列表"`
Total int64 `json:"total" description:"总数"`
Page int `json:"page" description:"当前页"`
PageSize int `json:"size" description:"每页数量"`
}
// TestGatewayErrorRuleRequest 测试上游错误分类请求
type TestGatewayErrorRuleRequest struct {
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:"未保存的规则草稿,传入时与已启用规则一起参与匹配(草稿按自身优先级排序)"`
}
// TestGatewayErrorRuleResponse 测试上游错误分类响应
type TestGatewayErrorRuleResponse struct {
Category string `json:"category" description:"命中类别"`
CategoryName string `json:"category_name" description:"命中类别名称"`
RuleID uint `json:"rule_id" description:"命中规则ID,未命中或命中草稿为 0"`
Keyword string `json:"keyword" description:"命中关键字,未命中为空"`
MaybeAccepted bool `json:"maybe_accepted" description:"上游可能已受理"`
Matched bool `json:"matched" description:"是否命中规则;未命中时按业务错误处理"`
}
// StopResumeRecordListRequest 停复机记录列表请求
type StopResumeRecordListRequest 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:"每页数量"`
ICCID string `json:"iccid" query:"iccid" validate:"omitempty,max=30" maxLength:"30" description:"ICCID"`
CarrierID *uint `json:"carrier_id" query:"carrier_id" validate:"omitempty" description:"运营商账户ID"`
Action string `json:"action" query:"action" validate:"omitempty,oneof=stop start" description:"动作 (stop:停机, start:复机)"`
Source string `json:"source" query:"source" validate:"omitempty,max=50" maxLength:"50" description:"来源"`
Result string `json:"result" query:"result" validate:"omitempty,oneof=success failed unknown already_target skipped" description:"结果 (success:成功, failed:失败, unknown:结果未知, already_target:已是目标状态, skipped:跳过)"`
ErrorCategory string `json:"error_category" query:"error_category" validate:"omitempty,max=30" maxLength:"30" description:"错误类别"`
StartTime time.Time `json:"start_time" query:"start_time" validate:"required" required:"true" description:"开始时间(必填,RFC3339)"`
EndTime time.Time `json:"end_time" query:"end_time" validate:"required" required:"true" description:"结束时间(必填,RFC3339,跨度不超过 31 天)"`
}
// CardStopResumeRecordListRequest 单卡停复机历史请求
type CardStopResumeRecordListRequest struct {
ID uint `json:"-" path:"id" description:"IoT卡ID"`
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:"每页数量"`
StartTime time.Time `json:"start_time" query:"start_time" description:"开始时间(RFC3339),为空取最近 31 天"`
EndTime time.Time `json:"end_time" query:"end_time" description:"结束时间(RFC3339),为空取当前"`
}
// StopResumeRecordResponse 停复机记录响应
type StopResumeRecordResponse struct {
ID uint `json:"id" description:"记录ID"`
CardID uint `json:"card_id" description:"IoT卡ID"`
ICCID string `json:"iccid" description:"ICCID"`
CarrierID uint `json:"carrier_id" description:"运营商账户ID"`
Action string `json:"action" description:"动作 (stop:停机, start:复机)"`
ActionName string `json:"action_name" description:"动作名称"`
Source string `json:"source" description:"来源"`
Scene string `json:"scene" description:"场景"`
Reason string `json:"reason" description:"停机原因"`
CommandID string `json:"command_id" description:"停复机命令标识,同一命令的多次尝试相同"`
Attempt int `json:"attempt" description:"尝试序号"`
Result string `json:"result" description:"结果 (success:成功, failed:失败, unknown:结果未知, already_target:已是目标状态, skipped:跳过)"`
ErrorCategory string `json:"error_category" description:"错误类别"`
ErrorCategoryName string `json:"error_category_name" description:"错误类别名称"`
ProviderCode string `json:"provider_code" description:"上游返回码"`
ProviderMessage string `json:"provider_message" description:"上游返回信息(已截断)"`
DurationMS int `json:"duration_ms" description:"耗时(毫秒)"`
CreatedAt time.Time `json:"created_at" description:"记录时间"`
}
// StopResumeRecordPageResult 停复机记录分页结果
type StopResumeRecordPageResult struct {
List []StopResumeRecordResponse `json:"items" description:"记录列表"`
Total int64 `json:"total" description:"总数"`
Page int `json:"page" description:"当前页"`
PageSize int `json:"size" description:"每页数量"`
}
// GatewayCallStatsRequest 按运营商账户的网关调用统计请求
type GatewayCallStatsRequest struct {
Minutes int `json:"minutes" query:"minutes" validate:"omitempty,min=1,max=60" minimum:"1" maximum:"60" description:"统计最近多少分钟,默认 15,最大 60"`
}
// GatewayCallTrendRequest 单个运营商账户的网关调用趋势请求
type GatewayCallTrendRequest struct {
CarrierID uint `json:"-" path:"carrier_id" description:"运营商账户ID(0 表示无法解析账户的卡)"`
Minutes int `json:"minutes" query:"minutes" validate:"omitempty,min=1,max=10080" minimum:"1" maximum:"10080" description:"统计最近多少分钟,默认 60,最大 10080(7 天)"`
BucketMinutes int `json:"bucket_minutes" query:"bucket_minutes" validate:"omitempty,min=1,max=1440" minimum:"1" maximum:"1440" description:"聚合粒度(分钟),默认 1"`
}
// GatewayOperationStat 某操作在统计窗口内的调用汇总
type GatewayOperationStat struct {
Operation string `json:"operation" description:"操作 (query_flow:查流量, query_status:查状态, query_realname:查实名, stop:停机, start:复机)"`
OperationName string `json:"operation_name" description:"操作名称"`
Attempts int64 `json:"attempts" description:"实际发出的请求数"`
Success int64 `json:"success" description:"成功数"`
SuccessRate float64 `json:"success_rate" description:"成功率(0~1)"`
AvgQPS float64 `json:"avg_qps" description:"平均每秒请求数"`
PeakMinuteQPS float64 `json:"peak_minute_qps" description:"峰值分钟的平均每秒请求数"`
WouldLimit int64 `json:"would_limit" description:"超过限流组上限的次数(只统计模式下为本应被限流次数)"`
RateLimited int64 `json:"rate_limited" description:"被限流拒绝的次数(拦截模式)"`
Failures map[string]int64 `json:"failures" description:"按错误类别的失败数(network/timeout/http/invalid_response/upstream:<类别>)"`
Exempt map[string]int64 `json:"exempt" description:"按豁免来源的调用量 (manual_click/channel_threshold/auto_renewal/manual_refresh)"`
AvgDurationMS float64 `json:"avg_duration_ms" description:"平均耗时(毫秒)"`
P95DurationMS int64 `json:"p95_duration_ms" description:"p95 耗时上界(毫秒,按分桶近似),-1 表示超过最大分桶"`
}
// GatewayCarrierStat 某运营商账户的网关调用汇总
type GatewayCarrierStat struct {
CarrierID uint `json:"carrier_id" description:"运营商账户ID(0 表示无法解析账户的卡)"`
CarrierName string `json:"carrier_name" description:"运营商账户名称"`
Operations []GatewayOperationStat `json:"operations" description:"各操作汇总"`
}
// GatewayCallStatsResponse 按运营商账户的网关调用统计响应
type GatewayCallStatsResponse struct {
Mode string `json:"mode" description:"当前限流模式 (observe:只统计, enforce:拦截)"`
Minutes int `json:"minutes" description:"统计窗口(分钟)"`
Carriers []GatewayCarrierStat `json:"carriers" description:"有调用的运营商账户汇总"`
}
// GatewayCallTrendPoint 趋势中的一个时间桶
type GatewayCallTrendPoint struct {
Time string `json:"time" description:"时间桶起点(上海时区,yyyy-MM-dd HH:mm)"`
Operations []GatewayOperationStat `json:"operations" description:"各操作在该时间桶的汇总"`
}
// GatewayCallTrendResponse 单个运营商账户的网关调用趋势响应
type GatewayCallTrendResponse struct {
CarrierID uint `json:"carrier_id" description:"运营商账户ID"`
Points []GatewayCallTrendPoint `json:"points" description:"时间桶列表"`
}
// PollingOptionItem 枚举选项
type PollingOptionItem struct {
Value string `json:"value" description:"取值"`
Label string `json:"label" description:"中文名称"`
}
// PollingOptionsResponse 轮询与网关限流相关枚举
type PollingOptionsResponse struct {
GatewayOperations []PollingOptionItem `json:"gateway_operations" description:"卡网关操作"`
ErrorCategories []PollingOptionItem `json:"error_categories" description:"上游错误分类类别"`
MatchTypes []PollingOptionItem `json:"match_types" description:"错误分类匹配方式"`
RateLimitModes []PollingOptionItem `json:"rate_limit_modes" description:"限流模式"`
ExemptSources []PollingOptionItem `json:"exempt_sources" description:"限流豁免来源"`
StopResumeResults []PollingOptionItem `json:"stop_resume_results" description:"停复机记录结果"`
StopResumeActions []PollingOptionItem `json:"stop_resume_actions" description:"停复机动作"`
}
// UpdateRateLimitGroupParams 修改网关限流组参数(路径 + 请求体,供接口文档使用)
type UpdateRateLimitGroupParams struct {
IDReq
SaveRateLimitGroupRequest
}
// UpdateGatewayErrorRuleParams 修改上游错误分类规则参数(路径 + 请求体,供接口文档使用)
type UpdateGatewayErrorRuleParams struct {
IDReq
SaveGatewayErrorRuleRequest
}