正确做法是保持接口可访问、行为冻结，仅添加Deprecation:true响应头、Sunset头及含deprecated/replacement字段的JSON响应体，状态码用200或206，不中断客户端调用链。
如何让旧版 HTTP 路由返回标准弃用响应
直接 404 或 301 重定向会打断客户端调用链，正确做法是保持接口可访问、行为冻结，只加明确弃用提示。必须返回 Deprecation: true 响应头（RFC 8594），并配合可读的 JSON body。
- 状态码用
200 OK或206 Partial Content，避免触发客户端错误处理逻辑 - 响应体中包含
deprecated字段（true）、replacement（如"/api/v2/users"）和可选的sunrise时间戳 - 加上
Sunset响应头（格式为 RFC 7231 的 HTTP-date），例如Sunset: Wed, 01 Jan 2027 00:00:00 GMT - 禁止在 handler 内修改字段结构、增删字段或变更类型——废弃 = 行为冻结，仅提示
怎么用 gorilla/mux 或 chi 封装 v1 路由为“已废弃”状态
不要删路由，而是把原 handler 包一层中间件或包装函数，在执行前注入弃用头和响应体。gorilla/mux 和 chi 都支持在子路由器上挂统一中间件，比逐个 handler 改写更安全。
- 对
v1 := router.PathPrefix("/v1").Subrouter()，调用v1.Use(deprecationMiddleware) -
deprecationMiddleware中先w.Header().Set("Deprecation", "true")，再检查是否已有响应体；若无，则拦截后续 handler，直接写入弃用 JSON - 如果仍需透传原逻辑（比如只加 header 不改 body），就在中间件末尾调用
next.ServeHTTP(w, r)，但确保不修改原有 status code 和 body - 避免在中间件里做耗时操作（如日志入库），否则影响所有 v1 请求性能
旧函数签名怎么包装才能不破坏调用方编译
Go 没有运行时注解机制，所有弃用提示都靠手动包装函数实现。关键约束是：签名一字不差，警告只打一次，不 panic，不改契约。
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 声明包级变量
var warnedOldDoSomething sync.Once，在包装函数内调用warnedOldDoSomething.Do(func() { log.Printf("WARNING: OldDoSomething is deprecated, use NewDoSomething instead") }) - 若原函数是
func OldGetUser(id int) (*User, error)，包装函数必须保持完全一致，内部调用NewGetUser(context.Background(), id)并做字段映射 - 禁止把
error替换为自定义错误类型，老代码依赖errors.Is(err, ErrNotFound)会失效 - godoc 注释开头加
// Deprecated: use NewDoSomething instead.，gopls 补全时会显示
为什么不能只靠 Accept 头做版本弃用管理
Accept 头方案看似“RESTful”，但在弃用场景下实际不可控：它无法被日志系统直接提取、curl 测试必须手动加 header、CDN 和网关难以识别，导致弃用策略形同虚设。
立即学习“go语言免费学习笔记（深入）”；
- 运维查问题时看不到请求版本，只能靠抓包或改代码加日志，响应延迟高
- 无法对
Accept: application/vnd.myapp.v1+json统一打标弃用，因为同一 URL 可能混杂多个 Accept 值 - OpenAPI 文档生成器（如 swaggo）很难自动识别 header 版本分支，文档易过期或漏标
- 真正需要弃用的是路径级语义（如 /v1/users），不是媒体类型协商——后者更适合格式切换（JSON/XML），而非行为迁移
