### Consistent Hash Module: Go Usage Example

Source: https://github.com/teanft/hamster/blob/dev/docs/USER_GUIDE.md

Demonstrates a complete Go example for initializing the consistent hash service, adding multiple peers, and then iteratively selecting peers for 100 different requests. Includes error handling and prints routing information.

```go
// 创建配置
config, err := domain.NewVirtualNodeConfig(150, nil)
if err != nil {
    log.Fatal(err)
}

// 创建一致性哈希实例
ch := infrastructure.NewConsistentHashImpl(config)
peerPicker := infrastructure.NewConsistentHashPeerPicker(ch)
service := application.NewConsistentHashApplicationService(peerPicker)

// 添加节点
peers := []application.PeerRequest{
    {ID: "node1", Address: "192.168.1.1:8080", Weight: 100},
    {ID: "node2", Address: "192.168.1.2:8080", Weight: 150},
    {ID: "node3", Address: "192.168.1.3:8080", Weight: 200},
}

cmd := application.AddPeersCommand{Peers: peers}
if err := service.AddPeers(ctx, cmd); err != nil {
    log.Fatal(err)
}

// 选择节点处理请求
for i := 0; i < 100; i++ {
    key := fmt.Sprintf("request:%d", i)
    result, err := service.SelectPeer(ctx, application.PeerSelectionCommand{Key: key})
    if err != nil {
        log.Printf("选择节点失败: %v", err)
        continue
    }
    
    fmt.Printf("请求 %s 路由到节点 %s\n", key, result.Peer.ID)
}
```

--------------------------------

### Distributed Lock Usage Example

Source: https://github.com/teanft/hamster/blob/dev/docs/USER_GUIDE.md

This example demonstrates the complete lifecycle of using a distributed lock service, from initialization to acquisition and release. It showcases how to configure lock parameters, handle acquisition failures, and ensure the lock is properly released using a deferred function.

```go
// 创建分布式锁服务
distributedLock := lock.NewMemoryDistributedLock()
service := lock.NewDistributedLockApplicationService(distributedLock)

// 配置锁参数
lockCmd := lock.LockCommand{
    Key:        "critical_section:order_processing",
    Expiration: 30 * time.Second,  // 锁30秒后自动过期
    Timeout:    5 * time.Second,   // 5秒内获取不到锁则超时
    RetryType:  "exponential",     // 指数退避重试
    RetryCount: 5,                 // 最多重试5次
    RetryBase:  100 * time.Millisecond, // 基础重试间隔
}

// 获取锁
result, err := service.Lock(ctx, lockCmd)
if err != nil {
    if err == domain.ErrFailedToPreemptLock {
        log.Println("获取锁失败，资源被其他进程占用")
        return
    }
    log.Fatal(err)
}

defer func() {
    // 确保锁被释放
    unlockCmd := lock.UnlockCommand{Key: lockCmd.Key}
    if err := service.Unlock(ctx, unlockCmd); err != nil {
        log.Printf("释放锁失败: %v", err)
    }
}()

// 执行需要互斥的业务逻辑
fmt.Printf("获取锁成功，开始处理订单...\n")
processOrder() // 业务逻辑
fmt.Printf("订单处理完成\n")
```

--------------------------------

### Go Cache Key Design Best Practices

Source: https://github.com/teanft/hamster/blob/dev/docs/USER_GUIDE.md

Illustrates best practices for designing cache keys in Go, emphasizing hierarchical and understandable key formats. It contrasts good examples with a poor, unmaintainable key design.

```Go
// 好的缓存键设计：有层次、易理解
userCacheKey := fmt.Sprintf("user:profile:%s", userID)
orderCacheKey := fmt.Sprintf("order:detail:%s", orderID)
listCacheKey := fmt.Sprintf("user:orders:%s:page:%d", userID, pageNum)

// 避免：无意义的键名
// cacheKey := "abc123" // 难以理解和维护
```

--------------------------------

### Go Cache Strategy Selection: Read-Through vs. Write-Back

Source: https://github.com/teanft/hamster/blob/dev/docs/USER_GUIDE.md

Provides examples of selecting appropriate caching strategies in Go based on access patterns. It shows initialization for read-through cache (read-heavy) and write-back cache (write-heavy) with configuration options.

```Go
// 读多写少的场景：使用读透缓存
readThroughService := cache.NewReadThroughApplicationService(readThroughRepo)

// 写多读少的场景：使用写回缓存
writeBackConfig := &cache.WriteBackConfig{
    FlushInterval: 5 * time.Minute,
    BatchSize:     100,
    MaxRetries:    3,
    RetryDelay:    time.Second
}
policy := cache.NewCachePolicy().WithWriteBack(writeBackConfig)
```

--------------------------------

### Consistent Hash API: Get Hash Statistics

Source: https://github.com/teanft/hamster/blob/dev/docs/USER_GUIDE.md

Defines the `HashStatsResult` struct for retrieving comprehensive consistent hash statistics, such as total peers, virtual nodes, replicas, key distribution, and load balance. Provides the `GetHashStats` method signature from `ConsistentHashApplicationService`.

