go-freelru 高性能无GC泛型LRU哈希映射库使用指南

go-freelru 是一个高性能、零GC压力的泛型LRU缓存库，特别适合需要高效缓存管理的Go应用场景。下面我将详细介绍其特性和使用方法。

主要特性

1. 无GC压力：通过预分配内存避免运行时GC
2. 泛型支持：支持任意类型的键和值
3. 高性能：基于高效哈希算法和LRU实现
4. 简单API：易用的缓存操作接口
5. 指标统计：内置缓存命中率等统计功能

安装

go get github.com/elastic/go-freelru

基本使用示例

package main

import (
	"fmt"
	"github.com/elastic/go-freelru"
)

func main() {
	// 创建LRU缓存，设置容量为1000
	lru, err := freelru.New[string, int](1000, 0.5)
	if err != nil {
		panic(err)
	}

	// 添加键值对
	lru.Add("one", 1)
	lru.Add("two", 2)
	lru.Add("three", 3)

	// 获取值
	if val, ok := lru.Get("two"); ok {
		fmt.Println("two:", val) // 输出: two: 2
	}

	// 检查存在性
	if lru.Contains("three") {
		fmt.Println("three exists")
	}

	// 删除键
	lru.Remove("one")

	// 获取缓存大小
	fmt.Println("Size:", lru.Len()) // 输出当前缓存中的元素数量
}

高级功能

1. 设置TTL(生存时间)

package main

import (
	"fmt"
	"time"
	"github.com/elastic/go-freelru"
)

func main() {
	// 创建带TTL的LRU缓存，TTL为5秒
	lru, err := freelru.New[string, string](1000, 0.5)
	if err != nil {
		panic(err)
	}
	lru.SetTTL(5 * time.Second)

	lru.Add("temp", "this will expire")
	
	if val, ok := lru.Get("temp"); ok {
		fmt.Println("Before expiry:", val)
	}

	time.Sleep(6 * time.Second)
	
	if _, ok := lru.Get("temp"); !ok {
		fmt.Println("Entry has expired")
	}
}

2. 使用自定义哈希函数

package main

import (
	"fmt"
	"github.com/elastic/go-freelru"
)

type customKey struct {
	id   int
	name string
}

func main() {
	// 自定义哈希函数
	hashFunc := func(k customKey) uint32 {
		return uint32(k.id) + uint32(len(k.name))
	}

	lru, err := freelru.NewWithHash[customKey, string](
		1000, 
		0.5,
		hashFunc,
	)
	if err != nil {
		panic(err)
	}

	key := customKey{id: 1, name: "test"}
	lru.Add(key, "value")

	if val, ok := lru.Get(key); ok {
		fmt.Println("Got:", val)
	}
}

3. 统计信息

package main

import (
	"fmt"
	"github.com/elastic/go-freelru"
)

func main() {
	lru, _ := freelru.New[string, int](1000, 0.5)

	// 模拟一些操作
	for i := 0; i < 100; i++ {
		key := fmt.Sprintf("key%d", i)
		lru.Add(key, i)
		lru.Get(key)
	}

	// 获取统计信息
	stats := lru.Metrics()
	fmt.Printf("Hit Ratio: %.2f%%\n", stats.HitRatio()*100)
	fmt.Println("Hits:", stats.Hits)
	fmt.Println("Misses:", stats.Misses)
	fmt.Println("Evictions:", stats.Evictions)
}

性能优化建议

1. 合理设置容量：根据实际需求设置缓存容量，避免过大或过小
2. 选择合适的哈希函数：对于复杂键类型，自定义高效的哈希函数
3. 批量操作：尽量使用批量操作方法减少锁竞争
4. 监控命中率：定期检查命中率指标，调整缓存策略

与标准库比较

相比标准库的container/list+map实现的LRU缓存，go-freelru有以下优势：

1. 内存效率更高，减少GC压力
2. 吞吐量更高，特别是在高并发场景
3. 提供更多统计信息和功能
4. 泛型支持使代码更类型安全

注意事项

1. 键类型必须实现可比较（Go泛型约束）
2. 对于非常大的缓存，需要考虑内存占用问题
3. 高并发场景下，性能可能受锁竞争影响

go-freelru是一个优秀的LRU缓存实现，特别适合对性能要求高且需要减少GC压力的场景。通过合理配置和使用，可以显著提升应用的缓存性能。