轻量型 GLS（Goroutine Local Storage）

Go 1.26 引入了轻量型的 Goroutine Local Storage（GLS），为每个 goroutine 提供了独立的存储空间。本文将详细介绍 GLS 的概念、使用场景、API 以及最佳实践。

什么是 GLS？

GLS（Goroutine Local Storage）是指为每个 goroutine 提供独立的存储空间，类似于线程本地存储（TLS）。每个 goroutine 可以访问和修改自己的数据，而不会影响其他 goroutine。

为什么需要 GLS？

基本用法

1. 创建 GLS 存储区

package main

import (
    "fmt"
    "runtime/gls"
)

// 定义一个 GLS 键
var requestIDKey = gls.NewKey("request-id")

func main() {
    // 为当前 goroutine 设置值
    gls.Set(requestIDKey, "req-12345")
    
    // 获取值
    value := gls.Get(requestIDKey)
    fmt.Println("Request ID:", value)  // Output: Request ID: req-12345
}

2. 跨函数访问 GLS

package main

import (
    "fmt"
    "runtime/gls"
)

var userIDKey = gls.NewKey("user-id")

func processRequest() {
    // 在内部函数中访问 GLS
    userID := gls.Get(userIDKey)
    fmt.Println("Processing for user:", userID)
}

func handleRequest() {
    gls.Set(userIDKey, "user-001")
    processRequest()  // 不需要传递 userID
}

func main() {
    handleRequest()
}

3. 不同 Goroutine 独立存储

package main

import (
    "fmt"
    "sync"
    "runtime/gls"
)

var taskIDKey = gls.NewKey("task-id")

func worker(id int, wg *sync.WaitGroup) {
    defer wg.Done()
    
    // 每个 goroutine 有自己独立的值
    gls.Set(taskIDKey, fmt.Sprintf("task-%d", id))
    
    fmt.Println("Worker", id, "task:", gls.Get(taskIDKey))
}

func main() {
    var wg sync.WaitGroup
    
    for i := 0; i < 3; i++ {
        wg.Add(1)
        go worker(i, &wg)
    }
    
    wg.Wait()
}

API 详解

gls.NewKey

创建一个新的 GLS 键，用于标识存储的值。

func NewKey(name string) *Key
package main

import "runtime/gls"

var (
    userIDKey   = gls.NewKey("user-id")
    traceIDKey  = gls.NewKey("trace-id")
    sessionKey  = gls.NewKey("session")
)

gls.Set

为当前 goroutine 设置键值对。

func Set(key *Key, value interface{})
package main

import (
    "fmt"
    "runtime/gls"
)

var contextKey = gls.NewKey("context")

func main() {
    // 设置简单值
    gls.Set(contextKey, "request-context")
    
    // 设置复杂值
    gls.Set(contextKey, map[string]interface{
        "user": "alice",
        "role": "admin",
    })
    
    fmt.Println(gls.Get(contextKey))
}

gls.Get

获取当前 goroutine 中键对应的值。

func Get(key *Key) interface{}
package main

import (
    "fmt"
    "runtime/gls"
)

var counterKey = gls.NewKey("counter")

func increment() {
    var count int
    if val := gls.Get(counterKey); val != nil {
        count = val.(int)
    }
    count++
    gls.Set(counterKey, count)
}

func main() {
    increment()
    increment()
    fmt.Println("Count:", gls.Get(counterKey))  // Output: Count: 2
}

gls.Delete

删除当前 goroutine 中的键值对。

func Delete(key *Key)
package main

import (
    "fmt"
    "runtime/gls"
)

var tempKey = gls.NewKey("temp")

func main() {
    gls.Set(tempKey, "temporary data")
    fmt.Println("Before delete:", gls.Get(tempKey))
    
    gls.Delete(tempKey)
    fmt.Println("After delete:", gls.Get(tempKey))  // Output: After delete: <nil>
}

gls.Clear

清除当前 goroutine 的所有 GLS 数据。

func Clear()
package main

import (
    "fmt"
    "runtime/gls"
)

var (
    key1 = gls.NewKey("key1")
    key2 = gls.NewKey("key2")
    key3 = gls.NewKey("key3")
)

func main() {
    gls.Set(key1, "value1")
    gls.Set(key2, "value2")
    gls.Set(key3, "value3")
    
    fmt.Println("Before clear:", gls.Get(key1), gls.Get(key2), gls.Get(key3))
    
    gls.Clear()
    
    fmt.Println("After clear:", gls.Get(key1), gls.Get(key2), gls.Get(key3))
}

