csrf token由crypto/rand生成32字节加密随机数，base64编码，与用户session.id强绑定并服务端持久化存储；首次请求生成，后续从上下文提取；需同时置于cookie（samesite=lax）和表单隐藏字段中比对验证。
CSRF Token 是怎么生成的
gin-contrib/csrf 和 gorilla/csrf 底层都依赖 crypto/rand 生成加密安全的随机字节，再经 base64 编码为字符串。不是时间戳、不是 session ID 拼接，也不是简单哈希——必须是不可预测、一次性、与用户会话绑定的值。
关键点在于：Token 必须和当前用户的 session.ID（或等效标识）强关联，且服务端需在内存或 Redis 中持久化存储该 Token 的有效状态（比如过期时间、是否已使用）。否则攻击者可复用旧 Token 或暴力猜测。
- 默认长度为 32 字节（
rand.Read读取），编码后约 44 字符 - 每次调用
csrf.Token(r)不会重复生成新值，而是从当前请求上下文里提取已生成的 Token；首次访问时才真正生成并存入 session - 若未启用 session（如纯 API 场景），需手动绑定 Token 到
context并配合自定义存储逻辑
为什么 Token 要放在 Cookie + 表单双位置
CSRF 防护要求「服务端可验证」且「前端能可靠携带」。只放 Cookie 会被 SameSite 属性限制；只放表单字段易被 XSS 窃取。所以标准做法是：服务端下发一个签名过的 _csrf Cookie（HttpOnly=false，SameSite=Lax），同时在 HTML 模板中用 {{.CsrfField}} 插入隐藏字段 <input type="hidden" name="csrf_token" value="...">。
中间件验证时，会比对这两个来源是否一致、签名是否有效、是否过期。不一致即拒绝请求。
- Cookie 的
SameSite=Lax可防大部分跨站 POST，但不能替代 Token 验证 - 隐藏字段值不能直接等于 Cookie 值，必须是带签名的派生值（如 HMAC(
cookie_value+session_id+timestamp)） - 前端 JS 若需发 AJAX 请求，必须从 DOM 读取隐藏字段值，或从 meta 标签、JS 变量中获取，不能读 HttpOnly Cookie
gin-contrib/csrf 默认行为的三个硬约束
gin-contrib/csrf 不是“开箱即用”的零配置方案，它隐含三个前提，缺一不可：
- 必须启用
gin-contrib/sessions（或其他兼容gin.Context的 session 实现），因为 Token 存储依赖c.MustGet("session") - HTTP 方法为
POST、PUT、PATCH、DELETE时才触发验证，GET、HEAD、OPTIONS默认跳过 - 路径匹配基于
IgnoreURLs白名单，默认放过/favicon.ico、/healthz等，但不会自动忽略/api/下所有接口——要显式配置
常见错误是没配 session 中间件就直接 use csrf.New()，结果所有 POST 请求返回 403，日志里却无提示。此时检查 c.Keys 是否含 "session" 就能快速定位。
Token 过期与刷新策略的实际影响
默认 Token 有效期为 24 小时（MaxAge: 86400），但实际生命周期由 session 过期时间主导。如果 session 设置为 30 分钟过期，那 Token 也最多活 30 分钟——即使你设了 24 小时。
更关键的是：Token 不支持自动续期。用户长时间停留在页面，提交时 Token 已失效，就会报错 csrf: invalid token。这不是 bug，是设计使然。
- 解决办法只有两个：前端监听 403 并重拉页面（带新 Token），或改用短生命周期 Token + 定期 AJAX 刷新（需后端提供
/csrf/token接口） - 不要把 Token 存 localStorage —— XSS 可读，等于白防护
- 调试时可通过
csrf.Secure(false)关闭 HTTPS 强制，但上线必须设为true，否则 Cookie 无法发送
最常被忽略的一点：Token 验证失败时，中间件直接 c.AbortWithStatusJSON(403, ...)，不会走后续 handler。如果你在 handler 里手动调用了 csrf.Token(c)，而中间件还没执行，那拿到的可能是空或过期值——顺序不能错。
