Go / 系统课时
安全使用 Context Value
安全使用 Context Value
context.Context 可以随一次请求在中间件和处理器之间传递少量元数据,但它不是通用参数包。本篇用请求身份示例建立安全边界:私有键避免冲突,读取时做类型检查,并把业务依赖继续放在显式参数或结构体字段中。
学习目标
- 使用私有键类型安全地写入和读取请求作用域值
- 区分适合放入 Context 的元数据与应显式传递的业务依赖
- 处理缺失值、类型不匹配和键冲突等常见边界
Context Value 只承载请求元数据
HTTP 请求天然携带一个 Context。中间件可以基于 r.Context() 派生新上下文,再通过 r.WithContext(ctx) 把它交给后续处理器。适合放入其中的是“跟着这次请求走”的少量信息,例如认证后的用户 ID、请求 ID 或租户 ID。

Context 中的值不应成为普通函数参数的替代品。数据库、客户端、仓储对象、配置和业务服务都有稳定的依赖关系,应由构造函数、结构体字段或函数参数显式表达,否则调用关系会变得不可见,也难以测试。若身份来自请求头,生产环境还必须由可信认证层校验或注入,不能直接相信公网客户端自报的用户 ID。
用私有键类型隔离命名空间
不要直接用字符串 "userID" 作为键。不同包可能恰好选择同一个字符串,造成无意覆盖。定义当前包私有的键类型和键值后,只有持有该键的代码才能可靠读取对应数据。
package main
import (
"context"
"fmt"
"net/http"
"net/http/httptest"
)
type contextKey string
const userIDKey contextKey = "user-id"
func withIdentity(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
userID := r.Header.Get("X-User-ID")
// 只把已经得到的请求身份写入派生 Context。
ctx := context.WithValue(r.Context(), userIDKey, userID)
next.ServeHTTP(w, r.WithContext(ctx))
})
}
func profile(w http.ResponseWriter, r *http.Request) {
userID, ok := r.Context().Value(userIDKey).(string)
// 缺失值和类型不匹配都按“没有有效身份”处理。
if !ok || userID == "" {
http.Error(w, "missing user id", http.StatusUnauthorized)
return
}
fmt.Fprintf(w, "user=%s", userID)
}
func main() {
req := httptest.NewRequest(http.MethodGet, "/profile", nil)
req.Header.Set("X-User-ID", "u-42")
rec := httptest.NewRecorder()
handler := withIdentity(http.HandlerFunc(profile))
handler.ServeHTTP(rec, req)
fmt.Println(rec.Code)
fmt.Println(rec.Body.String())
}预期输出
200
user=u-42示例中的 contextKey 与 userIDKey 都没有导出,其他包即使也使用 "user-id" 这个文本,也不会得到同一个动态键类型和值组合。读取时使用带 ok 的类型断言,可以避免值不存在或类型变化时触发 panic。
把依赖留在显式接口中
判断某个值是否应该进入 Context,可以问两个问题:它是否只在本次请求生命周期内有意义,以及它是否需要跨越 API 边界随请求传播。两个答案都接近“是”时,Context Value 才通常合适。
例如用户 ID、请求 ID 属于请求元数据;*sql.DB、HTTP 客户端、配置对象、缓存客户端和业务服务则是程序依赖。后者应放在处理器结构体中,让依赖在类型定义和测试构造阶段就可见。
读取边界要集中
工程中可以进一步把写入和读取封装成 withUserID、userIDFromContext 之类的包内函数,使键本身不暴露给业务代码。这样既能统一缺失值处理,也便于未来调整底层表示。
对于必须存在的业务输入,例如订单号、分页参数或待处理实体,仍应通过函数参数传递;Context Value 更适合“附着在请求上的辅助元数据”。守住这条边界,才能在获得跨中间件传递便利的同时,不牺牲接口可读性。