```APIDOC
type HashStatsResult struct {
    TotalPeers      int            `json:"total_peers"`
    VirtualNodes    int            `json:"virtual_nodes"`
    Replicas        int            `json:"replicas"`
    KeyDistribution map[string]int `json:"key_distribution"`
    LoadBalance     float64        `json:"load_balance"`
}

func (s *ConsistentHashApplicationService) GetHashStats(ctx context.Context) (*HashStatsResult, error)
```

--------------------------------

### Basic Cache Operations API

Source: https://github.com/teanft/hamster/blob/dev/docs/USER_GUIDE.md

This section defines the core data structures (`CacheItemCommand`, `CacheItemQuery`, `CacheItemResult`) and API functions (`Set`, `Get`, `Delete`) for interacting with the cache system. These interfaces enable fundamental operations like storing, retrieving, and removing cached items, supporting various cache modes.

```go
type CacheItemCommand struct {
    Key        string        `json:"key"`
    Value      any          `json:"value"`
    Expiration time.Duration `json:"expiration"`
}

type CacheItemQuery struct {
    Key string `json:"key"`
}

type CacheItemResult struct {
    Key       string    `json:"key"`
    Value     any      `json:"value"`
    Found     bool      `json:"found"`
    CreatedAt time.Time `json:"created_at"`
    IsDirty   bool      `json:"is_dirty"`
}

// 设置缓存
func (s *ApplicationService) Set(ctx context.Context, cmd CacheItemCommand) error

// 获取缓存
func (s *ApplicationService) Get(ctx context.Context, query CacheItemQuery) (*CacheItemResult, error)

// 删除缓存
func (s *ApplicationService) Delete(ctx context.Context, cmd CacheItemCommand) error
```

--------------------------------

### Cache Policy Configuration API

Source: https://github.com/teanft/hamster/blob/dev/docs/USER_GUIDE.md

This API defines the `CachePolicy` structure and an example of how to configure various cache behaviors. It allows setting parameters such as maximum size, memory limits, default time-to-live (TTL), eviction strategies (e.g., LRU), and enabling write-back caching with specific flush settings.

```go
type CachePolicy struct {
    maxSize       int64
    maxMemory     int64
    defaultTTL    time.Duration
    evictionStrategy EvictionStrategy
    enableWriteBack  bool
    writeBackConfig  *WriteBackConfig
}

// 创建缓存策略
policy := cache.NewCachePolicy().
    WithMaxSize(10000).                    // 最大10000个条目
    WithMaxMemory(500 * 1024 * 1024).      // 最大500MB内存
    WithDefaultTTL(2 * time.Hour).         // 默认2小时过期
    WithEvictionStrategy(cache.NewLRUEvictionStrategy()). // LRU淘汰策略
    WithWriteBack(&cache.WriteBackConfig{  // 启用写回模式
        FlushInterval: 5 * time.Minute,
        BatchSize:     100,
        MaxRetries:    3,
        RetryDelay:    time.Second,
    })
```

--------------------------------

### Go: Test MaxMemoryCache Concurrent Stress

Source: https://github.com/teanft/hamster/blob/dev/test-plan.md

Conducts a high-concurrency stress test on MaxMemoryCache using 100 goroutines. It performs a mix of Set, Get, and Delete operations concurrently. The test aims to verify final data consistency and utilizes the Go -race flag for detecting race conditions.

```Go
func TestMaxMemoryCache_ConcurrentStress(t *testing.T) {
    // 100个goroutine并发读写
    // 混合Set/Get/Delete操作
    // 使用-race参数检测
    // 验证最终一致性
}
```

--------------------------------

### API Documentation: Configuration Parameters Reference

Source: https://github.com/teanft/hamster/blob/dev/docs/USER_GUIDE.md

This section provides a quick reference for configuration parameters across Hamster's consistent hashing, distributed lock, and caching systems. It details parameters such as virtual node replicas, hash functions, lock expiration, retry policies, cache size, and eviction strategies, including their types, ranges, default values, and descriptions.

```APIDOC
Consistent Hashing Configuration:
| 参数 | 类型 | 范围 | 默认值 | 说明 |
|------|------|------|--------|------|
| replicas | int | 1-1000 | 150 | 虚拟节点倍数 |
| hashFunc | Hash | - | crc32.ChecksumIEEE | 哈希函数 |

Distributed Lock Configuration:
| 参数 | 类型 | 范围 | 默认值 | 说明 |
|------|------|------|--------|------|
| expiration | time.Duration | >0 | 30s | 锁过期时间 |
| timeout | time.Duration | >0 | 5s | 获取锁超时时间 |
| retryType | string | fixed/exponential/linear | exponential | 重试策略类型 |
| retryCount | int | ≥0 | 3 | 重试次数 |
| retryBase | time.Duration | >0 | 100ms | 基础重试间隔 |

Cache System Configuration:
| 参数 | 类型 | 范围 | 默认值 | 说明 |
|------|------|------|--------|------|
| maxSize | int64 | >0 | 1000 | 最大条目数 |
| maxMemory | int64 | >0 | 100MB | 最大内存使用 |
| defaultTTL | time.Duration | >0 | 1h | 默认过期时间 |
| evictionStrategy | EvictionStrategy | LRU/FIFO | LRU | 淘汰策略 |
```

