Gin集成OAuth鉴权90%失败源于RedirectURL未逐字匹配、state未安全生成校验、Exchange未传带超时context；须严格校验协议/域名/端口/路径（含末尾斜杠）、绑定session生成state、立即调Exchange并细判*oauth2.RetrieveError。
Gin 框架集成 OAuth 鉴权，90% 的失败不是没写完流程，而是 RedirectURL 没对齐、state 没校验、conf.Exchange 调用时丢了 context。安全边界卡不牢，HTTPS 再好也白搭。
RedirectURL 必须逐字节匹配平台注册值
GitHub、Google、微信开放平台全部强制校验协议、域名、端口、路径（含末尾斜杠），差一个字符就返回 invalid_request 或静默 400，错误体里通常不提示具体哪错了。
- 本地开发统一用
http://localhost:8080/callback，别混用127.0.0.1；生产环境必须是https://example.com/auth/callback，且证书有效 - 微信要求
redirect_uri在AuthCodeURL中做 URL 编码（如%2Fcallback），GitHub/Google 不接受编码——不能复用同一套拼接逻辑 - 多环境部署时，用
os.Getenv("OAUTH_REDIRECT_URL")注入，不要在代码里写if env == "prod"分支判断 - 调试时可用
curl -v "https://github.com/login/oauth/authorize?client_id=xxx&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Fcallback"看重定向响应头是否匹配
state 参数必须自己生成、绑定 session、一次性比对
state 是防 CSRF 的唯一有效手段，golang.org/x/oauth2 包完全不处理它——你漏掉，攻击者就能伪造跳转链接，把用户的 code 劫持到自己服务器。
- 生成用
crypto/rand.Read（不是math/rand），取 32 字节后hex.EncodeToString，长度 ≥ 32 字符 - 存入 session 时必须绑定当前会话 ID，例如 Redis key 为
"oauth_state:" + sessionID，不能全局共享 - 回调 handler 中先查 session 是否存在且未过期，再用
subtle.ConstantTimeCompare恒定时间比对，比对完立刻session.Delete("oauth_state") - 别往
state里塞next=/admin或user_id=123——它只用于防重放；业务跳转地址走后端 session 或 JWT payload
conf.Exchange 调用必须传带超时的 context 并细判 error
conf.Exchange(r.Context(), code) 失败常见报错如 invalid_grant、bad_verification_code、空 token，根本原因就三件事没做对：
- 传的是
r.Context()，不是context.Background()；否则超时、取消控制全失效 - 没提前读
r.Body：Gin/Echo 等框架中，r.Body可能已被中间件读空，需确保未被消费 - 必须细粒度判断错误类型：
*oauth2.RetrieveError要单独捕获，err == nil && token == nil也要处理（某些平台返回 200 但 body 为空）
鉴权中间件里别直接透传 token，要提取并校验 claims
OAuth 登录成功后拿到的 access_token，只是授权凭证，不是身份凭证。直接存进 c.Set("token", token) 然后放行，等于把门钥匙交给用户自己保管。
- 应在回调 handler 中调用第三方 API（如
https://www.googleapis.com/oauth2/v3/tokeninfo?access_token=xxx）或解析 JWT claims 校验aud、iss、exp - 校验通过后，应将可信用户标识（如
sub或email）存入 Gin context，例如c.Set("user_id", claims["sub"]) - 后续鉴权中间件（如
AuthMiddleware）应基于这个user_id做权限判断，而不是反复解析或转发原始 token - 若用
gin-jwt，建议在Authenticator中完成 OAuth token 校验，并返回用户结构体，交由 JWT 签发新 token，实现“OAuth 登录 → JWT 授权”解耦
最易被忽略的点：OAuth 流程和 JWT 鉴权是两层事——前者解决“你是谁”，后者解决“你能做什么”。混在一起做，调试时连是 token 过期还是 redirect_uri 错了都分不清。
