scan4all 依赖解析:go-cache 内存缓存的安装、并发使用与源码原理

原创2026-09-17 17:43:091,690 阅读
文章标签:网络安全应用安全漏洞扫描渗透测试

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 采用双层过期回收策略:

  1. 惰性过期(读取时检查):Get / GetWithExpiration 在命中 key 后,会额外判断 time.Now().UnixNano() > item.Expiration,一旦过期即视为未命中返回 nil, false。因此即使后台清理尚未执行,过期条目也不会被读出来。

  2. 后台 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)。两种典型用途:
    1. 从反序列化的缓存恢复状态——先用 gob.Encode() 编码 c.Items() 的结果持久化,启动时 gob.Decode() 后再传入 NewFrom;
    2. 性能优化——预分配容量,例如传入 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 解析结果、暂存指纹匹配中间结果,这些场景数据量大但生命周期短,正契合"单机 + 内存 + 过期回收"的定位。

实战建议汇总:

  1. 创建时明确两个时长:默认过期时间决定条目存活,清理间隔决定内存回收频率;扫描类任务建议把默认过期设短,避免脏数据滞留;
  2. 读必查 found:Get 的 bool 返回值是命中与否的唯一依据;
  3. 优先存指针:避免大结构体在断言时被拷贝;
  4. Add 与 Replace 实现「仅设置一次」「仅更新已有」语义,适合分布式去重和状态机流转;
  5. 需要进程重启恢复时,用 Items() 序列化 + NewFrom() 重建,并记得对存储类型 gob.Register;
  6. 高并发写入场景留意标准缓存的整表写锁,可评估分片方案;
  7. 数值计数优先用 Increment/Decrement,它们在锁内完成加减,天然线程安全。

参考与延伸

登录后查看全文
scan4all