--------------------------------

### API Documentation: Performance Benchmark Data

Source: https://github.com/teanft/hamster/blob/dev/docs/USER_GUIDE.md

This section presents performance benchmark data for Hamster's consistent hashing, distributed lock, and caching systems. It includes metrics such as Queries Per Second (QPS), P99 latency, and memory usage for various operations, providing insights into the system's expected performance under standard conditions.

```APIDOC
Consistent Hashing Performance:
| 操作 | QPS | 延迟(P99) | 内存使用 |
|------|-----|-----------|----------|
| 节点选择 | 1,000,000 | 0.1ms | 10MB/1000节点 |
| 添加节点 | 10,000 | 1ms | - |
| 移除节点 | 10,000 | 1ms | - |

Distributed Lock Performance:
| 操作 | QPS | 延迟(P99) | 内存使用 |
|------|-----|-----------|----------|
| TryLock | 100,000 | 0.5ms | 1KB/锁 |
| Lock(重试) | 50,000 | 10ms | 1KB/锁 |
| Unlock | 200,000 | 0.2ms | - |

Cache System Performance:
| 操作 | QPS | 延迟(P99) | 内存使用 |
|------|-----|-----------|----------|
| Get | 2,000,000 | 0.1ms | 配置值 |
| Set | 1,000,000 | 0.2ms | 配置值 |
| Delete | 1,500,000 | 0.1ms | - |

*注：以上数据基于标准测试环境（8核CPU，16GB内存），实际性能可能因环境而异。*
```

--------------------------------

### Consistent Hash API: Select Peer

Source: https://github.com/teanft/hamster/blob/dev/docs/USER_GUIDE.md

Defines the `PeerSelectionCommand` for specifying the key to select a peer, and `PeerSelectionResult` for the outcome, including the selected peer's details. Provides the `SelectPeer` method signature from `ConsistentHashApplicationService`.

```APIDOC
type PeerSelectionCommand struct {
    Key string `json:"key"`
}

type PeerSelectionResult struct {
    Key  string     `json:"key"`
    Peer PeerResult `json:"peer"`
}

func (s *ConsistentHashApplicationService) SelectPeer(ctx context.Context, cmd PeerSelectionCommand) (*PeerSelectionResult, error)
```

--------------------------------

### Go Cache Optimization with Bloom Filters for Non-Existent Data

Source: https://github.com/teanft/hamster/blob/dev/docs/USER_GUIDE.md

Shows how to integrate a Bloom filter in Go to optimize cache lookups for non-existent data, reducing database load. It includes Bloom filter configuration and a 'getUser' function demonstrating its usage before cache and database queries.

```Go
// 对于大量查询不存在数据的场景，使用布隆过滤器
bloomConfig, err := cache.NewBloomFilterConfig(1000000, 0.01) // 100万元素，1%假阳性率
if err != nil {
    log.Fatal(err)
}

bloomFilter := cache.NewInMemoryBloomFilter(bloomConfig)

// 在查询缓存前先检查布隆过滤器
func getUser(ctx context.Context, userID string) (*User, error) {
    cacheKey := fmt.Sprintf("user:%s", userID)

    // 先检查布隆过滤器
    if !bloomFilter.HasKey(ctx, cacheKey) {
        return nil, ErrUserNotFound // 肯定不存在
    }

    // 可能存在，查询缓存
    result, err := cacheService.Get(ctx, cache.CacheItemQuery{Key: cacheKey})
    if err != nil {
        return nil, err
    }

    if !result.Found {
        // 缓存未命中，查询数据库
        user, err := database.GetUser(userID)
        if err != nil {
            return nil, err
        }

        // 更新缓存和布隆过滤器
        cacheService.Set(ctx, cache.CacheItemCommand{
            Key:        cacheKey,
            Value:      user,
            Expiration: time.Hour
        })
        bloomFilter.Add(ctx, cacheKey)

        return user, nil
    }

    return result.Value.(*User), nil
}
```

--------------------------------

### Benchmark Consistent Hashing and Distributed Locks in Go

Source: https://github.com/teanft/hamster/blob/dev/docs/USER_GUIDE.md

This Go code provides benchmark functions for consistent hashing and distributed locks using `testing.B`. `BenchmarkConsistentHash` measures the performance of key selection in a consistent hash ring, while `BenchmarkDistributedLock` evaluates the acquisition and release latency of a distributed lock, both running in parallel.

```go
func BenchmarkConsistentHash(b *testing.B) {
    config, _ := domain.NewVirtualNodeConfig(150, nil)
    ch := infrastructure.NewConsistentHashImpl(config)

    // 添加节点
    for i := 0; i < 10; i++ {
        ch.Add(fmt.Sprintf("node%d", i))
    }

    b.ResetTimer()
    b.RunParallel(func(pb *testing.PB) {
        for pb.Next() {
            key := fmt.Sprintf("key%d", rand.Int())
            _, _ = ch.Get(key)
        }
    })
}

func BenchmarkDistributedLock(b *testing.B) {
    lock := lock.NewMemoryDistributedLock()
    ctx := context.Background()

    b.ResetTimer()
    b.RunParallel(func(pb *testing.PB) {
        for pb.Next() {
            key := fmt.Sprintf("lock%d", rand.Int())
            l, err := lock.TryLock(ctx, key, time.Second)
            if err == nil {
                l.Unlock(ctx)
            }
        }
    })
}
```

