性能优化

env 库针对高性能场景进行了优化。本文档介绍并发安全、对象池、内存管理等性能相关特性。

并发安全

线程安全保证

Loader 的所有方法都是线程安全的：

loader, _ := env.New(env.DefaultConfig())
defer loader.Close()

var wg sync.WaitGroup

// 并发读取
for i := 0; i < 100; i++ {
    wg.Add(1)
    go func() {
        defer wg.Done()
        loader.GetString("KEY")
    }()
}

// 并发写入
for i := 0; i < 100; i++ {
    wg.Add(1)
    go func(n int) {
        defer wg.Done()
        loader.Set(fmt.Sprintf("KEY_%d", n), "value")
    }(i)
}

wg.Wait()

包级函数线程安全

包级函数使用全局加载器，同样是线程安全的：

var wg sync.WaitGroup

for i := 0; i < 100; i++ {
    wg.Add(1)
    go func() {
        defer wg.Done()
        env.GetString("KEY", "default")
    }()
}

wg.Wait()

内部实现

库使用分片存储（Sharded Storage）减少锁竞争：

text

┌─────────────────────────────────────────┐
│          Loader（8 个分片）               │
├─────────────────────────────────────────┤
│  ┌─────────┐ ┌─────────┐    ┌────────┐ │
│  │ Shard 0 │ │ Shard 1 │... │ Shard 7│ │
│  │  Lock   │ │  Lock   │    │  Lock  │ │
│  │  Data   │ │  Data   │    │  Data  │ │
│  └─────────┘ └─────────┘    └────────┘ │
└─────────────────────────────────────────┘

键根据哈希值分配到不同分片
每个分片有独立锁
减少锁竞争，提高并发性能

对象池

为什么使用对象池

频繁创建和销毁对象会增加 GC 压力：

text

无对象池：
创建对象 → 使用 → GC 回收 → 创建对象 → 使用 → GC 回收 ...

有对象池：
创建对象 → 使用 → 放回池 → 获取 → 使用 → 放回池 ...

SecureValue 池

SecureValue 对象使用池化管理：

// 获取 SecureValue（可能从池中复用）
secret := env.GetSecure("API_KEY")

// 使用（Reveal 返回明文，String/Masked 返回掩码）
value := secret.Reveal()

// 释放回池
secret.Close()  // 或 secret.Release()

正确使用对象池

及时释放：

func processData() {
    secret := env.GetSecure("SECRET")
    defer secret.Close()  // 确保释放

    // 使用 secret...
}

不要持有引用：

// 错误：持有已释放对象的引用
var globalSecret *env.SecureValue

func init() {
    globalSecret = env.GetSecure("KEY")
    globalSecret.Close()  // 释放后对象被复用
}

func later() {
    // 危险：globalSecret 可能已被其他代码使用
    globalSecret.String()
}

// 正确：每次需要时获取
func getSecret() string {
    secret := env.GetSecure("KEY")
    defer secret.Close()
    return secret.Reveal()
}

检查关闭状态：

secret := env.GetSecure("KEY")

// 使用前检查
if secret.IsClosed() {
    // 对象已关闭，不可使用
}

// 使用后关闭
secret.Close()

// 关闭后检查
if secret.IsClosed() {
    // 已关闭
}

内存安全

内存锁定

启用内存锁定防止敏感数据交换到磁盘：

// 检查平台支持
if env.IsMemoryLockSupported() {
    env.SetMemoryLockEnabled(true)
}

平台支持：

平台	支持
Linux	✅
macOS	✅
Windows	✅
其他平台（FreeBSD/其他 BSD、Solaris、WASM 等）	❌

详见

SecureValue API - 内存锁定配置获取完整配置说明。

严格模式

严格模式下，内存锁定失败会导致错误：

env.SetMemoryLockStrict(true)

secret, err := env.NewSecureValueStrict("sensitive_data")
if err != nil {
    // 内存锁定失败
}

安全清零

SecureValue 关闭时自动清零内存：

secret := env.GetSecure("PASSWORD")
// 内部存储：['p', 'a', 's', 's', ...]

