性能优化

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	✅
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 关闭

全局加载器重置

// 并发不安全：不要在运行时调用
env.ResetDefaultLoader()

// 安全：仅在测试或启动时调用
func init() {
    env.ResetDefaultLoader()
    env.Load(".env")
}

性能优化 ​

并发安全 ​

线程安全保证 ​

包级函数线程安全 ​

内部实现 ​

对象池 ​

为什么使用对象池 ​

SecureValue 池 ​

正确使用对象池 ​

内存安全 ​

内存锁定 ​

严格模式 ​

安全清零 ​

性能模式 ​

初始化后只读 ​

动态配置刷新 ​

减少锁持有时间 ​

批量操作 ​

避免频繁调用 ​

性能影响 ​

对象池收益 ​

内存锁定开销 ​

基准测试 ​

读取性能 ​

写入性能 ​

混合读写 ​

注意事项 ​

避免在锁内阻塞 ​

Close 后的并发访问 ​

全局加载器重置 ​

相关文档 ​