gls.With

在函数作用域内临时设置 GLS 值，函数返回后自动恢复。

func With(key *Key, value interface{}, f func())
package main

import (
    "fmt"
    "runtime/gls"
)

var operationKey = gls.NewKey("operation")

func doWork() {
    fmt.Println("Current operation:", gls.Get(operationKey))
}

func main() {
    gls.Set(operationKey, "main")
    
    doWork()  // Output: Current operation: main
    
    // 临时修改操作名称
    gls.With(operationKey, "temporary", func() {
        doWork()  // Output: Current operation: temporary
    })
    
    doWork()  // Output: Current operation: main (已恢复)
}

gls.Range

遍历当前 goroutine 的所有 GLS 键值对。

func Range(f func(key *Key, value interface{}) bool)
package main

import (
    "fmt"
    "runtime/gls"
)

var (
    nameKey  = gls.NewKey("name")
    ageKey   = gls.NewKey("age")
    emailKey = gls.NewKey("email")
)

func main() {
    gls.Set(nameKey, "Alice")
    gls.Set(ageKey, 30)
    gls.Set(emailKey, "alice@example.com")
    
    fmt.Println("All GLS values:")
    gls.Range(func(key *Key, value interface{}) bool {
        fmt.Printf("  %s: %v\n", key.Name(), value)
        return true
    })
}

实际应用场景

1. 请求追踪（Request Tracing）

在 Web 请求处理中追踪请求 ID，方便日志关联和调试。

package main

import (
    "fmt"
    "log"
    "runtime/gls"
)

var traceIDKey = gls.NewKey("trace-id")

func logWithTrace(message string) {
    traceID := gls.Get(traceIDKey)
    log.Printf("[%s] %s\n", traceID, message)
}

func processRequest() {
    logWithTrace("Processing request")
    logWithTrace("Validating input")
    logWithTrace("Processing complete")
}

func handleRequest(traceID string) {
    gls.Set(traceIDKey, traceID)
    processRequest()
}

func main() {
    handleRequest("trace-12345")
}

2. 用户上下文管理

在微服务架构中传递用户信息，避免在每个函数中传递参数。

package main

import (
    "fmt"
    "runtime/gls"
)

type UserContext struct {
    UserID   string
    Username string
    Role     string
}

var userContextKey = gls.NewKey("user-context")

func getCurrentUser() *UserContext {
    if val := gls.Get(userContextKey); val != nil {
        return val.(*UserContext)
    }
    return nil
}

func checkPermission(resource string) bool {
    user := getCurrentUser()
    if user == nil {
        return false
    }
    
    if user.Role == "admin" {
        return true
    }
    
    // 其他权限检查逻辑
    return false
}

func accessResource(resource string) {
    if checkPermission(resource) {
        fmt.Printf("User %s can access %s\n", 
            getCurrentUser().Username, resource)
    } else {
        fmt.Println("Access denied")
    }
}

func main() {
    user := &UserContext{
        UserID:   "user-001",
        Username: "alice",
        Role:     "admin",
    }
    
    gls.Set(userContextKey, user)
    accessResource("secret-data")
}

3. 数据库连接管理

为每个请求提供独立的数据库连接，避免连接混淆。

package main

import (
    "fmt"
    "runtime/gls"
)

type DBConnection struct {
    ID     string
    Active bool
}

var dbConnectionKey = gls.NewKey("db-connection")

func getDBConnection() *DBConnection {
    if val := gls.Get(dbConnectionKey); val != nil {
        return val.(*DBConnection)
    }
    
    // 创建新连接
    conn := &DBConnection{
        ID:     fmt.Sprintf("conn-%d", gls.GoroutineID()),
        Active: true,
    }
    gls.Set(dbConnectionKey, conn)
    return conn
}

func queryData() {
    conn := getDBConnection()
    fmt.Printf("Querying with connection: %s\n", conn.ID)
}

func main() {
    queryData()
}

4. 错误处理和恢复

在错误处理中保留上下文信息，便于错误追踪。

package main

import (
    "fmt"
    "runtime/gls"
)

var operationKey = gls.NewKey("operation")

func safeExecute(operation string, f func()) {
    gls.With(operationKey, operation, func() {
        defer func() {
            if r := recover(); r != nil {
                op := gls.Get(operationKey)
                fmt.Printf("Panic in operation '%s': %v\n", op, r)
            }
        }()
        f()
    })
}

