老版本API下线前必须完成三重验证：网关日志过滤非业务路径、服务端埋点统计客户端类型版本、CDN缓存命中率分析；需用JSON Schema比对字段级兼容性；全量扫描代码与配置中v1硬编码；灰度期返回410 Gone并记录溯源日志。
老版本 API 下线前必须先确认真实调用量、客户端分布和字段契约依赖，否则直接删路由等于线上事故。
查清谁还在调用 /v1
别只看日志 grep "/v1"——那包含健康检查、爬虫、内部脚本等噪声。真实业务调用得靠三重交叉验证：
- 网关层统计：Nginx 或 Envoy 的 access log 中提取
$request_uri+$http_user_agent，过滤掉/v1/healthz、/v1/metrics等非业务路径 - 服务端埋点：在
v1路由入口加 Prometheus counter，标签带上client_type="mobile"、client_version="2.1.0"（若客户端上报） - CDN 缓存命中率：如果
/v1被 CDN 缓存，Cache-Status: HIT比例高，说明大量终端仍直连旧地址，不是 SDK 问题而是用户没升级
识别结构体字段级兼容性断裂点
共用 User struct 是最隐蔽的下线雷区。v1 客户端解析 v2 响应时 panic，往往不是因为新增字段，而是字段类型或零值行为变了：
-
v1.User.Name string→v2.User.Name *string：v1 客户端收到null会 JSON decode error，不是静默忽略 -
v2.User.CreatedAt time.Time默认序列化为 RFC3339 字符串，但 v1 客户端若用int64解析时间戳，直接崩溃 - 哪怕字段名相同，
json:"id,string"tag 在 v2 加上后，v1 客户端反序列化整数 ID 就失败
实操建议：用 go run -tags=jsonschema ./cmd/schema-diff v1/user.go v2/user.go（需提前写好 //go:generate 注释生成 JSON Schema）比对字段类型、tag、omitempty 行为差异。
立即学习“go语言免费学习笔记（深入）”；
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
验证下游依赖是否已解耦
很多团队以为“我只改了 HTTP handler”，其实下游系统可能硬编码依赖 /v1/users：
- 第三方系统回调地址写死在配置中心，比如支付平台异步通知 URL 是
https://api.example.com/v1/pay/callback - 数据库触发器或 CDC 工具监听了
/v1请求日志表，用于同步数据 - K8s readiness probe 仍指向
/v1/healthz，删掉会导致滚动更新卡住
查法：搜全量代码库（含 infra 仓库）的字符串 "v1/"，特别注意 config.yaml、terraform.tf、docker-compose.yml；再查注册中心（如 Nacos/Etcd）里有没有服务 metadata 标记了 api-version: v1。
灰度下线必须带监控兜底
直接 router.PathPrefix("/v1") 注册空 handler 或返回 404 是危险操作——它不区分是恶意扫描还是真实用户，且无法回滚。
- 上线前先切 5% 流量到
X-Deprecated: true响应头 + 日志打标，观察客户端错误率是否跳升 - 真正下线时，用
http.HandlerFunc拦截所有/v1/请求，记录r.RemoteAddr+r.UserAgent()+r.URL.Path到独立 topic，供安全团队溯源 - 保留
/v1路由至少 30 天，但返回410 Gone+X-Retry-After: /v2/users，避免缓存长期脏数据
真正的风险不在代码删不删得掉，而在你根本不知道哪些地方悄悄依赖了它——下线动作本身不会出错，暴露出来的未知依赖才会。
