Golang context.Context 传播实践咨询：HTTP JSON API 场景问题处理

我之前在开发HTTP JSON API服务时，也碰到过和你一模一样的context传播问题——想把request id这类链路标识通过context传递，让所有自研包的日志都带上统一的transaction id。结合踩过的坑和实际落地的经验，给你梳理下核心思路和具体实现方案：

• 明确context的定位：它是请求级别的临时上下文容器，只存请求生命周期内的链路标识（如request id、用户身份）、取消信号这类数据，绝对不要放全局配置、数据库连接这类进程级/持久化资源。
• 强制显式传播：context的核心就是“传递”，从请求入口注入标识后，所有下游调用（函数、goroutine、自研工具包）必须显式携带context参数，不能偷懒用空context或者全局context。
• 日志链路整合：把context和日志工具绑定，避免每次打日志都手动从context里取标识，实现“一次注入，全链路自动携带”。

1. 请求入口注入核心标识 #

在HTTP handler的最外层中间件里，生成或获取request id（也可以从请求头X-Request-ID读取，兼容网关传递的标识），存入context后传递给后续业务逻辑：

import (
    "context"
    "net/http"
    "github.com/google/uuid"
)

// 自定义context key类型，避免和其他包的key冲突
type contextKey string

const (
    requestIDKey contextKey = "requestID"
    userIDKey    contextKey = "userID" // 示例：扩展存储用户身份
)

// 请求入口中间件：注入request id到context
func injectRequestID(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // 优先从请求头获取，没有则生成新的
        requestID := r.Header.Get("X-Request-ID")
        if requestID == "" {
            requestID = uuid.NewString()
        }
        // 将request id存入context，生成新的context传递
        ctx := context.WithValue(r.Context(), requestIDKey, requestID)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

把这个中间件注册到你的路由上，比如用gorilla/mux的话：

r := mux.NewRouter()
r.Use(injectRequestID)
// 注册你的业务handler
r.HandleFunc("/api/v1/xxx", myBusinessHandler)

2. 跨Goroutine的Context传递 #

如果业务中有异步goroutine处理任务，必须把当前请求的context显式传入goroutine，绝对不能用context.Background()：

// 错误示例：用空context，无法获取request id
go func() {
    log.Println("async task finished") // 日志无链路标识
}()

// 正确示例：传递请求context
func myBusinessHandler(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()
    // 传入context到goroutine
    go func(ctx context.Context) {
        if requestID, ok := ctx.Value(requestIDKey).(string); ok {
            log.Printf("[%s] async task finished", requestID)
        }
        // 如果goroutine需要长时间运行，建议用WithCancel绑定请求生命周期
        // 避免请求结束后goroutine还在占用资源
    }(ctx)
}

3. 封装日志工具自动携带Context标识 #

为了避免每次打日志都手动取request id，最好封装一套日志工具，自动从context中提取链路标识：

基础版日志封装 #

import (
    "context"
    "fmt"
    "log"
)

func CtxLog(ctx context.Context, format string, v ...interface{}) {
    requestID := "unknown"
    if id, ok := ctx.Value(requestIDKey).(string); ok {
        requestID = id
    }
    // 把request id作为前缀加入日志
    log.Printf("[%s] %s", requestID, fmt.Sprintf(format, v...))
}

// 业务代码中直接使用
func myBusinessHandler(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()
    CtxLog(ctx, "received request for path: %s", r.URL.Path)
    // ...其他业务逻辑
}

成熟日志库整合（以Zap为例） #

如果用Zap这类结构化日志库，可以自定义一个带context的logger，自动注入链路标识：

import (
    "context"
    "go.uber.org/zap"
)

func NewCtxLogger(ctx context.Context, baseLogger *zap.Logger) *zap.Logger {
    logger := baseLogger
    // 从context中提取request id加入日志字段
    if requestID, ok := ctx.Value(requestIDKey).(string); ok {
        logger = logger.With(zap.String("request_id", requestID))
    }
    // 可以扩展提取其他字段，比如user_id
    if userID, ok := ctx.Value(userIDKey).(string); ok {
        logger = logger.With(zap.String("user_id", userID))
    }
    return logger
}

// 业务代码中使用
func myBusinessHandler(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()
    logger := NewCtxLogger(ctx, zap.L())
    logger.Info("request processed", zap.String("path", r.URL.Path))
    // 日志输出会自动包含request_id字段
}

4. 避免Context滥用的注意事项 #

• 不要用context传递常规参数：如果某个值是函数的必需输入（比如订单ID、分页参数），直接作为函数参数传递，不要存在context里——context是用来传递“请求上下文”，不是万能参数容器。
• 自定义key类型：一定要用自定义类型（比如上面的contextKey string）作为context的key，避免和其他包的key冲突（context.Value是基于类型+值判断唯一性的）。
• 不要存可变数据：context中的内容应该是只读的，禁止在下游函数中修改context里的值，避免并发问题。

5. 进程级数据的处理 #

你提到的“从进程中解析的相关数据”属于全局状态，不适合存在request级的context里，建议用全局变量或者依赖注入的方式管理：

// 进程启动时初始化的全局信息
var processMeta struct {
    ServiceName string
    Version     string
    Env         string
}

func init() {
    processMeta.ServiceName = "my-json-api"
    processMeta.Version = "v1.2.3"
    processMeta.Env = "production"
}

// 日志中同时携带进程信息和请求链路标识
func CtxLog(ctx context.Context, format string, v ...interface{}) {
    requestID := "unknown"
    if id, ok := ctx.Value(requestIDKey).(string); ok {
        requestID = id
    }
    log.Printf("[%s][%s/%s/%s] %s", 
        requestID, 
        processMeta.ServiceName, 
        processMeta.Version, 
        processMeta.Env, 
        fmt.Sprintf(format, v...))
}

内容的提问来源于stack exchange，提问作者lucabelluccini