secret.Close()
// 内部存储：[0, 0, 0, 0, ...]

手动清零字节切片：

sensitiveBytes := []byte("secret")
env.ClearBytes(sensitiveBytes)
// sensitiveBytes 现在全是 0

性能模式

初始化后只读

最高效的模式：启动时加载配置，运行时只读：

var config *Config

func init() {
    env.Load(".env")

    config = &Config{}
    env.ParseInto(config)
}

// 任意 goroutine 安全读取
func getValue() string {
    return config.Key
}

动态配置刷新

需要动态更新配置时的模式：

type ConfigManager struct {
    loader *env.Loader
    mu     sync.RWMutex
}

func (m *ConfigManager) Refresh() error {
    m.mu.Lock()
    defer m.mu.Unlock()

    return m.loader.LoadFiles(".env")
}

func (m *ConfigManager) Get(key string) string {
    m.mu.RLock()
    defer m.mu.RUnlock()

    return m.loader.GetString(key)
}

减少锁持有时间

// 不推荐：在锁内执行耗时操作
func (l *Loader) ProcessValue(key string) {
    value := l.GetString(key)
    // 耗时操作...
    processValue(value)
}

// 推荐：快速读取，锁外处理
func ProcessValue(key string) {
    value := loader.GetString(key)  // 快速获取
    go processValue(value)          // 异步处理
}

批量操作

// 一次性获取所有需要的值
func LoadAllConfig(loader *env.Loader) *Config {
    return &Config{
        Host:    loader.GetString("HOST"),
        Port:    loader.GetInt("PORT"),
        Debug:   loader.GetBool("DEBUG"),
        Timeout: loader.GetDuration("TIMEOUT"),
    }
}

避免频繁调用

// 不推荐：每次请求都读取
func Handler(w http.ResponseWriter, r *http.Request) {
    apiKey := env.GetString("API_KEY")  // 每次请求都加锁
    // ...
}

// 推荐：启动时缓存
var apiKey string

func init() {
    env.Load(".env")
    apiKey = env.GetString("API_KEY")
}

func Handler(w http.ResponseWriter, r *http.Request) {
    // 直接使用缓存值
    // ...
}

性能影响

对象池收益

操作	无池	有池
分配次数	N	~常数
GC 压力	高	低
延迟	不稳定	稳定

内存锁定开销

内存锁定（Linux 的 mlock / Windows 的 VirtualLock）仅在创建 SecureValue 时产生一次额外的 syscall 开销，读取操作（Reveal / String / Masked）无差异。建议保持 SecureValue 小而短命——用完立即 Close() / Release() 归还到对象池，避免长期持有大块锁定内存。

基准测试

读取性能

func BenchmarkConcurrentRead(b *testing.B) {
    loader, _ := env.New(env.DefaultConfig())
    loader.Set("KEY", "value")

    b.RunParallel(func(pb *testing.PB) {
        for pb.Next() {
            loader.GetString("KEY")
        }
    })
}

写入性能

func BenchmarkConcurrentWrite(b *testing.B) {
    loader, _ := env.New(env.DefaultConfig())

    var i int64
    b.RunParallel(func(pb *testing.PB) {
        for pb.Next() {
            n := atomic.AddInt64(&i, 1)
            loader.Set(fmt.Sprintf("KEY_%d", n), "value")
        }
    })
}

混合读写

func BenchmarkMixedReadWrite(b *testing.B) {
    loader, _ := env.New(env.DefaultConfig())
    loader.Set("KEY", "value")

    b.RunParallel(func(pb *testing.PB) {
        i := 0
        for pb.Next() {
            if i%10 == 0 {
                loader.Set("KEY", "new_value")
            } else {
                loader.GetString("KEY")
            }
            i++
        }
    })
}

注意事项

避免在锁内阻塞

// 危险：可能导致死锁
func (l *Loader) BadMethod() {
    // 锁内调用可能阻塞的操作
    l.Set("KEY", computeValue())  // computeValue 可能很慢
}