--------------------------------

### Go Cache Memory Management and Eviction Strategy

Source: https://github.com/teanft/hamster/blob/dev/docs/USER_GUIDE.md

Demonstrates how to configure cache memory limits and eviction policies in Go. It includes setting a maximum memory usage based on system memory and defining an LRU eviction strategy to prevent memory exhaustion.

```Go
// 根据系统内存设置合理的缓存大小
totalMemory := getTotalSystemMemory()
cacheMemory := totalMemory / 4 // 使用1/4的系统内存作为缓存

policy := cache.NewCachePolicy().
    WithMaxMemory(cacheMemory).
    WithMaxSize(10000). // 限制条目数量防止内存碎片
    WithEvictionStrategy(cache.NewLRUEvictionStrategy())
```

--------------------------------

### Hamster Module Relationship Diagram

Source: https://github.com/teanft/hamster/blob/dev/docs/USER_GUIDE.md

Visualizes the dependencies between the Application, Domain, Infrastructure, and Interfaces layers, and highlights subgraphs for Consistent Hash, Distributed Lock, and Cache System modules, showing their internal components.

```mermaid
graph TB
    A[应用层 Application] --> B[领域层 Domain]
    A --> C[基础设施层 Infrastructure]
    C --> B
    D[接口层 Interfaces] --> A
    
    subgraph "一致性哈希模块"
        E[ConsistentHashApplicationService]
        F[ConsistentHash Domain]
        G[ConsistentHashPeerPicker]
    end
    
    subgraph "分布式锁模块"
        H[DistributedLockApplicationService]
        I[DistributedLock Domain]
        J[MemoryDistributedLock]
    end
    
    subgraph "缓存系统模块"
        K[CacheApplicationService]
        L[Cache Domain]
        M[InMemoryCacheRepository]
    end
```

--------------------------------

### Go Consistent Hashing Load Distribution Check

Source: https://github.com/teanft/hamster/blob/dev/docs/USER_GUIDE.md

Provides a Go snippet to check the load distribution in a consistent hashing system. It helps identify load imbalances by querying service statistics and logging warnings if the balance falls below a threshold.

```Go
// 检查负载分布
stats, err := service.GetHashStats(ctx)
if err != nil {
    log.Fatal(err)
}

if stats.LoadBalance < 0.8 { // 负载均衡度低于80%
    log.Printf("负载不均衡，当前均衡度: %.2f", stats.LoadBalance)
    // 考虑增加虚拟节点数量或调整权重
}
```

--------------------------------

### Consistent Hash API: Add Peers

Source: https://github.com/teanft/hamster/blob/dev/docs/USER_GUIDE.md

Defines the `AddPeersCommand` struct for specifying peers to add, including `PeerRequest` for individual peer details (ID, Address, Weight). Also provides the `AddPeers` method signature from `ConsistentHashApplicationService`.

```APIDOC
type AddPeersCommand struct {
    Peers []PeerRequest `json:"peers"`
}

type PeerRequest struct {
    ID      string `json:"id"`
    Address string `json:"address"`
    Weight  int    `json:"weight"`
}

func (s *ConsistentHashApplicationService) AddPeers(ctx context.Context, cmd AddPeersCommand) error
```

--------------------------------

### Implement Fast Hash Function for Consistent Hashing in Go

Source: https://github.com/teanft/hamster/blob/dev/docs/USER_GUIDE.md

This Go snippet provides a `fastHash` function using `hash/fnv` for performance-sensitive consistent hashing scenarios. It demonstrates how to integrate a custom, faster hash function into a virtual node configuration.

```Go
import "hash/fnv"

// 对于性能敏感的场景，可以使用更快的哈希函数
func fastHash(data []byte) uint32 {
    h := fnv.New32a()
    h.Write(data)
    return h.Sum32()
}

config, err := domain.NewVirtualNodeConfig(150, fastHash)
```

--------------------------------

### Go Distributed Lock Error Handling with Defer

Source: https://github.com/teanft/hamster/blob/dev/docs/USER_GUIDE.md

Demonstrates robust error handling for distributed locks in Go, specifically addressing preemption failures and ensuring lock release using 'defer' even in case of errors during business logic execution.

```Go
func processWithLock(ctx context.Context, service *lock.DistributedLockApplicationService, key string) error {
    result, err := service.Lock(ctx, lockCmd)
    if err != nil {
        if err == domain.ErrFailedToPreemptLock {
            return fmt.Errorf("资源正在被其他进程处理")
        }
        return fmt.Errorf("获取锁失败: %w", err)
    }

    // 使用defer确保锁被释放
    defer func() {
        unlockCmd := lock.UnlockCommand{Key: key}
        if unlockErr := service.Unlock(ctx, unlockCmd); unlockErr != nil {
            log.Printf("释放锁失败: %v", unlockErr)
        }
    }()

    // 执行业务逻辑
    return processBusiness(ctx)
}
```

