移动端网络不稳定时，接口不能只靠重试兜底，需在http层与业务层联合做缓冲与降级：设readheadertimeout（3–5秒）和writetimeout（8–12秒），禁用readtimeout而改用io.limitreader控流；通过x-net-quality头实现端侧驱动的静默降级；平滑过渡关键在于连接生命周期对齐，需关闭长连接、确保k8s无会话亲和、客户端连接池三步切换；闭环验证依赖真实上报、灰度与fallback日志。
移动端网络不稳定时，接口不能只靠重试兜底
移动端真实网络环境远比本地调试复杂：弱网、DNS劫持、HTTP代理中断、运营商QoS限速都会导致请求卡在读 body、写响应或 TLS 握手阶段。单纯依赖前端重试或超时设置，无法解决服务端连接堆积、goroutine 泄漏、数据库连接耗尽等问题。Gin 本身不感知网络质量，必须在 HTTP 层+业务层联合做缓冲与降级。
用 ReadHeaderTimeout 和 WriteTimeout 切断慢连接
Gin 默认使用 http.Server，其超时参数对移动端特别关键。不设 ReadHeaderTimeout，恶意客户端可发半包阻塞 Accept；不设 WriteTimeout，弱网下响应写一半就卡住，连接长期占用。
-
ReadHeaderTimeout建议设为 3–5 秒：覆盖 95% 正常 DNS+TLS+Header 传输耗时，避免 header 读不完就挂起 -
WriteTimeout建议设为 8–12 秒：略长于后端主逻辑 P95 耗时，但必须短于客户端 timeout（如 Axios 默认 10s），否则服务端还在写，前端已断连 - 别设
ReadTimeout：它包含 body 读取，移动端上传图片/音视频时极易误杀正常请求；改用c.Request.Body+io.LimitReader在 handler 内部控流
通过 X-Net-Quality Header 实现端侧驱动的静默降级
和全局开关不同，移动端 SDK 可实时上报网络质量（如 Android 的 ConnectivityManager、iOS 的 NWPathMonitor），并在请求头带上 X-Net-Quality: poor 或 X-Net-Quality: good。服务端据此动态调整行为，用户无感。
- 在中间件里用
c.GetHeader("X-Net-Quality")提前判断，把值存入 context，下游 handler 统一读取 - 弱网时自动跳过非核心逻辑：比如不查 Redis 缓存详情、不调第三方推送、返回精简字段（用结构体嵌套指针控制序列化）
- 禁止在降级路径里调用
c.Abort()后还继续执行 DB 查询——必须用return显式退出 - 注意大小写：iOS 系统可能将 header 转成小写，建议统一用
strings.ToLower()归一化后再比较
平滑过渡的核心是「连接生命周期对齐」而非 URL 改动
很多团队以为换域名、加 CDN 就算过渡完成，但移动端 WebView 或原生容器里可能缓存了旧 IP、复用 Keep-Alive 连接、甚至硬编码了 http.Transport。真正平滑的关键，在于让新老服务共存期间，连接能自然迁移。
- 新服务上线前，先在旧服务上加
SetKeepAlivesEnabled(false)逐步关闭长连接，逼客户端重建连接到新地址 - 若用 K8s，Service 的
sessionAffinity: None必须确认开启，避免旧连接被 sticky 到已下线 Pod - 所有 DB、Redis、gRPC 客户端连接池，必须按「预热新池 → 原子切换指针 → 旧池限流退场」三步走，参考
atomic.Value+db.SetMaxOpenConns(0)方案
X-Net-Quality 是否真实、是否被代理篡改、是否和后端降级策略形成闭环验证。没埋点、没灰度、没 fallback 日志字段（如 log.WithField("net_quality", quality)），所谓平滑只是假象。golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
