@stackonward/cli 0.0.1 → 1.0.0

package/dist/resources/templates/go-backend/internal/core/resilience/circuitbreaker.go

@@ -0,0 +1,358 @@
+package resilience
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"sync"
+	"time"
+
+	"github.com/sony/gobreaker/v2"
+	"go.uber.org/zap"
+)
+
+// ═══════════════════════════════════════════════════════════════
+// 熔断器状态
+// ═══════════════════════════════════════════════════════════════
+
+// CircuitState 熔断器状态
+type CircuitState string
+
+const (
+	StateClosed   CircuitState = "CLOSED"
+	StateOpen     CircuitState = "OPEN"
+	StateHalfOpen CircuitState = "HALF_OPEN"
+)
+
+func fromGobreakerState(s gobreaker.State) CircuitState {
+	switch s {
+	case gobreaker.StateClosed:
+		return StateClosed
+	case gobreaker.StateOpen:
+		return StateOpen
+	case gobreaker.StateHalfOpen:
+		return StateHalfOpen
+	default:
+		return StateClosed
+	}
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 配置
+// ═══════════════════════════════════════════════════════════════
+
+// CircuitBreakerConfig 熔断器配置
+type CircuitBreakerConfig struct {
+	// 失败阈值 — 连续失败多少次后触发熔断（默认 5）
+	FailureThreshold uint32
+	// 成功阈值 — 半开状态下连续成功多少次后恢复（默认 2）
+	SuccessThreshold uint32
+	// 熔断恢复超时 — 熔断后等待多久进入半开状态（默认 30s）
+	ResetTimeout time.Duration
+	// 请求超时（默认 10s）
+	RequestTimeout time.Duration
+	// 滑动窗口大小（默认 10）
+	SlidingWindowSize uint32
+	// 失败率阈值百分比（默认 50）
+	FailureRateThreshold float64
+	// 是否记录状态变化
+	LogStateChanges bool
+}
+
+// DefaultCircuitBreakerConfig 默认熔断器配置
+var DefaultCircuitBreakerConfig = CircuitBreakerConfig{
+	FailureThreshold:     5,
+	SuccessThreshold:     2,
+	ResetTimeout:         30 * time.Second,
+	RequestTimeout:       10 * time.Second,
+	SlidingWindowSize:    10,
+	FailureRateThreshold: 50,
+	LogStateChanges:      true,
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 自定义错误
+// ═══════════════════════════════════════════════════════════════
+
+// CircuitBreakerOpenError 熔断器打开错误
+type CircuitBreakerOpenError struct {
+	Key         string
+	State       CircuitState
+	ResetTimeMs int64
+}
+
+func (e *CircuitBreakerOpenError) Error() string {
+	return fmt.Sprintf("circuit breaker '%s' is %s, retry after %dms", e.Key, e.State, e.ResetTimeMs)
+}
+
+// CircuitBreakerTimeoutError 请求超时错误
+type CircuitBreakerTimeoutError struct {
+	Key       string
+	TimeoutMs int64
+}
+
+func (e *CircuitBreakerTimeoutError) Error() string {
+	return fmt.Sprintf("circuit breaker '%s' request timed out after %dms", e.Key, e.TimeoutMs)
+}
+
+type dependencyAvailabilityError interface {
+	AffectsDependencyAvailability() bool
+}
+
+func circuitBreakerRequestSucceeded(err error) bool {
+	if err == nil {
+		return true
+	}
+	var availabilityErr dependencyAvailabilityError
+	return errors.As(err, &availabilityErr) && !availabilityErr.AffectsDependencyAvailability()
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 执行选项
+// ═══════════════════════════════════════════════════════════════
+
+// ExecuteOptions 熔断器执行选项
+type ExecuteOptions[T any] struct {
+	// 降级回调
+	Fallback func() (T, error)
+	// 单次请求超时覆盖
+	Timeout time.Duration
+	// 是否忽略熔断状态强制执行
+	ForceExecute bool
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 熔断器服务
+// ═══════════════════════════════════════════════════════════════
+
+// CircuitBreakerService 熔断器服务（按 key 隔离实例）
+type CircuitBreakerService struct {
+	logger       *zap.Logger
+	mu           sync.RWMutex
+	breakers     map[string]*gobreaker.CircuitBreaker[any]
+	globalConfig CircuitBreakerConfig
+}
+
+// NewCircuitBreakerService 创建熔断器服务
+func NewCircuitBreakerService(logger *zap.Logger, cfg ...CircuitBreakerConfig) *CircuitBreakerService {
+	config := DefaultCircuitBreakerConfig
+	if len(cfg) > 0 {
+		config = cfg[0]
+	}
+
+	return &CircuitBreakerService{
+		logger:       logger.Named("CircuitBreaker"),
+		breakers:     make(map[string]*gobreaker.CircuitBreaker[any]),
+		globalConfig: config,
+	}
+}
+
+// SetGlobalConfig 设置全局默认配置
+func (s *CircuitBreakerService) SetGlobalConfig(cfg CircuitBreakerConfig) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.globalConfig = cfg
+}
+
+// ConfigureCircuit 为特定 key 配置熔断器
+func (s *CircuitBreakerService) ConfigureCircuit(key string, cfg CircuitBreakerConfig) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.breakers[key] = s.createBreaker(key, cfg)
+}
+
+// Execute 在熔断器保护下执行操作
+func (s *CircuitBreakerService) Execute(ctx context.Context, key string, fn func() (any, error), opts ...ExecuteOptions[any]) (any, error) {
+	var opt ExecuteOptions[any]
+	if len(opts) > 0 {
+		opt = opts[0]
+	}
+
+	cb := s.getOrCreate(key)
+
+	// 带超时执行
+	timeout := s.globalConfig.RequestTimeout
+	if opt.Timeout > 0 {
+		timeout = opt.Timeout
+	}
+
+	wrappedFn := func() (any, error) {
+		ctx, cancel := context.WithTimeout(ctx, timeout)
+		defer cancel()
+
+		type result struct {
+			val any
+			err error
+		}
+
+		ch := make(chan result, 1)
+		go func() {
+			v, e := fn()
+			ch <- result{v, e}
+		}()
+
+		select {
+		case <-ctx.Done():
+			return nil, &CircuitBreakerTimeoutError{Key: key, TimeoutMs: timeout.Milliseconds()}
+		case r := <-ch:
+			return r.val, r.err
+		}
+	}
+
+	val, err := cb.Execute(wrappedFn)
+	if err != nil {
+		// gobreaker 返回 ErrOpenState 或 ErrTooManyRequests
+		if errors.Is(err, gobreaker.ErrOpenState) || errors.Is(err, gobreaker.ErrTooManyRequests) {
+			if opt.Fallback != nil {
+				s.logger.Debug("circuit is open, executing fallback", zap.String("key", key))
+				return opt.Fallback()
+			}
+			return nil, &CircuitBreakerOpenError{
+				Key:         key,
+				State:       StateOpen,
+				ResetTimeMs: s.globalConfig.ResetTimeout.Milliseconds(),
+			}
+		}
+
+		// 其他错误有降级则走降级
+		if opt.Fallback != nil {
+			s.logger.Debug("request failed, executing fallback", zap.String("key", key))
+			return opt.Fallback()
+		}
+		return nil, err
+	}
+
+	return val, nil
+}
+
+// GetState 获取熔断器状态
+func (s *CircuitBreakerService) GetState(key string) *CircuitBreakerState {
+	s.mu.RLock()
+	cb, exists := s.breakers[key]
+	s.mu.RUnlock()
+
+	if !exists {
+		return nil
+	}
+
+	counts := cb.Counts()
+	return &CircuitBreakerState{
+		State:        fromGobreakerState(cb.State()),
+		FailureCount: counts.TotalFailures,
+		SuccessCount: counts.TotalSuccesses,
+	}
+}
+
+// CircuitBreakerState 熔断器状态信息
+type CircuitBreakerState struct {
+	State        CircuitState
+	FailureCount uint32
+	SuccessCount uint32
+}
+
+// GetAllStates 获取所有熔断器状态
+func (s *CircuitBreakerService) GetAllStates() map[string]CircuitBreakerState {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	states := make(map[string]CircuitBreakerState, len(s.breakers))
+	for key, cb := range s.breakers {
+		counts := cb.Counts()
+		states[key] = CircuitBreakerState{
+			State:        fromGobreakerState(cb.State()),
+			FailureCount: counts.TotalFailures,
+			SuccessCount: counts.TotalSuccesses,
+		}
+	}
+	return states
+}
+
+// Reset 手动重置熔断器
+func (s *CircuitBreakerService) Reset(key string) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	// gobreaker 没有直接 reset 方法，重新创建实例
+	s.breakers[key] = s.createBreaker(key, s.globalConfig)
+	if s.globalConfig.LogStateChanges {
+		s.logger.Info("circuit breaker manually reset", zap.String("key", key))
+	}
+}
+
+// Close 清理所有熔断器
+func (s *CircuitBreakerService) Close() {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.breakers = make(map[string]*gobreaker.CircuitBreaker[any])
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 内部方法
+// ═══════════════════════════════════════════════════════════════
+
+func (s *CircuitBreakerService) getOrCreate(key string) *gobreaker.CircuitBreaker[any] {
+	s.mu.RLock()
+	cb, exists := s.breakers[key]
+	s.mu.RUnlock()
+
+	if exists {
+		return cb
+	}
+
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	// 双重检查
+	if cb, exists = s.breakers[key]; exists {
+		return cb
+	}
+
+	cb = s.createBreaker(key, s.globalConfig)
+	s.breakers[key] = cb
+	return cb
+}
+
+func (s *CircuitBreakerService) createBreaker(key string, cfg CircuitBreakerConfig) *gobreaker.CircuitBreaker[any] {
+	settings := gobreaker.Settings{
+		Name:         key,
+		MaxRequests:  cfg.SuccessThreshold,
+		Interval:     0, // 不使用 gobreaker 内部的计数器重置
+		Timeout:      cfg.ResetTimeout,
+		IsSuccessful: circuitBreakerRequestSucceeded,
+		ReadyToTrip: func(counts gobreaker.Counts) bool {
+			// 连续失败达到阈值
+			if counts.ConsecutiveFailures >= cfg.FailureThreshold {
+				return true
+			}
+			// 滑动窗口失败率（简化：使用总请求数作为窗口）
+			totalRequests := counts.Requests
+			if totalRequests >= cfg.SlidingWindowSize && totalRequests > 0 {
+				failureRate := float64(counts.TotalFailures) / float64(totalRequests) * 100
+				if failureRate >= cfg.FailureRateThreshold {
+					return true
+				}
+			}
+			return false
+		},
+		OnStateChange: func(name string, from, to gobreaker.State) {
+			if cfg.LogStateChanges {
+				fromState := fromGobreakerState(from)
+				toState := fromGobreakerState(to)
+				if to == gobreaker.StateOpen {
+					s.logger.Warn("circuit breaker state changed",
+						zap.String("key", name),
+						zap.String("from", string(fromState)),
+						zap.String("to", string(toState)),
+					)
+				} else {
+					s.logger.Info("circuit breaker state changed",
+						zap.String("key", name),
+						zap.String("from", string(fromState)),
+						zap.String("to", string(toState)),
+					)
+				}
+			}
+		},
+	}
+
+	return gobreaker.NewCircuitBreaker[any](settings)
+}