--------------------------------

### API Documentation: Complete Error Code List

Source: https://github.com/teanft/hamster/blob/dev/docs/USER_GUIDE.md

This section lists all error codes for Hamster's consistent hashing, distributed lock, and caching components. Each entry includes the error code, a descriptive error message, the corresponding HTTP status code, and suggested handling advice for developers.

```APIDOC
Consistent Hashing Error Codes:
| 错误码 | 错误信息 | HTTP状态码 | 处理建议 |
|--------|----------|------------|----------|
| `ErrInvalidKey` | 无效的哈希键 | 400 | 检查键格式和长度 |
| `ErrInvalidReplicas` | 无效的虚拟节点数 | 400 | 设置1-1000范围内的值 |
| `ErrNoPeersAvailable` | 没有可用节点 | 503 | 添加可用节点 |

Distributed Lock Error Codes:
| 错误码 | 错误信息 | HTTP状态码 | 处理建议 |
|--------|----------|------------|----------|
| `ErrFailedToPreemptLock` | 抢锁失败 | 409 | 等待或重试 |
| `ErrLockNotHold` | 未持有锁 | 400 | 检查锁状态 |
| `ErrLockExpired` | 锁已过期 | 410 | 重新获取锁 |
| `ErrInvalidLockKey` | 无效的锁键 | 400 | 检查键格式 |

Cache System Error Codes:
| 错误码 | 错误信息 | HTTP状态码 | 处理建议 |
|--------|----------|------------|----------|
| `ErrInvalidCacheKey` | 无效的缓存键 | 400 | 检查键格式 |
| `ErrKeyNotFound` | 键未找到 | 404 | 正常情况 |
| `ErrInvalidExpiration` | 无效的过期时间 | 400 | 设置正数值 |
```

--------------------------------

### Hamster DDD Architecture Layers

Source: https://github.com/teanft/hamster/blob/dev/docs/USER_GUIDE.md

Illustrates the four main layers of the Hamster project's Domain-Driven Design architecture, including Interfaces, Application, Domain, and Infrastructure layers, along with their typical file paths.

```text
┌─────────────────────────────────────┐
│           Interfaces Layer          │  对外接口层
│        (interfaces/types.go)        │
├─────────────────────────────────────┤
│         Application Layer           │  应用服务层
│     (application/*/service.go)      │
├─────────────────────────────────────┤
│           Domain Layer              │  领域模型层
│        (domain/*/entities.go)       │
├─────────────────────────────────────┤
│        Infrastructure Layer         │  基础设施层
│    (infrastructure/*/repository.go) │
└─────────────────────────────────────┘
```

--------------------------------

### Log Cache Operations with Structured Logging in Go

Source: https://github.com/teanft/hamster/blob/dev/docs/USER_GUIDE.md

This Go function demonstrates how to use `log/slog` for structured logging of cache operations. It logs success or failure, including details like operation type, key, duration, and error information, making logs easier to parse and analyze.

```Go
import "log/slog"

// 使用结构化日志记录关键操作
func logCacheOperation(operation string, key string, duration time.Duration, err error) {
    if err != nil {
        slog.Error("缓存操作失败",
            "operation", operation,
            "key", key,
            "duration", duration,
            "error", err,
        )
    } else {
        slog.Info("缓存操作成功",
            "operation", operation,
            "key", key,
            "duration", duration,
        )
    }
}
```

--------------------------------

### Define and Collect Performance Metrics in Go

Source: https://github.com/teanft/hamster/blob/dev/docs/USER_GUIDE.md

This Go snippet defines a `PerformanceMetrics` struct to encapsulate various metrics for consistent hashing, distributed locks, and caching. The `collectMetrics` function is intended to gather these performance indicators from different modules, providing a structured way to monitor system health.

```go
type PerformanceMetrics struct {
    // 一致性哈希指标
    HashSelectionLatency time.Duration
    LoadBalanceRatio     float64

    // 分布式锁指标
    LockAcquisitionLatency time.Duration
    LockContentionRate     float64

    // 缓存指标
    CacheHitRate     float64
    CacheLatency     time.Duration
    MemoryUsageRate  float64
}

func collectMetrics(ctx context.Context) *PerformanceMetrics {
    metrics := &PerformanceMetrics{}

    // 收集各模块的性能指标
    // ...

    return metrics
}
```

--------------------------------

### Calculate Optimal Virtual Node Replicas for Consistent Hashing in Go

Source: https://github.com/teanft/hamster/blob/dev/docs/USER_GUIDE.md

This Go function calculates an optimal number of virtual nodes for consistent hashing based on the total number of physical nodes. It dynamically adjusts the replica count to ensure better distribution and reduce hot spots, especially with varying cluster sizes.

```Go
// 根据节点数量动态调整虚拟节点数
func calculateOptimalReplicas(nodeCount int) int {
    if nodeCount <= 3 {
        return 300 // 节点少时增加虚拟节点
    } else if nodeCount <= 10 {
        return 150 // 中等节点数
    } else {
        return 100 // 节点多时减少虚拟节点
    }
}
```

