scan4all 依赖解析:go-cache 内存缓存的安装、并发使用与源码原理
scan4all 依赖解析:go-cache 内存缓存的安装、并发使用与源码原理
导读
go-cache 是一个与 memcached 类似、但运行在单机进程内存中的 key-value 缓存库,其本质是一把带过期时间的、线程安全的 map<a href="https://link.gitcode.com/i/a56b615bf98a296e73ede2f7d5f2a642" target="_blank">string]interface{}。它不需要序列化、不需要网络传输,任意类型的对象都可以按指定时长(或永久)存储,并且可被多个 goroutine 安全并发访问。本文以 scan4all 仓库中 vendored 的 [go-cache 官方 README 为骨架,结合 cache.go 与 sharded.go 的源码实现,讲透它的安装、核心 API、过期清理机制、持久化方案与最佳实践——读完后你可以在自己的 Go 工具链里直接落地这套缓存方案,也能理解它在 scan4all 这类扫描器项目中的定位。
为什么需要 go-cache:单机场景的内存缓存
go-cache 适合运行在单台机器上的应用程序。它的核心优势在于:底层就是带过期时间的线程安全 map[string]interface{},因此不需要像 memcached/Redis 那样序列化或通过网络传输内容。
- 任何对象都能存:
interface{}意味着结构体、切片、指针、基本类型均可入缓存; - 可设过期时间,也可永久保存:每个 key 可以单独指定生存期,也可以永久不过期;
- goroutine 安全:内部通过读写锁(
sync.RWMutex)保护,可被多个 goroutine 并发读写。
从源码看,底层数据结构非常直观(cache.go):
type Item struct {
Object interface{}
Expiration int64
}
type cache struct {
defaultExpiration time.Duration
items map[string]Item
mu sync.RWMutex
onEvicted func(string, interface{})
janitor *janitor
}
每个条目包含存储对象与 UnixNano() 时间戳形式的过期时刻;整张表由一把 RWMutex 保护读多写少的访问模式。由于不依赖网络和外部进程,它天然适合作为扫描器、CLI 工具内部的临时去重表、DNS 缓存、指纹匹配缓存等高频小数据场景。
安装
在 Go 模块项目中直接拉取依赖:
go get github.com/patrickmn/go-cache
在 scan4all 仓库中,该库以 vendor 形式固化在 vendor/github.com/patrickmn/go-cache/ 下(README),并在 go.mod / go.sum 中登记为依赖。此外,它的衍生实现还被 projectdiscovery/hmap 的缓存模块 以 "Forked and adapted" 的方式改造使用,可见该缓存模型的通用性。
快速上手:完整用法示例
以下示例完整取自官方 README,覆盖了缓存的创建、写入、读取与类型断言的常见模式(README):
import (
"fmt"
"github.com/patrickmn/go-cache"
"time"
)
func main() {
// 创建一个默认过期时间为 5 分钟、每 10 分钟清理一次过期项的缓存
c := cache.New(5*time.Minute, 10*time.Minute)
// 用默认过期时间写入 key "foo",值为 "bar"
c.Set("foo", "bar", cache.DefaultExpiration)
// 写入 key "baz",值 42,永不过期
// (除非重新 Set,或用 c.Delete("baz") 删除,否则不会被移除)
c.Set("baz", 42, cache.NoExpiration)
// 从缓存读取 key "foo" 对应的字符串
foo, found := c.Get("foo")
if found {
fmt.Println(foo)
}
// Go 是静态类型语言,而缓存值是 interface{},
// 传入不接受任意类型的函数时必须做类型断言。
// 对只使用一次的值,最简单的方式是:
foo, found := c.Get("foo")
if found {
MyFunction(foo.(string))
}
// 如果同一个值在函数里要用多次,断言就会变得繁琐,可以用下面两种写法:
if x, found := c.Get("foo"); found {
foo := x.(string)
// ...
}
// 或
var foo string
if x, found := c.Get("foo"); found {
foo = x.(string)
}
// ...
// 之后 foo 就可以作为 string 自由传递
// 想要性能?存指针!
c.Set("foo", &MyStruct, cache.DefaultExpiration)
if x, found := c.Get("foo"); found {
foo := x.(*MyStruct)
// ...
}
}
要点拆解:
cache.New(默认过期, 清理间隔):创建缓存。两个参数都用time.Duration表示,详见下文「过期与清理机制」。cache.DefaultExpiration(值为0):表示沿用创建缓存时传入的默认过期时间;cache.NoExpiration(值为-1):表示该条目永不过期,只能手动删除或覆盖;c.Get返回(值, 是否命中),命中与否必须检查found,未命中时值恒为nil;- 由于缓存值是
interface{},取回后必须做类型断言;存指针、取指针是官方推荐的性能写法,能避免大对象在断言时的值拷贝。
两个关键常量:DefaultExpiration 与 NoExpiration
cache.go 顶部定义了这两个贯穿全部 API 的常量(cache.go):
const (
// 用于所有接收过期时间参数的函数。
NoExpiration time.Duration = -1
// 等价于向函数传入创建缓存时(New/NewFrom)给定的那个默认过期时长(如 5 分钟)。
DefaultExpiration time.Duration = 0
)
- 传
DefaultExpiration (0):条目使用缓存级默认过期时间; - 传
NoExpiration (-1):条目永久有效; - 传任意正值
d:条目在d时长后过期。
在 Set 的实现中可以看到过期时间戳的计算逻辑(cache.go):当 d == DefaultExpiration 时回退到 c.defaultExpiration,仅当 d > 0 时才计算 time.Now().Add(d).UnixNano() 作为过期时刻——也就是 Item.Expiration 为 0 时代表不过期,这与 Item.Expired() 的判断逻辑(Expiration == 0 返回 false)严格对应。
过期与清理机制:惰性检查 + janitor 后台清扫
go-cache 采用双层过期回收策略:
-
惰性过期(读取时检查):
Get/GetWithExpiration在命中 key 后,会额外判断time.Now().UnixNano() > item.Expiration,一旦过期即视为未命中返回nil, false。因此即使后台清理尚未执行,过期条目也不会被读出来。 -
后台 janitor 清扫(周期清理):创建缓存时传入的第二个参数
cleanupInterval会启动一个名为 janitor 的后台 goroutine,周期性调用DeleteExpired(),把Expiration > 0且已过期的条目物理删除(cache.go)。
janitor 的启动与停止细节值得注意(cache.go):它运行在一个独立的 goroutine 里,通过 time.Tick 驱动;newCacheWithJanitor 使用 runtime.SetFinalizer 技巧——当外层 *Cache 对象被 GC 回收时,finalizer 会先向 janitor 发送停止信号,避免后台 goroutine 无限存活导致泄漏。这是源码中一个非常实用的内存安全设计。
参数取值的实际影响
| 参数 | 取值 | 行为 |
|---|---|---|
defaultExpiration |
< 1 或 NoExpiration |
条目默认永不过期,必须手动删除 |
defaultExpiration |
> 0 |
条目默认在该时长后过期 |
cleanupInterval |
< 1 |
不启动 janitor,过期条目需手动调用 c.DeleteExpired() 清理 |
cleanupInterval |
> 0 |
后台按该周期自动清理过期条目 |
官方 README 的原话是:如果过期时长小于 1(或 NoExpiration),条目默认永不过期;如果清理间隔小于 1,则过期条目不会被自动删除,只能手动调用 c.DeleteExpired()(cache.go)。
完整 API 参考:写入、读取、计数与淘汰回调
除 Set / Get 外,官方还提供了一整套面向不同语义的 API:
写入类
Set(k, x, d):写入或覆盖,d可为DefaultExpiration/NoExpiration/ 具体时长(cache.go);SetDefault(k, x):等价于Set(k, x, DefaultExpiration),用缓存默认过期时间写入(cache.go);Add(k, x, d) error:仅当 key 不存在或已过期时才写入,否则返回Item k already exists错误——典型的「只在缺失时设置」语义(cache.go);Replace(k, x, d) error:仅当 key 已存在且未过期时才覆盖,否则返回Item k doesn't exist——与Add恰好互补(cache.go)。
读取类
Get(k) (interface{}, bool):取回值并返回是否命中(cache.go);GetWithExpiration(k) (interface{}, time.Time, bool):取回值的同时返回该条目的过期时刻,未命中或未设过期时返回零值time.Time{}(cache.go)。
数值运算与删除
Increment/Decrement:对缓存中的数值型条目做原子加减,覆盖int、int8/16/32/64、uint、uintptr、float32/64全家族(cache.go),适合做计数器、限流统计;Delete(k):删除条目,若注册了淘汰回调会触发回调(cache.go);DeleteExpired():手动清理全部过期条目(cache.go);ItemCount():返回条目总数(cache.go);Flush():清空整个缓存(cache.go)。
淘汰回调
OnEvicted(func(k string, v interface{})) 可以注册一个回调函数,在任何条目被淘汰(包括手动 Delete)时收到通知,但被覆盖重写时不会触发(cache.go)。这在实现 LRU 旁路、清理下游资源(关闭连接、释放句柄)时非常有用。
持久化:Items() + NewFrom() 的启动恢复方案
go-cache 不打算作为持久化数据存储,但它支持把整个缓存保存到文件、再从文件加载,用于快速恢复停机(官方 README 明确推荐用 c.Items() 取出 items 序列化,再用 NewFrom() 从反序列化结果重建缓存,并提示阅读 NewFrom() 的注意事项)。
Items() map<a href="https://link.gitcode.com/i/7792829849a8b1b99da1b9fc2fd6eed5" target="_blank">string]Item:返回底层条目 map 的快照([cache.go)。官方警告:返回的 map 与缓存共享底层数据,若同时操作需要自行加同步;NewFrom(defaultExpiration, cleanupInterval, items):用一张预先构造好的 map 直接创建缓存(cache.go)。两种典型用途:- 从反序列化的缓存恢复状态——先用
gob.Encode()编码c.Items()的结果持久化,启动时gob.Decode()后再传入NewFrom; - 性能优化——预分配容量,例如传入
make(map[string]Item, 500),当缓存预期达到一定规模时可改善启动性能。
- 从反序列化的缓存恢复状态——先用
- 官方同时强调两个 caveat:只有缓存的方法才会同步访问该 map,不要在外层长期持有引用;用 gob 序列化时必须先用
gob.Register()注册缓存中存储的各具体类型,编码、解码两侧都要注册。
此外,库还提供一组已标记 deprecated 的 Save / SaveFile / Load / LoadFile 方法(基于 gob 直接读写),官方在注释中明确建议改用 Items() + NewFrom() 组合(cache.go)。
进阶:分片缓存 shardedCache 的设计
sharded.go 中还有一个实验性、当前未导出的分片缓存实现(sharded.go)。其动机是改善并发下的算法复杂度:写入时不再锁住整张缓存,而是按 key 哈希路由到某个分片,只锁分片内部的锁,从而避免写入操作互相阻塞。
- 哈希函数
djb33是 DJB2 的变体(作者注释称其比带hash.Hash开销的 FNV 快约 5 倍),用系统 CSPRNG 生成随机种子(sharded.go); bucket(k)通过djb33(seed, k) % m定位分片,各分片就是标准cache实例(sharded.go);- 每个分片有独立的 janitor 后台清理(sharded.go)。
源码注释给出了重要的性能权衡结论:在总缓存规模较小时,分片选择本身的开销使操作比标准缓存慢约两倍;规模较大时则更快。这提示我们在业务中做取舍:小缓存用标准 cache.New 即可,超大并发缓存可考虑分片思路(或等该实现未来导出)。
在 scan4all 仓库中的角色与使用建议
scan4all 将 go-cache 以 vendor 方式固定为依赖(vendor/github.com/patrickmn/go-cache/),同时其上游生态(projectdiscovery 系列)也衍生维护了基于它的缓存实现(hmap 缓存模块的 doc.go 明确标注 Forked and adapted)。这侧面说明:go-cache 适合作为安全扫描、子域枚举、端口探测等工具内部的进程级缓存基础设施——例如去重 URL、缓存 DNS 解析结果、暂存指纹匹配中间结果,这些场景数据量大但生命周期短,正契合"单机 + 内存 + 过期回收"的定位。
实战建议汇总:
- 创建时明确两个时长:默认过期时间决定条目存活,清理间隔决定内存回收频率;扫描类任务建议把默认过期设短,避免脏数据滞留;
- 读必查 found:
Get的 bool 返回值是命中与否的唯一依据; - 优先存指针:避免大结构体在断言时被拷贝;
Add与Replace实现「仅设置一次」「仅更新已有」语义,适合分布式去重和状态机流转;- 需要进程重启恢复时,用
Items()序列化 +NewFrom()重建,并记得对存储类型gob.Register; - 高并发写入场景留意标准缓存的整表写锁,可评估分片方案;
- 数值计数优先用
Increment/Decrement,它们在锁内完成加减,天然线程安全。
参考与延伸
- 官方文档主体:go-cache README
- 核心实现:cache.go(Item 定义、常量、Set/Get、janitor、持久化、New/NewFrom)
- 分片实验实现:sharded.go
- 衍生适配:projectdiscovery/hmap 缓存模块