Gin 默认无状态因其不内置session、cookie或状态缓存，每个Context独立生命周期；确保无状态需避免全局变量、显式注入依赖、JWT替代session、防范中间件隐式状态泄漏。
为什么 Gin 的默认行为天然适合无状态 API
Gin 本身不内置 session、cookie 管理或请求间状态缓存，每个 gin.Context 都是独立生命周期，从接收请求到写出响应全程无共享内存（除非你手动往 c.Set() 里塞东西或用全局变量）。这意味着只要你不主动引入外部状态依赖，Gin 接口默认就是无状态的——它不保存用户登录态、不维护连接上下文、不缓存前序请求数据。
但现实里容易踩坑的地方在于：开发者常误以为“没写 session 就安全”，结果在中间件里用了闭包捕获变量、在 handler 中复用 struct 实例、或直接把数据库连接池当状态容器传参，导致并发下数据错乱。
如何确保 handler 函数真正无状态
无状态的核心是：同一输入（URL + method + body + headers）在任意时刻、任意实例上，都应产生相同输出，且不改变任何服务端持久化或共享内存状态。
- 避免在 handler 内使用包级变量或全局 map 存储临时数据，比如
var userCache = make(map[string]*User)—— 这会变成隐式状态，且非线程安全 - 所有依赖必须显式注入：数据库句柄、配置、日志实例等，通过
func(c *gin.Context)外部传入，而非在 handler 内部调用GetDB()单例函数 - 禁止在 handler 中修改传入的
c.Request.Body或重用c.Request结构体字段（如反复调用c.ShouldBindJSON()会因 body 已读完而失败） - 若需解析多次 body，用
c.Request.Body = io.NopCloser(bytes.NewBuffer(bodyBytes))显式重置，但更推荐只解析一次并存为局部变量
JWT 替代 session 实现认证态无状态化
传统 session 把用户信息存在服务端（Redis / DB），违背无状态原则；JWT 则把加密后的用户 ID、角色、过期时间等编码进 token，由客户端每次携带，服务端只需校验签名和有效期，无需查库。
立即学习“go语言免费学习笔记（深入）”；
实操要点：
- 用
github.com/golang-jwt/jwt/v5而非老版本，避免已知漏洞 - 签发时只放必要字段，如
claims := jwt.MapClaims{"uid": 123, "exp": time.Now().Add(24*time.Hour).Unix()}，不放敏感信息（密码哈希、权限列表全量） - 校验必须包含
VerifySignature和ValidateExp，否则攻击者可篡改过期时间 - 不要在 Gin 中间件里用
c.Set("user_id", uid)后续 handler 直接读取——这仍是内存态。应改为每次需要时从 context 解析 token 并验证，或把解析结果作为参数传给业务函数
注意中间件链中的隐式状态泄漏
看似无害的中间件可能悄悄引入状态：比如日志中间件记录请求耗时，若用 time.Now() 记录开始时间后，在 defer 里读取 c.Writer.Size()，这没问题；但若中间件里做了 c.Set("trace_id", genID())，然后后续 handler 又依赖这个 trace_id 做逻辑分支，就等于把 trace_id 当成了控制流状态。
更危险的是错误恢复中间件：
func Recovery() gin.HandlerFunc {
return func(c *gin.Context) {
defer func() {
if err := recover(); err != nil {
c.AbortWithStatusJSON(500, gin.H{"error": "internal error"})
// ❌ 错误：这里 c 已被 Abort，再调用 c.Next() 或写响应会 panic
}
}()
c.Next()
}
}
这类代码会让多个中间件对同一个 c 产生竞态。真正无状态的做法是：中间件只做纯函数式转换（加 header、记录指标、鉴权），不干预控制流，异常统一由顶层 handler 或专用错误中间件处理。
复杂点往往不在 Gin 本身，而在于你是否把“无状态”当成接口契约来约束每一层——从路由定义、中间件顺序，到数据库查询方式，甚至单元测试的数据 setup 方式，都得按这个前提设计。否则上线后横向扩缩容或灰度发布时，状态不一致的问题才真正浮现。