--------------------------------

### Optimize Bloom Filter Parameters Dynamically in Go

Source: https://github.com/teanft/hamster/blob/dev/docs/USER_GUIDE.md

This Go code defines functions to create an optimal Bloom filter by dynamically adjusting its parameters based on expected elements and a memory budget. It calculates an optimal false positive rate (FPR) and adjusts it if the memory usage exceeds the budget, ensuring efficient memory utilization.

```go
// 根据数据量动态调整布隆过滤器参数
func createOptimalBloomFilter(expectedElements uint64, memoryBudget uint64) (*cache.InMemoryBloomFilter, error) {
    // 计算在内存预算内的最优假阳性率
    optimalFPR := calculateOptimalFPR(expectedElements, memoryBudget)

    config, err := cache.NewBloomFilterConfig(expectedElements, optimalFPR)
    if err != nil {
        return nil, err
    }

    // 检查内存使用是否在预算内
    if config.MemoryUsage() > memoryBudget {
        // 调整假阳性率以适应内存预算
        adjustedFPR := adjustFPRForMemory(expectedElements, memoryBudget)
        config, err = cache.NewBloomFilterConfig(expectedElements, adjustedFPR)
        if err != nil {
            return nil, err
        }
    }

    return cache.NewInMemoryBloomFilter(config), nil
}

func calculateOptimalFPR(elements uint64, memoryBytes uint64) float64 {
    // 基于内存预算计算最优假阳性率
    // 这里使用简化的计算，实际可以更复杂
    bitsPerElement := float64(memoryBytes*8) / float64(elements)
    return math.Pow(0.6185, bitsPerElement) // 布隆过滤器理论最优值
}
```

--------------------------------

### Distributed Lock API: Lock (With Retry)

Source: https://github.com/teanft/hamster/blob/dev/docs/USER_GUIDE.md

Defines the `LockCommand` struct for acquiring a distributed lock, including parameters for key, expiration, timeout, retry type (fixed, exponential, linear), retry count, and retry base. Provides the `Lock` method signature from `DistributedLockApplicationService`.

```APIDOC
type LockCommand struct {
    Key        string        `json:"key"`
    Expiration time.Duration `json:"expiration"`
    Timeout    time.Duration `json:"timeout"`
    RetryType  string        `json:"retry_type"` // "fixed", "exponential", "linear"
    RetryCount int           `json:"retry_count"`
    RetryBase  time.Duration `json:"retry_base"`
}

func (s *DistributedLockApplicationService) Lock(ctx context.Context, cmd LockCommand) (*LockResult, error)
```

--------------------------------

### Go: Test MaxMemoryCache LoadAndDelete Method

Source: https://github.com/teanft/hamster/blob/dev/test-plan.md

Tests the LoadAndDelete method of MaxMemoryCache. This includes normal operations when a key exists and scenarios where the key does not exist. The test validates the return values and ensures memory statistics are correctly updated.

```Go
func TestMaxMemoryCache_LoadAndDelete(t *testing.T) {
    // 测试用例1: 存在key的正常操作
    // 测试用例2: key不存在的场景
    // 验证返回值和内存统计
}
```

--------------------------------

### MaxMemoryCache Test Strategy Flowchart

Source: https://github.com/teanft/hamster/blob/dev/test-plan.md

A visual representation of the testing strategy for MaxMemoryCache, outlining different test categories such as basic functionality, concurrency, boundary conditions, and error handling, and their respective sub-tests.

```Mermaid
graph TD
    A[基础功能测试] --> B[Delete方法]
    A --> C[LoadAndDelete方法]
    A --> D[类型断言失败]
    
    E[并发测试] --> F[读写混合]
    E --> G[内存淘汰]
    E --> H[回调函数]
    
    I[边界测试] --> J[零值处理]
    I --> K[内存极限]
    
    L[错误处理] --> M[底层错误传递]
```

--------------------------------

### Read-Through Cache API

Source: https://github.com/teanft/hamster/blob/dev/docs/USER_GUIDE.md

This API defines the `GetWithLoader` function, which implements a read-through caching pattern. When a requested item is not found in the cache, this function automatically invokes a provided loader function to fetch the data from the underlying source and populate the cache before returning the result.

```go
func (s *ReadThroughApplicationService) GetWithLoader(
    ctx context.Context,
    query CacheItemQuery,
    loader func(ctx context.Context, key string) (any, error),
    expiration time.Duration,
) (*CacheItemResult, error)
```

--------------------------------

### Perform Batch Cache Set Operations in Go

Source: https://github.com/teanft/hamster/blob/dev/docs/USER_GUIDE.md

This Go function demonstrates how to perform batch set operations on a cache system to reduce lock contention and improve efficiency. It iterates through items in batches, setting them in the cache and handling potential errors for each batch.

