@stackonward/cli 0.0.1 → 1.0.0

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

@@ -0,0 +1,984 @@
+package resilience
+
+import (
+	"context"
+	"errors"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.uber.org/zap"
+	"go.uber.org/zap/zaptest"
+)
+
+// newTestBulkheadService 创建测试用舱壁服务
+func newTestBulkheadService(t *testing.T, cfg BulkheadConfig) *BulkheadService {
+	t.Helper()
+	logger := zaptest.NewLogger(t)
+	return NewBulkheadService(logger, cfg)
+}
+
+// newTestBulkheadServiceDefault 使用默认配置创建测试用舱壁服务
+func newTestBulkheadServiceDefault(t *testing.T) *BulkheadService {
+	t.Helper()
+	logger := zaptest.NewLogger(t)
+	return NewBulkheadService(logger)
+}
+
+// blockingFn 返回一个在 started 信号后阻塞直到 release 关闭的函数
+func blockingFn(started chan<- struct{}, release <-chan struct{}, result any) func() (any, error) {
+	return func() (any, error) {
+		if started != nil {
+			started <- struct{}{}
+		}
+		<-release
+		return result, nil
+	}
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 测试 1: NewBulkheadService 创建有效服务
+// ═══════════════════════════════════════════════════════════════
+
+func TestBulkhead_NewService(t *testing.T) {
+	t.Run("使用默认配置创建服务", func(t *testing.T) {
+		logger := zap.NewNop()
+		svc := NewBulkheadService(logger)
+		require.NotNil(t, svc)
+		assert.Equal(t, DefaultBulkheadConfig.MaxConcurrent, svc.globalConfig.MaxConcurrent)
+		assert.Equal(t, DefaultBulkheadConfig.MaxQueue, svc.globalConfig.MaxQueue)
+		assert.Equal(t, DefaultBulkheadConfig.QueueTimeout, svc.globalConfig.QueueTimeout)
+	})
+
+	t.Run("使用自定义配置创建服务", func(t *testing.T) {
+		cfg := BulkheadConfig{
+			MaxConcurrent:   3,
+			MaxQueue:        5,
+			QueueTimeout:    2 * time.Second,
+			LogStateChanges: false,
+		}
+		svc := newTestBulkheadService(t, cfg)
+		require.NotNil(t, svc)
+		assert.Equal(t, 3, svc.globalConfig.MaxConcurrent)
+		assert.Equal(t, 5, svc.globalConfig.MaxQueue)
+		assert.Equal(t, 2*time.Second, svc.globalConfig.QueueTimeout)
+	})
+
+	t.Run("bulkheads map 已初始化", func(t *testing.T) {
+		svc := newTestBulkheadServiceDefault(t)
+		require.NotNil(t, svc.bulkheads)
+		assert.Empty(t, svc.bulkheads)
+	})
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 测试 2: 容量以内 — 所有调用立即执行
+// ═══════════════════════════════════════════════════════════════
+
+func TestBulkhead_UnderCapacity(t *testing.T) {
+	svc := newTestBulkheadService(t, BulkheadConfig{
+		MaxConcurrent:   3,
+		MaxQueue:        5,
+		QueueTimeout:    1 * time.Second,
+		LogStateChanges: false,
+	})
+
+	ctx := context.Background()
+	const key = "test-service"
+
+	// 3 次调用均在并发限制内，应立即完成
+	for i := 0; i < 3; i++ {
+		result, err := svc.Execute(ctx, key, func() (any, error) {
+			return "ok", nil
+		})
+		require.NoError(t, err)
+		assert.Equal(t, "ok", result)
+	}
+
+	state := svc.GetState(key)
+	require.NotNil(t, state)
+	assert.Equal(t, 0, state.ActiveCalls)
+	assert.Equal(t, 0, state.QueueSize)
+	assert.Equal(t, int64(0), state.RejectedCount)
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 测试 3: 达到容量上限 — 调用进入队列
+// ═══════════════════════════════════════════════════════════════
+
+func TestBulkhead_AtCapacity_QueueUp(t *testing.T) {
+	const maxConcurrent = 2
+	svc := newTestBulkheadService(t, BulkheadConfig{
+		MaxConcurrent:   maxConcurrent,
+		MaxQueue:        5,
+		QueueTimeout:    2 * time.Second,
+		LogStateChanges: false,
+	})
+
+	ctx := context.Background()
+	const key = "queue-test"
+
+	release := make(chan struct{})
+	allStarted := make(chan struct{}, maxConcurrent)
+
+	// 启动 maxConcurrent 个阻塞调用占满槽位
+	var wg sync.WaitGroup
+	for i := 0; i < maxConcurrent; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			_, _ = svc.Execute(ctx, key, blockingFn(allStarted, release, "done"))
+		}()
+	}
+
+	// 等待所有槽位被占满
+	for i := 0; i < maxConcurrent; i++ {
+		<-allStarted
+	}
+
+	// 验证槽位已满
+	state := svc.GetState(key)
+	require.NotNil(t, state)
+	assert.Equal(t, maxConcurrent, state.ActiveCalls)
+
+	// 启动第 3 个调用，应该进入队列
+	queued := make(chan struct{})
+	queuedResult := make(chan any, 1)
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		close(queued)
+		result, err := svc.Execute(ctx, key, func() (any, error) {
+			return "queued-executed", nil
+		})
+		if err == nil {
+			queuedResult <- result
+		}
+	}()
+
+	<-queued
+	// 给排队 goroutine 时间进入等待
+	time.Sleep(20 * time.Millisecond)
+
+	state = svc.GetState(key)
+	assert.Equal(t, maxConcurrent, state.ActiveCalls)
+	assert.Equal(t, 1, state.QueueSize)
+
+	// 释放阻塞调用，排队请求应当被执行
+	close(release)
+
+	select {
+	case result := <-queuedResult:
+		assert.Equal(t, "queued-executed", result)
+	case <-time.After(2 * time.Second):
+		t.Fatal("queued request was not executed after slots were released")
+	}
+
+	wg.Wait()
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 测试 4: 超过容量（队列满）— 调用被拒绝，返回 BulkheadFullError
+// ═══════════════════════════════════════════════════════════════
+
+func TestBulkhead_OverCapacity_Rejected(t *testing.T) {
+	const (
+		maxConcurrent = 2
+		maxQueue      = 2
+	)
+	svc := newTestBulkheadService(t, BulkheadConfig{
+		MaxConcurrent:   maxConcurrent,
+		MaxQueue:        maxQueue,
+		QueueTimeout:    5 * time.Second,
+		LogStateChanges: false,
+	})
+
+	ctx := context.Background()
+	const key = "overflow-test"
+
+	release := make(chan struct{})
+	started := make(chan struct{}, maxConcurrent+maxQueue)
+
+	var wg sync.WaitGroup
+
+	// 占满并发槽位
+	for i := 0; i < maxConcurrent; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			_, _ = svc.Execute(ctx, key, blockingFn(started, release, nil))
+		}()
+	}
+	for i := 0; i < maxConcurrent; i++ {
+		<-started
+	}
+
+	// 填满队列
+	for i := 0; i < maxQueue; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			_, _ = svc.Execute(ctx, key, blockingFn(nil, release, nil))
+		}()
+	}
+	// 给队列请求时间入队
+	time.Sleep(30 * time.Millisecond)
+
+	state := svc.GetState(key)
+	require.NotNil(t, state)
+	assert.Equal(t, maxConcurrent, state.ActiveCalls)
+	assert.Equal(t, maxQueue, state.QueueSize)
+
+	// 现在再发一个请求，应该被拒绝
+	result, err := svc.Execute(ctx, key, func() (any, error) {
+		return "should-not-run", nil
+	})
+
+	assert.Nil(t, result)
+	require.Error(t, err)
+
+	var fullErr *BulkheadFullError
+	require.True(t, errors.As(err, &fullErr), "expected BulkheadFullError, got %T: %v", err, err)
+	assert.Equal(t, key, fullErr.Key)
+	assert.Equal(t, maxConcurrent, fullErr.ActiveCalls)
+	assert.Equal(t, maxQueue, fullErr.QueueSize)
+	assert.Equal(t, maxConcurrent, fullErr.MaxConcurrent)
+	assert.Equal(t, maxQueue, fullErr.MaxQueue)
+	assert.Contains(t, fullErr.Error(), key)
+
+	// 验证拒绝计数
+	state = svc.GetState(key)
+	assert.Equal(t, int64(1), state.RejectedCount)
+
+	close(release)
+	wg.Wait()
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 测试 5: 优先级排序 — 高优先级任务优先执行
+// ═══════════════════════════════════════════════════════════════
+
+func TestBulkhead_PriorityOrdering(t *testing.T) {
+	const maxConcurrent = 1
+	svc := newTestBulkheadService(t, BulkheadConfig{
+		MaxConcurrent:   maxConcurrent,
+		MaxQueue:        10,
+		QueueTimeout:    5 * time.Second,
+		LogStateChanges: false,
+	})
+
+	ctx := context.Background()
+	const key = "priority-test"
+
+	// 用一个阻塞调用占住唯一的槽位
+	release := make(chan struct{})
+	slotOccupied := make(chan struct{})
+
+	var wg sync.WaitGroup
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		_, _ = svc.Execute(ctx, key, blockingFn(slotOccupied, release, nil))
+	}()
+	<-slotOccupied
+
+	// 以不同优先级入队（数值越小优先级越高）
+	executionOrder := make([]int, 0, 3)
+	var orderMu sync.Mutex
+
+	type queuedJob struct {
+		priority int
+		label    int
+	}
+
+	jobs := []queuedJob{
+		{priority: 10, label: 10}, // 低优先级
+		{priority: 1, label: 1},   // 高优先级
+		{priority: 5, label: 5},   // 中优先级
+	}
+
+	enqueued := make(chan struct{}, len(jobs))
+
+	for _, job := range jobs {
+		job := job
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			enqueued <- struct{}{}
+			_, _ = svc.Execute(ctx, key, func() (any, error) {
+				orderMu.Lock()
+				executionOrder = append(executionOrder, job.label)
+				orderMu.Unlock()
+				return nil, nil
+			}, BulkheadOptions{Priority: job.priority})
+		}()
+	}
+
+	// 等待所有任务入队
+	for i := 0; i < len(jobs); i++ {
+		<-enqueued
+	}
+	time.Sleep(30 * time.Millisecond)
+
+	// 验证队列已填满（3 个任务）
+	state := svc.GetState(key)
+	assert.Equal(t, len(jobs), state.QueueSize, "all jobs should be queued")
+
+	// 逐个释放槽位，每次只允许一个任务执行，便于观察顺序
+	// 关闭 release 后，占位 goroutine 结束，队列中最高优先级的任务获得槽位
+	close(release)
+
+	wg.Wait()
+
+	// 执行顺序应为优先级升序：1 → 5 → 10
+	orderMu.Lock()
+	defer orderMu.Unlock()
+	require.Len(t, executionOrder, len(jobs))
+	assert.Equal(t, []int{1, 5, 10}, executionOrder,
+		"jobs should execute in priority order (lowest number = highest priority)")
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 测试 6: TryExecute — 非阻塞，无空闲槽位时立即失败
+// ═══════════════════════════════════════════════════════════════
+
+func TestBulkhead_TryExecute(t *testing.T) {
+	t.Run("有空闲槽位时执行成功", func(t *testing.T) {
+		svc := newTestBulkheadService(t, BulkheadConfig{
+			MaxConcurrent:   2,
+			MaxQueue:        5,
+			QueueTimeout:    time.Second,
+			LogStateChanges: false,
+		})
+
+		result, err := svc.TryExecute(context.Background(), "try-test", func() (any, error) {
+			return "executed", nil
+		})
+		require.NoError(t, err)
+		assert.Equal(t, "executed", result)
+	})
+
+	t.Run("无空闲槽位时返回 nil,nil", func(t *testing.T) {
+		svc := newTestBulkheadService(t, BulkheadConfig{
+			MaxConcurrent:   1,
+			MaxQueue:        5,
+			QueueTimeout:    time.Second,
+			LogStateChanges: false,
+		})
+
+		const key = "try-full-test"
+		release := make(chan struct{})
+		started := make(chan struct{})
+
+		var wg sync.WaitGroup
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			_, _ = svc.Execute(context.Background(), key, blockingFn(started, release, nil))
+		}()
+		<-started
+
+		// 槽位已满，TryExecute 应立即返回 nil, nil
+		result, err := svc.TryExecute(context.Background(), key, func() (any, error) {
+			return "should-not-execute", nil
+		})
+		assert.Nil(t, result)
+		assert.NoError(t, err, "TryExecute should return nil error when no slots available")
+
+		close(release)
+		wg.Wait()
+	})
+
+	t.Run("TryExecute 不排队", func(t *testing.T) {
+		svc := newTestBulkheadService(t, BulkheadConfig{
+			MaxConcurrent:   1,
+			MaxQueue:        10,
+			QueueTimeout:    100 * time.Millisecond,
+			LogStateChanges: false,
+		})
+
+		const key = "try-no-queue"
+		release := make(chan struct{})
+		started := make(chan struct{})
+
+		var wg sync.WaitGroup
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			_, _ = svc.Execute(context.Background(), key, blockingFn(started, release, nil))
+		}()
+		<-started
+
+		// TryExecute 在有阻塞的情况下不应加入队列
+		result, err := svc.TryExecute(context.Background(), key, func() (any, error) {
+			return "skip", nil
+		})
+		assert.Nil(t, result)
+		assert.NoError(t, err)
+
+		state := svc.GetState(key)
+		assert.Equal(t, 0, state.QueueSize, "TryExecute must not enqueue")
+
+		close(release)
+		wg.Wait()
+	})
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 测试 7: 队列超时 — 等待超时后返回 BulkheadQueueTimeoutError
+// ═══════════════════════════════════════════════════════════════
+
+func TestBulkhead_QueueTimeout(t *testing.T) {
+	const queueTimeout = 100 * time.Millisecond
+	svc := newTestBulkheadService(t, BulkheadConfig{
+		MaxConcurrent:   1,
+		MaxQueue:        5,
+		QueueTimeout:    queueTimeout,
+		LogStateChanges: false,
+	})
+
+	ctx := context.Background()
+	const key = "timeout-test"
+
+	// 占住唯一槽位
+	release := make(chan struct{})
+	started := make(chan struct{})
+
+	var wg sync.WaitGroup
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		_, _ = svc.Execute(ctx, key, blockingFn(started, release, nil))
+	}()
+	<-started
+
+	// 发起一个会超时的队列请求
+	start := time.Now()
+	result, err := svc.Execute(ctx, key, func() (any, error) {
+		return "should-timeout", nil
+	}, BulkheadOptions{QueueTimeout: queueTimeout})
+
+	elapsed := time.Since(start)
+	assert.Nil(t, result)
+	require.Error(t, err)
+
+	var timeoutErr *BulkheadQueueTimeoutError
+	require.True(t, errors.As(err, &timeoutErr), "expected BulkheadQueueTimeoutError, got %T: %v", err, err)
+	assert.Equal(t, key, timeoutErr.Key)
+	assert.Equal(t, queueTimeout, timeoutErr.Timeout)
+	assert.Contains(t, timeoutErr.Error(), key)
+
+	// 超时应在合理时间内发生（允许 ±50ms 误差）
+	assert.GreaterOrEqual(t, elapsed, queueTimeout, "should wait at least the timeout duration")
+	assert.Less(t, elapsed, queueTimeout+150*time.Millisecond, "should not wait much longer than timeout")
+
+	// 超时计数应增加
+	state := svc.GetState(key)
+	assert.Equal(t, int64(1), state.TimeoutCount)
+	// 超时后队列应为空
+	assert.Equal(t, 0, state.QueueSize)
+
+	// 释放占位 goroutine，然后等待其退出
+	close(release)
+	wg.Wait()
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 测试 8: 槽位释放 — 完成调用后槽位释放给排队请求
+// ═══════════════════════════════════════════════════════════════
+
+func TestBulkhead_SlotRelease(t *testing.T) {
+	svc := newTestBulkheadService(t, BulkheadConfig{
+		MaxConcurrent:   1,
+		MaxQueue:        5,
+		QueueTimeout:    2 * time.Second,
+		LogStateChanges: false,
+	})
+
+	ctx := context.Background()
+	const key = "release-test"
+
+	firstDone := make(chan struct{})
+	releaseFirst := make(chan struct{})
+
+	var wg sync.WaitGroup
+	var secondExecuted atomic.Bool
+
+	// 第一个调用占住槽位
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		_, _ = svc.Execute(ctx, key, func() (any, error) {
+			firstDone <- struct{}{}
+			<-releaseFirst
+			return "first", nil
+		})
+	}()
+	<-firstDone
+
+	// 第二个调用进入队列
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		_, err := svc.Execute(ctx, key, func() (any, error) {
+			secondExecuted.Store(true)
+			return "second", nil
+		})
+		require.NoError(t, err)
+	}()
+
+	// 给第二个调用时间入队
+	time.Sleep(20 * time.Millisecond)
+	state := svc.GetState(key)
+	assert.Equal(t, 1, state.QueueSize, "second call should be queued")
+	assert.False(t, secondExecuted.Load(), "second call should not execute yet")
+
+	// 释放第一个调用
+	close(releaseFirst)
+
+	// 等待第二个调用完成
+	wg.Wait()
+
+	assert.True(t, secondExecuted.Load(), "second call should execute after first releases slot")
+	state = svc.GetState(key)
+	assert.Equal(t, 0, state.ActiveCalls)
+	assert.Equal(t, 0, state.QueueSize)
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 测试 9: 不同 key 的舱壁相互独立
+// ═══════════════════════════════════════════════════════════════
+
+func TestBulkhead_IndependentKeys(t *testing.T) {
+	svc := newTestBulkheadService(t, BulkheadConfig{
+		MaxConcurrent:   1,
+		MaxQueue:        1,
+		QueueTimeout:    time.Second,
+		LogStateChanges: false,
+	})
+
+	ctx := context.Background()
+	const keyA = "service-A"
+	const keyB = "service-B"
+
+	releaseA := make(chan struct{})
+	startedA := make(chan struct{})
+
+	var wg sync.WaitGroup
+
+	// 占住 keyA 的槽位
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		_, _ = svc.Execute(ctx, keyA, blockingFn(startedA, releaseA, nil))
+	}()
+	<-startedA
+
+	// keyA 已满，但 keyB 应该不受影响
+	result, err := svc.Execute(ctx, keyB, func() (any, error) {
+		return "keyB-ok", nil
+	})
+	require.NoError(t, err)
+	assert.Equal(t, "keyB-ok", result)
+
+	// 验证各自状态独立
+	stateA := svc.GetState(keyA)
+	stateB := svc.GetState(keyB)
+	require.NotNil(t, stateA)
+	require.NotNil(t, stateB)
+
+	assert.Equal(t, 1, stateA.ActiveCalls, "keyA should have 1 active call")
+	assert.Equal(t, 0, stateB.ActiveCalls, "keyB should have 0 active calls")
+
+	// 验证 keyA 拒绝请求不影响 keyB
+	_, rejErr := svc.Execute(ctx, keyA, func() (any, error) {
+		return nil, nil
+	}, BulkheadOptions{QueueTimeout: 5 * time.Millisecond})
+	// keyA 应该队列等待后超时（队列容量为 1，已经有一个在队列中等待或满了）
+	// 实际上此时队列为空，第二个请求会进入队列等待后超时
+	_ = rejErr // 可能超时或正常执行
+
+	// keyB 仍然可以正常执行
+	result2, err2 := svc.Execute(ctx, keyB, func() (any, error) {
+		return "keyB-still-ok", nil
+	})
+	require.NoError(t, err2)
+	assert.Equal(t, "keyB-still-ok", result2)
+
+	close(releaseA)
+	wg.Wait()
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 测试 10: GetState — 返回正确的活跃数和队列大小
+// ═══════════════════════════════════════════════════════════════
+
+func TestBulkhead_GetState(t *testing.T) {
+	t.Run("不存在的 key 返回 nil", func(t *testing.T) {
+		svc := newTestBulkheadServiceDefault(t)
+		state := svc.GetState("nonexistent")
+		assert.Nil(t, state)
+	})
+
+	t.Run("初始状态正确", func(t *testing.T) {
+		const (
+			maxConcurrent = 3
+			maxQueue      = 6
+		)
+		svc := newTestBulkheadService(t, BulkheadConfig{
+			MaxConcurrent:   maxConcurrent,
+			MaxQueue:        maxQueue,
+			QueueTimeout:    time.Second,
+			LogStateChanges: false,
+		})
+
+		// 触发创建实例
+		_, _ = svc.Execute(context.Background(), "status-test", func() (any, error) {
+			return nil, nil
+		})
+
+		state := svc.GetState("status-test")
+		require.NotNil(t, state)
+		assert.Equal(t, 0, state.ActiveCalls)
+		assert.Equal(t, 0, state.QueueSize)
+		assert.Equal(t, maxConcurrent, state.MaxConcurrent)
+		assert.Equal(t, maxQueue, state.MaxQueue)
+		assert.Equal(t, maxConcurrent, state.AvailableSlots)
+		assert.Equal(t, maxQueue, state.AvailableQueueSlots)
+		assert.Equal(t, int64(0), state.RejectedCount)
+		assert.Equal(t, int64(0), state.TimeoutCount)
+	})
+
+	t.Run("活跃调用时状态正确", func(t *testing.T) {
+		const (
+			maxConcurrent = 2
+			maxQueue      = 4
+		)
+		svc := newTestBulkheadService(t, BulkheadConfig{
+			MaxConcurrent:   maxConcurrent,
+			MaxQueue:        maxQueue,
+			QueueTimeout:    2 * time.Second,
+			LogStateChanges: false,
+		})
+
+		ctx := context.Background()
+		const key = "active-status"
+
+		release := make(chan struct{})
+		started := make(chan struct{}, maxConcurrent)
+
+		var wg sync.WaitGroup
+
+		// 启动 2 个活跃调用
+		for i := 0; i < maxConcurrent; i++ {
+			wg.Add(1)
+			go func() {
+				defer wg.Done()
+				_, _ = svc.Execute(ctx, key, blockingFn(started, release, nil))
+			}()
+		}
+		for i := 0; i < maxConcurrent; i++ {
+			<-started
+		}
+
+		// 再启动 2 个排队调用
+		for i := 0; i < 2; i++ {
+			wg.Add(1)
+			go func() {
+				defer wg.Done()
+				_, _ = svc.Execute(ctx, key, blockingFn(nil, release, nil))
+			}()
+		}
+		time.Sleep(30 * time.Millisecond)
+
+		state := svc.GetState(key)
+		require.NotNil(t, state)
+		assert.Equal(t, maxConcurrent, state.ActiveCalls)
+		assert.Equal(t, 2, state.QueueSize)
+		assert.Equal(t, maxConcurrent, state.MaxConcurrent)
+		assert.Equal(t, maxQueue, state.MaxQueue)
+		assert.Equal(t, 0, state.AvailableSlots)
+		assert.Equal(t, maxQueue-2, state.AvailableQueueSlots)
+
+		close(release)
+		wg.Wait()
+
+		// 全部完成后状态归零
+		state = svc.GetState(key)
+		assert.Equal(t, 0, state.ActiveCalls)
+		assert.Equal(t, 0, state.QueueSize)
+		assert.Equal(t, maxConcurrent, state.AvailableSlots)
+	})
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 测试 11: 并发访问 — 多 goroutine 竞争有限槽位
+// ═══════════════════════════════════════════════════════════════
+
+func TestBulkhead_ConcurrentAccess(t *testing.T) {
+	const (
+		maxConcurrent   = 3
+		maxQueue        = 5
+		totalGoroutines = 20
+	)
+
+	svc := newTestBulkheadService(t, BulkheadConfig{
+		MaxConcurrent:   maxConcurrent,
+		MaxQueue:        maxQueue,
+		QueueTimeout:    500 * time.Millisecond,
+		LogStateChanges: false,
+	})
+
+	ctx := context.Background()
+	const key = "concurrent-test"
+
+	var (
+		successCount  atomic.Int64
+		rejectedCount atomic.Int64
+		timeoutCount  atomic.Int64
+		peakActive    atomic.Int64
+	)
+
+	// 用于追踪同时活跃的最大调用数
+	var currentActive atomic.Int64
+
+	var wg sync.WaitGroup
+	start := make(chan struct{})
+
+	for i := 0; i < totalGoroutines; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			<-start // 所有 goroutine 同时出发
+
+			_, err := svc.Execute(ctx, key, func() (any, error) {
+				// 追踪并发峰值
+				current := currentActive.Add(1)
+				defer currentActive.Add(-1)
+
+				// 更新峰值记录
+				for {
+					old := peakActive.Load()
+					if current <= old || peakActive.CompareAndSwap(old, current) {
+						break
+					}
+				}
+
+				// 模拟短暂工作
+				time.Sleep(10 * time.Millisecond)
+				return nil, nil
+			})
+
+			switch {
+			case err == nil:
+				successCount.Add(1)
+			case errors.As(err, new(*BulkheadFullError)):
+				rejectedCount.Add(1)
+			case errors.As(err, new(*BulkheadQueueTimeoutError)):
+				timeoutCount.Add(1)
+			default:
+				t.Errorf("unexpected error type: %T: %v", err, err)
+			}
+		}()
+	}
+
+	close(start)
+	wg.Wait()
+
+	total := successCount.Load() + rejectedCount.Load() + timeoutCount.Load()
+	assert.Equal(t, int64(totalGoroutines), total, "all goroutines should have a result")
+
+	// 并发峰值不应超过 maxConcurrent
+	assert.LessOrEqual(t, peakActive.Load(), int64(maxConcurrent),
+		"concurrent active calls must not exceed maxConcurrent")
+
+	// 验证 GetState 中的 RejectedCount 与实际统计一致
+	state := svc.GetState(key)
+	require.NotNil(t, state)
+	assert.Equal(t, rejectedCount.Load(), state.RejectedCount)
+
+	t.Logf("结果: success=%d, rejected=%d, timeout=%d, peak_active=%d",
+		successCount.Load(), rejectedCount.Load(), timeoutCount.Load(), peakActive.Load())
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 额外测试: Context 取消应从队列中移除请求
+// ═══════════════════════════════════════════════════════════════
+
+func TestBulkhead_ContextCancellation(t *testing.T) {
+	svc := newTestBulkheadService(t, BulkheadConfig{
+		MaxConcurrent:   1,
+		MaxQueue:        5,
+		QueueTimeout:    5 * time.Second,
+		LogStateChanges: false,
+	})
+
+	const key = "ctx-cancel-test"
+	release := make(chan struct{})
+	started := make(chan struct{})
+
+	var wg sync.WaitGroup
+
+	// 占住槽位
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		_, _ = svc.Execute(context.Background(), key, blockingFn(started, release, nil))
+	}()
+	<-started
+
+	// 可取消的排队请求
+	ctx, cancel := context.WithCancel(context.Background())
+	errCh := make(chan error, 1)
+
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		_, err := svc.Execute(ctx, key, func() (any, error) {
+			return "cancelled", nil
+		})
+		errCh <- err
+	}()
+
+	// 给排队 goroutine 时间入队
+	time.Sleep(20 * time.Millisecond)
+	state := svc.GetState(key)
+	assert.Equal(t, 1, state.QueueSize)
+
+	// 取消 context
+	cancel()
+
+	select {
+	case err := <-errCh:
+		assert.ErrorIs(t, err, context.Canceled)
+	case <-time.After(time.Second):
+		t.Fatal("expected context cancellation error")
+	}
+
+	// 队列应已清空
+	time.Sleep(10 * time.Millisecond)
+	state = svc.GetState(key)
+	assert.Equal(t, 0, state.QueueSize, "cancelled request should be removed from queue")
+
+	// 释放占位 goroutine，然后等待其退出（避免死锁）
+	close(release)
+	wg.Wait()
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 额外测试: 函数返回错误时槽位仍然释放
+// ═══════════════════════════════════════════════════════════════
+
+func TestBulkhead_SlotReleasedOnFunctionError(t *testing.T) {
+	svc := newTestBulkheadService(t, BulkheadConfig{
+		MaxConcurrent:   1,
+		MaxQueue:        5,
+		QueueTimeout:    time.Second,
+		LogStateChanges: false,
+	})
+
+	ctx := context.Background()
+	const key = "error-release-test"
+	expectedErr := errors.New("function error")
+
+	result, err := svc.Execute(ctx, key, func() (any, error) {
+		return nil, expectedErr
+	})
+	assert.Nil(t, result)
+	assert.ErrorIs(t, err, expectedErr)
+
+	// 槽位应已释放
+	state := svc.GetState(key)
+	require.NotNil(t, state)
+	assert.Equal(t, 0, state.ActiveCalls)
+	assert.Equal(t, 1, state.AvailableSlots)
+
+	// 后续请求可以正常执行
+	result2, err2 := svc.Execute(ctx, key, func() (any, error) {
+		return "after-error", nil
+	})
+	require.NoError(t, err2)
+	assert.Equal(t, "after-error", result2)
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 额外测试: ResetStats 重置计数
+// ═══════════════════════════════════════════════════════════════
+
+func TestBulkhead_ResetStats(t *testing.T) {
+	const (
+		maxConcurrent = 1
+		maxQueue      = 0
+	)
+	svc := newTestBulkheadService(t, BulkheadConfig{
+		MaxConcurrent:   maxConcurrent,
+		MaxQueue:        maxQueue,
+		QueueTimeout:    50 * time.Millisecond,
+		LogStateChanges: false,
+	})
+
+	ctx := context.Background()
+	const key = "reset-test"
+
+	release := make(chan struct{})
+	started := make(chan struct{})
+	var wg sync.WaitGroup
+
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		_, _ = svc.Execute(ctx, key, blockingFn(started, release, nil))
+	}()
+	<-started
+
+	// 触发拒绝
+	_, _ = svc.Execute(ctx, key, func() (any, error) { return nil, nil })
+
+	close(release)
+	wg.Wait()
+
+	state := svc.GetState(key)
+	require.NotNil(t, state)
+	assert.Equal(t, int64(1), state.RejectedCount)
+
+	svc.ResetStats(key)
+
+	state = svc.GetState(key)
+	assert.Equal(t, int64(0), state.RejectedCount)
+	assert.Equal(t, int64(0), state.TimeoutCount)
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 额外测试: BulkheadFullError 错误信息格式
+// ═══════════════════════════════════════════════════════════════
+
+func TestBulkhead_ErrorMessages(t *testing.T) {
+	t.Run("BulkheadFullError 错误信息", func(t *testing.T) {
+		err := &BulkheadFullError{
+			Key:           "my-service",
+			ActiveCalls:   5,
+			QueueSize:     10,
+			MaxConcurrent: 5,
+			MaxQueue:      10,
+		}
+		msg := err.Error()
+		assert.Contains(t, msg, "my-service")
+		assert.Contains(t, msg, "5")
+		assert.Contains(t, msg, "10")
+	})
+
+	t.Run("BulkheadQueueTimeoutError 错误信息", func(t *testing.T) {
+		err := &BulkheadQueueTimeoutError{
+			Key:           "slow-service",
+			Timeout:       3 * time.Second,
+			QueuePosition: 2,
+		}
+		msg := err.Error()
+		assert.Contains(t, msg, "slow-service")
+		assert.Contains(t, msg, "3s")
+		assert.Contains(t, msg, "2")
+	})
+}