func riskyOperation() {
    panic("something went wrong")
}

func main() {
    safeExecute("data-processing", riskyOperation)
}

5. 配置覆盖

在测试或特定场景中临时覆盖配置。

package main

import (
    "fmt"
    "runtime/gls"
)

var configKey = gls.NewKey("config")

type Config struct {
    Debug bool
    MaxRetries int
}

func getConfig() *Config {
    if val := gls.Get(configKey); val != nil {
        return val.(*Config)
    }
    // 返回默认配置
    return &Config{Debug: false, MaxRetries: 3}
}

func doOperation() {
    config := getConfig()
    fmt.Printf("Debug: %v, MaxRetries: %d\n", config.Debug, config.MaxRetries)
}

func main() {
    // 使用默认配置
    doOperation()
    
    // 临时使用测试配置
    testConfig := &Config{Debug: true, MaxRetries: 1}
    gls.With(configKey, testConfig, func() {
        doOperation()
    })
    
    // 恢复默认配置
    doOperation()
}

最佳实践

1. 避免滥用

GLS 应该谨慎使用，不要过度依赖。它适用于特定的场景，如请求追踪、上下文传递等。

2. 明确键的命名

使用清晰、唯一的键名，避免冲突。

// 好的做法
var requestTraceIDKey = gls.NewKey("request-trace-id")
var userAuthenticationTokenKey = gls.NewKey("user-auth-token")

// 不好的做法
var key1 = gls.NewKey("k1")
var key2 = gls.NewKey("k2")

3. 及时清理

在使用完毕后及时清理 GLS 数据，避免内存泄漏。

func processRequest() {
    gls.Set(traceIDKey, traceID)
    defer gls.Delete(traceIDKey)
    
    // 处理请求
}

4. 类型安全

使用类型断言时要小心，确保类型安全。

func getUserName() string {
    val := gls.Get(userNameKey)
    if val == nil {
        return ""
    }
    
    if name, ok := val.(string); ok {
        return name
    }
    
    return ""
}

5. 文档说明

在使用 GLS 的代码中添加文档说明，帮助其他开发者理解。

// processUser 处理用户请求。
//
// 此函数依赖 GLS 存储用户上下文信息：
//   - user-context: 用户上下文对象，包含用户 ID 和角色
//
// 必须在调用此函数之前通过 gls.Set 设置用户上下文。

6. 考虑 Context 作为替代

在某些场景下，使用 context.Context 可能是更好的选择。

// 使用 Context
func processWithContext(ctx context.Context) {
    userID := ctx.Value("user-id").(string)
    // 处理逻辑
}

// 使用 GLS
func processWithGLS() {
    userID := gls.Get(userIDKey).(string)
    // 处理逻辑
}

性能考虑

1. 内存开销

GLS 的实现非常轻量，每个 goroutine 的存储开销很小。但仍然应该避免存储大量数据。

2. 访问速度

GLS 的访问速度非常快，接近于普通变量访问。但在性能关键路径上，应该进行基准测试。

package main

import (
    "runtime/gls"
    "testing"
)

var testKey = gls.NewKey("test")

func BenchmarkGLSGet(b *testing.B) {
    gls.Set(testKey, "value")
    b.ResetTimer()
    
    for i := 0; i < b.N; i++ {
        _ = gls.Get(testKey)
    }
}

3. 与 Context 的对比

限制和注意事项

1. Goroutine 生命周期

GLS 数据与 goroutine 绑定，goroutine 结束后数据会被自动清理。

2. 跨 Goroutine 访问

GLS 数据不能跨 goroutine 访问，每个 goroutine 有自己独立的存储空间。

func main() {
    gls.Set(key, "main-value")
    
    go func() {
        // 这里获取不到 main goroutine 的值
        fmt.Println(gls.Get(key))  // Output: <nil>
    }()
}

3. 与 Go Context 的关系

GLS 和 Context 是互补的机制，应该根据场景选择使用。

总结

Go 1.26 引入的轻量型 GLS 为开发者提供了一个强大而灵活的工具，用于管理 goroutine 级别的存储。通过合理使用 GLS，可以：

但同时也要注意，GLS 应该谨慎使用，避免滥用导致代码难以理解和维护。在实际应用中，应该根据具体场景选择最合适的方案。