```Go
// 批量设置缓存，减少锁竞争
func setBatchCache(ctx context.Context, service *cache.ApplicationService, items map[string]interface{}) error {
    // 按批次处理
    batchSize := 100
    keys := make([]string, 0, len(items))
    for k := range items {
        keys = append(keys, k)
    }

    for i := 0; i < len(keys); i += batchSize {
        end := i + batchSize
        if end > len(keys) {
            end = len(keys)
        }

        batch := keys[i:end]
        for _, key := range batch {
            cmd := cache.CacheItemCommand{
                Key:        key,
                Value:      items[key],
                Expiration: time.Hour,
            }

            if err := service.Set(ctx, cmd); err != nil {
                return fmt.Errorf("批量设置缓存失败: %w", err)
            }
        }
    }

    return nil
}
```

--------------------------------

### Define and Record Prometheus Metrics in Go

Source: https://github.com/teanft/hamster/blob/dev/docs/USER_GUIDE.md

This Go code defines Prometheus metrics (histogram and gauge) for tracking lock acquisition duration and cache hit rate. It includes a function to record lock metrics, demonstrating how to observe durations and label values for analysis.

```Go
// 定义指标
var (
    lockAcquisitionDuration = prometheus.NewHistogramVec(
        prometheus.HistogramOpts{
            Name: "lock_acquisition_duration_seconds",
            Help: "锁获取耗时",
        },
        []string{"key", "result"},
    )

    cacheHitRate = prometheus.NewGaugeVec(
        prometheus.GaugeOpts{
            Name: "cache_hit_rate",
            Help: "缓存命中率",
        },
        []string{"cache_type"},
    )
)

// 记录指标
func recordLockMetrics(key string, duration time.Duration, success bool) {
    result := "success"
    if !success {
        result = "failure"
    }
    lockAcquisitionDuration.WithLabelValues(key, result).Observe(duration.Seconds())
}
```

--------------------------------

### Go Distributed Lock Deadlock Detection and Monitoring

Source: https://github.com/teanft/hamster/blob/dev/docs/USER_GUIDE.md

Implements a Go routine for detecting potential deadlocks in a distributed lock system by periodically checking for locks held for an unusually long duration. It suggests actions like forced release or alerting.

```Go
// 死锁检测和恢复
func detectDeadlock(ctx context.Context, service *lock.DistributedLockApplicationService) {
    ticker := time.NewTicker(time.Minute)
    defer ticker.Stop()

    for range ticker.C {
        // 检查长时间持有的锁
        stats, err := service.GetLockStats(ctx)
        if err != nil {
            continue
        }

        for _, lockInfo := range stats.ActiveLocks {
            if time.Since(lockInfo.CreatedAt) > 10*time.Minute {
                log.Printf("检测到可能的死锁: %s", lockInfo.Key)
                // 可以考虑强制释放或告警
            }
        }
    }
}
```

--------------------------------

### Go Cache Memory Usage Monitoring

Source: https://github.com/teanft/hamster/blob/dev/docs/USER_GUIDE.md

Provides a Go function to monitor cache memory usage periodically. It calculates the percentage of memory used and logs a warning if it exceeds a predefined threshold, indicating potential memory issues.

```Go
// 内存监控
func monitorCacheMemory(ctx context.Context, service *cache.ApplicationService) {
    ticker := time.NewTicker(30 * time.Second)
    defer ticker.Stop()

    for range ticker.C {
        stats, err := service.GetStats(ctx)
        if err != nil {
            continue
        }

        memoryUsagePercent := float64(stats.MemoryUsage) / float64(stats.MaxMemory) * 100
        if memoryUsagePercent > 90 {
            log.Printf("缓存内存使用率过高: %.2f%%", memoryUsagePercent)
            // 触发手动清理或调整策略
        }
    }
}
```

--------------------------------

### Optimize Cache Policy with Pre-allocated Memory in Go

Source: https://github.com/teanft/hamster/blob/dev/docs/USER_GUIDE.md

This Go function creates an optimized cache policy by pre-allocating memory based on an expected cache size. This approach helps reduce garbage collection pressure and improve performance by setting explicit maximum size and memory limits for the cache.

```Go
// 预分配内存，减少GC压力
func createOptimizedCachePolicy(expectedSize int) *cache.CachePolicy {
    // 根据预期大小计算内存需求
    estimatedMemory := int64(expectedSize * 1024) // 假设每个条目1KB

    return cache.NewCachePolicy().
        WithMaxSize(int64(expectedSize)).
        WithMaxMemory(estimatedMemory).
        WithDefaultTTL(time.Hour).
        WithEvictionStrategy(cache.NewLRUEvictionStrategy())
}
```

--------------------------------

### Optimize Concurrent Resource Access with Singleflight Lock in Go

Source: https://github.com/teanft/hamster/blob/dev/docs/USER_GUIDE.md

This Go function demonstrates using a `SingleflightLock` to reduce contention for shared resources under high concurrency. It ensures that only one goroutine attempts to acquire the lock and process the resource, while others wait for the result, preventing thundering herd issues.

