feat: 卡网关按运营商账户限流并记录停复机调用
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 9m33s
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:
142
internal/gateway/call_guard.go
Normal file
142
internal/gateway/call_guard.go
Normal 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
|
||||
}
|
||||
@@ -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
|
||||
|
||||
@@ -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) {
|
||||
|
||||
Reference in New Issue
Block a user