// 安全：先计算，再设置
func GoodMethod() {
    value := computeValue()  // 锁外计算
    loader.Set("KEY", value)  // 快速设置
}

Close 后的并发访问

loader, _ := env.New(cfg)

// 启动 goroutine
go func() {
    time.Sleep(1 * time.Second)
    loader.GetString("KEY")  // 返回空字符串（GetString 不返回 error）
}()

loader.Close()  // 主 goroutine 关闭

全局加载器重置

ResetDefaultLoader 本身是并发安全的（源码注释明示），返回关闭旧 loader 的 error，应检查处理。但仍建议仅在测试或启动阶段调用：重置后到下一次 Load 之前，全局函数会短暂回到未初始化状态（返回 ErrNotInitialized），运行中重置会让依赖全局加载器的代码撞上这一窗口。

// 并发安全，但建议仅在测试或启动阶段调用；返回的 error 应处理
if err := env.ResetDefaultLoader(); err != nil {
    fmt.Printf("重置默认加载器失败: %v\n", err)
}
env.Load(".env")

内部并发实现深读

本节从源码层面说明库的并发优化手段，帮助评估与调优。文中引用的量化数字（如 23.6% 原子操作热点、终结器约占创建成本 60%）来自 v1.2.2/v1.2.3 的基准测试与性能剖析（见 CHANGES.md）。

分片存储（secureMap）

所有变量以 SecureValue 形式存储在 8 个分片中，键经 FNV-1a 哈希定位分片，每个分片持有独立 sync.RWMutex——不同分片的读写完全并行，将锁竞争分散化。

批量写入的分桶

secureMap.SetAll/secureMap.SetAllIfAbsent（文件加载路径）将整批键值按分桶一次平坦分配，随后每个分片只加锁一次完成整批写入；已存在的键原地更新（复用 SecureValue 对象），避免对象池往返与额外分配。

读路径的锁优化

单键读取无锁化：Lookup/GetSecure 以原子闭态标志绕过 loader 级读锁——高并发下 RWMutex 自身的读者计数就是瓶颈
secureMap.Has 零分配：仅原子读取 closed 标志，不复制值字符串
Get 免二次加锁：分片读锁已保证 SecureValue 数据稳定，省去对象级读锁（该锁曾是剖析中 23.6% 的原子操作热点）
Set 快路径：OverwriteExisting=true 且未开 AutoApply 时仅需读锁，并发 Set 不在 loader 互斥锁上串行

对象池与终结器

SecureValue 经 sync.Pool 复用；GC 终结器在对象首次创建时设置一次（约占地创建成本 60%），池化循环不再重复支付。覆盖已有键时原地重置，进一步减少分配。

近似快照语义

Len 用原子计数器 O(1) 返回；Keys/ToMap 以原子计数估算容量后遍历分片。并发写入下结果可能是略过期的近似值（遍历期间的其他修改不保证可见）——需要精确快照时由调用方外部同步。

审计的性能开关意识

审计启用后，加载路径会增加 time.Now 与事件构造开销（未启用时这些成本完全规避）。高频场景建议仅在 Production 预设下开启审计，或使用 ChannelAuditHandler 异步消费。

性能优化 ​

并发安全 ​

线程安全保证 ​

包级函数线程安全 ​

内部实现 ​

对象池 ​

为什么使用对象池 ​

SecureValue 池 ​

正确使用对象池 ​

内存安全 ​

内存锁定 ​

严格模式 ​

安全清零 ​

性能模式 ​

初始化后只读 ​

动态配置刷新 ​

减少锁持有时间 ​

批量操作 ​

避免频繁调用 ​

性能影响 ​

对象池收益 ​

内存锁定开销 ​

基准测试 ​

读取性能 ​

写入性能 ​

混合读写 ​

注意事项 ​

避免在锁内阻塞 ​

Close 后的并发访问 ​

全局加载器重置 ​

内部并发实现深读 ​

分片存储（secureMap） ​

批量写入的分桶 ​

读路径的锁优化 ​

对象池与终结器 ​

近似快照语义 ​

审计的性能开关意识 ​

相关文档 ​