@stackonward/cli 0.0.1 → 1.0.0

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

@@ -0,0 +1,788 @@
+package resilience
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.uber.org/zap"
+	"go.uber.org/zap/zaptest"
+)
+
+// errTest 测试用的通用错误
+var errTest = errors.New("test error")
+
+type dependencyAvailableTestError struct{}
+
+func (dependencyAvailableTestError) Error() string {
+	return "dependency returned a business result"
+}
+
+func (dependencyAvailableTestError) AffectsDependencyAvailability() bool {
+	return false
+}
+
+// newTestService 创建适合单元测试的熔断器服务（短超时 + 低阈值）
+func newTestService(t *testing.T, cfg CircuitBreakerConfig) *CircuitBreakerService {
+	t.Helper()
+	logger := zaptest.NewLogger(t)
+	return NewCircuitBreakerService(logger, cfg)
+}
+
+// minimalCfg 最小测试配置：3 次连续失败触发熔断，50ms 恢复超时
+func minimalCfg() CircuitBreakerConfig {
+	return CircuitBreakerConfig{
+		FailureThreshold:     3,
+		SuccessThreshold:     2,
+		ResetTimeout:         50 * time.Millisecond,
+		RequestTimeout:       500 * time.Millisecond,
+		SlidingWindowSize:    10,
+		FailureRateThreshold: 50,
+		LogStateChanges:      false,
+	}
+}
+
+// successFn 总是成功的操作
+func successFn() (any, error) {
+	return "ok", nil
+}
+
+// failFn 总是失败的操作
+func failFn() (any, error) {
+	return nil, errTest
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 测试 1：NewCircuitBreakerService 创建合法服务
+// ═══════════════════════════════════════════════════════════════
+
+func TestNewCircuitBreakerService_CreatesValidService(t *testing.T) {
+	logger := zaptest.NewLogger(t)
+
+	t.Run("使用默认配置创建", func(t *testing.T) {
+		svc := NewCircuitBreakerService(logger)
+		require.NotNil(t, svc)
+		assert.NotNil(t, svc.logger)
+		assert.NotNil(t, svc.breakers)
+		assert.Equal(t, DefaultCircuitBreakerConfig, svc.globalConfig)
+	})
+
+	t.Run("使用自定义配置创建", func(t *testing.T) {
+		cfg := minimalCfg()
+		svc := NewCircuitBreakerService(logger, cfg)
+		require.NotNil(t, svc)
+		assert.Equal(t, cfg, svc.globalConfig)
+	})
+
+	t.Run("初始状态无熔断器实例", func(t *testing.T) {
+		svc := NewCircuitBreakerService(logger)
+		states := svc.GetAllStates()
+		assert.Empty(t, states)
+	})
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 测试 2：Closed 状态 — 成功调用正常通过
+// ═══════════════════════════════════════════════════════════════
+
+func TestCircuitBreaker_ClosedState_SuccessfulCallsPassThrough(t *testing.T) {
+	svc := newTestService(t, minimalCfg())
+	ctx := context.Background()
+	const key = "test-closed"
+
+	for i := range 5 {
+		val, err := svc.Execute(ctx, key, successFn)
+		require.NoError(t, err, "第 %d 次调用应成功", i+1)
+		assert.Equal(t, "ok", val)
+	}
+
+	state := svc.GetState(key)
+	require.NotNil(t, state)
+	assert.Equal(t, StateClosed, state.State)
+}
+
+func TestCircuitBreaker_DependencyAvailableErrorCountsAsSuccess(t *testing.T) {
+	cfg := minimalCfg()
+	cfg.FailureThreshold = 1
+	svc := newTestService(t, cfg)
+	ctx := context.Background()
+	const key = "test-dependency-available-error"
+
+	for range 3 {
+		_, err := svc.Execute(ctx, key, func() (any, error) {
+			return nil, dependencyAvailableTestError{}
+		})
+		require.Error(t, err)
+	}
+
+	state := svc.GetState(key)
+	require.NotNil(t, state)
+	assert.Equal(t, StateClosed, state.State)
+	assert.Equal(t, uint32(3), state.SuccessCount)
+	assert.Equal(t, uint32(0), state.FailureCount)
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 测试 3：Closed → Open — 连续失败 N 次后熔断器打开
+// ═══════════════════════════════════════════════════════════════
+
+func TestCircuitBreaker_ClosedToOpen_AfterConsecutiveFailures(t *testing.T) {
+	cfg := minimalCfg()
+	cfg.FailureThreshold = 3
+	svc := newTestService(t, cfg)
+	ctx := context.Background()
+	const key = "test-open-transition"
+
+	// 前 N-1 次失败：熔断器仍然关闭
+	for i := range int(cfg.FailureThreshold) - 1 {
+		_, err := svc.Execute(ctx, key, failFn)
+		require.Error(t, err)
+		assert.ErrorIs(t, err, errTest, "第 %d 次应返回原始错误", i+1)
+		state := svc.GetState(key)
+		assert.Equal(t, StateClosed, state.State, "第 %d 次失败后应仍为 Closed", i+1)
+	}
+
+	// 第 N 次失败：触发熔断
+	_, err := svc.Execute(ctx, key, failFn)
+	require.Error(t, err)
+
+	state := svc.GetState(key)
+	require.NotNil(t, state)
+	assert.Equal(t, StateOpen, state.State, "达到失败阈值后应转为 Open")
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 测试 4：Open 状态 — 调用立即失败并返回 CircuitBreakerOpenError
+// ═══════════════════════════════════════════════════════════════
+
+func TestCircuitBreaker_OpenState_FailsImmediately(t *testing.T) {
+	cfg := minimalCfg()
+	cfg.FailureThreshold = 2
+	svc := newTestService(t, cfg)
+	ctx := context.Background()
+	const key = "test-open-fail"
+
+	// 触发熔断
+	for range cfg.FailureThreshold {
+		svc.Execute(ctx, key, failFn) //nolint:errcheck
+	}
+
+	// 验证处于 Open 状态
+	state := svc.GetState(key)
+	require.Equal(t, StateOpen, state.State)
+
+	// Open 状态下调用应立即返回 CircuitBreakerOpenError
+	var callCount int
+	_, err := svc.Execute(ctx, key, func() (any, error) {
+		callCount++
+		return "should-not-execute", nil
+	})
+
+	require.Error(t, err)
+	assert.Equal(t, 0, callCount, "Open 状态下业务函数不应被调用")
+
+	var openErr *CircuitBreakerOpenError
+	assert.ErrorAs(t, err, &openErr, "应返回 CircuitBreakerOpenError")
+	assert.Equal(t, key, openErr.Key)
+	assert.Equal(t, StateOpen, openErr.State)
+	assert.Greater(t, openErr.ResetTimeMs, int64(0))
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 测试 5：Open → Half-Open — 重置超时后允许一次探测
+// ═══════════════════════════════════════════════════════════════
+
+func TestCircuitBreaker_OpenToHalfOpen_AfterResetTimeout(t *testing.T) {
+	cfg := minimalCfg()
+	cfg.FailureThreshold = 2
+	cfg.ResetTimeout = 60 * time.Millisecond
+	svc := newTestService(t, cfg)
+	ctx := context.Background()
+	const key = "test-half-open-transition"
+
+	// 触发熔断
+	for range cfg.FailureThreshold {
+		svc.Execute(ctx, key, failFn) //nolint:errcheck
+	}
+	require.Equal(t, StateOpen, svc.GetState(key).State)
+
+	// Open 状态下调用应立即拒绝
+	_, err := svc.Execute(ctx, key, successFn)
+	require.Error(t, err)
+	var openErr *CircuitBreakerOpenError
+	require.ErrorAs(t, err, &openErr)
+
+	// 等待 ResetTimeout 到期
+	time.Sleep(cfg.ResetTimeout + 20*time.Millisecond)
+
+	// 探测请求应该被允许执行（状态变为 Half-Open 后放行）
+	probeExecuted := false
+	_, err = svc.Execute(ctx, key, func() (any, error) {
+		probeExecuted = true
+		return "probe", nil
+	})
+	// 探测成功则无错误；如果此时仍在 Open 则有错误
+	// 关键验证：探测函数被执行了（说明进入了 Half-Open）
+	assert.True(t, probeExecuted, "Reset 超时后探测函数应被执行")
+	assert.NoError(t, err)
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 测试 6：Half-Open → Closed — 探测成功后电路关闭
+// ═══════════════════════════════════════════════════════════════
+
+func TestCircuitBreaker_HalfOpenToClosed_IfProbeSucceeds(t *testing.T) {
+	cfg := minimalCfg()
+	cfg.FailureThreshold = 2
+	cfg.SuccessThreshold = 2 // 需要 2 次成功才能关闭
+	cfg.ResetTimeout = 60 * time.Millisecond
+	svc := newTestService(t, cfg)
+	ctx := context.Background()
+	const key = "test-half-open-close"
+
+	// 触发熔断
+	for range cfg.FailureThreshold {
+		svc.Execute(ctx, key, failFn) //nolint:errcheck
+	}
+	require.Equal(t, StateOpen, svc.GetState(key).State)
+
+	// 等待进入 Half-Open
+	time.Sleep(cfg.ResetTimeout + 20*time.Millisecond)
+
+	// 执行 SuccessThreshold 次成功探测
+	for i := range int(cfg.SuccessThreshold) {
+		_, err := svc.Execute(ctx, key, successFn)
+		assert.NoError(t, err, "第 %d 次探测应成功", i+1)
+	}
+
+	// 验证熔断器已关闭
+	state := svc.GetState(key)
+	require.NotNil(t, state)
+	assert.Equal(t, StateClosed, state.State, "探测成功后应转为 Closed")
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 测试 7：Half-Open → Open — 探测失败后电路重新打开
+// ═══════════════════════════════════════════════════════════════
+
+func TestCircuitBreaker_HalfOpenToOpen_IfProbeFails(t *testing.T) {
+	cfg := minimalCfg()
+	cfg.FailureThreshold = 2
+	cfg.ResetTimeout = 60 * time.Millisecond
+	svc := newTestService(t, cfg)
+	ctx := context.Background()
+	const key = "test-half-open-reopen"
+
+	// 触发熔断
+	for range cfg.FailureThreshold {
+		svc.Execute(ctx, key, failFn) //nolint:errcheck
+	}
+	require.Equal(t, StateOpen, svc.GetState(key).State)
+
+	// 等待进入 Half-Open
+	time.Sleep(cfg.ResetTimeout + 20*time.Millisecond)
+
+	// 探测失败
+	_, err := svc.Execute(ctx, key, failFn)
+	require.Error(t, err)
+
+	// 验证熔断器重新打开
+	state := svc.GetState(key)
+	require.NotNil(t, state)
+	assert.Equal(t, StateOpen, state.State, "探测失败后应重新转为 Open")
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 测试 8：Fallback — 电路打开时调用降级函数
+// ═══════════════════════════════════════════════════════════════
+
+func TestCircuitBreaker_Fallback_CalledWhenCircuitOpen(t *testing.T) {
+	cfg := minimalCfg()
+	cfg.FailureThreshold = 2
+	svc := newTestService(t, cfg)
+	ctx := context.Background()
+	const key = "test-fallback"
+
+	// 触发熔断
+	for range cfg.FailureThreshold {
+		svc.Execute(ctx, key, failFn) //nolint:errcheck
+	}
+	require.Equal(t, StateOpen, svc.GetState(key).State)
+
+	// 带 Fallback 的调用：电路打开时应使用降级值
+	fallbackCalled := false
+	val, err := svc.Execute(ctx, key, func() (any, error) {
+		return "main", nil
+	}, ExecuteOptions[any]{
+		Fallback: func() (any, error) {
+			fallbackCalled = true
+			return "fallback-value", nil
+		},
+	})
+
+	require.NoError(t, err)
+	assert.True(t, fallbackCalled, "电路打开时应调用 Fallback")
+	assert.Equal(t, "fallback-value", val)
+}
+
+func TestCircuitBreaker_Fallback_CalledOnNonOpenError(t *testing.T) {
+	cfg := minimalCfg()
+	// 高阈值确保熔断器不会因为少量失败而打开
+	cfg.FailureThreshold = 100
+	svc := newTestService(t, cfg)
+	ctx := context.Background()
+	const key = "test-fallback-error"
+
+	// 普通失败时如果有 Fallback 也应使用降级值
+	fallbackCalled := false
+	val, err := svc.Execute(ctx, key, failFn, ExecuteOptions[any]{
+		Fallback: func() (any, error) {
+			fallbackCalled = true
+			return "fallback-on-error", nil
+		},
+	})
+
+	require.NoError(t, err)
+	assert.True(t, fallbackCalled, "普通失败时有 Fallback 应被调用")
+	assert.Equal(t, "fallback-on-error", val)
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 测试 9：Timeout — 超时操作返回 CircuitBreakerTimeoutError
+// ═══════════════════════════════════════════════════════════════
+
+func TestCircuitBreaker_Timeout_ReturnsTimeoutError(t *testing.T) {
+	cfg := minimalCfg()
+	cfg.RequestTimeout = 50 * time.Millisecond
+	svc := newTestService(t, cfg)
+	ctx := context.Background()
+	const key = "test-timeout"
+
+	slowFn := func() (any, error) {
+		time.Sleep(200 * time.Millisecond)
+		return "slow", nil
+	}
+
+	start := time.Now()
+	_, err := svc.Execute(ctx, key, slowFn)
+	elapsed := time.Since(start)
+
+	require.Error(t, err)
+	// 验证在超时时间附近返回（允许 100ms 宽松）
+	assert.Less(t, elapsed, 200*time.Millisecond, "应在函数完成前超时返回")
+
+	var timeoutErr *CircuitBreakerTimeoutError
+	assert.ErrorAs(t, err, &timeoutErr, "应返回 CircuitBreakerTimeoutError")
+	assert.Equal(t, key, timeoutErr.Key)
+	assert.Equal(t, cfg.RequestTimeout.Milliseconds(), timeoutErr.TimeoutMs)
+}
+
+func TestCircuitBreaker_Timeout_PerCallOverride(t *testing.T) {
+	cfg := minimalCfg()
+	cfg.RequestTimeout = 500 * time.Millisecond // 全局超时较长
+	svc := newTestService(t, cfg)
+	ctx := context.Background()
+	const key = "test-timeout-override"
+
+	customTimeout := 30 * time.Millisecond
+	slowFn := func() (any, error) {
+		time.Sleep(200 * time.Millisecond)
+		return "slow", nil
+	}
+
+	start := time.Now()
+	_, err := svc.Execute(ctx, key, slowFn, ExecuteOptions[any]{
+		Timeout: customTimeout,
+	})
+	elapsed := time.Since(start)
+
+	require.Error(t, err)
+	assert.Less(t, elapsed, 200*time.Millisecond, "应使用覆盖的超时时间")
+
+	var timeoutErr *CircuitBreakerTimeoutError
+	assert.ErrorAs(t, err, &timeoutErr)
+	assert.Equal(t, customTimeout.Milliseconds(), timeoutErr.TimeoutMs)
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 测试 10：Keyed 实例 — 不同 key 的熔断器相互独立
+// ═══════════════════════════════════════════════════════════════
+
+func TestCircuitBreaker_KeyedInstances_AreIndependent(t *testing.T) {
+	cfg := minimalCfg()
+	cfg.FailureThreshold = 2
+	svc := newTestService(t, cfg)
+	ctx := context.Background()
+
+	const keyA = "service-a"
+	const keyB = "service-b"
+
+	// 只让 keyA 触发熔断
+	for range cfg.FailureThreshold {
+		svc.Execute(ctx, keyA, failFn) //nolint:errcheck
+	}
+
+	stateA := svc.GetState(keyA)
+	require.NotNil(t, stateA)
+	assert.Equal(t, StateOpen, stateA.State, "keyA 应已熔断")
+
+	// keyB 未使用时 GetState 应返回 nil
+	stateB := svc.GetState(keyB)
+	assert.Nil(t, stateB, "未使用的 keyB 应返回 nil")
+
+	// keyB 正常调用应成功
+	val, err := svc.Execute(ctx, keyB, successFn)
+	require.NoError(t, err, "keyB 不受 keyA 熔断影响")
+	assert.Equal(t, "ok", val)
+
+	stateBAfter := svc.GetState(keyB)
+	require.NotNil(t, stateBAfter)
+	assert.Equal(t, StateClosed, stateBAfter.State, "keyB 应仍为 Closed")
+}
+
+func TestCircuitBreaker_KeyedInstances_MultipleKeys(t *testing.T) {
+	cfg := minimalCfg()
+	cfg.FailureThreshold = 2
+	svc := newTestService(t, cfg)
+	ctx := context.Background()
+
+	keys := []string{"svc-1", "svc-2", "svc-3"}
+
+	// 只让 svc-1 熔断
+	for range cfg.FailureThreshold {
+		svc.Execute(ctx, "svc-1", failFn) //nolint:errcheck
+	}
+
+	// svc-2 和 svc-3 正常调用
+	for _, k := range []string{"svc-2", "svc-3"} {
+		_, err := svc.Execute(ctx, k, successFn)
+		assert.NoError(t, err, "%s 不应受 svc-1 影响", k)
+	}
+
+	// 验证所有 key 的状态
+	all := svc.GetAllStates()
+	assert.Equal(t, len(keys), len(all))
+	assert.Equal(t, StateOpen, all["svc-1"].State)
+	assert.Equal(t, StateClosed, all["svc-2"].State)
+	assert.Equal(t, StateClosed, all["svc-3"].State)
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 测试 11：GetState — 正确返回每个 key 的状态
+// ═══════════════════════════════════════════════════════════════
+
+func TestCircuitBreaker_GetState_ReturnsCorrectState(t *testing.T) {
+	cfg := minimalCfg()
+	cfg.FailureThreshold = 2
+	svc := newTestService(t, cfg)
+	ctx := context.Background()
+
+	t.Run("未知 key 返回 nil", func(t *testing.T) {
+		state := svc.GetState("nonexistent")
+		assert.Nil(t, state)
+	})
+
+	t.Run("Closed 状态正确返回", func(t *testing.T) {
+		const key = "state-closed"
+		svc.Execute(ctx, key, successFn) //nolint:errcheck
+		state := svc.GetState(key)
+		require.NotNil(t, state)
+		assert.Equal(t, StateClosed, state.State)
+		assert.Greater(t, state.SuccessCount, uint32(0))
+	})
+
+	t.Run("Open 状态正确返回", func(t *testing.T) {
+		const key = "state-open"
+		for range cfg.FailureThreshold {
+			svc.Execute(ctx, key, failFn) //nolint:errcheck
+		}
+		state := svc.GetState(key)
+		require.NotNil(t, state)
+		assert.Equal(t, StateOpen, state.State)
+	})
+
+	t.Run("GetAllStates 包含所有已创建 key", func(t *testing.T) {
+		freshSvc := newTestService(t, cfg)
+		keys := []string{"k1", "k2", "k3"}
+		for _, k := range keys {
+			freshSvc.Execute(ctx, k, successFn) //nolint:errcheck
+		}
+		all := freshSvc.GetAllStates()
+		assert.Len(t, all, len(keys))
+		for _, k := range keys {
+			_, ok := all[k]
+			assert.True(t, ok, "GetAllStates 应包含 %s", k)
+		}
+	})
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 测试 12：并发访问 — 多个 goroutine 使用同一电路
+// ═══════════════════════════════════════════════════════════════
+
+func TestCircuitBreaker_ConcurrentAccess_SameCircuit(t *testing.T) {
+	cfg := minimalCfg()
+	cfg.FailureThreshold = 5
+	cfg.RequestTimeout = 100 * time.Millisecond
+	svc := newTestService(t, cfg)
+	ctx := context.Background()
+	const key = "concurrent-key"
+
+	const goroutines = 20
+	const callsPerGoroutine = 10
+
+	var successCount atomic.Int64
+	var errorCount atomic.Int64
+
+	var wg sync.WaitGroup
+	wg.Add(goroutines)
+
+	for i := range goroutines {
+		go func(id int) {
+			defer wg.Done()
+			for j := range callsPerGoroutine {
+				fn := successFn
+				// 让部分 goroutine 产生失败
+				if id%4 == 0 && j%3 == 0 {
+					fn = failFn
+				}
+				_, err := svc.Execute(ctx, key, fn)
+				if err != nil {
+					errorCount.Add(1)
+				} else {
+					successCount.Add(1)
+				}
+			}
+		}(i)
+	}
+
+	wg.Wait()
+
+	// 核心验证：程序没有崩溃，GetState 可以正常访问
+	state := svc.GetState(key)
+	assert.NotNil(t, state)
+	assert.Contains(t, []CircuitState{StateClosed, StateOpen, StateHalfOpen}, state.State)
+
+	total := successCount.Load() + errorCount.Load()
+	assert.Equal(t, int64(goroutines*callsPerGoroutine), total, "所有请求都应有明确结果")
+}
+
+func TestCircuitBreaker_ConcurrentAccess_MultipleKeys(t *testing.T) {
+	cfg := minimalCfg()
+	svc := newTestService(t, cfg)
+	ctx := context.Background()
+
+	const goroutines = 30
+	keys := []string{"svc-a", "svc-b", "svc-c", "svc-d", "svc-e"}
+
+	var wg sync.WaitGroup
+	wg.Add(goroutines)
+
+	for i := range goroutines {
+		go func(id int) {
+			defer wg.Done()
+			key := keys[id%len(keys)]
+			for range 5 {
+				fn := successFn
+				if id%3 == 0 {
+					fn = failFn
+				}
+				svc.Execute(ctx, key, fn) //nolint:errcheck
+			}
+		}(i)
+	}
+
+	wg.Wait()
+
+	// 验证 GetAllStates 在并发后仍然可以正常工作
+	all := svc.GetAllStates()
+	assert.NotEmpty(t, all)
+	for k, v := range all {
+		assert.Contains(t, keys, k)
+		assert.Contains(t, []CircuitState{StateClosed, StateOpen, StateHalfOpen}, v.State)
+	}
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 测试：ConfigureCircuit — 为特定 key 配置自定义参数
+// ═══════════════════════════════════════════════════════════════
+
+func TestCircuitBreaker_ConfigureCircuit_OverridesGlobal(t *testing.T) {
+	globalCfg := minimalCfg()
+	globalCfg.FailureThreshold = 10 // 全局高阈值
+	svc := newTestService(t, globalCfg)
+	ctx := context.Background()
+
+	const key = "custom-circuit"
+	customCfg := minimalCfg()
+	customCfg.FailureThreshold = 2 // 自定义低阈值
+	svc.ConfigureCircuit(key, customCfg)
+
+	// 只需 2 次失败即可触发熔断（使用自定义配置）
+	for range customCfg.FailureThreshold {
+		svc.Execute(ctx, key, failFn) //nolint:errcheck
+	}
+
+	state := svc.GetState(key)
+	require.NotNil(t, state)
+	assert.Equal(t, StateOpen, state.State, "自定义阈值应生效")
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 测试：Reset — 手动重置熔断器
+// ═══════════════════════════════════════════════════════════════
+
+func TestCircuitBreaker_Reset_RestoresClosedState(t *testing.T) {
+	cfg := minimalCfg()
+	cfg.FailureThreshold = 2
+	cfg.ResetTimeout = 10 * time.Second // 长超时，确保不会自动恢复
+	svc := newTestService(t, cfg)
+	ctx := context.Background()
+	const key = "test-reset"
+
+	// 触发熔断
+	for range cfg.FailureThreshold {
+		svc.Execute(ctx, key, failFn) //nolint:errcheck
+	}
+	require.Equal(t, StateOpen, svc.GetState(key).State)
+
+	// 手动重置
+	svc.Reset(key)
+
+	// 重置后应重新创建为 Closed 状态（此时 GetState 前需要先有请求）
+	// Reset 会重新创建 breaker 实例，新实例从 Closed 开始
+	val, err := svc.Execute(ctx, key, successFn)
+	require.NoError(t, err, "重置后应可以成功执行")
+	assert.Equal(t, "ok", val)
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 测试：Close — 清理所有熔断器
+// ═══════════════════════════════════════════════════════════════
+
+func TestCircuitBreaker_Close_ClearsAllBreakers(t *testing.T) {
+	cfg := minimalCfg()
+	svc := newTestService(t, cfg)
+	ctx := context.Background()
+
+	// 创建几个 key
+	for _, k := range []string{"a", "b", "c"} {
+		svc.Execute(ctx, k, successFn) //nolint:errcheck
+	}
+	assert.Len(t, svc.GetAllStates(), 3)
+
+	svc.Close()
+
+	assert.Empty(t, svc.GetAllStates(), "Close 后应清空所有熔断器")
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 测试：CircuitBreakerOpenError 错误格式
+// ═══════════════════════════════════════════════════════════════
+
+func TestCircuitBreakerOpenError_ErrorMessage(t *testing.T) {
+	err := &CircuitBreakerOpenError{
+		Key:         "my-service",
+		State:       StateOpen,
+		ResetTimeMs: 5000,
+	}
+	msg := err.Error()
+	assert.Contains(t, msg, "my-service")
+	assert.Contains(t, msg, "OPEN")
+	assert.Contains(t, msg, "5000")
+}
+
+func TestCircuitBreakerTimeoutError_ErrorMessage(t *testing.T) {
+	err := &CircuitBreakerTimeoutError{
+		Key:       "slow-service",
+		TimeoutMs: 100,
+	}
+	msg := err.Error()
+	assert.Contains(t, msg, "slow-service")
+	assert.Contains(t, msg, "100")
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 测试：SetGlobalConfig
+// ═══════════════════════════════════════════════════════════════
+
+func TestCircuitBreaker_SetGlobalConfig_UpdatesConfig(t *testing.T) {
+	cfg := minimalCfg()
+	svc := newTestService(t, cfg)
+
+	newCfg := minimalCfg()
+	newCfg.FailureThreshold = 99
+	svc.SetGlobalConfig(newCfg)
+
+	assert.Equal(t, uint32(99), svc.globalConfig.FailureThreshold)
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 测试：失败率触发熔断（滑动窗口阈值）
+// ═══════════════════════════════════════════════════════════════
+
+func TestCircuitBreaker_FailureRateThreshold_TripsCircuit(t *testing.T) {
+	cfg := minimalCfg()
+	cfg.FailureThreshold = 100    // 高连续失败阈值，不依赖连续失败
+	cfg.SlidingWindowSize = 4     // 4 次请求后开始计算失败率
+	cfg.FailureRateThreshold = 50 // 50% 失败率触发熔断
+	cfg.SuccessThreshold = 1
+	svc := newTestService(t, cfg)
+	ctx := context.Background()
+	const key = "test-failure-rate"
+
+	// 发送 4 次请求，其中 2 次失败 = 50% 失败率
+	svc.Execute(ctx, key, successFn) //nolint:errcheck
+	svc.Execute(ctx, key, successFn) //nolint:errcheck
+	svc.Execute(ctx, key, failFn)    //nolint:errcheck
+	svc.Execute(ctx, key, failFn)    //nolint:errcheck
+
+	state := svc.GetState(key)
+	require.NotNil(t, state)
+	assert.Equal(t, StateOpen, state.State, "失败率达到阈值后应触发熔断")
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 测试：fromGobreakerState 内部映射
+// ═══════════════════════════════════════════════════════════════
+
+func TestFromGobreakerState_MapsCorrectly(t *testing.T) {
+	cases := []struct {
+		name string
+		want CircuitState
+	}{
+		{"closed", StateClosed},
+		{"half-open", StateHalfOpen},
+		{"open", StateOpen},
+	}
+
+	for _, tc := range cases {
+		t.Run(fmt.Sprintf("state_%s", tc.name), func(t *testing.T) {
+			// 通过完整流程间接验证状态映射
+			_ = tc.want
+		})
+	}
+
+	// 直接验证枚举常量值
+	assert.Equal(t, CircuitState("CLOSED"), StateClosed)
+	assert.Equal(t, CircuitState("OPEN"), StateOpen)
+	assert.Equal(t, CircuitState("HALF_OPEN"), StateHalfOpen)
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 测试：zap.Logger 注入的正确性
+// ═══════════════════════════════════════════════════════════════
+
+func TestNewCircuitBreakerService_LoggerNamed(t *testing.T) {
+	logger := zap.NewNop()
+	svc := NewCircuitBreakerService(logger)
+	require.NotNil(t, svc.logger)
+	// logger 应是命名过的（Named("CircuitBreaker")）
+	// 通过字段验证不崩溃即可
+}