feat: 卡网关按运营商账户限流并记录停复机调用
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 9m33s

- 新增网关限流:按本系统运营商账户(卡 carrier_id)→ 限流组 → 操作限制每秒请求数,每次 HTTP 尝试计量,默认限流、仅后台人工点击/通道阈值/自动续费/手动刷新豁免;支持只统计与拦截两种模式,默认只统计
- Asynq 遇限流不计失败、固定短延迟重试;轮询任务与停复机业务重试遇限流短延迟重排
- 停机、复机不再使用网关内部重试,只发一次请求
- 网关返回结构化错误;新增上游错误分类规则表与测试接口
- 新增按月分区的停复机记录表:系统自动停复机只写记录,不再写统一审计与集成日志;普通轮询查询不再写集成日志
- 新增限流组、错误分类、停复机记录、按账户调用统计与枚举后台接口
- 迁移 000243~000246;同步 OpenSpec 提案(含后续 6 个 change)与技术方案、工程约束
This commit is contained in:
邹进
2026-10-24 15:06:41 +09:00
parent 9e45097aa2
commit 42e881576d
106 changed files with 7173 additions and 48 deletions

View File

@@ -3,6 +3,7 @@ package bootstrap
import (
systemConfigApp "github.com/break/junhong_cmp_fiber/internal/application/systemconfig"
"github.com/break/junhong_cmp_fiber/internal/gateway"
"github.com/break/junhong_cmp_fiber/internal/infrastructure/gatewaylimit"
systemConfigInfra "github.com/break/junhong_cmp_fiber/internal/infrastructure/systemconfig"
"github.com/break/junhong_cmp_fiber/internal/service/verification"
"github.com/break/junhong_cmp_fiber/pkg/auth"
@@ -26,6 +27,7 @@ type Dependencies struct {
QueueClient *queue.Client // Asynq 任务队列客户端
StorageService *storage.Service // 对象存储服务(可选,配置缺失时为 nil)
GatewayClient *gateway.Client // Gateway API 客户端(可选,配置缺失时为 nil)
GatewayLimit *gatewaylimit.Runtime // 卡网关运营商账户限流组件(可选)
WechatPayment wechat.PaymentServiceInterface // 微信支付服务(可选)
SystemConfigRegistry *systemConfigInfra.Registry // 业务模块共享的受控配置注册表(可选)
SystemConfigAudit systemConfigApp.AuditWriter // 配置变更审计 Port;生产为空时装配统一 Writer

View File

@@ -21,6 +21,7 @@ import (
approvalInfra "github.com/break/junhong_cmp_fiber/internal/infrastructure/approval"
auditInfra "github.com/break/junhong_cmp_fiber/internal/infrastructure/audit"
"github.com/break/junhong_cmp_fiber/internal/infrastructure/carriercallback"
"github.com/break/junhong_cmp_fiber/internal/infrastructure/gatewaylimit"
"github.com/break/junhong_cmp_fiber/internal/infrastructure/integrationlog"
"github.com/break/junhong_cmp_fiber/internal/infrastructure/messaging/outbox"
notificationInfra "github.com/break/junhong_cmp_fiber/internal/infrastructure/notification"
@@ -120,6 +121,7 @@ func initHandlers(svc *services, deps *Dependencies) *Handlers {
}
registerCarrierCallbackConfigDefinitions(systemConfigRegistry, deps.Logger)
registerPaymentMethodConfigDefinitions(systemConfigRegistry, deps.Logger)
gatewaylimit.RegisterConfigDefinitions(systemConfigRegistry, deps.Logger)
systemConfigAlerts := systemConfigInfra.NewLogAlertSink(deps.Logger)
var systemConfigCache systemConfigInfra.Cache
if deps.Redis != nil {
@@ -329,6 +331,7 @@ func initHandlers(svc *services, deps *Dependencies) *Handlers {
),
WeComApprovalCallback: wecomApprovalCallback,
PollingConfig: admin.NewPollingConfigHandler(svc.PollingConfig),
GatewayRateLimit: admin.NewGatewayRateLimitHandler(pollingSvcPkg.NewGatewayRateLimitService(deps.DB, auditInfra.NewWriter(auditInfra.NewRegistry(), nil), deps.GatewayLimit), deps.Redis, validate),
PollingConcurrency: admin.NewPollingConcurrencyHandler(svc.PollingConcurrency),
PollingMonitoring: admin.NewPollingMonitoringHandler(svc.PollingMonitoring),
PollingAlert: admin.NewPollingAlertHandler(svc.PollingAlert),

View File

@@ -263,6 +263,9 @@ func initServices(s *stores, deps *Dependencies) *services {
stopResumeService.SetObservationSeriesEventWriter(deps.DB, observationSeriesEvents)
stopResumeService.SetPriorityEventWriter(priorityEvents)
stopResumeService.SetUnifiedAudit(auditWriter, integrationlog.NewRepository(deps.DB))
if deps.GatewayLimit != nil {
stopResumeService.SetStopResumeRecorder(deps.GatewayLimit.Recorder)
}
// 持通道阈值锁的卡在周期内拒绝一切复机(自动、手动、保护期强制、机卡分离)。
stopResumeService.SetChannelThresholdLockGuard(carrierThresholdService)
iotCard.SetRealnameActivator(packageActivation)
@@ -293,6 +296,9 @@ func initServices(s *stores, deps *Dependencies) *services {
device.SetGatewayIntegrationLog(integrationlog.NewRepository(deps.DB))
device.SetObservationSeriesEventWriter(observationSeriesEvents)
device.SetObservationSeriesDispatcher(observationSeries)
if deps.GatewayLimit != nil {
device.SetStopResumeRecorder(deps.GatewayLimit.Recorder)
}
operationPassword := operationPasswordSvc.New(deps.Redis)
shopCommission := shopCommissionSvc.New(s.Shop, s.Account, s.AgentWallet, s.CommissionWithdrawalRequest, s.CommissionWithdrawalSetting, s.CommissionRecord, s.AgentWalletTransaction, deps.DB, deps.Logger)
shopCommission.SetAuditWriter(auditWriter)

View File

@@ -64,6 +64,7 @@ type Handlers struct {
CUCCRealnameRemovalCallback *callback.CUCCRealnameRemovalHandler
WeComApprovalCallback *callback.WeComApprovalHandler
PollingConfig *admin.PollingConfigHandler
GatewayRateLimit *admin.GatewayRateLimitHandler
PollingConcurrency *admin.PollingConcurrencyHandler
PollingMonitoring *admin.PollingMonitoringHandler
PollingAlert *admin.PollingAlertHandler

View File

@@ -7,6 +7,7 @@ import (
"gorm.io/gorm"
"github.com/break/junhong_cmp_fiber/internal/gateway"
"github.com/break/junhong_cmp_fiber/internal/infrastructure/gatewaylimit"
"github.com/break/junhong_cmp_fiber/pkg/queue"
"github.com/break/junhong_cmp_fiber/pkg/storage"
)
@@ -16,10 +17,11 @@ type WorkerDependencies struct {
DB *gorm.DB
Redis *redis.Client
Logger *zap.Logger
AsynqClient *asynq.Client // Worker 特有:用于 Scheduler 提交任务
QueueClient *queue.Client // 统一业务任务客户端,用于 Worker 内产生后续任务
StorageService *storage.Service // 对象存储(可选)
GatewayClient *gateway.Client // Gateway 客户端(可选)
AsynqClient *asynq.Client // Worker 特有:用于 Scheduler 提交任务
QueueClient *queue.Client // 统一业务任务客户端,用于 Worker 内产生后续任务
StorageService *storage.Service // 对象存储(可选)
GatewayClient *gateway.Client // Gateway 客户端(可选)
GatewayLimit *gatewaylimit.Runtime // 卡网关运营商账户限流组件(可选)
}
// WorkerBootstrapResult Worker Bootstrap 初始化结果

View File

@@ -187,6 +187,9 @@ func initWorkerServices(stores *queue.WorkerStores, deps *WorkerDependencies) *q
stopResumeService.SetObservationSeriesEventWriter(deps.DB, observationSeriesEvents)
stopResumeService.SetPriorityEventWriter(priorityEvents)
stopResumeService.SetUnifiedAudit(auditWriter, integrationlog.NewRepository(deps.DB))
if deps.GatewayLimit != nil {
stopResumeService.SetStopResumeRecorder(deps.GatewayLimit.Recorder)
}
// 持通道阈值锁的卡在周期内拒绝一切复机(自动、手动、保护期强制、机卡分离)。
stopResumeService.SetChannelThresholdLockGuard(carrierThresholdService)
// 停复机执行端口复用既有停复机服务作为唯一事实源:消费者与两个计划任务共用同一用例实例。

View File

@@ -0,0 +1,142 @@
package gateway
import (
"context"
stderrors "errors"
"time"
"unicode/utf8"
"github.com/break/junhong_cmp_fiber/pkg/constants"
"github.com/break/junhong_cmp_fiber/pkg/errors"
)
// GatewayError 是网关调用失败的结构化错误。
// 它包裹原有的 *errors.AppError:Error() 文本与错误码保持不变,调用方仍可 errors.As 取 AppError;
// 需要类别、上游业务码、上游信息与耗时的调用方用 errors.As 取 *GatewayError。
type GatewayError struct {
Category string // 错误类别,见 constants.GatewayError*
ProviderCode int // 网关业务码(仅上游业务错误时非 0)
ProviderMessage string // 网关返回信息(已截断,仅上游业务错误时非空)
HTTPStatus int // HTTP 状态码(仅 HTTP 异常时非 0)
Duration time.Duration // 本次 HTTP 尝试耗时
app *errors.AppError
}
// Error 返回与原 AppError 一致的文本。
func (e *GatewayError) Error() string {
if e == nil || e.app == nil {
return "Gateway 调用失败"
}
return e.app.Error()
}
// Unwrap 返回原 AppError,保持错误码判断兼容。
func (e *GatewayError) Unwrap() error {
if e == nil || e.app == nil {
return nil
}
return e.app
}
func newGatewayError(category string, app *errors.AppError) *GatewayError {
return &GatewayError{Category: category, app: app}
}
// AsGatewayError 从错误链中取出结构化网关错误。
func AsGatewayError(err error) (*GatewayError, bool) {
var gwErr *GatewayError
if stderrors.As(err, &gwErr) && gwErr != nil {
return gwErr, true
}
return nil, false
}
// IsRateLimited 判断错误是否为本系统运营商账户限流拒绝(未发出请求)。
func IsRateLimited(err error) bool {
gwErr, ok := AsGatewayError(err)
return ok && gwErr.Category == constants.GatewayErrorRateLimited
}
// NewRateLimitedError 创建限流拒绝错误;由限流守卫在拿不到名额时返回。
func NewRateLimitedError() error {
return newGatewayError(constants.GatewayErrorRateLimited,
errors.New(errors.CodeTooManyRequests, "运营商账户网关调用已达限流上限,请稍后重试"))
}
// truncateProviderMessage 按字符截断上游信息,避免超长内容落库或展示。
func truncateProviderMessage(msg string) string {
if utf8.RuneCountInString(msg) <= constants.GatewayProviderMessageMaxLen {
return msg
}
runes := []rune(msg)
return string(runes[:constants.GatewayProviderMessageMaxLen])
}
// CallInfo 描述一次卡网关 HTTP 尝试,供调用守卫限流与统计。
type CallInfo struct {
Operation string // 卡网关操作,见 constants.GatewayOp*
CardNo string // 卡号(ICCID)
CarrierID uint // 调用方已知的运营商账户 ID(本系统 tb_carrier.id),0 表示由守卫按卡号解析
ExemptSource string // 豁免限流来源,空表示受限流约束
Attempt int // 本次方法调用内的尝试序号,从 1 开始
}
// CallGuard 是卡网关调用守卫:每次 HTTP 尝试前取限流名额,尝试结束后记录统计。
// BeforeAttempt 返回错误时本次方法调用立即结束,不再发起后续尝试。
type CallGuard interface {
BeforeAttempt(ctx context.Context, call CallInfo) error
AfterAttempt(ctx context.Context, call CallInfo, callErr error, duration time.Duration)
}
type cardCallKey struct{}
type carrierKey struct{}
type exemptKey struct{}
type cardCall struct {
operation string
cardNo string
}
// WithCarrier 声明本次调用目标卡所属的运营商账户(本系统 tb_carrier.id),避免守卫按卡号再查一次。
func WithCarrier(ctx context.Context, carrierID uint) context.Context {
if carrierID == 0 {
return ctx
}
return context.WithValue(ctx, carrierKey{}, carrierID)
}
// WithRateLimitExempt 声明本次调用豁免运营商账户限流,只允许后台人工点击、通道阈值、自动续费、手动刷新使用。
func WithRateLimitExempt(ctx context.Context, source string) context.Context {
if source == "" {
return ctx
}
return context.WithValue(ctx, exemptKey{}, source)
}
// RateLimitExemptSource 返回 ctx 中声明的豁免来源,未声明返回空串。
func RateLimitExemptSource(ctx context.Context) string {
source, _ := ctx.Value(exemptKey{}).(string)
return source
}
func withCardCall(ctx context.Context, operation, cardNo string) context.Context {
return context.WithValue(ctx, cardCallKey{}, cardCall{operation: operation, cardNo: cardNo})
}
// cardCallInfo 从 ctx 取出本次卡网关调用信息;非卡操作返回 false。
func cardCallInfo(ctx context.Context) (CallInfo, bool) {
call, ok := ctx.Value(cardCallKey{}).(cardCall)
if !ok {
return CallInfo{}, false
}
carrierID, _ := ctx.Value(carrierKey{}).(uint)
return CallInfo{
Operation: call.operation, CardNo: call.cardNo, CarrierID: carrierID,
ExemptSource: RateLimitExemptSource(ctx),
}, true
}
// SetCallGuard 设置卡网关调用守卫;为 nil 时不限流、不统计。
func (c *Client) SetCallGuard(guard CallGuard) {
c.guard = guard
}

View File

@@ -11,6 +11,7 @@ import (
"net/http"
"time"
"github.com/break/junhong_cmp_fiber/pkg/constants"
"github.com/break/junhong_cmp_fiber/pkg/errors"
"github.com/bytedance/sonic"
"go.uber.org/zap"
@@ -36,6 +37,7 @@ type Client struct {
timeout time.Duration
logger *zap.Logger
maxRetries int
guard CallGuard // 卡网关调用守卫(限流与统计),为 nil 时不生效
}
type attemptObserverKey struct{}
@@ -138,6 +140,7 @@ func (c *Client) executeWithRetry(ctx context.Context, path, encryptedData strin
// 带重试的 HTTP 请求
var lastErr error
observer, _ := ctx.Value(attemptObserverKey{}).(AttemptObserver)
call, isCardCall := cardCallInfo(ctx)
for attempt := 0; attempt <= c.maxRetries; attempt++ {
if attempt > 0 {
// 检查用户 Context 是否已取消
@@ -158,12 +161,30 @@ func (c *Client) executeWithRetry(ctx context.Context, path, encryptedData strin
}
attemptNumber := attempt + 1
// 卡网关操作每次 HTTP 尝试前各取一次限流名额,内部重试同样计量;拿不到名额时本次调用立即结束。
if isCardCall && c.guard != nil {
call.Attempt = attemptNumber
if err := c.guard.BeforeAttempt(ctx, call); err != nil {
if attempt > 0 {
c.logger.Warn("Gateway 重试被限流中止", zap.String("path", path), zap.Int("attempt", attemptNumber), zap.NamedError("last_error", lastErr))
}
return nil, err
}
}
if observer != nil {
if err := observer.BeforeAttempt(ctx, attemptNumber); err != nil {
return nil, err
}
}
attemptStartedAt := time.Now()
result, retryable, err := c.executeHTTPRequest(ctx, path, encryptedData)
attemptDuration := time.Since(attemptStartedAt)
if gwErr, ok := AsGatewayError(err); ok {
gwErr.Duration = attemptDuration
}
if isCardCall && c.guard != nil {
c.guard.AfterAttempt(ctx, call, err, attemptDuration)
}
if observer != nil {
if observeErr := observer.AfterAttempt(ctx, attemptNumber, err); observeErr != nil {
return nil, observeErr
@@ -238,30 +259,32 @@ func (c *Client) executeHTTPRequest(ctx context.Context, path string, encryptedD
if err != nil {
// 用户 Context 已取消 — 不可重试
if ctx.Err() != nil {
return nil, false, errors.Wrap(errors.CodeGatewayError, ctx.Err(), "请求被取消")
return nil, false, newGatewayError(constants.GatewayErrorNetwork, errors.Wrap(errors.CodeGatewayError, ctx.Err(), "请求被取消"))
}
// Client 超时 — 可重试
if reqCtx.Err() == context.DeadlineExceeded {
return nil, true, errors.Wrap(errors.CodeGatewayTimeout, err, "Gateway 请求超时")
return nil, true, newGatewayError(constants.GatewayErrorTimeout, errors.Wrap(errors.CodeGatewayTimeout, err, "Gateway 请求超时"))
}
// 其他网络错误(连接失败、DNS 解析等)— 可重试
return nil, true, errors.Wrap(errors.CodeGatewayError, err, "发送 HTTP 请求失败")
return nil, true, newGatewayError(constants.GatewayErrorNetwork, errors.Wrap(errors.CodeGatewayError, err, "发送 HTTP 请求失败"))
}
defer resp.Body.Close()
// HTTP 状态码错误 — 不可重试
if resp.StatusCode != http.StatusOK {
return nil, false, errors.New(errors.CodeGatewayError, fmt.Sprintf("HTTP 状态码异常: %d", resp.StatusCode))
gwErr := newGatewayError(constants.GatewayErrorHTTP, errors.New(errors.CodeGatewayError, fmt.Sprintf("HTTP 状态码异常: %d", resp.StatusCode)))
gwErr.HTTPStatus = resp.StatusCode
return nil, false, gwErr
}
body, err := io.ReadAll(resp.Body)
if err != nil {
return nil, false, errors.Wrap(errors.CodeGatewayInvalidResp, err, "读取响应体失败")
return nil, false, newGatewayError(constants.GatewayErrorInvalidResponse, errors.Wrap(errors.CodeGatewayInvalidResp, err, "读取响应体失败"))
}
var gatewayResp GatewayResponse
if err := sonic.Unmarshal(body, &gatewayResp); err != nil {
return nil, false, errors.Wrap(errors.CodeGatewayInvalidResp, err, "解析 Gateway 响应失败")
return nil, false, newGatewayError(constants.GatewayErrorInvalidResponse, errors.Wrap(errors.CodeGatewayInvalidResp, err, "解析 Gateway 响应失败"))
}
// Gateway 业务错误 — 不可重试
@@ -271,7 +294,10 @@ func (c *Client) executeHTTPRequest(ctx context.Context, path string, encryptedD
zap.Int("gateway_code", gatewayResp.Code),
zap.String("gateway_msg", gatewayResp.Msg),
)
return nil, false, errors.New(errors.CodeGatewayError, fmt.Sprintf("Gateway 业务错误: code=%d, msg=%s", gatewayResp.Code, gatewayResp.Msg))
gwErr := newGatewayError(constants.GatewayErrorUpstream, errors.New(errors.CodeGatewayError, fmt.Sprintf("Gateway 业务错误: code=%d, msg=%s", gatewayResp.Code, gatewayResp.Msg)))
gwErr.ProviderCode = gatewayResp.Code
gwErr.ProviderMessage = truncateProviderMessage(gatewayResp.Msg)
return nil, false, gwErr
}
return gatewayResp.Data, false, nil

View File

@@ -4,41 +4,74 @@ package gateway
import (
"context"
"github.com/break/junhong_cmp_fiber/pkg/constants"
"github.com/break/junhong_cmp_fiber/pkg/errors"
)
// QueryCardStatus 查询流量卡状态
// POST /flow-card/status
func (c *Client) QueryCardStatus(ctx context.Context, req *CardStatusReq) (*CardStatusResp, error) {
ctx = withCardCall(ctx, constants.GatewayOpQueryStatus, cardNoOf(req))
return doRequestWithResponse[CardStatusResp](c, ctx, "/flow-card/status", req)
}
// QueryFlow 查询流量使用情况
// POST /flow-card/flow
func (c *Client) QueryFlow(ctx context.Context, req *FlowQueryReq) (*FlowUsageResp, error) {
ctx = withCardCall(ctx, constants.GatewayOpQueryFlow, flowCardNoOf(req))
return doRequestWithResponse[FlowUsageResp](c, ctx, "/flow-card/flow", req)
}
// QueryRealnameStatus 查询实名认证状态
// POST /flow-card/realName
func (c *Client) QueryRealnameStatus(ctx context.Context, req *CardStatusReq) (*RealnameStatusResp, error) {
ctx = withCardCall(ctx, constants.GatewayOpQueryRealname, cardNoOf(req))
return doRequestWithResponse[RealnameStatusResp](c, ctx, "/flow-card/realName", req)
}
// StopCard 流量卡停机
// POST /flow-card/cardStop
// 停机是外部状态写入:超时或连接失败时上游可能已受理,内部重试会对同一张卡连发并撞上游单卡频率限制,故只发一次请求。
func (c *Client) StopCard(ctx context.Context, req *CardOperationReq) error {
_, err := c.doRequest(ctx, "/flow-card/cardStop", req)
ctx = withCardCall(ctx, constants.GatewayOpStop, operationCardNoOf(req))
requestClient := *c
requestClient.maxRetries = 0
_, err := requestClient.doRequest(ctx, "/flow-card/cardStop", req)
return err
}
// StartCard 流量卡复机
// POST /flow-card/cardStart
// 复机同停机,只发一次请求,不使用内部重试。
func (c *Client) StartCard(ctx context.Context, req *CardOperationReq) error {
_, err := c.doRequest(ctx, "/flow-card/cardStart", req)
ctx = withCardCall(ctx, constants.GatewayOpStart, operationCardNoOf(req))
requestClient := *c
requestClient.maxRetries = 0
_, err := requestClient.doRequest(ctx, "/flow-card/cardStart", req)
return err
}
func cardNoOf(req *CardStatusReq) string {
if req == nil {
return ""
}
return req.CardNo
}
func flowCardNoOf(req *FlowQueryReq) string {
if req == nil {
return ""
}
return req.CardNo
}
func operationCardNoOf(req *CardOperationReq) string {
if req == nil {
return ""
}
return req.CardNo
}
// GetRealnameLink 获取实名认证跳转链接
// POST /flow-card/RealNameVerification
func (c *Client) GetRealnameLink(ctx context.Context, req *CardStatusReq) (*RealnameLinkResp, error) {

View File

@@ -11,6 +11,7 @@ import (
"github.com/gofiber/fiber/v2"
"github.com/hibiken/asynq"
"github.com/break/junhong_cmp_fiber/internal/gateway"
"github.com/break/junhong_cmp_fiber/internal/handler/validation"
dto "github.com/break/junhong_cmp_fiber/internal/model/dto"
packageExpiryQuery "github.com/break/junhong_cmp_fiber/internal/query/packageexpiry"
@@ -447,7 +448,7 @@ func (h *AssetHandler) Stop(c *fiber.Ctx) error {
switch asset.AssetType {
case "device":
result, devErr := h.deviceService.StopDevice(c.UserContext(), asset.AssetID)
result, devErr := h.deviceService.StopDevice(gateway.WithRateLimitExempt(c.UserContext(), constants.RateLimitExemptManualClick), asset.AssetID)
if devErr != nil {
return devErr
}
@@ -456,7 +457,7 @@ func (h *AssetHandler) Stop(c *fiber.Ctx) error {
if asset.ICCID == "" {
return errors.New(errors.CodeInternalError, "卡 ICCID 为空,无法停机")
}
if cardErr := h.iotCardStopResume.ManualStopCard(c.UserContext(), asset.ICCID); cardErr != nil {
if cardErr := h.iotCardStopResume.ManualStopCard(gateway.WithRateLimitExempt(c.UserContext(), constants.RateLimitExemptManualClick), asset.ICCID); cardErr != nil {
return cardErr
}
return response.Success(c, nil)
@@ -475,7 +476,7 @@ func (h *AssetHandler) Start(c *fiber.Ctx) error {
switch asset.AssetType {
case "device":
if devErr := h.deviceService.StartDevice(c.UserContext(), asset.AssetID); devErr != nil {
if devErr := h.deviceService.StartDevice(gateway.WithRateLimitExempt(c.UserContext(), constants.RateLimitExemptManualClick), asset.AssetID); devErr != nil {
return devErr
}
return response.Success(c, nil)
@@ -483,7 +484,7 @@ func (h *AssetHandler) Start(c *fiber.Ctx) error {
if asset.ICCID == "" {
return errors.New(errors.CodeInternalError, "卡 ICCID 为空,无法复机")
}
if cardErr := h.iotCardStopResume.ManualStartCard(c.UserContext(), asset.ICCID); cardErr != nil {
if cardErr := h.iotCardStopResume.ManualStartCard(gateway.WithRateLimitExempt(c.UserContext(), constants.RateLimitExemptManualClick), asset.ICCID); cardErr != nil {
return cardErr
}
return response.Success(c, nil)

View File

@@ -0,0 +1,343 @@
package admin
import (
"strconv"
"github.com/go-playground/validator/v10"
"github.com/gofiber/fiber/v2"
"github.com/redis/go-redis/v9"
"github.com/break/junhong_cmp_fiber/internal/model/dto"
pollingService "github.com/break/junhong_cmp_fiber/internal/service/polling"
"github.com/break/junhong_cmp_fiber/pkg/errors"
"github.com/break/junhong_cmp_fiber/pkg/response"
)
// GatewayRateLimitHandler 运营商账户网关限流、上游错误分类、停复机记录与调用统计 Handler。
type GatewayRateLimitHandler struct {
service *pollingService.GatewayRateLimitService
redis *redis.Client
validator *validator.Validate
}
// NewGatewayRateLimitHandler 创建网关限流 Handler。
func NewGatewayRateLimitHandler(service *pollingService.GatewayRateLimitService, redisClient *redis.Client, validate *validator.Validate) *GatewayRateLimitHandler {
if validate == nil {
validate = validator.New()
}
return &GatewayRateLimitHandler{service: service, redis: redisClient, validator: validate}
}
func (h *GatewayRateLimitHandler) validate(prefix string, req any) error {
if err := h.validator.Struct(req); err != nil {
return errors.New(errors.CodeInvalidParam, validationMessage(prefix, req, err))
}
return nil
}
func rateLimitPathID(c *fiber.Ctx, name, label string) (uint, error) {
value, err := strconv.ParseUint(c.Params(name), 10, 64)
if err != nil || value == 0 {
return 0, errors.New(errors.CodeInvalidParam, "无效的"+label)
}
return uint(value), nil
}
// ListGroups 查询网关限流组列表。
// GET /api/admin/polling-rate-limit-groups
func (h *GatewayRateLimitHandler) ListGroups(c *fiber.Ctx) error {
var req dto.RateLimitGroupListRequest
if err := c.QueryParser(&req); err != nil {
return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
}
if err := h.validate("网关限流组查询参数不合法", &req); err != nil {
return err
}
result, err := h.service.ListGroups(c.UserContext(), &req)
if err != nil {
return err
}
return response.SuccessWithPagination(c, result.List, result.Total, result.Page, result.PageSize)
}
// GetGroup 查询网关限流组详情。
// GET /api/admin/polling-rate-limit-groups/:id
func (h *GatewayRateLimitHandler) GetGroup(c *fiber.Ctx) error {
id, err := rateLimitPathID(c, "id", "限流组 ID")
if err != nil {
return err
}
result, err := h.service.GetGroup(c.UserContext(), id)
if err != nil {
return err
}
return response.Success(c, result)
}
// CreateGroup 新建网关限流组。
// POST /api/admin/polling-rate-limit-groups
func (h *GatewayRateLimitHandler) CreateGroup(c *fiber.Ctx) error {
var req dto.SaveRateLimitGroupRequest
if err := c.BodyParser(&req); err != nil {
return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
}
if err := h.validate("网关限流组参数不合法", &req); err != nil {
return err
}
result, err := h.service.CreateGroup(c.UserContext(), &req)
if err != nil {
return err
}
return response.Success(c, result)
}
// UpdateGroup 修改网关限流组。
// PUT /api/admin/polling-rate-limit-groups/:id
func (h *GatewayRateLimitHandler) UpdateGroup(c *fiber.Ctx) error {
var req dto.SaveRateLimitGroupRequest
if err := c.BodyParser(&req); err != nil {
return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
}
id, err := rateLimitPathID(c, "id", "限流组 ID")
if err != nil {
return err
}
req.ID = id
if err := h.validate("网关限流组参数不合法", &req); err != nil {
return err
}
result, err := h.service.UpdateGroup(c.UserContext(), &req)
if err != nil {
return err
}
return response.Success(c, result)
}
// UpdateGroupStatus 启停网关限流组。
// PUT /api/admin/polling-rate-limit-groups/:id/status
func (h *GatewayRateLimitHandler) UpdateGroupStatus(c *fiber.Ctx) error {
var req dto.UpdateRateLimitGroupStatusRequest
if err := c.BodyParser(&req); err != nil {
return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
}
id, err := rateLimitPathID(c, "id", "限流组 ID")
if err != nil {
return err
}
req.ID = id
if err := h.validate("网关限流组状态参数不合法", &req); err != nil {
return err
}
if err := h.service.UpdateGroupStatus(c.UserContext(), req.ID, *req.Status); err != nil {
return err
}
return response.Success(c, nil)
}
// DeleteGroup 删除网关限流组。
// DELETE /api/admin/polling-rate-limit-groups/:id
func (h *GatewayRateLimitHandler) DeleteGroup(c *fiber.Ctx) error {
id, err := rateLimitPathID(c, "id", "限流组 ID")
if err != nil {
return err
}
if err := h.service.DeleteGroup(c.UserContext(), id); err != nil {
return err
}
return response.Success(c, nil)
}
// ListRules 查询上游错误分类规则列表。
// GET /api/admin/gateway-error-classifications
func (h *GatewayRateLimitHandler) ListRules(c *fiber.Ctx) error {
var req dto.GatewayErrorRuleListRequest
if err := c.QueryParser(&req); err != nil {
return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
}
if err := h.validate("上游错误分类规则查询参数不合法", &req); err != nil {
return err
}
result, err := h.service.ListRules(c.UserContext(), &req)
if err != nil {
return err
}
return response.SuccessWithPagination(c, result.List, result.Total, result.Page, result.PageSize)
}
// CreateRule 新建上游错误分类规则。
// POST /api/admin/gateway-error-classifications
func (h *GatewayRateLimitHandler) CreateRule(c *fiber.Ctx) error {
var req dto.SaveGatewayErrorRuleRequest
if err := c.BodyParser(&req); err != nil {
return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
}
if err := h.validate("上游错误分类规则参数不合法", &req); err != nil {
return err
}
result, err := h.service.CreateRule(c.UserContext(), &req)
if err != nil {
return err
}
return response.Success(c, result)
}
// UpdateRule 修改上游错误分类规则。
// PUT /api/admin/gateway-error-classifications/:id
func (h *GatewayRateLimitHandler) UpdateRule(c *fiber.Ctx) error {
var req dto.SaveGatewayErrorRuleRequest
if err := c.BodyParser(&req); err != nil {
return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
}
id, err := rateLimitPathID(c, "id", "规则 ID")
if err != nil {
return err
}
req.ID = id
if err := h.validate("上游错误分类规则参数不合法", &req); err != nil {
return err
}
result, err := h.service.UpdateRule(c.UserContext(), &req)
if err != nil {
return err
}
return response.Success(c, result)
}
// UpdateRuleStatus 启停上游错误分类规则。
// PUT /api/admin/gateway-error-classifications/:id/status
func (h *GatewayRateLimitHandler) UpdateRuleStatus(c *fiber.Ctx) error {
var req dto.UpdateGatewayErrorRuleStatusRequest
if err := c.BodyParser(&req); err != nil {
return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
}
id, err := rateLimitPathID(c, "id", "规则 ID")
if err != nil {
return err
}
req.ID = id
if err := h.validate("上游错误分类规则状态参数不合法", &req); err != nil {
return err
}
if err := h.service.UpdateRuleStatus(c.UserContext(), req.ID, *req.Status); err != nil {
return err
}
return response.Success(c, nil)
}
// DeleteRule 删除上游错误分类规则。
// DELETE /api/admin/gateway-error-classifications/:id
func (h *GatewayRateLimitHandler) DeleteRule(c *fiber.Ctx) error {
id, err := rateLimitPathID(c, "id", "规则 ID")
if err != nil {
return err
}
if err := h.service.DeleteRule(c.UserContext(), id); err != nil {
return err
}
return response.Success(c, nil)
}
// TestRule 用已启用规则(可附带草稿)对一段上游返回信息分类,不写任何数据。
// POST /api/admin/gateway-error-classifications/test
func (h *GatewayRateLimitHandler) TestRule(c *fiber.Ctx) error {
var req dto.TestGatewayErrorRuleRequest
if err := c.BodyParser(&req); err != nil {
return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
}
if err := h.validate("上游错误分类测试参数不合法", &req); err != nil {
return err
}
result, err := h.service.TestRule(c.UserContext(), &req)
if err != nil {
return err
}
return response.Success(c, result)
}
// ListStopResumeRecords 查询停复机记录。
// GET /api/admin/card-stop-resume-records
func (h *GatewayRateLimitHandler) ListStopResumeRecords(c *fiber.Ctx) error {
var req dto.StopResumeRecordListRequest
if err := c.QueryParser(&req); err != nil {
return errors.New(errors.CodeInvalidParam, "请求参数解析失败,时间请使用 RFC3339 格式")
}
if err := h.validate("停复机记录查询参数不合法", &req); err != nil {
return err
}
result, err := h.service.ListStopResumeRecords(c.UserContext(), &req)
if err != nil {
return err
}
return response.SuccessWithPagination(c, result.List, result.Total, result.Page, result.PageSize)
}
// ListCardStopResumeRecords 查询单卡停复机历史。
// GET /api/admin/iot-cards/:id/stop-resume-records
func (h *GatewayRateLimitHandler) ListCardStopResumeRecords(c *fiber.Ctx) error {
var req dto.CardStopResumeRecordListRequest
if err := c.QueryParser(&req); err != nil {
return errors.New(errors.CodeInvalidParam, "请求参数解析失败,时间请使用 RFC3339 格式")
}
id, err := rateLimitPathID(c, "id", "IoT 卡 ID")
if err != nil {
return err
}
req.ID = id
if err := h.validate("单卡停复机记录查询参数不合法", &req); err != nil {
return err
}
result, err := h.service.ListCardStopResumeRecords(c.UserContext(), &req)
if err != nil {
return err
}
return response.SuccessWithPagination(c, result.List, result.Total, result.Page, result.PageSize)
}
// CarrierCallStats 按运营商账户汇总最近若干分钟的网关调用。
// GET /api/admin/polling-stats/carriers
func (h *GatewayRateLimitHandler) CarrierCallStats(c *fiber.Ctx) error {
var req dto.GatewayCallStatsRequest
if err := c.QueryParser(&req); err != nil {
return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
}
if err := h.validate("网关调用统计参数不合法", &req); err != nil {
return err
}
result, err := h.service.CarrierCallStats(c.UserContext(), h.redis, &req)
if err != nil {
return err
}
return response.Success(c, result)
}
// CarrierCallTrend 查询单个运营商账户的网关调用趋势。
// GET /api/admin/polling-stats/carriers/:carrier_id/trend
func (h *GatewayRateLimitHandler) CarrierCallTrend(c *fiber.Ctx) error {
var req dto.GatewayCallTrendRequest
if err := c.QueryParser(&req); err != nil {
return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
}
carrierID, err := strconv.ParseUint(c.Params("carrier_id"), 10, 64)
if err != nil {
return errors.New(errors.CodeInvalidParam, "无效的运营商账户 ID")
}
req.CarrierID = uint(carrierID)
if err := h.validate("网关调用趋势参数不合法", &req); err != nil {
return err
}
result, err := h.service.CarrierCallTrend(c.UserContext(), h.redis, &req)
if err != nil {
return err
}
return response.Success(c, result)
}
// PollingOptions 返回轮询与网关限流相关枚举。
// GET /api/admin/polling-options
func (h *GatewayRateLimitHandler) PollingOptions(c *fiber.Ctx) error {
result, err := h.service.PollingOptions(c.UserContext())
if err != nil {
return err
}
return response.Success(c, result)
}

View File

@@ -5,7 +5,9 @@ import (
"context"
assetAutoRenewalApp "github.com/break/junhong_cmp_fiber/internal/application/assetautorenewal"
"github.com/break/junhong_cmp_fiber/internal/gateway"
iotCardSvc "github.com/break/junhong_cmp_fiber/internal/service/iot_card"
"github.com/break/junhong_cmp_fiber/pkg/constants"
"github.com/break/junhong_cmp_fiber/pkg/errors"
)
@@ -35,7 +37,7 @@ func (c *CardCommander) ResumeAssetForAutoRenewal(ctx context.Context, assetType
if c == nil || c.service == nil {
return assetAutoRenewalApp.ResumeOutcome{}, errCommanderUnavailable()
}
outcome, err := c.service.ResumeAssetForAutoRenewal(ctx, assetType, assetID)
outcome, err := c.service.ResumeAssetForAutoRenewal(gateway.WithRateLimitExempt(ctx, constants.RateLimitExemptAutoRenewal), assetType, assetID)
return assetAutoRenewalApp.ResumeOutcome{
Applied: outcome.Applied, IntegrationID: outcome.IntegrationID,
Result: outcome.Result, SafeReason: outcome.SafeReason,
@@ -47,7 +49,7 @@ func (c *CardCommander) QueryAutoRenewalResumeState(ctx context.Context, assetTy
if c == nil || c.service == nil {
return false, false, "", errCommanderUnavailable()
}
return c.service.QueryAutoRenewalResumeState(ctx, assetType, assetID)
return c.service.QueryAutoRenewalResumeState(gateway.WithRateLimitExempt(ctx, constants.RateLimitExemptAutoRenewal), assetType, assetID)
}
// errCommanderUnavailable 返回复机执行端口未配置的稳定错误。

View File

@@ -259,6 +259,14 @@ func NewRegistry() *Registry {
pollingConfigUpdated := pollingAction(constants.AuditActionPollingConfigUpdated, "更新轮询配置", constants.AuditResourcePollingConfig, constants.AuditRiskHigh)
pollingConfigDeleted := pollingAction(constants.AuditActionPollingConfigDeleted, "删除轮询配置", constants.AuditResourcePollingConfig, constants.AuditRiskHigh)
pollingConfigStatusUpdated := pollingAction(constants.AuditActionPollingConfigStatusUpdated, "更新轮询配置状态", constants.AuditResourcePollingConfig, constants.AuditRiskHigh)
rateLimitGroupCreated := pollingAction(constants.AuditActionRateLimitGroupCreated, "创建网关限流组", constants.AuditResourceRateLimitGroup, constants.AuditRiskHigh)
rateLimitGroupUpdated := pollingAction(constants.AuditActionRateLimitGroupUpdated, "更新网关限流组", constants.AuditResourceRateLimitGroup, constants.AuditRiskHigh)
rateLimitGroupStatusUpdated := pollingAction(constants.AuditActionRateLimitGroupStatusUpdated, "更新网关限流组状态", constants.AuditResourceRateLimitGroup, constants.AuditRiskHigh)
rateLimitGroupDeleted := pollingAction(constants.AuditActionRateLimitGroupDeleted, "删除网关限流组", constants.AuditResourceRateLimitGroup, constants.AuditRiskHigh)
gatewayErrorRuleCreated := pollingAction(constants.AuditActionGatewayErrorRuleCreated, "创建上游错误分类规则", constants.AuditResourceGatewayErrorRule, constants.AuditRiskNormal)
gatewayErrorRuleUpdated := pollingAction(constants.AuditActionGatewayErrorRuleUpdated, "更新上游错误分类规则", constants.AuditResourceGatewayErrorRule, constants.AuditRiskNormal)
gatewayErrorRuleStatusUpdated := pollingAction(constants.AuditActionGatewayErrorRuleStatusUpdated, "更新上游错误分类规则状态", constants.AuditResourceGatewayErrorRule, constants.AuditRiskNormal)
gatewayErrorRuleDeleted := pollingAction(constants.AuditActionGatewayErrorRuleDeleted, "删除上游错误分类规则", constants.AuditResourceGatewayErrorRule, constants.AuditRiskNormal)
pollingConcurrencyUpdated := pollingAction(constants.AuditActionPollingConcurrencyUpdated, "更新轮询并发配置", constants.AuditResourcePollingConcurrencyConfig, constants.AuditRiskNormal)
pollingConcurrencyReset := pollingAction(constants.AuditActionPollingConcurrencyReset, "重置轮询并发计数", constants.AuditResourcePollingConcurrencyConfig, constants.AuditRiskNormal)
pollingAlertRuleCreated := pollingAction(constants.AuditActionPollingAlertRuleCreated, "创建轮询告警规则", constants.AuditResourcePollingAlertRule, constants.AuditRiskNormal)
@@ -650,6 +658,14 @@ func NewRegistry() *Registry {
constants.AuditActionPollingConfigUpdated: pollingConfigUpdated,
constants.AuditActionPollingConfigDeleted: pollingConfigDeleted,
constants.AuditActionPollingConfigStatusUpdated: pollingConfigStatusUpdated,
constants.AuditActionRateLimitGroupCreated: rateLimitGroupCreated,
constants.AuditActionRateLimitGroupUpdated: rateLimitGroupUpdated,
constants.AuditActionRateLimitGroupStatusUpdated: rateLimitGroupStatusUpdated,
constants.AuditActionRateLimitGroupDeleted: rateLimitGroupDeleted,
constants.AuditActionGatewayErrorRuleCreated: gatewayErrorRuleCreated,
constants.AuditActionGatewayErrorRuleUpdated: gatewayErrorRuleUpdated,
constants.AuditActionGatewayErrorRuleStatusUpdated: gatewayErrorRuleStatusUpdated,
constants.AuditActionGatewayErrorRuleDeleted: gatewayErrorRuleDeleted,
constants.AuditActionPollingConcurrencyUpdated: pollingConcurrencyUpdated,
constants.AuditActionPollingConcurrencyReset: pollingConcurrencyReset,
constants.AuditActionPollingAlertRuleCreated: pollingAlertRuleCreated,
@@ -930,6 +946,14 @@ func NewRegistry() *Registry {
Type: constants.AuditResourcePollingConcurrencyConfig, Name: "轮询并发配置",
IdentityFields: []string{"id", "task_type", "max_concurrency"},
},
constants.AuditResourceRateLimitGroup: {
Type: constants.AuditResourceRateLimitGroup, Name: "网关限流组",
IdentityFields: []string{"id", "carrier_id", "group_code", "group_name", "max_qps", "reserved_qps", "status"},
},
constants.AuditResourceGatewayErrorRule: {
Type: constants.AuditResourceGatewayErrorRule, Name: "上游错误分类规则",
IdentityFields: []string{"id", "keyword", "match_type", "category", "priority", "status"},
},
constants.AuditResourcePollingAlertRule: {
Type: constants.AuditResourcePollingAlertRule, Name: "轮询告警规则",
IdentityFields: []string{"id", "rule_name", "task_type", "metric_type", "operator", "threshold", "alert_level", "status"},

View File

@@ -9,7 +9,9 @@ import (
carrierthresholdapp "github.com/break/junhong_cmp_fiber/internal/application/carrierthreshold"
carrierthresholddomain "github.com/break/junhong_cmp_fiber/internal/domain/carrierthreshold"
"github.com/break/junhong_cmp_fiber/internal/gateway"
iotcardsvc "github.com/break/junhong_cmp_fiber/internal/service/iot_card"
"github.com/break/junhong_cmp_fiber/pkg/constants"
"github.com/break/junhong_cmp_fiber/pkg/errors"
)
@@ -34,7 +36,7 @@ func (c *CardCommander) StopCardForThreshold(ctx context.Context, cardID uint) (
if c == nil || c.service == nil {
return carrierthresholddomain.CommandOutcome{}, errors.New(errors.CodeServiceUnavailable, "通道流量阈值停机执行能力未配置")
}
return c.service.StopCardForChannelThreshold(ctx, cardID)
return c.service.StopCardForChannelThreshold(gateway.WithRateLimitExempt(ctx, constants.RateLimitExemptChannelThreshold), cardID)
}
// ResumeCardForThreshold 执行通道阈值新周期复机。
@@ -42,7 +44,7 @@ func (c *CardCommander) ResumeCardForThreshold(ctx context.Context, cardID uint)
if c == nil || c.service == nil {
return carrierthresholddomain.CommandOutcome{}, errors.New(errors.CodeServiceUnavailable, "通道流量阈值复机执行能力未配置")
}
return c.service.ResumeCardForChannelThreshold(ctx, cardID)
return c.service.ResumeCardForChannelThreshold(gateway.WithRateLimitExempt(ctx, constants.RateLimitExemptChannelThreshold), cardID)
}
// ResumeReady 判断解锁后的卡是否满足自动复机条件。
@@ -58,7 +60,7 @@ func (c *CardCommander) CardNetworkStatus(ctx context.Context, cardID uint) (int
if c == nil || c.service == nil {
return 0, false, "", errors.New(errors.CodeServiceUnavailable, "通道流量阈值状态查询能力未配置")
}
return c.service.QueryChannelThresholdCardStatus(ctx, cardID)
return c.service.QueryChannelThresholdCardStatus(gateway.WithRateLimitExempt(ctx, constants.RateLimitExemptChannelThreshold), cardID)
}
// ConfirmCardState 按已确认的运营商结果补写卡状态。

View File

@@ -0,0 +1,139 @@
package gatewaylimit
import (
"context"
"regexp"
"strings"
"sync"
"time"
"go.uber.org/zap"
"github.com/break/junhong_cmp_fiber/internal/model"
"github.com/break/junhong_cmp_fiber/pkg/constants"
)
// ClassificationLoader 读取全部启用的错误分类规则(按优先级排序)。
type ClassificationLoader interface {
ListEnabled(ctx context.Context) ([]model.GatewayErrorClassification, error)
}
// Classification 是一次上游错误的分类结果。
type Classification struct {
Category string // 见 constants.GatewayClass*
RuleID uint // 命中的规则 ID,未命中为 0
Keyword string // 命中的关键字
MaybeAccepted bool // 上游可能已受理
}
type compiledRule struct {
row model.GatewayErrorClassification
ops map[string]bool
regex *regexp.Regexp
}
// Classifier 按后台维护的关键字规则对上游错误分类;规则在进程内缓存,超过 TTL 重新加载。
type Classifier struct {
loader ClassificationLoader
logger *zap.Logger
mu sync.Mutex
rules []compiledRule
loaded time.Time
}
// NewClassifier 创建错误分类器;loader 为 nil 时一律归为业务错误。
func NewClassifier(loader ClassificationLoader, logger *zap.Logger) *Classifier {
if logger == nil {
logger = zap.NewNop()
}
return &Classifier{loader: loader, logger: logger}
}
// Invalidate 使规则缓存立即失效,后台保存规则后调用。
func (c *Classifier) Invalidate() {
if c == nil {
return
}
c.mu.Lock()
c.loaded = time.Time{}
c.mu.Unlock()
}
// Classify 对某操作的上游返回信息分类;未命中任何启用规则时归为业务错误。
func (c *Classifier) Classify(ctx context.Context, op, message string) Classification {
if c == nil {
return Classification{Category: constants.GatewayClassBusiness}
}
return MatchRules(c.current(ctx), op, message)
}
// ClassifyWith 用给定规则列表分类,供测试接口在不写数据的前提下验证规则。
func ClassifyWith(rows []model.GatewayErrorClassification, op, message string) Classification {
return MatchRules(compileRules(rows, zap.NewNop()), op, message)
}
// MatchRules 按优先级顺序返回第一个命中的规则分类。
func MatchRules(rules []compiledRule, op, message string) Classification {
for _, rule := range rules {
if len(rule.ops) > 0 && !rule.ops[op] {
continue
}
if !ruleMatches(rule, message) {
continue
}
return Classification{Category: rule.row.Category, RuleID: rule.row.ID, Keyword: rule.row.Keyword, MaybeAccepted: rule.row.MaybeAccepted}
}
return Classification{Category: constants.GatewayClassBusiness}
}
func ruleMatches(rule compiledRule, message string) bool {
switch rule.row.MatchType {
case constants.GatewayMatchPrefix:
return strings.HasPrefix(message, rule.row.Keyword)
case constants.GatewayMatchRegex:
return rule.regex != nil && rule.regex.MatchString(message)
default:
return strings.Contains(message, rule.row.Keyword)
}
}
func (c *Classifier) current(ctx context.Context) []compiledRule {
c.mu.Lock()
defer c.mu.Unlock()
if c.loader == nil || time.Since(c.loaded) < constants.GatewayRateLimitConfigTTL {
return c.rules
}
rows, err := c.loader.ListEnabled(ctx)
c.loaded = time.Now()
if err != nil {
c.logger.Warn("加载上游错误分类规则失败,沿用上一次规则", zap.Error(err))
return c.rules
}
c.rules = compileRules(rows, c.logger)
return c.rules
}
func compileRules(rows []model.GatewayErrorClassification, logger *zap.Logger) []compiledRule {
rules := make([]compiledRule, 0, len(rows))
for _, row := range rows {
rule := compiledRule{row: row, ops: map[string]bool{}}
ops, err := DecodeOperations(row.Operations)
if err != nil {
logger.Warn("错误分类规则适用操作非法,已跳过", zap.Uint("rule_id", row.ID))
continue
}
for _, op := range ops {
rule.ops[op] = true
}
if row.MatchType == constants.GatewayMatchRegex {
re, err := regexp.Compile(row.Keyword)
if err != nil {
logger.Warn("错误分类规则正则非法,已跳过", zap.Uint("rule_id", row.ID))
continue
}
rule.regex = re
}
rules = append(rules, rule)
}
return rules
}

View File

@@ -0,0 +1,130 @@
package gatewaylimit
import (
"context"
"sync"
"time"
"github.com/bytedance/sonic"
"go.uber.org/zap"
"github.com/break/junhong_cmp_fiber/internal/model"
"github.com/break/junhong_cmp_fiber/pkg/constants"
)
// defaultGroupCode 是未被任何启用限流组覆盖时使用的默认组标识(每个账户每个操作独立窗口)。
const defaultGroupCode = "default"
// GroupRule 是一个限流组对某个操作生效的规则快照。
type GroupRule struct {
GroupCode string
MaxQPS int
ReservedQPS int
HighPriority bool // 该操作在组内是否为高优先级
}
// groupIndex 是启用限流组按"账户 → 操作"建立的索引。
type groupIndex struct {
byCarrier map[uint]map[string]GroupRule
global map[string]GroupRule
}
// GroupLoader 读取全部启用的限流组。
type GroupLoader interface {
ListEnabled(ctx context.Context) ([]model.CarrierRateLimitGroup, error)
}
// GroupProvider 在进程内缓存启用限流组,超过 TTL 重新加载,后台修改数秒内生效。
type GroupProvider struct {
loader GroupLoader
logger *zap.Logger
mu sync.Mutex
index groupIndex
loaded time.Time
}
// NewGroupProvider 创建限流组提供者;loader 为 nil 时所有操作使用默认 QPS。
func NewGroupProvider(loader GroupLoader, logger *zap.Logger) *GroupProvider {
if logger == nil {
logger = zap.NewNop()
}
return &GroupProvider{loader: loader, logger: logger, index: groupIndex{byCarrier: map[uint]map[string]GroupRule{}, global: map[string]GroupRule{}}}
}
// Invalidate 使缓存立即失效,后台保存限流组后调用。
func (p *GroupProvider) Invalidate() {
if p == nil {
return
}
p.mu.Lock()
p.loaded = time.Time{}
p.mu.Unlock()
}
// Resolve 返回某账户某操作的账户组规则(未覆盖时 ok=false)与全局组规则(未配置时 ok=false)。
func (p *GroupProvider) Resolve(ctx context.Context, carrierID uint, op string) (account GroupRule, accountOK bool, global GroupRule, globalOK bool) {
index := p.current(ctx)
if rules, ok := index.byCarrier[carrierID]; ok {
account, accountOK = rules[op]
}
global, globalOK = index.global[op]
return
}
func (p *GroupProvider) current(ctx context.Context) groupIndex {
if p == nil {
return groupIndex{}
}
p.mu.Lock()
defer p.mu.Unlock()
if p.loader == nil || time.Since(p.loaded) < constants.GatewayRateLimitConfigTTL {
return p.index
}
rows, err := p.loader.ListEnabled(ctx)
p.loaded = time.Now()
if err != nil {
p.logger.Warn("加载网关限流组失败,沿用上一次配置", zap.Error(err))
return p.index
}
p.index = buildGroupIndex(rows, p.logger)
return p.index
}
func buildGroupIndex(rows []model.CarrierRateLimitGroup, logger *zap.Logger) groupIndex {
index := groupIndex{byCarrier: map[uint]map[string]GroupRule{}, global: map[string]GroupRule{}}
for _, row := range rows {
ops, err := DecodeOperations(row.Operations)
if err != nil {
logger.Warn("限流组操作列表非法,已跳过该组", zap.Uint("group_id", row.ID), zap.Error(err))
continue
}
highOps, _ := DecodeOperations(row.HighPriorityOperations)
high := map[string]bool{}
for _, op := range highOps {
high[op] = true
}
target := index.global
if row.CarrierID != nil {
if index.byCarrier[*row.CarrierID] == nil {
index.byCarrier[*row.CarrierID] = map[string]GroupRule{}
}
target = index.byCarrier[*row.CarrierID]
}
for _, op := range ops {
target[op] = GroupRule{GroupCode: row.GroupCode, MaxQPS: row.MaxQPS, ReservedQPS: row.ReservedQPS, HighPriority: high[op]}
}
}
return index
}
// DecodeOperations 解析 JSON 字符串数组形式的操作列表。
func DecodeOperations(raw []byte) ([]string, error) {
if len(raw) == 0 {
return nil, nil
}
var ops []string
if err := sonic.Unmarshal(raw, &ops); err != nil {
return nil, err
}
return ops, nil
}

View File

@@ -0,0 +1,169 @@
package gatewaylimit
import (
"context"
"strconv"
"time"
"github.com/redis/go-redis/v9"
"go.uber.org/zap"
"github.com/break/junhong_cmp_fiber/internal/gateway"
"github.com/break/junhong_cmp_fiber/pkg/constants"
)
// 分钟计数 Hash 的字段名。
const (
statFieldWouldLimit = "would_limit"
statFieldDurationSum = "duration_ms_sum"
statFieldAttempts = "attempts"
statPrefixExempt = "exempt:"
statPrefixUpstream = "upstream:"
statPrefixDuration = "duration_le:"
)
// durationBuckets 是耗时分桶上界(毫秒),用于近似计算 p95。
var durationBuckets = []int64{100, 300, 500, 1000, 3000, 10000, 60000}
// Guard 实现 gateway.CallGuard:每次卡网关 HTTP 尝试前按运营商账户限流,结束后写分钟计数与卡最近错误。
type Guard struct {
limiter *Limiter
resolver *CarrierResolver
classifier *Classifier
redis *redis.Client
logger *zap.Logger
}
// NewGuard 创建卡网关调用守卫。
func NewGuard(limiter *Limiter, resolver *CarrierResolver, classifier *Classifier, redisClient *redis.Client, logger *zap.Logger) *Guard {
if logger == nil {
logger = zap.NewNop()
}
return &Guard{limiter: limiter, resolver: resolver, classifier: classifier, redis: redisClient, logger: logger}
}
var _ gateway.CallGuard = (*Guard)(nil)
// BeforeAttempt 取限流名额;豁免调用直接放行。拦截模式下拿不到名额返回限流错误,本次方法调用随即结束。
func (g *Guard) BeforeAttempt(ctx context.Context, call gateway.CallInfo) error {
if g == nil || g.limiter == nil || call.ExemptSource != "" {
return nil
}
carrierID := g.carrierOf(ctx, call)
decision, err := g.limiter.Check(ctx, carrierID, call.Operation)
if err != nil {
// 限流器故障时失败开放,避免 Redis 抖动阻断全部网关调用。
g.logger.Warn("网关限流判断失败,本次放行", zap.Uint("carrier_id", carrierID), zap.String("operation", call.Operation), zap.Error(err))
return nil
}
if decision.Exceed {
g.incr(ctx, carrierID, call.Operation, statFieldWouldLimit)
}
if !decision.Allowed {
g.incr(ctx, carrierID, call.Operation, constants.GatewayErrorRateLimited)
return gateway.NewRateLimitedError()
}
return nil
}
// AfterAttempt 写分钟计数(按结果类别与耗时分桶);查询失败时写卡该操作最近一次错误。
func (g *Guard) AfterAttempt(ctx context.Context, call gateway.CallInfo, callErr error, duration time.Duration) {
if g == nil || g.redis == nil {
return
}
ctx = context.WithoutCancel(ctx)
carrierID := g.carrierOf(ctx, call)
field := constants.GatewayResultSuccess
var classification Classification
gwErr, isGatewayErr := gateway.AsGatewayError(callErr)
if callErr != nil {
field = constants.GatewayErrorNetwork
if isGatewayErr {
field = gwErr.Category
if gwErr.Category == constants.GatewayErrorUpstream {
classification = g.classifier.Classify(ctx, call.Operation, gwErr.ProviderMessage)
field = statPrefixUpstream + classification.Category
}
}
}
key := constants.RedisGatewayCallStatKey(carrierID, call.Operation, statMinute(time.Now()))
durationMS := duration.Milliseconds()
pipe := g.redis.Pipeline()
pipe.HIncrBy(ctx, key, field, 1)
pipe.HIncrBy(ctx, key, statFieldAttempts, 1)
pipe.HIncrBy(ctx, key, statFieldDurationSum, durationMS)
pipe.HIncrBy(ctx, key, statPrefixDuration+durationBucket(durationMS), 1)
if call.ExemptSource != "" {
pipe.HIncrBy(ctx, key, statPrefixExempt+call.ExemptSource, 1)
}
pipe.Expire(ctx, key, constants.GatewayCallStatTTL)
if callErr != nil && isQueryOperation(call.Operation) && call.CardNo != "" {
errKey := constants.RedisGatewayCardLastErrorKey(call.CardNo, call.Operation)
values := map[string]any{"category": field, "at": time.Now().Format(time.RFC3339)}
if isGatewayErr {
values["provider_code"] = strconv.Itoa(gwErr.ProviderCode)
values["provider_message"] = gwErr.ProviderMessage
}
pipe.HSet(ctx, errKey, values)
pipe.Expire(ctx, errKey, constants.GatewayCardLastErrorTTL)
}
if _, err := pipe.Exec(ctx); err != nil {
g.logger.Debug("写网关调用统计失败", zap.Error(err))
}
}
// Classify 暴露分类器供停复机记录等调用方对上游错误分类。
func (g *Guard) Classify(ctx context.Context, op, message string) Classification {
if g == nil {
return Classification{Category: constants.GatewayClassBusiness}
}
return g.classifier.Classify(ctx, op, message)
}
func (g *Guard) carrierOf(ctx context.Context, call gateway.CallInfo) uint {
if call.CarrierID != 0 || g.resolver == nil {
return call.CarrierID
}
carrierID, err := g.resolver.Resolve(ctx, call.CardNo)
if err != nil {
g.logger.Debug("解析卡所属运营商账户失败,按未知账户计量", zap.String("iccid", call.CardNo), zap.Error(err))
}
return carrierID
}
func (g *Guard) incr(ctx context.Context, carrierID uint, op, field string) {
if g.redis == nil {
return
}
key := constants.RedisGatewayCallStatKey(carrierID, op, statMinute(time.Now()))
pipe := g.redis.Pipeline()
pipe.HIncrBy(ctx, key, field, 1)
pipe.Expire(ctx, key, constants.GatewayCallStatTTL)
_, _ = pipe.Exec(context.WithoutCancel(ctx))
}
func isQueryOperation(op string) bool {
return op == constants.GatewayOpQueryFlow || op == constants.GatewayOpQueryStatus || op == constants.GatewayOpQueryRealname
}
// statMinute 返回上海时区的分钟标识(yyyyMMddHHmm)。
func statMinute(t time.Time) string {
return t.In(shanghai()).Format("200601021504")
}
func durationBucket(ms int64) string {
for _, upper := range durationBuckets {
if ms <= upper {
return strconv.FormatInt(upper, 10)
}
}
return "inf"
}
func shanghai() *time.Location {
location, err := time.LoadLocation("Asia/Shanghai")
if err != nil {
return time.FixedZone("CST", 8*3600)
}
return location
}

View File

@@ -0,0 +1,191 @@
package gatewaylimit
import (
"context"
"crypto/rand"
"encoding/hex"
"strconv"
"time"
"github.com/redis/go-redis/v9"
"github.com/break/junhong_cmp_fiber/pkg/constants"
)
// slidingWindowScript 在一次原子执行内判断账户组窗口与可选的全局组窗口。
//
// KEYS[1] 账户组窗口 ZSET;KEYS[2] 账户组高优先级等待计数;KEYS[3] 全局组窗口 ZSET(无全局组时传空串占位)。
// ARGV:now_ms、window_ms、max_qps、reserved_qps、is_high(0/1)、global_max(0 表示无全局组)、member、dry_run(0/1)。
// 返回 {allowed(1/0), wait_ms}:dry_run=1(只统计)时总是记录本次请求,allowed=0 表示"本应被限流"。
const slidingWindowLua = `
local now = tonumber(ARGV[1])
local window = tonumber(ARGV[2])
local maxQPS = tonumber(ARGV[3])
local reserved = tonumber(ARGV[4])
local isHigh = tonumber(ARGV[5])
local globalMax = tonumber(ARGV[6])
local member = ARGV[7]
local dryRun = tonumber(ARGV[8])
local useGlobal = globalMax > 0 and KEYS[3] ~= ''
redis.call('ZREMRANGEBYSCORE', KEYS[1], '-inf', now - window)
if useGlobal then
redis.call('ZREMRANGEBYSCORE', KEYS[3], '-inf', now - window)
end
local limit = maxQPS
if isHigh == 0 then
limit = maxQPS - reserved
if reserved > 0 then
local waiting = tonumber(redis.call('GET', KEYS[2]) or '0')
if waiting > 0 then
limit = 0
end
end
end
local allowed = 1
local wait = 0
local count = redis.call('ZCARD', KEYS[1])
if count >= limit then
allowed = 0
local oldest = redis.call('ZRANGE', KEYS[1], 0, 0, 'WITHSCORES')
if oldest[2] then
wait = tonumber(oldest[2]) + window - now
else
wait = window
end
end
if allowed == 1 and useGlobal then
local gcount = redis.call('ZCARD', KEYS[3])
if gcount >= globalMax then
allowed = 0
local goldest = redis.call('ZRANGE', KEYS[3], 0, 0, 'WITHSCORES')
if goldest[2] then
wait = tonumber(goldest[2]) + window - now
else
wait = window
end
end
end
if allowed == 1 or dryRun == 1 then
redis.call('ZADD', KEYS[1], now, member)
redis.call('PEXPIRE', KEYS[1], window * 2)
if useGlobal then
redis.call('ZADD', KEYS[3], now, member)
redis.call('PEXPIRE', KEYS[3], window * 2)
end
end
if wait < 1 and allowed == 0 then
wait = 1
end
return {allowed, wait}
`
var slidingWindowScript = redis.NewScript(slidingWindowLua)
// Decision 是一次限流判断的结果。
type Decision struct {
Allowed bool // 是否放行(只统计模式下恒为 true)
Exceed bool // 是否超过上限(只统计模式下表示"本应被限流")
Wait time.Duration // 拦截时建议的等待时长
}
// Limiter 是基于 Redis 滑动窗口的运营商账户限流器,跨全部进程共享。
type Limiter struct {
redis *redis.Client
groups *GroupProvider
settings *SettingsProvider
}
// NewLimiter 创建限流器。
func NewLimiter(redisClient *redis.Client, groups *GroupProvider, settings *SettingsProvider) *Limiter {
return &Limiter{redis: redisClient, groups: groups, settings: settings}
}
// Check 立即判断一次请求能否放行,不等待。拦截模式下超过上限返回 Allowed=false;
// 只统计模式下总是放行,Exceed 表示本应被限流。Redis 故障时放行(失败开放),避免限流故障阻断业务。
func (l *Limiter) Check(ctx context.Context, carrierID uint, op string) (Decision, error) {
settings := l.settings.Current(ctx)
account, accountOK, global, globalOK := l.groups.Resolve(ctx, carrierID, op)
if !accountOK {
account = GroupRule{GroupCode: defaultGroupCode + ":" + op, MaxQPS: settings.DefaultQPS}
}
globalKey, globalMax := "", 0
if globalOK {
globalKey, globalMax = constants.RedisGatewayGlobalQPSKey(global.GroupCode), global.MaxQPS
}
isHigh, dryRun := 0, 1
if account.HighPriority {
isHigh = 1
}
if settings.Enforce() {
dryRun = 0
}
now := time.Now().UnixMilli()
result, err := slidingWindowScript.Run(ctx, l.redis,
[]string{constants.RedisGatewayQPSKey(carrierID, account.GroupCode), constants.RedisGatewayQPSHighWaitingKey(carrierID, account.GroupCode), globalKey},
now, constants.GatewayRateLimitWindow.Milliseconds(), account.MaxQPS, account.ReservedQPS, isHigh, globalMax, windowMember(now), dryRun,
).Int64Slice()
if err != nil || len(result) != 2 {
return Decision{Allowed: true}, err
}
exceed := result[0] == 0
decision := Decision{Allowed: !exceed || dryRun == 1, Exceed: exceed}
if exceed && dryRun == 0 {
decision.Wait = time.Duration(result[1]) * time.Millisecond
}
return decision, nil
}
// Wait 在拦截模式下按建议时长等待名额,总等待不超过 maxWait;超时返回 false。
// 高优先级操作等待期间登记等待计数,使同组普通操作拿不到新名额。本 Change 中 Asynq 任务不使用该方法。
func (l *Limiter) Wait(ctx context.Context, carrierID uint, op string, maxWait time.Duration) (bool, error) {
deadline := time.Now().Add(maxWait)
registered := false
var waitingKey string
defer func() {
if registered {
l.redis.Decr(context.WithoutCancel(ctx), waitingKey)
}
}()
for {
decision, err := l.Check(ctx, carrierID, op)
if err != nil || decision.Allowed {
return true, err
}
if !registered {
account, accountOK, _, _ := l.groups.Resolve(ctx, carrierID, op)
if accountOK && account.HighPriority && account.ReservedQPS > 0 {
waitingKey = constants.RedisGatewayQPSHighWaitingKey(carrierID, account.GroupCode)
pipe := l.redis.TxPipeline()
pipe.Incr(ctx, waitingKey)
pipe.Expire(ctx, waitingKey, 10*time.Second)
if _, err := pipe.Exec(ctx); err == nil {
registered = true
}
}
}
sleep := decision.Wait
if remaining := time.Until(deadline); remaining <= 0 {
return false, nil
} else if sleep > remaining {
sleep = remaining
}
timer := time.NewTimer(sleep)
select {
case <-ctx.Done():
timer.Stop()
return false, ctx.Err()
case <-timer.C:
}
}
}
// windowMember 生成窗口内唯一成员,避免同毫秒请求互相覆盖。
func windowMember(nowMS int64) string {
buf := make([]byte, 6)
_, _ = rand.Read(buf)
return strconv.FormatInt(nowMS, 10) + "-" + hex.EncodeToString(buf)
}

View File

@@ -0,0 +1,61 @@
package gatewaylimit
import (
"context"
stderrors "errors"
"time"
"github.com/hibiken/asynq"
"go.uber.org/zap"
"github.com/break/junhong_cmp_fiber/internal/store/postgres"
)
// partitionDropLookbackMonths 是每次清理向前检查的过期月数,覆盖维护任务停摆一段时间后的补删。
const partitionDropLookbackMonths = 12
// PartitionMaintainer 维护停复机记录按月分区:提前创建未来分区,按保留期整区删除过期分区。
type PartitionMaintainer struct {
store *postgres.CardStopResumeRecordStore
settings *SettingsProvider
logger *zap.Logger
}
// NewPartitionMaintainer 创建分区维护任务。
func NewPartitionMaintainer(store *postgres.CardStopResumeRecordStore, settings *SettingsProvider, logger *zap.Logger) *PartitionMaintainer {
if logger == nil {
logger = zap.NewNop()
}
return &PartitionMaintainer{store: store, settings: settings, logger: logger}
}
// Handle 是 Asynq 定时任务入口;任一分区操作失败时写错误告警并返回错误,由 Asynq 按既有规则重试。
func (m *PartitionMaintainer) Handle(ctx context.Context, _ *asynq.Task) error {
if m == nil || m.store == nil {
return stderrors.New("停复机记录分区维护未配置")
}
settings := m.settings.Current(ctx)
monthStart := currentMonthStart(time.Now())
var failed error
for i := 0; i <= settings.RecordPremakeMonth; i++ {
month := monthStart.AddDate(0, i, 0)
if err := m.store.EnsureMonthPartition(ctx, month); err != nil {
m.logger.Error("创建停复机记录分区失败,记录将落入默认分区", zap.String("month", month.Format("200601")), zap.Error(err))
failed = err
}
}
for k := 0; k < partitionDropLookbackMonths; k++ {
month := monthStart.AddDate(0, -(settings.RecordRetention + k), 0)
if err := m.store.DropMonthPartition(ctx, month); err != nil {
m.logger.Error("删除过期停复机记录分区失败", zap.String("month", month.Format("200601")), zap.Error(err))
failed = err
}
}
return failed
}
// currentMonthStart 返回上海时区当月 1 日 0 点。
func currentMonthStart(now time.Time) time.Time {
local := now.In(shanghai())
return time.Date(local.Year(), local.Month(), 1, 0, 0, 0, 0, shanghai())
}

View File

@@ -0,0 +1,53 @@
package gatewaylimit
import (
"context"
"strconv"
"github.com/redis/go-redis/v9"
"gorm.io/gorm"
"github.com/break/junhong_cmp_fiber/pkg/constants"
)
// CarrierResolver 按 ICCID 解析卡所属的本系统运营商账户(tb_iot_card.carrier_id),结果缓存在 Redis。
type CarrierResolver struct {
db *gorm.DB
redis *redis.Client
}
// NewCarrierResolver 创建运营商账户解析器。
func NewCarrierResolver(db *gorm.DB, redisClient *redis.Client) *CarrierResolver {
return &CarrierResolver{db: db, redis: redisClient}
}
// Resolve 返回 ICCID 对应卡的运营商账户 ID;卡不存在时返回 0、nil,由调用方按未知账户处理。
func (r *CarrierResolver) Resolve(ctx context.Context, iccid string) (uint, error) {
if r == nil || iccid == "" {
return 0, nil
}
cacheKey := constants.RedisGatewayCardCarrierKey(iccid)
if r.redis != nil {
if raw, err := r.redis.Get(ctx, cacheKey).Result(); err == nil {
if value, parseErr := strconv.ParseUint(raw, 10, 64); parseErr == nil {
return uint(value), nil
}
}
}
if r.db == nil {
return 0, nil
}
var carrierIDs []uint
err := r.db.WithContext(ctx).Table("tb_iot_card").
Where("iccid = ? AND deleted_at IS NULL", iccid).Limit(1).Pluck("carrier_id", &carrierIDs).Error
if err != nil {
return 0, err
}
if len(carrierIDs) == 0 {
return 0, nil
}
if r.redis != nil {
_ = r.redis.Set(ctx, cacheKey, strconv.FormatUint(uint64(carrierIDs[0]), 10), constants.GatewayCardCarrierCacheTTL).Err()
}
return carrierIDs[0], nil
}

View File

@@ -0,0 +1,79 @@
package gatewaylimit
import (
"context"
"crypto/sha1"
"encoding/hex"
"time"
"github.com/hibiken/asynq"
"github.com/redis/go-redis/v9"
"go.uber.org/zap"
"gorm.io/gorm"
"github.com/break/junhong_cmp_fiber/internal/infrastructure/systemconfig"
"github.com/break/junhong_cmp_fiber/internal/store/postgres"
"github.com/break/junhong_cmp_fiber/pkg/constants"
)
// Runtime 汇总一个进程内的网关限流组件,API 与 Worker 各自创建一份,限流窗口经 Redis 跨进程共享。
type Runtime struct {
Settings *SettingsProvider
Groups *GroupProvider
Classifier *Classifier
Limiter *Limiter
Guard *Guard
Recorder *StopResumeRecorder
redisClient *redis.Client
logger *zap.Logger
}
// NewRuntime 创建网关限流运行组件;配置读取使用独立注册表,与后台系统配置共享同一份数据库与缓存数据。
func NewRuntime(db *gorm.DB, redisClient *redis.Client, logger *zap.Logger) *Runtime {
if logger == nil {
logger = zap.NewNop()
}
registry := systemconfig.NewRegistry()
RegisterConfigDefinitions(registry, logger)
var cache systemconfig.Cache
if redisClient != nil {
cache = systemconfig.NewRedisCache(redisClient)
}
reader := systemconfig.NewReader(db, registry, cache, systemconfig.NewLogAlertSink(logger))
settings := NewSettingsProvider(reader, logger)
groups := NewGroupProvider(postgres.NewCarrierRateLimitGroupStore(db), logger)
classifier := NewClassifier(postgres.NewGatewayErrorClassificationStore(db), logger)
limiter := NewLimiter(redisClient, groups, settings)
guard := NewGuard(limiter, NewCarrierResolver(db, redisClient), classifier, redisClient, logger)
recorder := NewStopResumeRecorder(postgres.NewCardStopResumeRecordStore(db), classifier, logger)
return &Runtime{Settings: settings, Groups: groups, Classifier: classifier, Limiter: limiter, Guard: guard, Recorder: recorder, redisClient: redisClient, logger: logger}
}
// TrackDeferral 记录 Asynq 任务因限流被推迟;同一任务首次被限流起累计推迟超过阈值时写一次错误告警,任务继续重试。
// 任务以"类型 + 载荷摘要"标识,记录 1 天后自动过期。
func (r *Runtime) TrackDeferral(task *asynq.Task) {
if r == nil || r.redisClient == nil || task == nil {
return
}
ctx := context.Background()
sum := sha1.Sum(task.Payload())
taskKey := task.Type() + ":" + hex.EncodeToString(sum[:])
key := constants.RedisRateLimitDeferStartKey(taskKey)
now := time.Now()
if ok, err := r.redisClient.SetNX(ctx, key, now.Unix(), 24*time.Hour).Result(); err != nil || ok {
return
}
startedUnix, err := r.redisClient.Get(ctx, key).Int64()
if err != nil {
return
}
deferred := now.Sub(time.Unix(startedUnix, 0))
if deferred < r.Settings.Current(ctx).DeferAlert {
return
}
if alerted, _ := r.redisClient.SetNX(ctx, key+":alerted", 1, 24*time.Hour).Result(); alerted {
r.logger.Error("异步任务因运营商账户网关限流累计推迟超过告警阈值,任务继续重试",
zap.String("task_type", task.Type()), zap.String("task_key", taskKey), zap.Duration("deferred", deferred))
}
}

View File

@@ -0,0 +1,136 @@
// Package gatewaylimit 实现按运营商账户(本系统 tb_carrier)的卡网关调用限流、错误分类与调用统计。
//
// 账户口径:限流单位是本系统的运营商账户(卡上的 carrier_id),与网关客户端自身的 appId 无关。
// 调用方已知卡所属账户时用 gateway.WithCarrier 传入;否则守卫按 ICCID 查本系统卡表解析。
package gatewaylimit
import (
"context"
stderrors "errors"
"strconv"
"sync"
"time"
"go.uber.org/zap"
"github.com/break/junhong_cmp_fiber/internal/infrastructure/systemconfig"
"github.com/break/junhong_cmp_fiber/pkg/constants"
)
// RegisterConfigDefinitions 向受控系统配置注册表注册网关限流相关配置;已注册的 Key 跳过。
func RegisterConfigDefinitions(registry *systemconfig.Registry, logger *zap.Logger) {
if registry == nil {
return
}
minOne, minZero := int64(1), int64(0)
maxQPS, maxDelay, maxAlert, maxMonths := int64(10000), int64(3600), int64(86400*7), int64(120)
definitions := []systemconfig.Definition{
{Key: constants.SystemConfigPollingRateLimitMode, Module: constants.SystemConfigModulePolling, ValueType: constants.SystemConfigTypeString, DefaultValue: constants.RateLimitModeObserve, Description: "网关限流模式:observe 只统计不拦截,enforce 拦截", EnumValues: []string{constants.RateLimitModeObserve, constants.RateLimitModeEnforce}},
{Key: constants.SystemConfigPollingGatewayDefaultQPS, Module: constants.SystemConfigModulePolling, ValueType: constants.SystemConfigTypeInt, DefaultValue: "10", Description: "未被启用限流组覆盖的卡网关操作的默认每秒请求上限", Min: &minOne, Max: &maxQPS},
{Key: constants.SystemConfigPollingRateLimitedRetryDelay, Module: constants.SystemConfigModulePolling, ValueType: constants.SystemConfigTypeInt, DefaultValue: "5", Description: "Asynq 任务遇限流后的固定重试延迟(秒)", Min: &minOne, Max: &maxDelay},
{Key: constants.SystemConfigPollingRateLimitDeferAlert, Module: constants.SystemConfigModulePolling, ValueType: constants.SystemConfigTypeInt, DefaultValue: "600", Description: "同一任务因限流累计推迟超过该时长(秒)时写告警", Min: &minOne, Max: &maxAlert},
{Key: constants.SystemConfigPollingStopResumeRecordRetention, Module: constants.SystemConfigModulePolling, ValueType: constants.SystemConfigTypeInt, DefaultValue: "6", Description: "停复机记录保留月数,到期整区删除", Min: &minOne, Max: &maxMonths},
{Key: constants.SystemConfigPollingStopResumeRecordPremake, Module: constants.SystemConfigModulePolling, ValueType: constants.SystemConfigTypeInt, DefaultValue: "3", Description: "停复机记录提前创建未来分区的月数", Min: &minZero, Max: &maxMonths},
}
for _, definition := range definitions {
if _, exists := registry.Get(definition.Key); exists {
continue
}
if err := registry.Register(definition); err != nil && logger != nil {
logger.Error("注册网关限流系统配置失败,将使用代码默认值", zap.String("config_key", definition.Key), zap.Error(err))
}
}
}
// ConfigReader 读取已注册的受控系统配置。
type ConfigReader interface {
Get(ctx context.Context, key string) (string, error)
}
// Settings 是网关限流运行参数快照。
type Settings struct {
Mode string
DefaultQPS int
RetryDelay time.Duration
DeferAlert time.Duration
RecordRetention int
RecordPremakeMonth int
}
// Enforce 判断当前是否为拦截模式。
func (s Settings) Enforce() bool {
return s.Mode == constants.RateLimitModeEnforce
}
// defaultSettings 是配置读取失败时的安全默认值:只统计、不拦截。
func defaultSettings() Settings {
return Settings{Mode: constants.RateLimitModeObserve, DefaultQPS: 10, RetryDelay: 5 * time.Second, DeferAlert: 10 * time.Minute, RecordRetention: 6, RecordPremakeMonth: 3}
}
// SettingsProvider 在进程内缓存限流参数,超过 TTL 重新读取,后台修改数秒内生效。
type SettingsProvider struct {
reader ConfigReader
logger *zap.Logger
mu sync.Mutex
cached Settings
loaded time.Time
}
// NewSettingsProvider 创建限流参数提供者;reader 为 nil 时始终返回安全默认值。
func NewSettingsProvider(reader ConfigReader, logger *zap.Logger) *SettingsProvider {
if logger == nil {
logger = zap.NewNop()
}
return &SettingsProvider{reader: reader, logger: logger, cached: defaultSettings()}
}
// Current 返回当前限流参数;读取失败时保留上一次成功值。
func (p *SettingsProvider) Current(ctx context.Context) Settings {
if p == nil {
return defaultSettings()
}
p.mu.Lock()
defer p.mu.Unlock()
if p.reader == nil || time.Since(p.loaded) < constants.GatewayRateLimitConfigTTL {
return p.cached
}
next, err := p.load(ctx)
p.loaded = time.Now()
if err != nil {
p.logger.Warn("读取网关限流配置失败,沿用上一次配置", zap.Error(err))
return p.cached
}
p.cached = next
return next
}
func (p *SettingsProvider) load(ctx context.Context) (Settings, error) {
settings := defaultSettings()
mode, err := p.reader.Get(ctx, constants.SystemConfigPollingRateLimitMode)
if err != nil {
return settings, err
}
settings.Mode = mode
ints := []struct {
key string
set func(int)
}{
{constants.SystemConfigPollingGatewayDefaultQPS, func(v int) { settings.DefaultQPS = v }},
{constants.SystemConfigPollingRateLimitedRetryDelay, func(v int) { settings.RetryDelay = time.Duration(v) * time.Second }},
{constants.SystemConfigPollingRateLimitDeferAlert, func(v int) { settings.DeferAlert = time.Duration(v) * time.Second }},
{constants.SystemConfigPollingStopResumeRecordRetention, func(v int) { settings.RecordRetention = v }},
{constants.SystemConfigPollingStopResumeRecordPremake, func(v int) { settings.RecordPremakeMonth = v }},
}
for _, item := range ints {
raw, err := p.reader.Get(ctx, item.key)
if err != nil {
return settings, err
}
value, err := strconv.Atoi(raw)
if err != nil {
return settings, stderrors.New("网关限流整数配置非法")
}
item.set(value)
}
return settings, nil
}

View File

@@ -0,0 +1,86 @@
package gatewaylimit
import (
"context"
"strconv"
"time"
"go.uber.org/zap"
"github.com/break/junhong_cmp_fiber/internal/gateway"
"github.com/break/junhong_cmp_fiber/internal/model"
"github.com/break/junhong_cmp_fiber/internal/store/postgres"
"github.com/break/junhong_cmp_fiber/pkg/constants"
)
// StopResumeRecordInput 描述一次实际调用上游停机或复机的结果。
type StopResumeRecordInput struct {
CardID uint
ICCID string
CarrierID uint
Action string // constants.StopResumeActionStop / StopResumeActionStart
Source string // 来源:豁免来源或审计来源
Scene string
Reason string // 停机原因
CommandID string // 同一次停复机命令的多次尝试共用
Attempt int
CallErr error
Duration time.Duration
}
// StopResumeRecorder 把每次停复机上游调用写入停复机记录表;写入失败只记日志与计数,不影响业务回写。
type StopResumeRecorder struct {
store *postgres.CardStopResumeRecordStore
classifier *Classifier
logger *zap.Logger
}
// NewStopResumeRecorder 创建停复机记录写入器。
func NewStopResumeRecorder(store *postgres.CardStopResumeRecordStore, classifier *Classifier, logger *zap.Logger) *StopResumeRecorder {
if logger == nil {
logger = zap.NewNop()
}
return &StopResumeRecorder{store: store, classifier: classifier, logger: logger}
}
// Record 写入一条停复机记录;限流拒绝(请求未发出)不写。
func (r *StopResumeRecorder) Record(ctx context.Context, input StopResumeRecordInput) {
if r == nil || r.store == nil || gateway.IsRateLimited(input.CallErr) {
return
}
row := &model.CardStopResumeRecord{
CardID: input.CardID, ICCID: input.ICCID, CarrierID: input.CarrierID, Action: input.Action,
Source: input.Source, Scene: input.Scene, Reason: input.Reason, CommandID: input.CommandID,
Attempt: input.Attempt, Result: constants.StopResumeRecordSuccess,
DurationMS: int(input.Duration.Milliseconds()), CreatedAt: time.Now(),
}
if input.CallErr != nil {
row.Result = constants.StopResumeRecordFailed
if gwErr, ok := gateway.AsGatewayError(input.CallErr); ok {
row.ErrorCategory = gwErr.Category
switch gwErr.Category {
case constants.GatewayErrorTimeout, constants.GatewayErrorNetwork:
// 超时或连接失败时上游可能已受理,按结果未知记录。
row.Result = constants.StopResumeRecordUnknown
case constants.GatewayErrorUpstream:
op := constants.GatewayOpStop
if input.Action == constants.StopResumeActionStart {
op = constants.GatewayOpStart
}
classification := r.classifier.Classify(ctx, op, gwErr.ProviderMessage)
row.ErrorCategory = classification.Category
if classification.Category == constants.GatewayClassAlreadyTarget {
row.Result = constants.StopResumeRecordAlreadyTarget
}
row.ProviderCode = strconv.Itoa(gwErr.ProviderCode)
row.ProviderMessage = gwErr.ProviderMessage
}
}
}
writeCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 3*time.Second)
defer cancel()
if err := r.store.Create(writeCtx, row); err != nil {
r.logger.Warn("写停复机记录失败,不影响停复机结果回写",
zap.Uint("card_id", input.CardID), zap.String("action", input.Action), zap.String("metric", "stop_resume_record.write_failed"), zap.Error(err))
}
}

View File

@@ -0,0 +1,262 @@
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" description:"状态 (0:停用, 1:启用)"`
}
// 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:启用),新建默认启用"`
}
// 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:启用);停用后组内操作回落为默认每秒请求上限"`
}
// 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" 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:启用)"`
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:"备注"`
}
// 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:启用)"`
}
// 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" 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
}

View File

@@ -4,7 +4,7 @@ import "time"
// SystemConfigListRequest 是系统配置分页查询参数。
type SystemConfigListRequest struct {
Module string `json:"module" query:"module" validate:"omitempty,oneof=carrier_callback c2b.payment" enum:"carrier_callback,c2b.payment" description:"模块筛选 (carrier_callback:运营商回调配置, c2b.payment:C端支付方式配置)"`
Module string `json:"module" query:"module" validate:"omitempty,oneof=carrier_callback c2b.payment polling" enum:"carrier_callback,c2b.payment,polling" description:"模块筛选 (carrier_callback:运营商回调配置, c2b.payment:C端支付方式配置, polling:轮询与网关限流配置)"`
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:"每页数量"`
}
@@ -14,7 +14,7 @@ type SystemConfigItem struct {
ConfigKey string `json:"config_key" description:"稳定配置 Key"`
Value string `json:"value" description:"配置值;敏感值按注册策略脱敏"`
ValueType string `json:"value_type" description:"值类型 (string:字符串, int:整数, bool:布尔, json:JSON)"`
Module string `json:"module" enum:"carrier_callback,c2b.payment" description:"所属模块 (carrier_callback:运营商回调配置, c2b.payment:C端支付方式配置)"`
Module string `json:"module" enum:"carrier_callback,c2b.payment,polling" description:"所属模块 (carrier_callback:运营商回调配置, c2b.payment:C端支付方式配置, polling:轮询与网关限流配置)"`
Description string `json:"description" description:"中文说明"`
Readonly bool `json:"readonly" description:"是否只读"`
Sensitive bool `json:"sensitive" description:"是否敏感"`

View File

@@ -0,0 +1,72 @@
package model
import (
"time"
"gorm.io/datatypes"
"gorm.io/gorm"
)
// CarrierRateLimitGroup 运营商账户网关限流组。
// CarrierID 为 nil 表示全局组;Operations、HighPriorityOperations 为卡网关操作字符串数组(JSON)。
type CarrierRateLimitGroup struct {
gorm.Model
BaseModel `gorm:"embedded"`
CarrierID *uint `gorm:"column:carrier_id;comment:运营商账户ID,为空表示全局组" json:"carrier_id"`
GroupCode string `gorm:"column:group_code;type:varchar(50);not null;comment:组标识" json:"group_code"`
GroupName string `gorm:"column:group_name;type:varchar(100);not null;comment:组名称" json:"group_name"`
MaxQPS int `gorm:"column:max_qps;not null;comment:每秒请求上限" json:"max_qps"`
Operations datatypes.JSON `gorm:"column:operations;type:jsonb;not null;comment:组内操作" json:"operations"`
HighPriorityOperations datatypes.JSON `gorm:"column:high_priority_operations;type:jsonb;not null;comment:高优先级操作" json:"high_priority_operations"`
ReservedQPS int `gorm:"column:reserved_qps;not null;default:0;comment:预留给高优先级操作的额度" json:"reserved_qps"`
Status int `gorm:"column:status;type:smallint;not null;default:1;comment:状态 0-停用 1-启用" json:"status"`
}
// TableName 返回限流组表名。
func (CarrierRateLimitGroup) TableName() string {
return "tb_carrier_rate_limit_group"
}
// GatewayErrorClassification 上游错误分类规则。
type GatewayErrorClassification struct {
gorm.Model
BaseModel `gorm:"embedded"`
Keyword string `gorm:"column:keyword;type:varchar(200);not null;comment:匹配关键字或正则" json:"keyword"`
MatchType string `gorm:"column:match_type;type:varchar(20);not null;default:contains;comment:匹配方式" json:"match_type"`
Category string `gorm:"column:category;type:varchar(30);not null;comment:类别" json:"category"`
Operations datatypes.JSON `gorm:"column:operations;type:jsonb;not null;comment:适用操作,空数组表示全部" json:"operations"`
Priority int `gorm:"column:priority;not null;default:100;comment:匹配优先级" json:"priority"`
MaybeAccepted bool `gorm:"column:maybe_accepted;not null;default:false;comment:上游可能已受理" json:"maybe_accepted"`
Status int `gorm:"column:status;type:smallint;not null;default:1;comment:状态 0-停用 1-启用" json:"status"`
Remark string `gorm:"column:remark;type:varchar(500);not null;default:'';comment:备注" json:"remark"`
}
// TableName 返回错误分类规则表名。
func (GatewayErrorClassification) TableName() string {
return "tb_gateway_error_classification"
}
// CardStopResumeRecord 停复机调用记录(按月分区表),每次实际调用上游停机或复机一条。
type CardStopResumeRecord struct {
ID uint `gorm:"column:id;primaryKey;autoIncrement" json:"id"`
CardID uint `gorm:"column:card_id;not null" json:"card_id"`
ICCID string `gorm:"column:iccid;type:varchar(30);not null;default:''" json:"iccid"`
CarrierID uint `gorm:"column:carrier_id;not null;default:0" json:"carrier_id"`
Action string `gorm:"column:action;type:varchar(10);not null" json:"action"`
Source string `gorm:"column:source;type:varchar(50);not null;default:''" json:"source"`
Scene string `gorm:"column:scene;type:varchar(50);not null;default:''" json:"scene"`
Reason string `gorm:"column:reason;type:varchar(50);not null;default:''" json:"reason"`
CommandID string `gorm:"column:command_id;type:varchar(64);not null;default:''" json:"command_id"`
Attempt int `gorm:"column:attempt;not null;default:1" json:"attempt"`
Result string `gorm:"column:result;type:varchar(20);not null" json:"result"`
ErrorCategory string `gorm:"column:error_category;type:varchar(30);not null;default:''" json:"error_category"`
ProviderCode string `gorm:"column:provider_code;type:varchar(30);not null;default:''" json:"provider_code"`
ProviderMessage string `gorm:"column:provider_message;type:varchar(500);not null;default:''" json:"provider_message"`
DurationMS int `gorm:"column:duration_ms;not null;default:0" json:"duration_ms"`
CreatedAt time.Time `gorm:"column:created_at;type:timestamptz;primaryKey;not null" json:"created_at"`
}
// TableName 返回停复机记录表名。
func (CardStopResumeRecord) TableName() string {
return "tb_card_stop_resume_record"
}

View File

@@ -133,6 +133,9 @@ func RegisterAdminRoutes(router fiber.Router, handlers *bootstrap.Handlers, midd
if handlers.PollingConfig != nil {
registerPollingConfigRoutes(authGroup, handlers.PollingConfig, doc, basePath)
}
if handlers.GatewayRateLimit != nil {
registerGatewayRateLimitRoutes(authGroup, handlers.GatewayRateLimit, doc, basePath)
}
if handlers.PollingConcurrency != nil {
registerPollingConcurrencyRoutes(authGroup, handlers.PollingConcurrency, doc, basePath)
}

View File

@@ -0,0 +1,72 @@
package routes
import (
"github.com/gofiber/fiber/v2"
"github.com/break/junhong_cmp_fiber/internal/handler/admin"
"github.com/break/junhong_cmp_fiber/internal/model/dto"
"github.com/break/junhong_cmp_fiber/pkg/openapi"
)
// registerGatewayRateLimitRoutes 注册运营商账户网关限流、错误分类、停复机记录与调用统计路由。
func registerGatewayRateLimitRoutes(router fiber.Router, handler *admin.GatewayRateLimitHandler, doc *openapi.Generator, basePath string) {
tags := []string{"网关限流"}
groups := router.Group("/polling-rate-limit-groups")
groupsPath := basePath + "/polling-rate-limit-groups"
Register(groups, doc, groupsPath, "GET", "", handler.ListGroups, RouteSpec{
Summary: "查询网关限流组列表", Tags: tags, Input: new(dto.RateLimitGroupListRequest), Output: new(dto.RateLimitGroupPageResult), Auth: true,
})
Register(groups, doc, groupsPath, "POST", "", handler.CreateGroup, RouteSpec{
Summary: "新建网关限流组(仅超级管理员)", Tags: tags, Input: new(dto.SaveRateLimitGroupRequest), Output: new(dto.RateLimitGroupResponse), Auth: true,
})
Register(groups, doc, groupsPath, "GET", "/:id", handler.GetGroup, RouteSpec{
Summary: "查询网关限流组详情", Tags: tags, Input: new(dto.IDReq), Output: new(dto.RateLimitGroupResponse), Auth: true,
})
Register(groups, doc, groupsPath, "PUT", "/:id", handler.UpdateGroup, RouteSpec{
Summary: "修改网关限流组(仅超级管理员)", Tags: tags, Input: new(dto.UpdateRateLimitGroupParams), Output: new(dto.RateLimitGroupResponse), Auth: true,
})
Register(groups, doc, groupsPath, "PUT", "/:id/status", handler.UpdateGroupStatus, RouteSpec{
Summary: "启停网关限流组(仅超级管理员)", Tags: tags, Input: new(dto.UpdateRateLimitGroupStatusRequest), Output: nil, Auth: true,
})
Register(groups, doc, groupsPath, "DELETE", "/:id", handler.DeleteGroup, RouteSpec{
Summary: "删除网关限流组(仅超级管理员)", Tags: tags, Input: new(dto.IDReq), Output: nil, Auth: true,
})
rules := router.Group("/gateway-error-classifications")
rulesPath := basePath + "/gateway-error-classifications"
Register(rules, doc, rulesPath, "GET", "", handler.ListRules, RouteSpec{
Summary: "查询上游错误分类规则列表", Tags: tags, Input: new(dto.GatewayErrorRuleListRequest), Output: new(dto.GatewayErrorRulePageResult), Auth: true,
})
Register(rules, doc, rulesPath, "POST", "", handler.CreateRule, RouteSpec{
Summary: "新建上游错误分类规则(仅超级管理员)", Tags: tags, Input: new(dto.SaveGatewayErrorRuleRequest), Output: new(dto.GatewayErrorRuleResponse), Auth: true,
})
Register(rules, doc, rulesPath, "POST", "/test", handler.TestRule, RouteSpec{
Summary: "测试上游错误分类(不写数据)", Tags: tags, Input: new(dto.TestGatewayErrorRuleRequest), Output: new(dto.TestGatewayErrorRuleResponse), Auth: true,
})
Register(rules, doc, rulesPath, "PUT", "/:id", handler.UpdateRule, RouteSpec{
Summary: "修改上游错误分类规则(仅超级管理员)", Tags: tags, Input: new(dto.UpdateGatewayErrorRuleParams), Output: new(dto.GatewayErrorRuleResponse), Auth: true,
})
Register(rules, doc, rulesPath, "PUT", "/:id/status", handler.UpdateRuleStatus, RouteSpec{
Summary: "启停上游错误分类规则(仅超级管理员)", Tags: tags, Input: new(dto.UpdateGatewayErrorRuleStatusRequest), Output: nil, Auth: true,
})
Register(rules, doc, rulesPath, "DELETE", "/:id", handler.DeleteRule, RouteSpec{
Summary: "删除上游错误分类规则(仅超级管理员)", Tags: tags, Input: new(dto.IDReq), Output: nil, Auth: true,
})
Register(router, doc, basePath, "GET", "/card-stop-resume-records", handler.ListStopResumeRecords, RouteSpec{
Summary: "查询停复机记录(时间范围必填,跨度不超过 31 天)", Tags: tags, Input: new(dto.StopResumeRecordListRequest), Output: new(dto.StopResumeRecordPageResult), Auth: true,
})
Register(router, doc, basePath, "GET", "/iot-cards/:id/stop-resume-records", handler.ListCardStopResumeRecords, RouteSpec{
Summary: "查询单卡停复机历史", Tags: tags, Input: new(dto.CardStopResumeRecordListRequest), Output: new(dto.StopResumeRecordPageResult), Auth: true,
})
Register(router, doc, basePath, "GET", "/polling-stats/carriers", handler.CarrierCallStats, RouteSpec{
Summary: "按运营商账户汇总网关调用", Tags: tags, Input: new(dto.GatewayCallStatsRequest), Output: new(dto.GatewayCallStatsResponse), Auth: true,
})
Register(router, doc, basePath, "GET", "/polling-stats/carriers/:carrier_id/trend", handler.CarrierCallTrend, RouteSpec{
Summary: "查询单个运营商账户的网关调用趋势", Tags: tags, Input: new(dto.GatewayCallTrendRequest), Output: new(dto.GatewayCallTrendResponse), Auth: true,
})
Register(router, doc, basePath, "GET", "/polling-options", handler.PollingOptions, RouteSpec{
Summary: "查询轮询与网关限流枚举", Tags: tags, Input: nil, Output: new(dto.PollingOptionsResponse), Auth: true,
})
}

View File

@@ -653,6 +653,8 @@ func flexIntPtr(fi gateway.FlexInt) *int {
// Refresh 刷新资产数据(调网关同步)
func (s *Service) Refresh(ctx context.Context, assetType string, id uint) (*dto.AssetRealtimeStatusResponse, error) {
// 手动刷新是用户在页面等待结果的操作,豁免运营商账户网关限流(限流只约束自动触发的调用)。
ctx = gateway.WithRateLimitExempt(ctx, constants.RateLimitExemptManualRefresh)
switch assetType {
case "card":
card, err := s.iotCardStore.GetByID(ctx, id)

View File

@@ -15,6 +15,7 @@ import (
"github.com/break/junhong_cmp_fiber/internal/gateway"
auditinfra "github.com/break/junhong_cmp_fiber/internal/infrastructure/audit"
"github.com/break/junhong_cmp_fiber/internal/infrastructure/gatewaylimit"
"github.com/break/junhong_cmp_fiber/internal/model"
"github.com/break/junhong_cmp_fiber/internal/model/dto"
packageexpiry "github.com/break/junhong_cmp_fiber/internal/query/packageexpiry"
@@ -28,6 +29,7 @@ import (
)
type Service struct {
stopResumeRecorder *gatewaylimit.StopResumeRecorder
db *gorm.DB
redis *redis.Client
deviceStore *postgres.DeviceStore
@@ -1440,7 +1442,9 @@ func (s *Service) StopDevice(ctx context.Context, deviceID uint) (*dto.DeviceSus
log.Info("调用网关停机(设备)",
zap.Uint("device_id", deviceID),
zap.String("iccid", card.ICCID))
gwErr := s.gatewayClient.StopCard(gateway.WithAttemptObserver(ctx, observer), &gateway.CardOperationReq{CardNo: card.ICCID})
callStartedAt := time.Now()
gwErr := s.gatewayClient.StopCard(gateway.WithCarrier(gateway.WithAttemptObserver(ctx, observer), card.CarrierID), &gateway.CardOperationReq{CardNo: card.ICCID})
s.recordCardCommand(ctx, card, constants.StopResumeActionStop, constants.StopReasonManual, gwErr, time.Since(callStartedAt))
integrationID = observer.integration
if gwErr != nil {
log.Error("设备停机-调网关停机失败",
@@ -1601,7 +1605,9 @@ func (s *Service) StartDevice(ctx context.Context, deviceID uint) error {
log.Info("调用网关复机(设备)",
zap.Uint("device_id", deviceID),
zap.String("iccid", card.ICCID))
gwErr := s.gatewayClient.StartCard(gateway.WithAttemptObserver(ctx, observer), &gateway.CardOperationReq{CardNo: card.ICCID})
callStartedAt := time.Now()
gwErr := s.gatewayClient.StartCard(gateway.WithCarrier(gateway.WithAttemptObserver(ctx, observer), card.CarrierID), &gateway.CardOperationReq{CardNo: card.ICCID})
s.recordCardCommand(ctx, card, constants.StopResumeActionStart, "", gwErr, time.Since(callStartedAt))
integrationID = observer.integration
if gwErr != nil {
log.Error("设备复机-调网关复机失败",
@@ -1757,3 +1763,24 @@ func (s *Service) updateCardAndAppendNetworkSeries(
})
})
}
// SetStopResumeRecorder 注入停复机记录写入器;设备停复机每次上游调用写一条记录。
func (s *Service) SetStopResumeRecorder(recorder *gatewaylimit.StopResumeRecorder) {
s.stopResumeRecorder = recorder
}
// recordCardCommand 写设备下单卡的停复机记录;停复机只发一次请求,尝试序号恒为 1。
func (s *Service) recordCardCommand(ctx context.Context, card *model.IotCard, action, reason string, callErr error, duration time.Duration) {
if s.stopResumeRecorder == nil || card == nil {
return
}
source := gateway.RateLimitExemptSource(ctx)
if source == "" {
source = constants.AuditSourceWorker
}
s.stopResumeRecorder.Record(ctx, gatewaylimit.StopResumeRecordInput{
CardID: card.ID, ICCID: card.ICCID, CarrierID: card.CarrierID, Action: action,
Source: source, Scene: "device_command", Reason: reason, CommandID: deviceCommandSeriesKey(ctx),
Attempt: 1, CallErr: callErr, Duration: duration,
})
}

View File

@@ -8,7 +8,9 @@ import (
"github.com/google/uuid"
"gorm.io/gorm"
"github.com/break/junhong_cmp_fiber/internal/gateway"
"github.com/break/junhong_cmp_fiber/internal/infrastructure/audit"
"github.com/break/junhong_cmp_fiber/internal/infrastructure/gatewaylimit"
"github.com/break/junhong_cmp_fiber/internal/infrastructure/integrationlog"
"github.com/break/junhong_cmp_fiber/internal/model"
assetAuditSvc "github.com/break/junhong_cmp_fiber/internal/service/asset_audit"
@@ -25,6 +27,9 @@ func (s *StopResumeService) appendCardCommandAudit(
beforeData, afterData map[string]any,
businessErr error,
) error {
if !commandAuditRequired(ctx, actionCode, result) {
return nil
}
if s.auditWriter == nil || card == nil || card.ID == 0 {
return errors.New(errors.CodeInvalidStatus, "IoT 卡停复机统一审计接缝未配置或资源不完整")
}
@@ -62,6 +67,9 @@ func (s *StopResumeService) recordCardCommandAudit(
beforeData, afterData map[string]any,
businessErr error,
) {
if !commandAuditRequired(ctx, actionCode, result) {
return
}
if s.db == nil || s.auditWriter == nil || card == nil || card.ID == 0 {
recordCardAuditSecondaryFailure(ctx, actionCode, cardID(card), businessErr,
errors.New(errors.CodeInvalidStatus, "IoT 卡停复机统一审计接缝未配置"))
@@ -74,6 +82,49 @@ func (s *StopResumeService) recordCardCommandAudit(
}
}
// legacyCommandLogging 判断本次停复机是否沿用统一审计与集成日志:
// 带限流豁免标记的入口(后台人工点击、通道阈值、自动续费)与账户、个人客户、OpenAPI 发起的操作沿用;
// 系统自动停复机(轮询、Outbox、激活、重置、退款等系统任务)只写停复机记录(add-carrier-gateway-rate-limit)。
// 通道阈值与自动续费的恢复扫描依赖集成日志标识,因此必须沿用。
func legacyCommandLogging(ctx context.Context) bool {
if gateway.RateLimitExemptSource(ctx) != "" {
return true
}
switch auditcontext.From(ctx).ActorKind {
case constants.AuditActorAccount, constants.AuditActorPersonalCustomer, constants.AuditActorOpenAPI:
return true
default:
return false
}
}
// commandAuditRequired 判断停复机命令结果是否写统一审计:系统自动停复机的成功、失败与结果未知改由停复机记录承载;
// 被拒绝(未调用上游)与非停复机命令的审计保持不变。
func commandAuditRequired(ctx context.Context, actionCode, result string) bool {
if legacyCommandLogging(ctx) || result == constants.AuditResultDenied {
return true
}
switch actionCode {
case constants.AuditActionIotCardAutoStopped, constants.AuditActionIotCardAutoStarted,
constants.AuditActionIotCardManualStopped, constants.AuditActionIotCardManualStarted,
constants.AuditActionIotCardOpenAPIStarted:
return false
default:
return true
}
}
// commandSource 返回停复机记录的来源:豁免来源优先,其次审计来源。
func commandSource(ctx context.Context) string {
if source := gateway.RateLimitExemptSource(ctx); source != "" {
return source
}
if source := auditcontext.From(ctx).Source; source != "" {
return source
}
return constants.AuditSourceWorker
}
func cardID(card *model.IotCard) uint {
if card == nil {
return 0
@@ -191,6 +242,10 @@ type cardCommandAttemptObserver struct {
operation string
scene string
seriesKey string
action string // constants.StopResumeActionStop / StopResumeActionStart
reason string // 停机原因(复机为空)
legacy bool // 是否沿用集成日志(见 legacyCommandLogging)
startedAt time.Time
nextAttempt int
current *gatewayAttempt
successful *gatewayAttempt
@@ -203,6 +258,13 @@ type cardCommandAttemptObserver struct {
func (o *cardCommandAttemptObserver) BeforeAttempt(ctx context.Context, _ int) error {
o.nextAttempt++
o.lastCallErr = nil
o.startedAt = time.Now()
if !o.legacy {
// 系统自动停复机不再写集成日志,只在尝试结束后写停复机记录。
o.current = nil
o.lastIntegrationID = ""
return nil
}
attempt, err := o.service.startCardCommandAttempt(ctx, o.card, o.operation, o.scene, o.seriesKey, o.nextAttempt)
if err != nil {
o.recordingErr = err
@@ -218,6 +280,10 @@ func (o *cardCommandAttemptObserver) AfterAttempt(ctx context.Context, _ int, ca
if isGatewayTimeout(callErr) {
o.unknown = true
}
o.service.recordStopResumeAttempt(ctx, o, callErr)
if !o.legacy {
return nil
}
if callErr == nil {
o.successful = o.current
o.current = nil
@@ -237,3 +303,15 @@ func (o *cardCommandAttemptObserver) auditResult(lastErr error) string {
}
return cardCommandAuditResult(lastErr)
}
// recordStopResumeAttempt 每次实际调用上游停机或复机后写一条停复机记录,写入失败不影响业务回写。
func (s *StopResumeService) recordStopResumeAttempt(ctx context.Context, o *cardCommandAttemptObserver, callErr error) {
if s.stopResumeRecorder == nil || o == nil || o.card == nil {
return
}
s.stopResumeRecorder.Record(ctx, gatewaylimit.StopResumeRecordInput{
CardID: o.card.ID, ICCID: o.card.ICCID, CarrierID: o.card.CarrierID, Action: o.action,
Source: commandSource(ctx), Scene: o.scene, Reason: o.reason, CommandID: o.seriesKey,
Attempt: o.nextAttempt, CallErr: callErr, Duration: time.Since(o.startedAt),
})
}

View File

@@ -16,6 +16,7 @@ import (
"github.com/break/junhong_cmp_fiber/internal/gateway"
"github.com/break/junhong_cmp_fiber/internal/infrastructure/audit"
"github.com/break/junhong_cmp_fiber/internal/infrastructure/gatewaylimit"
"github.com/break/junhong_cmp_fiber/internal/infrastructure/integrationlog"
"github.com/break/junhong_cmp_fiber/internal/model"
packagepkg "github.com/break/junhong_cmp_fiber/internal/service/package"
@@ -61,6 +62,13 @@ type StopResumeService struct {
retryInterval time.Duration
// channelThresholdGuard 是可选的通道阈值持锁判定能力;未注入时不做持锁拒绝。
channelThresholdGuard ChannelThresholdLockGuard
// stopResumeRecorder 写每次上游停复机调用的停复机记录;未注入时不写。
stopResumeRecorder *gatewaylimit.StopResumeRecorder
}
// SetStopResumeRecorder 注入停复机记录写入器。
func (s *StopResumeService) SetStopResumeRecorder(recorder *gatewaylimit.StopResumeRecorder) {
s.stopResumeRecorder = recorder
}
// SetObservationSeriesEventWriter 注入停复机成功观测序列 Outbox Writer。
@@ -717,8 +725,9 @@ func (s *StopResumeService) stopCardWithRetry(ctx context.Context, card *model.I
attemptObserver := &cardCommandAttemptObserver{
service: s, card: card, operation: constants.IntegrationOperationGatewayStopCard,
scene: constants.CardObservationSceneBusinessStop, seriesKey: seriesKey,
action: constants.StopResumeActionStop, reason: stopReason, legacy: legacyCommandLogging(ctx),
}
gatewayCtx := gateway.WithAttemptObserver(ctx, attemptObserver)
gatewayCtx := gateway.WithCarrier(gateway.WithAttemptObserver(ctx, attemptObserver), card.CarrierID)
var lastErr error
lastIntegrationID := ""
for i := 0; i < s.maxRetries; i++ {
@@ -730,6 +739,11 @@ func (s *StopResumeService) stopCardWithRetry(ctx context.Context, card *model.I
}
callErr := s.gatewayClient.StopCard(gatewayCtx, &gateway.CardOperationReq{CardNo: card.ICCID})
if gateway.IsRateLimited(callErr) {
// 被运营商账户限流拒绝时请求并未发出:不重试、不写失败审计,由调用方的既有重试或兜底路径稍后处理。
s.logger.Warn("停机被运营商账户网关限流,本次不调用上游", zap.Uint("card_id", card.ID), zap.String("iccid", card.ICCID))
return carrierthresholddomain.CommandOutcome{Result: constants.AuditResultFailed}, callErr
}
lastIntegrationID = attemptObserver.lastIntegrationID
if attemptObserver.recordingErr != nil {
s.logger.Error("记录停机 Integration Log 失败", zap.String("integration_id", lastIntegrationID), zap.Error(attemptObserver.recordingErr))
@@ -818,8 +832,9 @@ func (s *StopResumeService) resumeCardWithRetry(ctx context.Context, card *model
attemptObserver := &cardCommandAttemptObserver{
service: s, card: card, operation: constants.IntegrationOperationGatewayStartCard,
scene: constants.CardObservationSceneBusinessResume, seriesKey: seriesKey,
action: constants.StopResumeActionStart, legacy: legacyCommandLogging(ctx),
}
gatewayCtx := gateway.WithAttemptObserver(ctx, attemptObserver)
gatewayCtx := gateway.WithCarrier(gateway.WithAttemptObserver(ctx, attemptObserver), card.CarrierID)
var lastErr error
lastIntegrationID := ""
for i := 0; i < s.maxRetries; i++ {
@@ -835,6 +850,11 @@ func (s *StopResumeService) resumeCardWithRetry(ctx context.Context, card *model
req.Extend = constants.GatewayCardStartExtendMachineSeparated
}
callErr := s.gatewayClient.StartCard(gatewayCtx, req)
if gateway.IsRateLimited(callErr) {
// 被运营商账户限流拒绝时请求并未发出:不重试、不写失败审计,由调用方的既有重试或兜底路径稍后处理。
s.logger.Warn("复机被运营商账户网关限流,本次不调用上游", zap.Uint("card_id", card.ID), zap.String("iccid", card.ICCID))
return nil, "", callErr
}
lastIntegrationID = attemptObserver.lastIntegrationID
if attemptObserver.recordingErr != nil {
s.logger.Error("记录复机 Integration Log 失败", zap.String("integration_id", lastIntegrationID), zap.Error(attemptObserver.recordingErr))

View File

@@ -0,0 +1,366 @@
package polling
import (
"context"
"sort"
"strconv"
"strings"
"time"
"github.com/redis/go-redis/v9"
"github.com/break/junhong_cmp_fiber/internal/model"
"github.com/break/junhong_cmp_fiber/internal/model/dto"
"github.com/break/junhong_cmp_fiber/internal/store/postgres"
"github.com/break/junhong_cmp_fiber/pkg/constants"
"github.com/break/junhong_cmp_fiber/pkg/errors"
)
// 分钟计数 Hash 字段(与 gatewaylimit.Guard 写入口径一致)。
const (
statAttempts = "attempts"
statDurationSum = "duration_ms_sum"
statWouldLimit = "would_limit"
statPrefixDur = "duration_le:"
statPrefixExem = "exempt:"
statPrefixUp = "upstream:"
)
// statDurationBuckets 与写入端分桶上界一致(毫秒)。
var statDurationBuckets = []string{"100", "300", "500", "1000", "3000", "10000", "60000", "inf"}
// ListStopResumeRecords 按条件查询停复机记录;时间范围必填且跨度不超过 31 天。
func (s *GatewayRateLimitService) ListStopResumeRecords(ctx context.Context, req *dto.StopResumeRecordListRequest) (*dto.StopResumeRecordPageResult, error) {
if err := requirePlatformReader(ctx); err != nil {
return nil, err
}
if req.StartTime.IsZero() || req.EndTime.IsZero() {
return nil, errors.New(errors.CodeInvalidParam, "停复机记录查询参数不合法:开始时间与结束时间必填")
}
if !req.EndTime.After(req.StartTime) || req.EndTime.Sub(req.StartTime) > time.Duration(constants.StopResumeRecordQueryMaxDays)*24*time.Hour {
return nil, errors.New(errors.CodeInvalidParam, "停复机记录查询参数不合法:时间跨度须大于 0 且不超过 31 天")
}
page, size := normalizePage(req.Page, req.PageSize)
return s.listRecords(ctx, postgres.StopResumeRecordFilter{
ICCID: strings.TrimSpace(req.ICCID), CarrierID: req.CarrierID, Action: req.Action, Source: req.Source,
Result: req.Result, ErrorCategory: req.ErrorCategory, StartTime: req.StartTime, EndTime: req.EndTime,
Page: page, PageSize: size,
})
}
// ListCardStopResumeRecords 查询单卡停复机历史;未传时间默认最近 31 天。
func (s *GatewayRateLimitService) ListCardStopResumeRecords(ctx context.Context, req *dto.CardStopResumeRecordListRequest) (*dto.StopResumeRecordPageResult, error) {
if err := requirePlatformReader(ctx); err != nil {
return nil, err
}
var count int64
if err := s.db.WithContext(ctx).Model(&model.IotCard{}).Where("id = ?", req.ID).Count(&count).Error; err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询 IoT 卡失败")
}
if count == 0 {
return nil, errors.New(errors.CodeNotFound, "IoT 卡不存在")
}
end := req.EndTime
if end.IsZero() {
end = time.Now()
}
start := req.StartTime
if start.IsZero() {
start = end.AddDate(0, 0, -constants.StopResumeRecordQueryMaxDays)
}
if !end.After(start) || end.Sub(start) > time.Duration(constants.StopResumeRecordQueryMaxDays)*24*time.Hour {
return nil, errors.New(errors.CodeInvalidParam, "停复机记录查询参数不合法:时间跨度须大于 0 且不超过 31 天")
}
page, size := normalizePage(req.Page, req.PageSize)
cardID := req.ID
return s.listRecords(ctx, postgres.StopResumeRecordFilter{CardID: &cardID, StartTime: start, EndTime: end, Page: page, PageSize: size})
}
func (s *GatewayRateLimitService) listRecords(ctx context.Context, filter postgres.StopResumeRecordFilter) (*dto.StopResumeRecordPageResult, error) {
rows, total, err := postgres.NewCardStopResumeRecordStore(s.db).List(ctx, filter)
if err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询停复机记录失败")
}
items := make([]dto.StopResumeRecordResponse, 0, len(rows))
for _, row := range rows {
items = append(items, dto.StopResumeRecordResponse{
ID: row.ID, CardID: row.CardID, ICCID: row.ICCID, CarrierID: row.CarrierID, Action: row.Action,
ActionName: stopResumeActionName(row.Action), Source: row.Source, Scene: row.Scene, Reason: row.Reason,
CommandID: row.CommandID, Attempt: row.Attempt, Result: row.Result, ErrorCategory: row.ErrorCategory,
ErrorCategoryName: errorCategoryName(row.ErrorCategory), ProviderCode: row.ProviderCode,
ProviderMessage: row.ProviderMessage, DurationMS: row.DurationMS, CreatedAt: row.CreatedAt,
})
}
return &dto.StopResumeRecordPageResult{List: items, Total: total, Page: filter.Page, PageSize: filter.PageSize}, nil
}
// CarrierCallStats 汇总最近若干分钟各运营商账户的网关调用(只返回有调用的账户)。
func (s *GatewayRateLimitService) CarrierCallStats(ctx context.Context, redisClient *redis.Client, req *dto.GatewayCallStatsRequest) (*dto.GatewayCallStatsResponse, error) {
if err := requirePlatformReader(ctx); err != nil {
return nil, err
}
minutes := req.Minutes
if minutes <= 0 {
minutes = 15
}
names, err := s.carrierNames(ctx)
if err != nil {
return nil, err
}
carrierIDs := []uint{0}
for id := range names {
carrierIDs = append(carrierIDs, id)
}
sort.Slice(carrierIDs, func(i, j int) bool { return carrierIDs[i] < carrierIDs[j] })
stamps := minuteStamps(time.Now(), minutes)
data, err := loadStatHashes(ctx, redisClient, carrierIDs, stamps)
if err != nil {
return nil, err
}
resp := &dto.GatewayCallStatsResponse{Mode: s.currentMode(ctx), Minutes: minutes, Carriers: []dto.GatewayCarrierStat{}}
for _, carrierID := range carrierIDs {
var ops []dto.GatewayOperationStat
for _, op := range constants.GatewayCardOperations {
stat := aggregateOperation(op, data[statKey{carrierID, op}], len(stamps))
if stat.Attempts > 0 || stat.RateLimited > 0 || stat.WouldLimit > 0 {
ops = append(ops, stat)
}
}
if len(ops) == 0 {
continue
}
name := names[carrierID]
if carrierID == 0 {
name = "未知账户"
}
resp.Carriers = append(resp.Carriers, dto.GatewayCarrierStat{CarrierID: carrierID, CarrierName: name, Operations: ops})
}
return resp, nil
}
// CarrierCallTrend 返回单个运营商账户按时间桶聚合的网关调用趋势。
func (s *GatewayRateLimitService) CarrierCallTrend(ctx context.Context, redisClient *redis.Client, req *dto.GatewayCallTrendRequest) (*dto.GatewayCallTrendResponse, error) {
if err := requirePlatformReader(ctx); err != nil {
return nil, err
}
minutes, bucket := req.Minutes, req.BucketMinutes
if minutes <= 0 {
minutes = 60
}
if bucket <= 0 {
bucket = 1
}
stamps := minuteStamps(time.Now(), minutes)
data, err := loadStatHashes(ctx, redisClient, []uint{req.CarrierID}, stamps)
if err != nil {
return nil, err
}
resp := &dto.GatewayCallTrendResponse{CarrierID: req.CarrierID, Points: []dto.GatewayCallTrendPoint{}}
for start := 0; start < len(stamps); start += bucket {
end := start + bucket
if end > len(stamps) {
end = len(stamps)
}
point := dto.GatewayCallTrendPoint{Time: formatStamp(stamps[start]), Operations: []dto.GatewayOperationStat{}}
for _, op := range constants.GatewayCardOperations {
series := data[statKey{req.CarrierID, op}]
if series == nil {
continue
}
stat := aggregateOperation(op, series[start:end], end-start)
if stat.Attempts > 0 || stat.RateLimited > 0 || stat.WouldLimit > 0 {
point.Operations = append(point.Operations, stat)
}
}
resp.Points = append(resp.Points, point)
}
return resp, nil
}
func (s *GatewayRateLimitService) currentMode(ctx context.Context) string {
if s.runtime == nil {
return constants.RateLimitModeObserve
}
return s.runtime.Settings.Current(ctx).Mode
}
type statKey struct {
carrierID uint
op string
}
// minuteStamps 返回从最早到最近的分钟标识(上海时区 yyyyMMddHHmm)。
func minuteStamps(now time.Time, minutes int) []string {
location := shanghaiLocation()
current := now.In(location).Truncate(time.Minute)
stamps := make([]string, minutes)
for i := 0; i < minutes; i++ {
stamps[minutes-1-i] = current.Add(-time.Duration(i) * time.Minute).Format("200601021504")
}
return stamps
}
func formatStamp(stamp string) string {
t, err := time.ParseInLocation("200601021504", stamp, shanghaiLocation())
if err != nil {
return stamp
}
return t.Format("2006-01-02 15:04")
}
// loadStatHashes 用管道批量读取分钟计数;返回每个账户 × 操作按分钟顺序的 Hash 列表。
func loadStatHashes(ctx context.Context, redisClient *redis.Client, carrierIDs []uint, stamps []string) (map[statKey][]map[string]string, error) {
result := map[statKey][]map[string]string{}
if redisClient == nil {
return result, nil
}
type pending struct {
key statKey
idx int
cmd *redis.MapStringStringCmd
}
pipe := redisClient.Pipeline()
cmds := make([]pending, 0, len(carrierIDs)*len(constants.GatewayCardOperations)*len(stamps))
for _, carrierID := range carrierIDs {
for _, op := range constants.GatewayCardOperations {
key := statKey{carrierID, op}
result[key] = make([]map[string]string, len(stamps))
for idx, stamp := range stamps {
cmds = append(cmds, pending{key: key, idx: idx, cmd: pipe.HGetAll(ctx, constants.RedisGatewayCallStatKey(carrierID, op, stamp))})
}
}
}
if _, err := pipe.Exec(ctx); err != nil && err != redis.Nil {
return nil, errors.Wrap(errors.CodeRedisError, err, "读取网关调用统计失败")
}
for _, item := range cmds {
values, err := item.cmd.Result()
if err == nil && len(values) > 0 {
result[item.key][item.idx] = values
}
}
return result, nil
}
// aggregateOperation 汇总一个操作在若干分钟内的计数。
func aggregateOperation(op string, minutes []map[string]string, minuteCount int) dto.GatewayOperationStat {
stat := dto.GatewayOperationStat{Operation: op, OperationName: constants.GatewayOperationName(op), Failures: map[string]int64{}, Exempt: map[string]int64{}}
buckets := map[string]int64{}
var durationSum int64
for _, values := range minutes {
var minuteAttempts int64
for field, raw := range values {
value, err := strconv.ParseInt(raw, 10, 64)
if err != nil {
continue
}
switch {
case field == statAttempts:
stat.Attempts += value
minuteAttempts = value
case field == statDurationSum:
durationSum += value
case field == statWouldLimit:
stat.WouldLimit += value
case field == constants.GatewayErrorRateLimited:
stat.RateLimited += value
case field == constants.GatewayResultSuccess:
stat.Success += value
case strings.HasPrefix(field, statPrefixDur):
buckets[strings.TrimPrefix(field, statPrefixDur)] += value
case strings.HasPrefix(field, statPrefixExem):
stat.Exempt[strings.TrimPrefix(field, statPrefixExem)] += value
default:
stat.Failures[field] += value
}
}
if qps := float64(minuteAttempts) / 60; qps > stat.PeakMinuteQPS {
stat.PeakMinuteQPS = qps
}
}
if minuteCount > 0 {
stat.AvgQPS = float64(stat.Attempts) / float64(minuteCount*60)
}
if stat.Attempts > 0 {
stat.SuccessRate = float64(stat.Success) / float64(stat.Attempts)
stat.AvgDurationMS = float64(durationSum) / float64(stat.Attempts)
stat.P95DurationMS = percentileBucket(buckets, stat.Attempts, 0.95)
}
return stat
}
// percentileBucket 返回累计占比达到 p 的分桶上界;落在最后一个分桶时返回 -1。
func percentileBucket(buckets map[string]int64, total int64, p float64) int64 {
threshold := int64(float64(total)*p + 0.5)
var cumulative int64
for _, upper := range statDurationBuckets {
cumulative += buckets[upper]
if cumulative >= threshold {
if upper == "inf" {
return -1
}
value, _ := strconv.ParseInt(upper, 10, 64)
return value
}
}
return -1
}
func shanghaiLocation() *time.Location {
location, err := time.LoadLocation("Asia/Shanghai")
if err != nil {
return time.FixedZone("CST", 8*3600)
}
return location
}
func stopResumeActionName(action string) string {
if action == constants.StopResumeActionStart {
return "复机"
}
return "停机"
}
func errorCategoryName(category string) string {
switch category {
case "":
return ""
case constants.GatewayErrorNetwork:
return "网络错误"
case constants.GatewayErrorTimeout:
return "请求超时"
case constants.GatewayErrorHTTP:
return "HTTP 异常"
case constants.GatewayErrorInvalidResponse:
return "响应无效"
default:
return constants.GatewayErrorClassName(category)
}
}
// PollingOptions 返回轮询与网关限流相关的前端枚举,前端不写死取值。
func (s *GatewayRateLimitService) PollingOptions(ctx context.Context) (*dto.PollingOptionsResponse, error) {
if err := requirePlatformReader(ctx); err != nil {
return nil, err
}
resp := &dto.PollingOptionsResponse{}
for _, op := range constants.GatewayCardOperations {
resp.GatewayOperations = append(resp.GatewayOperations, dto.PollingOptionItem{Value: op, Label: constants.GatewayOperationName(op)})
}
for _, class := range constants.GatewayErrorClasses {
resp.ErrorCategories = append(resp.ErrorCategories, dto.PollingOptionItem{Value: class, Label: constants.GatewayErrorClassName(class)})
}
resp.MatchTypes = []dto.PollingOptionItem{{Value: constants.GatewayMatchContains, Label: "包含"}, {Value: constants.GatewayMatchPrefix, Label: "前缀"}, {Value: constants.GatewayMatchRegex, Label: "正则"}}
resp.RateLimitModes = []dto.PollingOptionItem{{Value: constants.RateLimitModeObserve, Label: "只统计不拦截"}, {Value: constants.RateLimitModeEnforce, Label: "拦截"}}
resp.ExemptSources = []dto.PollingOptionItem{
{Value: constants.RateLimitExemptManualClick, Label: "后台人工点击"}, {Value: constants.RateLimitExemptChannelThreshold, Label: "通道阈值"},
{Value: constants.RateLimitExemptAutoRenewal, Label: "自动续费"}, {Value: constants.RateLimitExemptManualRefresh, Label: "手动刷新"},
}
resp.StopResumeResults = []dto.PollingOptionItem{
{Value: constants.StopResumeRecordSuccess, Label: "成功"}, {Value: constants.StopResumeRecordFailed, Label: "失败"},
{Value: constants.StopResumeRecordUnknown, Label: "结果未知"}, {Value: constants.StopResumeRecordAlreadyTarget, Label: "已是目标状态"},
{Value: constants.StopResumeRecordSkipped, Label: "跳过"},
}
resp.StopResumeActions = []dto.PollingOptionItem{{Value: constants.StopResumeActionStop, Label: "停机"}, {Value: constants.StopResumeActionStart, Label: "复机"}}
return resp, nil
}

View File

@@ -0,0 +1,638 @@
package polling
import (
"context"
"regexp"
"sort"
"strconv"
"strings"
"github.com/bytedance/sonic"
"gorm.io/datatypes"
"gorm.io/gorm"
auditinfra "github.com/break/junhong_cmp_fiber/internal/infrastructure/audit"
"github.com/break/junhong_cmp_fiber/internal/infrastructure/gatewaylimit"
"github.com/break/junhong_cmp_fiber/internal/model"
"github.com/break/junhong_cmp_fiber/internal/model/dto"
"github.com/break/junhong_cmp_fiber/internal/store/postgres"
"github.com/break/junhong_cmp_fiber/pkg/constants"
"github.com/break/junhong_cmp_fiber/pkg/errors"
"github.com/break/junhong_cmp_fiber/pkg/middleware"
)
// GatewayRateLimitService 维护运营商账户网关限流组与上游错误分类规则(后台配置,简单写事务脚本)。
// 读取仅超级管理员与平台用户可用;修改仅超级管理员可用,并在同一事务写统一审计。
type GatewayRateLimitService struct {
db *gorm.DB
auditWriter *auditinfra.Writer
groups *postgres.CarrierRateLimitGroupStore
rules *postgres.GatewayErrorClassificationStore
runtime *gatewaylimit.Runtime
}
// NewGatewayRateLimitService 创建网关限流配置服务。
func NewGatewayRateLimitService(db *gorm.DB, auditWriter *auditinfra.Writer, runtime *gatewaylimit.Runtime) *GatewayRateLimitService {
return &GatewayRateLimitService{
db: db, auditWriter: auditWriter, runtime: runtime,
groups: postgres.NewCarrierRateLimitGroupStore(db), rules: postgres.NewGatewayErrorClassificationStore(db),
}
}
// requirePlatformReader 校验读取权限:超级管理员或平台用户。
func requirePlatformReader(ctx context.Context) error {
switch middleware.GetUserTypeFromContext(ctx) {
case constants.UserTypeSuperAdmin, constants.UserTypePlatform:
return nil
default:
return errors.New(errors.CodeForbidden, "仅平台账号可查看网关限流配置")
}
}
// requireSuperAdminWriter 校验修改权限:仅超级管理员,返回操作者 ID。
func requireSuperAdminWriter(ctx context.Context) (uint, error) {
if middleware.GetUserTypeFromContext(ctx) != constants.UserTypeSuperAdmin {
return 0, errors.New(errors.CodeForbidden, "仅超级管理员可修改网关限流配置")
}
operatorID := middleware.GetUserIDFromContext(ctx)
if operatorID == 0 {
return 0, errors.New(errors.CodeUnauthorized, "未授权访问")
}
return operatorID, nil
}
func normalizePage(page, size int) (int, int) {
if page < 1 {
page = 1
}
if size < 1 {
size = 20
}
if size > 100 {
size = 100
}
return page, size
}
// ListGroups 分页查询限流组。
func (s *GatewayRateLimitService) ListGroups(ctx context.Context, req *dto.RateLimitGroupListRequest) (*dto.RateLimitGroupPageResult, error) {
if err := requirePlatformReader(ctx); err != nil {
return nil, err
}
page, size := normalizePage(req.Page, req.PageSize)
rows, total, err := s.groups.List(ctx, postgres.RateLimitGroupFilter{CarrierID: req.CarrierID, OnlyGlobal: req.OnlyGlobal, Status: req.Status, Page: page, PageSize: size})
if err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询网关限流组失败")
}
names, err := s.carrierNames(ctx)
if err != nil {
return nil, err
}
items := make([]dto.RateLimitGroupResponse, 0, len(rows))
for i := range rows {
items = append(items, toRateLimitGroupResponse(&rows[i], names))
}
return &dto.RateLimitGroupPageResult{List: items, Total: total, Page: page, PageSize: size}, nil
}
// GetGroup 查询限流组详情。
func (s *GatewayRateLimitService) GetGroup(ctx context.Context, id uint) (*dto.RateLimitGroupResponse, error) {
if err := requirePlatformReader(ctx); err != nil {
return nil, err
}
row, err := s.loadGroup(ctx, id)
if err != nil {
return nil, err
}
names, err := s.carrierNames(ctx)
if err != nil {
return nil, err
}
resp := toRateLimitGroupResponse(row, names)
return &resp, nil
}
// CreateGroup 新建限流组。
func (s *GatewayRateLimitService) CreateGroup(ctx context.Context, req *dto.SaveRateLimitGroupRequest) (*dto.RateLimitGroupResponse, error) {
operatorID, err := requireSuperAdminWriter(ctx)
if err != nil {
return nil, err
}
if err := s.validateGroup(ctx, req, 0); err != nil {
return nil, err
}
row := &model.CarrierRateLimitGroup{CarrierID: req.CarrierID, Status: constants.RateLimitGroupStatusEnabled}
applyGroupRequest(row, req)
row.Creator, row.Updater = operatorID, operatorID
err = runPollingTransaction(ctx, s.db, s.auditWriter, func(tx *gorm.DB) error {
if err := tx.WithContext(ctx).Create(row).Error; err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "新建网关限流组失败")
}
return writePollingAudit(ctx, tx, s.auditWriter, groupAudit(constants.AuditActionRateLimitGroupCreated, "创建网关限流组", row, operatorID, nil))
})
if err != nil {
return nil, err
}
s.invalidateGroups()
return s.GetGroup(ctx, row.ID)
}
// UpdateGroup 修改限流组。
func (s *GatewayRateLimitService) UpdateGroup(ctx context.Context, req *dto.SaveRateLimitGroupRequest) (*dto.RateLimitGroupResponse, error) {
operatorID, err := requireSuperAdminWriter(ctx)
if err != nil {
return nil, err
}
row, err := s.loadGroup(ctx, req.ID)
if err != nil {
return nil, err
}
if !sameCarrier(row.CarrierID, req.CarrierID) {
return nil, errors.New(errors.CodeInvalidParam, "限流组所属运营商账户不可修改,请删除后重新创建")
}
if err := s.validateGroup(ctx, req, row.ID); err != nil {
return nil, err
}
before := groupState(row)
applyGroupRequest(row, req)
row.Updater = operatorID
err = runPollingTransaction(ctx, s.db, s.auditWriter, func(tx *gorm.DB) error {
if err := tx.WithContext(ctx).Save(row).Error; err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "修改网关限流组失败")
}
return writePollingAudit(ctx, tx, s.auditWriter, groupAudit(constants.AuditActionRateLimitGroupUpdated, "更新网关限流组", row, operatorID, before))
})
if err != nil {
return nil, err
}
s.invalidateGroups()
return s.GetGroup(ctx, row.ID)
}
// UpdateGroupStatus 启停限流组;停用后组内操作回落为默认每秒请求上限。
func (s *GatewayRateLimitService) UpdateGroupStatus(ctx context.Context, id uint, status int) error {
operatorID, err := requireSuperAdminWriter(ctx)
if err != nil {
return err
}
row, err := s.loadGroup(ctx, id)
if err != nil {
return err
}
if status == constants.RateLimitGroupStatusEnabled {
ops, _ := gatewaylimit.DecodeOperations(row.Operations)
if err := s.checkOperationsFree(ctx, row.CarrierID, ops, row.ID); err != nil {
return err
}
}
before := groupState(row)
row.Status, row.Updater = status, operatorID
err = runPollingTransaction(ctx, s.db, s.auditWriter, func(tx *gorm.DB) error {
if err := tx.WithContext(ctx).Model(&model.CarrierRateLimitGroup{}).Where("id = ?", id).
Updates(map[string]any{"status": status, "updater": operatorID}).Error; err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "更新网关限流组状态失败")
}
return writePollingAudit(ctx, tx, s.auditWriter, groupAudit(constants.AuditActionRateLimitGroupStatusUpdated, "更新网关限流组状态", row, operatorID, before))
})
if err != nil {
return err
}
s.invalidateGroups()
return nil
}
// DeleteGroup 删除限流组;组内操作回落为默认每秒请求上限。
func (s *GatewayRateLimitService) DeleteGroup(ctx context.Context, id uint) error {
operatorID, err := requireSuperAdminWriter(ctx)
if err != nil {
return err
}
row, err := s.loadGroup(ctx, id)
if err != nil {
return err
}
err = runPollingTransaction(ctx, s.db, s.auditWriter, func(tx *gorm.DB) error {
if err := tx.WithContext(ctx).Delete(&model.CarrierRateLimitGroup{}, id).Error; err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "删除网关限流组失败")
}
return writePollingAudit(ctx, tx, s.auditWriter, groupAudit(constants.AuditActionRateLimitGroupDeleted, "删除网关限流组", row, operatorID, groupState(row)))
})
if err != nil {
return err
}
s.invalidateGroups()
return nil
}
func (s *GatewayRateLimitService) loadGroup(ctx context.Context, id uint) (*model.CarrierRateLimitGroup, error) {
row, err := s.groups.Get(ctx, id)
if err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询网关限流组失败")
}
if row == nil {
return nil, errors.New(errors.CodeNotFound, "网关限流组不存在")
}
return row, nil
}
// validateGroup 校验预留额度、高优先级操作归属、同账户同操作只属于一个启用组、组标识唯一。
func (s *GatewayRateLimitService) validateGroup(ctx context.Context, req *dto.SaveRateLimitGroupRequest, selfID uint) error {
if req.ReservedQPS >= req.MaxQPS {
return errors.New(errors.CodeInvalidParam, "预留额度必须小于每秒请求上限")
}
ops := uniqueStrings(req.Operations)
opSet := map[string]bool{}
for _, op := range ops {
opSet[op] = true
}
for _, op := range req.HighPriorityOperations {
if !opSet[op] {
return errors.New(errors.CodeInvalidParam, "高优先级操作必须属于组内操作:"+constants.GatewayOperationName(op))
}
}
if req.ReservedQPS > 0 && len(req.HighPriorityOperations) == 0 {
return errors.New(errors.CodeInvalidParam, "设置预留额度时必须指定高优先级操作")
}
if req.CarrierID != nil {
var count int64
if err := s.db.WithContext(ctx).Model(&model.Carrier{}).Where("id = ?", *req.CarrierID).Count(&count).Error; err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "查询运营商账户失败")
}
if count == 0 {
return errors.New(errors.CodeInvalidParam, "运营商账户不存在")
}
}
existing, err := s.groups.ListByCarrier(ctx, req.CarrierID)
if err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "查询网关限流组失败")
}
for _, row := range existing {
if row.ID != selfID && row.GroupCode == req.GroupCode {
return errors.New(errors.CodeInvalidParam, "同一运营商账户内组标识已存在")
}
}
if req.Status == nil || *req.Status == constants.RateLimitGroupStatusEnabled {
return s.checkOperationsFree(ctx, req.CarrierID, ops, selfID)
}
return nil
}
// checkOperationsFree 校验操作未被同账户其他启用组占用。
func (s *GatewayRateLimitService) checkOperationsFree(ctx context.Context, carrierID *uint, ops []string, selfID uint) error {
existing, err := s.groups.ListByCarrier(ctx, carrierID)
if err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "查询网关限流组失败")
}
for _, row := range existing {
if row.ID == selfID || row.Status != constants.RateLimitGroupStatusEnabled {
continue
}
used, _ := gatewaylimit.DecodeOperations(row.Operations)
for _, op := range used {
for _, want := range ops {
if op == want {
return errors.New(errors.CodeInvalidParam, "操作「"+constants.GatewayOperationName(op)+"」已属于限流组「"+row.GroupName+"」,同一账户下每个操作只能属于一个启用的组")
}
}
}
}
return nil
}
func applyGroupRequest(row *model.CarrierRateLimitGroup, req *dto.SaveRateLimitGroupRequest) {
row.GroupCode = strings.TrimSpace(req.GroupCode)
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))
if req.Status != nil {
row.Status = *req.Status
}
}
func groupState(row *model.CarrierRateLimitGroup) map[string]any {
ops, _ := gatewaylimit.DecodeOperations(row.Operations)
high, _ := gatewaylimit.DecodeOperations(row.HighPriorityOperations)
return map[string]any{"group_code": row.GroupCode, "group_name": row.GroupName, "max_qps": row.MaxQPS,
"reserved_qps": row.ReservedQPS, "operations": ops, "high_priority_operations": high, "status": row.Status}
}
func groupAudit(action, summary string, row *model.CarrierRateLimitGroup, operatorID uint, before map[string]any) auditinfra.PollingInput {
var carrierID any
if row.CarrierID != nil {
carrierID = *row.CarrierID
}
return auditinfra.PollingInput{
ActionCode: action, Summary: summary, ResourceType: constants.AuditResourceRateLimitGroup,
ResourceID: row.ID, ResourceKey: "rate_limit_group:" + uintString(row.ID), DisplayName: row.GroupName,
OperatorID: operatorID,
IdentitySnapshot: map[string]any{"id": row.ID, "carrier_id": carrierID, "group_code": row.GroupCode,
"group_name": row.GroupName, "max_qps": row.MaxQPS, "reserved_qps": row.ReservedQPS, "status": row.Status},
BeforeData: before, AfterData: groupState(row),
}
}
func toRateLimitGroupResponse(row *model.CarrierRateLimitGroup, names map[uint]string) dto.RateLimitGroupResponse {
ops, _ := gatewaylimit.DecodeOperations(row.Operations)
high, _ := gatewaylimit.DecodeOperations(row.HighPriorityOperations)
resp := dto.RateLimitGroupResponse{
ID: row.ID, CarrierID: row.CarrierID, GroupCode: row.GroupCode, GroupName: row.GroupName, MaxQPS: row.MaxQPS,
Operations: nonNil(ops), HighPriorityOperations: nonNil(high), ReservedQPS: row.ReservedQPS,
Status: row.Status, StatusName: enabledName(row.Status), CreatedAt: row.CreatedAt, UpdatedAt: row.UpdatedAt,
}
if row.CarrierID != nil {
resp.CarrierName = names[*row.CarrierID]
}
return resp
}
// ListRules 分页查询上游错误分类规则。
func (s *GatewayRateLimitService) ListRules(ctx context.Context, req *dto.GatewayErrorRuleListRequest) (*dto.GatewayErrorRulePageResult, error) {
if err := requirePlatformReader(ctx); err != nil {
return nil, err
}
page, size := normalizePage(req.Page, req.PageSize)
rows, total, err := s.rules.List(ctx, postgres.ErrorClassificationFilter{Category: req.Category, Status: req.Status, Keyword: strings.TrimSpace(req.Keyword), Page: page, PageSize: size})
if err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询上游错误分类规则失败")
}
items := make([]dto.GatewayErrorRuleResponse, 0, len(rows))
for i := range rows {
items = append(items, toRuleResponse(&rows[i]))
}
return &dto.GatewayErrorRulePageResult{List: items, Total: total, Page: page, PageSize: size}, nil
}
// CreateRule 新建上游错误分类规则。
func (s *GatewayRateLimitService) CreateRule(ctx context.Context, req *dto.SaveGatewayErrorRuleRequest) (*dto.GatewayErrorRuleResponse, error) {
operatorID, err := requireSuperAdminWriter(ctx)
if err != nil {
return nil, err
}
if err := validateRule(req); err != nil {
return nil, err
}
row := &model.GatewayErrorClassification{Status: constants.RateLimitGroupStatusEnabled}
applyRuleRequest(row, req)
row.Creator, row.Updater = operatorID, operatorID
err = runPollingTransaction(ctx, s.db, s.auditWriter, func(tx *gorm.DB) error {
if err := tx.WithContext(ctx).Create(row).Error; err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "新建上游错误分类规则失败")
}
return writePollingAudit(ctx, tx, s.auditWriter, ruleAudit(constants.AuditActionGatewayErrorRuleCreated, "创建上游错误分类规则", row, operatorID, nil))
})
if err != nil {
return nil, err
}
s.invalidateRules()
resp := toRuleResponse(row)
return &resp, nil
}
// UpdateRule 修改上游错误分类规则。
func (s *GatewayRateLimitService) UpdateRule(ctx context.Context, req *dto.SaveGatewayErrorRuleRequest) (*dto.GatewayErrorRuleResponse, error) {
operatorID, err := requireSuperAdminWriter(ctx)
if err != nil {
return nil, err
}
if err := validateRule(req); err != nil {
return nil, err
}
row, err := s.loadRule(ctx, req.ID)
if err != nil {
return nil, err
}
before := ruleState(row)
applyRuleRequest(row, req)
row.Updater = operatorID
err = runPollingTransaction(ctx, s.db, s.auditWriter, func(tx *gorm.DB) error {
if err := tx.WithContext(ctx).Save(row).Error; err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "修改上游错误分类规则失败")
}
return writePollingAudit(ctx, tx, s.auditWriter, ruleAudit(constants.AuditActionGatewayErrorRuleUpdated, "更新上游错误分类规则", row, operatorID, before))
})
if err != nil {
return nil, err
}
s.invalidateRules()
resp := toRuleResponse(row)
return &resp, nil
}
// UpdateRuleStatus 启停上游错误分类规则。
func (s *GatewayRateLimitService) UpdateRuleStatus(ctx context.Context, id uint, status int) error {
operatorID, err := requireSuperAdminWriter(ctx)
if err != nil {
return err
}
row, err := s.loadRule(ctx, id)
if err != nil {
return err
}
before := ruleState(row)
row.Status, row.Updater = status, operatorID
err = runPollingTransaction(ctx, s.db, s.auditWriter, func(tx *gorm.DB) error {
if err := tx.WithContext(ctx).Model(&model.GatewayErrorClassification{}).Where("id = ?", id).
Updates(map[string]any{"status": status, "updater": operatorID}).Error; err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "更新上游错误分类规则状态失败")
}
return writePollingAudit(ctx, tx, s.auditWriter, ruleAudit(constants.AuditActionGatewayErrorRuleStatusUpdated, "更新上游错误分类规则状态", row, operatorID, before))
})
if err != nil {
return err
}
s.invalidateRules()
return nil
}
// DeleteRule 删除上游错误分类规则。
func (s *GatewayRateLimitService) DeleteRule(ctx context.Context, id uint) error {
operatorID, err := requireSuperAdminWriter(ctx)
if err != nil {
return err
}
row, err := s.loadRule(ctx, id)
if err != nil {
return err
}
err = runPollingTransaction(ctx, s.db, s.auditWriter, func(tx *gorm.DB) error {
if err := tx.WithContext(ctx).Delete(&model.GatewayErrorClassification{}, id).Error; err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "删除上游错误分类规则失败")
}
return writePollingAudit(ctx, tx, s.auditWriter, ruleAudit(constants.AuditActionGatewayErrorRuleDeleted, "删除上游错误分类规则", row, operatorID, ruleState(row)))
})
if err != nil {
return err
}
s.invalidateRules()
return nil
}
// TestRule 用已启用规则(可附带一条未保存的草稿)对上游返回信息分类,不写任何数据。
func (s *GatewayRateLimitService) TestRule(ctx context.Context, req *dto.TestGatewayErrorRuleRequest) (*dto.TestGatewayErrorRuleResponse, error) {
if err := requirePlatformReader(ctx); err != nil {
return nil, err
}
rows, err := s.rules.ListEnabled(ctx)
if err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询上游错误分类规则失败")
}
if req.Draft != nil {
if err := validateRule(req.Draft); err != nil {
return nil, err
}
draft := model.GatewayErrorClassification{}
applyRuleRequest(&draft, req.Draft)
rows = append(rows, draft)
sort.SliceStable(rows, func(i, j int) bool { return rows[i].Priority < rows[j].Priority })
}
result := gatewaylimit.ClassifyWith(rows, req.Operation, req.Message)
matched := result.Keyword != ""
return &dto.TestGatewayErrorRuleResponse{
Category: result.Category, CategoryName: constants.GatewayErrorClassName(result.Category),
RuleID: result.RuleID, Keyword: result.Keyword, MaybeAccepted: result.MaybeAccepted, Matched: matched,
}, nil
}
func (s *GatewayRateLimitService) loadRule(ctx context.Context, id uint) (*model.GatewayErrorClassification, error) {
row, err := s.rules.Get(ctx, id)
if err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询上游错误分类规则失败")
}
if row == nil {
return nil, errors.New(errors.CodeNotFound, "上游错误分类规则不存在")
}
return row, nil
}
func validateRule(req *dto.SaveGatewayErrorRuleRequest) error {
if strings.TrimSpace(req.Keyword) == "" {
return errors.New(errors.CodeInvalidParam, "匹配关键字不能为空")
}
if req.MatchType == constants.GatewayMatchRegex {
if _, err := regexp.Compile(req.Keyword); err != nil {
return errors.New(errors.CodeInvalidParam, "正则表达式不合法")
}
}
return nil
}
func applyRuleRequest(row *model.GatewayErrorClassification, req *dto.SaveGatewayErrorRuleRequest) {
row.Keyword = strings.TrimSpace(req.Keyword)
row.MatchType = req.MatchType
row.Category = req.Category
row.Operations = encodeStrings(uniqueStrings(req.Operations))
row.Priority = req.Priority
if row.Priority == 0 {
row.Priority = 100
}
row.MaybeAccepted = req.MaybeAccepted
row.Remark = strings.TrimSpace(req.Remark)
if req.Status != nil {
row.Status = *req.Status
}
}
func ruleState(row *model.GatewayErrorClassification) map[string]any {
ops, _ := gatewaylimit.DecodeOperations(row.Operations)
return map[string]any{"keyword": row.Keyword, "match_type": row.MatchType, "category": row.Category,
"operations": ops, "priority": row.Priority, "maybe_accepted": row.MaybeAccepted, "status": row.Status}
}
func ruleAudit(action, summary string, row *model.GatewayErrorClassification, operatorID uint, before map[string]any) auditinfra.PollingInput {
return auditinfra.PollingInput{
ActionCode: action, Summary: summary, ResourceType: constants.AuditResourceGatewayErrorRule,
ResourceID: row.ID, ResourceKey: "gateway_error_rule:" + uintString(row.ID), DisplayName: row.Keyword,
OperatorID: operatorID,
IdentitySnapshot: map[string]any{"id": row.ID, "keyword": row.Keyword, "match_type": row.MatchType,
"category": row.Category, "priority": row.Priority, "status": row.Status},
BeforeData: before, AfterData: ruleState(row),
}
}
func toRuleResponse(row *model.GatewayErrorClassification) dto.GatewayErrorRuleResponse {
ops, _ := gatewaylimit.DecodeOperations(row.Operations)
return dto.GatewayErrorRuleResponse{
ID: row.ID, Keyword: row.Keyword, MatchType: row.MatchType, Category: row.Category,
CategoryName: constants.GatewayErrorClassName(row.Category), Operations: nonNil(ops), Priority: row.Priority,
MaybeAccepted: row.MaybeAccepted, Status: row.Status, Remark: row.Remark, CreatedAt: row.CreatedAt, UpdatedAt: row.UpdatedAt,
}
}
// carrierNames 返回运营商账户 ID → 名称映射(含已删除账户,便于展示历史配置)。
func (s *GatewayRateLimitService) carrierNames(ctx context.Context) (map[uint]string, error) {
var carriers []model.Carrier
if err := s.db.WithContext(ctx).Unscoped().Select("id", "carrier_name").Find(&carriers).Error; err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询运营商账户失败")
}
names := make(map[uint]string, len(carriers))
for _, carrier := range carriers {
names[carrier.ID] = carrier.CarrierName
}
return names, nil
}
func sameCarrier(a, b *uint) bool {
if a == nil || b == nil {
return a == nil && b == nil
}
return *a == *b
}
func uniqueStrings(values []string) []string {
seen := map[string]bool{}
out := make([]string, 0, len(values))
for _, value := range values {
value = strings.TrimSpace(value)
if value == "" || seen[value] {
continue
}
seen[value] = true
out = append(out, value)
}
return out
}
func encodeStrings(values []string) datatypes.JSON {
if values == nil {
values = []string{}
}
raw, err := sonic.Marshal(values)
if err != nil {
return datatypes.JSON("[]")
}
return datatypes.JSON(raw)
}
func nonNil(values []string) []string {
if values == nil {
return []string{}
}
return values
}
func enabledName(status int) string {
if status == constants.RateLimitGroupStatusEnabled {
return "启用"
}
return "停用"
}
func uintString(value uint) string {
return strconv.FormatUint(uint64(value), 10)
}
// invalidateGroups 让本进程限流组缓存立即失效;其他进程在缓存时长(数秒)内自动刷新。
func (s *GatewayRateLimitService) invalidateGroups() {
if s.runtime != nil {
s.invalidateGroups()
}
}
// invalidateRules 让本进程错误分类规则缓存立即失效。
func (s *GatewayRateLimitService) invalidateRules() {
if s.runtime != nil {
s.invalidateRules()
}
}

View File

@@ -0,0 +1,258 @@
package postgres
import (
"context"
stderrors "errors"
"fmt"
"time"
"gorm.io/gorm"
"github.com/break/junhong_cmp_fiber/internal/model"
)
// CarrierRateLimitGroupStore 运营商账户网关限流组存储。
type CarrierRateLimitGroupStore struct {
db *gorm.DB
}
// NewCarrierRateLimitGroupStore 创建限流组存储。
func NewCarrierRateLimitGroupStore(db *gorm.DB) *CarrierRateLimitGroupStore {
return &CarrierRateLimitGroupStore{db: db}
}
// RateLimitGroupFilter 是限流组列表筛选条件;CarrierID 为 nil 不限,OnlyGlobal 只返回全局组。
type RateLimitGroupFilter struct {
CarrierID *uint
OnlyGlobal bool
Status *int
Page int
PageSize int
}
// List 分页查询限流组。
func (s *CarrierRateLimitGroupStore) List(ctx context.Context, filter RateLimitGroupFilter) ([]model.CarrierRateLimitGroup, int64, error) {
query := s.db.WithContext(ctx).Model(&model.CarrierRateLimitGroup{})
if filter.OnlyGlobal {
query = query.Where("carrier_id IS NULL")
} else if filter.CarrierID != nil {
query = query.Where("carrier_id = ?", *filter.CarrierID)
}
if filter.Status != nil {
query = query.Where("status = ?", *filter.Status)
}
var total int64
if err := query.Count(&total).Error; err != nil {
return nil, 0, err
}
var rows []model.CarrierRateLimitGroup
err := query.Order("carrier_id NULLS FIRST, id").Offset((filter.Page - 1) * filter.PageSize).Limit(filter.PageSize).Find(&rows).Error
return rows, total, err
}
// ListEnabled 返回全部启用的限流组,供限流器加载。
func (s *CarrierRateLimitGroupStore) ListEnabled(ctx context.Context) ([]model.CarrierRateLimitGroup, error) {
var rows []model.CarrierRateLimitGroup
err := s.db.WithContext(ctx).Where("status = ?", 1).Order("id").Find(&rows).Error
return rows, err
}
// ListByCarrier 返回同一账户(nil 为全局组)下的全部未删除组,供保存时校验操作归属。
func (s *CarrierRateLimitGroupStore) ListByCarrier(ctx context.Context, carrierID *uint) ([]model.CarrierRateLimitGroup, error) {
query := s.db.WithContext(ctx)
if carrierID == nil {
query = query.Where("carrier_id IS NULL")
} else {
query = query.Where("carrier_id = ?", *carrierID)
}
var rows []model.CarrierRateLimitGroup
err := query.Find(&rows).Error
return rows, err
}
// Get 按 ID 查询限流组;不存在返回 nil、nil。
func (s *CarrierRateLimitGroupStore) Get(ctx context.Context, id uint) (*model.CarrierRateLimitGroup, error) {
var row model.CarrierRateLimitGroup
err := s.db.WithContext(ctx).First(&row, id).Error
if stderrors.Is(err, gorm.ErrRecordNotFound) {
return nil, nil
}
if err != nil {
return nil, err
}
return &row, nil
}
// Create 新建限流组。
func (s *CarrierRateLimitGroupStore) Create(ctx context.Context, row *model.CarrierRateLimitGroup) error {
return s.db.WithContext(ctx).Create(row).Error
}
// Save 保存限流组全部字段。
func (s *CarrierRateLimitGroupStore) Save(ctx context.Context, row *model.CarrierRateLimitGroup) error {
return s.db.WithContext(ctx).Save(row).Error
}
// Delete 软删除限流组。
func (s *CarrierRateLimitGroupStore) Delete(ctx context.Context, id uint) error {
return s.db.WithContext(ctx).Delete(&model.CarrierRateLimitGroup{}, id).Error
}
// GatewayErrorClassificationStore 上游错误分类规则存储。
type GatewayErrorClassificationStore struct {
db *gorm.DB
}
// NewGatewayErrorClassificationStore 创建错误分类规则存储。
func NewGatewayErrorClassificationStore(db *gorm.DB) *GatewayErrorClassificationStore {
return &GatewayErrorClassificationStore{db: db}
}
// ErrorClassificationFilter 是错误分类规则列表筛选条件。
type ErrorClassificationFilter struct {
Category string
Status *int
Keyword string
Page int
PageSize int
}
// List 分页查询错误分类规则。
func (s *GatewayErrorClassificationStore) List(ctx context.Context, filter ErrorClassificationFilter) ([]model.GatewayErrorClassification, int64, error) {
query := s.db.WithContext(ctx).Model(&model.GatewayErrorClassification{})
if filter.Category != "" {
query = query.Where("category = ?", filter.Category)
}
if filter.Status != nil {
query = query.Where("status = ?", *filter.Status)
}
if filter.Keyword != "" {
query = query.Where("keyword LIKE ?", "%"+filter.Keyword+"%")
}
var total int64
if err := query.Count(&total).Error; err != nil {
return nil, 0, err
}
var rows []model.GatewayErrorClassification
err := query.Order("priority, id").Offset((filter.Page - 1) * filter.PageSize).Limit(filter.PageSize).Find(&rows).Error
return rows, total, err
}
// ListEnabled 返回全部启用规则(按优先级),供分类器加载。
func (s *GatewayErrorClassificationStore) ListEnabled(ctx context.Context) ([]model.GatewayErrorClassification, error) {
var rows []model.GatewayErrorClassification
err := s.db.WithContext(ctx).Where("status = ?", 1).Order("priority, id").Find(&rows).Error
return rows, err
}
// Get 按 ID 查询规则;不存在返回 nil、nil。
func (s *GatewayErrorClassificationStore) Get(ctx context.Context, id uint) (*model.GatewayErrorClassification, error) {
var row model.GatewayErrorClassification
err := s.db.WithContext(ctx).First(&row, id).Error
if stderrors.Is(err, gorm.ErrRecordNotFound) {
return nil, nil
}
if err != nil {
return nil, err
}
return &row, nil
}
// Create 新建规则。
func (s *GatewayErrorClassificationStore) Create(ctx context.Context, row *model.GatewayErrorClassification) error {
return s.db.WithContext(ctx).Create(row).Error
}
// Save 保存规则全部字段。
func (s *GatewayErrorClassificationStore) Save(ctx context.Context, row *model.GatewayErrorClassification) error {
return s.db.WithContext(ctx).Save(row).Error
}
// Delete 软删除规则。
func (s *GatewayErrorClassificationStore) Delete(ctx context.Context, id uint) error {
return s.db.WithContext(ctx).Delete(&model.GatewayErrorClassification{}, id).Error
}
// CardStopResumeRecordStore 停复机调用记录存储(分区表)。
type CardStopResumeRecordStore struct {
db *gorm.DB
}
// NewCardStopResumeRecordStore 创建停复机记录存储。
func NewCardStopResumeRecordStore(db *gorm.DB) *CardStopResumeRecordStore {
return &CardStopResumeRecordStore{db: db}
}
// StopResumeRecordFilter 是停复机记录列表筛选条件;时间范围由调用方保证必填且有上限。
type StopResumeRecordFilter struct {
CardID *uint
ICCID string
CarrierID *uint
Action string
Source string
Result string
ErrorCategory string
StartTime time.Time
EndTime time.Time
Page int
PageSize int
}
// Create 写入一条停复机记录。
func (s *CardStopResumeRecordStore) Create(ctx context.Context, row *model.CardStopResumeRecord) error {
return s.db.WithContext(ctx).Create(row).Error
}
// List 按条件分页查询停复机记录,按时间倒序。
func (s *CardStopResumeRecordStore) List(ctx context.Context, filter StopResumeRecordFilter) ([]model.CardStopResumeRecord, int64, error) {
query := s.db.WithContext(ctx).Model(&model.CardStopResumeRecord{}).
Where("created_at >= ? AND created_at < ?", filter.StartTime, filter.EndTime)
if filter.CardID != nil {
query = query.Where("card_id = ?", *filter.CardID)
}
if filter.ICCID != "" {
query = query.Where("iccid = ?", filter.ICCID)
}
if filter.CarrierID != nil {
query = query.Where("carrier_id = ?", *filter.CarrierID)
}
if filter.Action != "" {
query = query.Where("action = ?", filter.Action)
}
if filter.Source != "" {
query = query.Where("source = ?", filter.Source)
}
if filter.Result != "" {
query = query.Where("result = ?", filter.Result)
}
if filter.ErrorCategory != "" {
query = query.Where("error_category = ?", filter.ErrorCategory)
}
var total int64
if err := query.Count(&total).Error; err != nil {
return nil, 0, err
}
var rows []model.CardStopResumeRecord
err := query.Order("created_at DESC, id DESC").Offset((filter.Page - 1) * filter.PageSize).Limit(filter.PageSize).Find(&rows).Error
return rows, total, err
}
// stopResumeRecordPartitionName 返回某月分区表名(上海时区月份)。
func stopResumeRecordPartitionName(month time.Time) string {
return "tb_card_stop_resume_record_" + month.Format("200601")
}
// EnsureMonthPartition 创建 month 所在月的分区(已存在则跳过);month 须为上海时区月初。
func (s *CardStopResumeRecordStore) EnsureMonthPartition(ctx context.Context, month time.Time) error {
next := month.AddDate(0, 1, 0)
sql := fmt.Sprintf(
"CREATE TABLE IF NOT EXISTS %s PARTITION OF tb_card_stop_resume_record FOR VALUES FROM ('%s') TO ('%s')",
stopResumeRecordPartitionName(month), month.Format(time.RFC3339), next.Format(time.RFC3339))
return s.db.WithContext(ctx).Exec(sql).Error
}
// DropMonthPartition 删除 month 所在月的分区(不存在则跳过),用于按保留期清理。
func (s *CardStopResumeRecordStore) DropMonthPartition(ctx context.Context, month time.Time) error {
sql := fmt.Sprintf("DROP TABLE IF EXISTS %s", stopResumeRecordPartitionName(month))
return s.db.WithContext(ctx).Exec(sql).Error
}

View File

@@ -70,6 +70,24 @@ type PollingBase struct {
priorityStore *postgres.PollingPriorityItemStore
priorityAudit *audit.Writer
scopeChecker *polling.PollingLifecycleService
rateLimitedDelay func() time.Duration // 卡网关调用被运营商账户限流后的固定重入队延迟
}
// SetRateLimitedDelay 设置被运营商账户限流后的重入队延迟来源(受控系统配置,即时生效)。
func (b *PollingBase) SetRateLimitedDelay(delay func() time.Duration) {
b.rateLimitedDelay = delay
}
// requeueRateLimited 卡网关调用被运营商账户限流拒绝时请求并未发出:不计失败、不写失败统计与失败审计,
// 按固定短延迟重入队,不在任务内等待名额(避免占满与其他业务共用的 Asynq 协程)。
func (b *PollingBase) requeueRateLimited(cardID uint, taskType string) error {
delay := 5 * time.Second
if b.rateLimitedDelay != nil {
if configured := b.rateLimitedDelay(); configured > 0 {
delay = configured
}
}
return b.requeueCardAt(cardID, taskType, time.Now().Add(delay))
}
// NewPollingBase 创建轮询共享基类

View File

@@ -82,7 +82,11 @@ func (h *PollingCarddataHandler) Handle(ctx context.Context, task *asynq.Task) e
}
priority.MarkExecution(ctx)
attempt := newGatewayAttempt(cardID, constants.IntegrationOperationGatewayTraffic, constants.CardObservationSceneTrafficPolling)
result, err := h.gateway.QueryFlow(ctx, &gateway.FlowQueryReq{CardNo: card.ICCID})
result, err := h.gateway.QueryFlow(gateway.WithCarrier(ctx, card.CarrierID), &gateway.FlowQueryReq{CardNo: card.ICCID})
if gateway.IsRateLimited(err) {
priority.FailRetryable(ctx, "运营商账户网关限流,稍后重试")
return h.base.requeueRateLimited(cardID, constants.TaskTypePollingCarddata)
}
if err != nil {
_ = recordPriorityGatewayAttempt(ctx, h.integration, attempt, constants.IntegrationResultFailed, false, "查询流量失败", priority)
priority.FailRetryable(ctx, "查询流量失败")

View File

@@ -82,7 +82,11 @@ func (h *PollingCardStatusHandler) Handle(ctx context.Context, task *asynq.Task)
}
priority.MarkExecution(ctx)
attempt := newGatewayAttempt(cardID, constants.IntegrationOperationGatewayNetwork, constants.CardObservationSceneNetworkPolling)
result, err := h.gateway.QueryCardStatus(ctx, &gateway.CardStatusReq{CardNo: card.ICCID})
result, err := h.gateway.QueryCardStatus(gateway.WithCarrier(ctx, card.CarrierID), &gateway.CardStatusReq{CardNo: card.ICCID})
if gateway.IsRateLimited(err) {
priority.FailRetryable(ctx, "运营商账户网关限流,稍后重试")
return h.base.requeueRateLimited(cardID, constants.TaskTypePollingCardStatus)
}
if err != nil {
_ = recordPriorityGatewayAttempt(ctx, h.integration, attempt, constants.IntegrationResultFailed, false, "查询卡状态失败", priority)
priority.FailRetryable(ctx, "查询卡状态失败")

View File

@@ -39,9 +39,9 @@ func recordGatewayAttempt(ctx context.Context, repository *integrationlog.Reposi
return err
}
// recordPriorityGatewayAttempt 记录外部交互日志,并把真正落库的日志标识回写优先项。
// 成功且无变化的轮询按既有语义不落库,因此只有落库成功才回写标识,避免悬挂引用;
// 其余调用方(无优先项在途)继续使用 recordGatewayAttempt。
// recordPriorityGatewayAttempt 只在本轮同时是一次优先执行时写外部交互日志,并把日志标识回写优先项。
// 普通轮询查询(无优先项在途)不再写集成日志:失败原因与调用量改由网关调用分钟计数与卡最近错误保留
// (add-carrier-gateway-rate-limit);优先执行仍按优先轮询可追溯要求保留日志引用。
func recordPriorityGatewayAttempt(
ctx context.Context,
repository *integrationlog.Repository,
@@ -51,6 +51,9 @@ func recordPriorityGatewayAttempt(
summary string,
round *pollingPriorityRound,
) error {
if round == nil {
return nil
}
if err := recordGatewayAttempt(ctx, repository, attempt, result, changed, summary); err != nil {
return err
}

View File

@@ -73,7 +73,11 @@ func (h *PollingRealnameHandler) Handle(ctx context.Context, task *asynq.Task) e
}
priority.MarkExecution(ctx)
attempt := newGatewayAttempt(cardID, constants.IntegrationOperationGatewayRealname, constants.CardObservationSceneRealnamePolling)
result, err := h.gateway.QueryRealnameStatus(ctx, &gateway.CardStatusReq{CardNo: card.ICCID})
result, err := h.gateway.QueryRealnameStatus(gateway.WithCarrier(ctx, card.CarrierID), &gateway.CardStatusReq{CardNo: card.ICCID})
if gateway.IsRateLimited(err) {
priority.FailRetryable(ctx, "运营商账户网关限流,稍后重试")
return h.base.requeueRateLimited(cardID, constants.TaskTypePollingRealname)
}
if err != nil {
_ = recordPriorityGatewayAttempt(ctx, h.integration, attempt, constants.IntegrationResultFailed, false, "查询实名状态失败", priority)
priority.FailRetryable(ctx, "查询实名状态失败")