```Go
// 对于相同资源的并发请求，使用 SingleflightLock
func processResourceWithOptimization(ctx context.Context, resourceID string) error {
    // 使用 singleflight 减少锁竞争
    result, err := service.SingleflightLock(ctx, lock.LockCommand{
        Key:        fmt.Sprintf("resource:%s", resourceID),
        Expiration: 30 * time.Second,
        Timeout:    5 * time.Second,
    })

    if err != nil {
        return err
    }

    defer service.Unlock(ctx, lock.UnlockCommand{Key: result.Key})

    return processResource(resourceID)
}
```

--------------------------------

### Go Distributed Lock Automatic Renewal for Long-Running Tasks

Source: https://github.com/teanft/hamster/blob/dev/docs/USER_GUIDE.md

Illustrates how to implement automatic renewal for distributed locks in Go, crucial for long-running tasks to prevent lock expiration. It shows configuring renewal interval and timeout.

```Go
// 对于长时间运行的任务，使用自动续约
go func() {
    autoRefreshCmd := lock.AutoRefreshCommand{
        Key:      lockKey,
        Interval: 10 * time.Second, // 每10秒续约一次
        Timeout:  time.Minute      // 续约超时时间
    }

    if err := service.AutoRefresh(ctx, autoRefreshCmd); err != nil {
        log.Printf("自动续约失败: %v", err)
    }
}()
```

--------------------------------

### Go: Test MaxMemoryCache Concurrent Eviction

Source: https://github.com/teanft/hamster/blob/dev/test-plan.md

Tests the concurrent memory eviction mechanism of MaxMemoryCache. The cache memory is set to a critical threshold, and multiple goroutines simultaneously trigger eviction. The test verifies the order of eviction and the correct execution of associated callback functions.

```Go
func TestMaxMemoryCache_ConcurrentEviction(t *testing.T) {
    // 内存设置为临界值
    // 多个goroutine同时触发淘汰
    // 验证淘汰顺序和回调
}
```

--------------------------------

### Singleflight Optimized Lock Acquisition

Source: https://github.com/teanft/hamster/blob/dev/docs/USER_GUIDE.md

This function provides a singleflight-optimized mechanism to acquire a distributed lock. It ensures that only one goroutine attempts to acquire the lock at a time for a given key, preventing redundant lock acquisition attempts and improving efficiency.

```go
func (s *DistributedLockApplicationService) SingleflightLock(ctx context.Context, cmd LockCommand) (*LockResult, error)
```

--------------------------------

### Go: Test MaxMemoryCache Delete Method

Source: https://github.com/teanft/hamster/blob/dev/test-plan.md

Tests the Delete method of MaxMemoryCache. It covers scenarios like deleting an existing key and attempting to delete a non-existent key. The test also verifies the used memory statistics and policy updates after deletion operations.

```Go
func TestMaxMemoryCache_Delete(t *testing.T) {
    // 测试用例1: 删除存在的key
    // 测试用例2: 删除不存在的key 
    // 验证used内存统计
    // 验证policy更新
}
```

--------------------------------

### Distributed Lock API: Try Lock (No Retry)

Source: https://github.com/teanft/hamster/blob/dev/docs/USER_GUIDE.md

Provides the `TryLock` method signature from `DistributedLockApplicationService`, which attempts to acquire a distributed lock immediately without any retry mechanism. It returns a `LockResult` upon success or an error.

```APIDOC
func (s *DistributedLockApplicationService) TryLock(ctx context.Context, cmd LockCommand) (*LockResult, error)
```

--------------------------------

### Create Optimal Retry Strategy for Distributed Locks in Go

Source: https://github.com/teanft/hamster/blob/dev/docs/USER_GUIDE.md

This Go function generates a tailored retry strategy for distributed locks based on the concurrency level. It configures different retry types (fixed, linear, exponential), counts, and base delays to optimize lock acquisition under varying load conditions.

```Go
// 根据并发情况调整重试策略
func createOptimalRetryStrategy(concurrencyLevel string) lock.LockCommand {
    switch concurrencyLevel {
    case "low":
        return lock.LockCommand{
            RetryType:  "fixed",
            RetryCount: 3,
            RetryBase:  50 * time.Millisecond,
        }
    case "medium":
        return lock.LockCommand{
            RetryType:  "linear",
            RetryCount: 5,
            RetryBase:  100 * time.Millisecond,
        }
    case "high":
        return lock.LockCommand{
            RetryType:  "exponential",
            RetryCount: 7,
            RetryBase:  200 * time.Millisecond,
        }
    default:
        return lock.LockCommand{
            RetryType:  "exponential",
            RetryCount: 5,
            RetryBase:  100 * time.Millisecond,
        }
    }
}
```

--------------------------------

### Automatic Lock Renewal

Source: https://github.com/teanft/hamster/blob/dev/docs/USER_GUIDE.md

This snippet defines the `AutoRefreshCommand` structure and the `AutoRefresh` function for automatically renewing a distributed lock. It is essential for maintaining locks during long-running operations, preventing premature expiration and ensuring continued exclusive access.

```go
type AutoRefreshCommand struct {
    Key      string        `json:"key"`
    Interval time.Duration `json:"interval"`
    Timeout  time.Duration `json:"timeout"`
}

func (s *DistributedLockApplicationService) AutoRefresh(ctx context.Context, cmd AutoRefreshCommand) error
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.