Golang怎么制定团队内部的API版本废弃规范-Golang-PHP中文网

废弃接口必须返回http 200并设置deprecation: true和rfc 7231格式sunset头，配合replacement字段，而非404；因404会导致客户端panic、监控误报及sdk无法识别迁移提示。

golang怎么制定团队内部的api版本废弃规范

必须用 HTTP 200 + Deprecation: true 响应头，配合明确的 sunset 时间戳和 replacement 字段，而不是返回 404 或 301。 这是唯一能被客户端自动识别、不中断调用链、且符合 RFC 8594 的做法。

废弃接口为什么不能返回 404

404 会直接导致客户端 panic、重试风暴或静默失败——尤其在 gRPC-Web 或 SDK 自动生成场景下，错误处理逻辑往往只覆盖 2xx/5xx，对 404 做了“资源不存在”的假设，而非“你该升级了”。 - 客户端 SDK 不会解析响应 body，但会检查标准 header - 监控系统（如 Prometheus）按 status_code 统计时，404 会被归为“故障”，掩盖真实迁移进度 - 日志告警规则若监听 status_code != 200，会误报，干扰 SLO 判断

怎么设置 Deprecation 和 Sunset 头

Go 标准库支持直接写 header，无需额外依赖： - Deprecation: true 是强制项，必须小写 true，不能是 "True" 或 1 - Sunset 必须是 RFC 7231 格式的 HTTP-date，例如 Wed, 01 Oct 2026 00:00:00 GMT，不能是 ISO 8601（如 2026-10-01T00:00:00Z） - 示例代码片段：

func deprecatedV1Handler(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Deprecation", "true")
    w.Header().Set("Sunset", "Wed, 01 Oct 2026 00:00:00 GMT")
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(http.StatusOK)
    json.NewEncoder(w).Encode(map[string]interface{}{
        "error":       "endpoint deprecated",
        "replacement": "/api/v2/users",
        "sunrise":     "2024-10-01",
    })
}

团队协作时最容易漏掉的三件事

- Deprecation header 没有加到所有 v1 handler，只加在主路由，漏了 /v1/users/{id}/profile 这类嵌套路由 - Sunset 时间写成本地时区（如 CST），没转成 GMT，导致客户端解析失败 - 响应 body 里写了 deprecated: true，但字段名用了小写 deprecated 而非大驼峰 Deprecated，和团队已有的 JSON schema 不一致，SDK 反序列化失败

监控废弃接口调用量衰减才是下线依据

不要靠“过了 Sunset 时间就删代码”。真实节奏是： - 在上线 Sunset 头的同时，Prometheus 打点 http_requests_total{path=~"/v1/.*", status_code="200"} - 设置告警：连续 7 天该指标下降 >95%，才触发下线评审 - 删除前，用 git grep -n "/v1/" 全局扫描，确认没有内部服务还在直连 v1（比如 cron job 或 admin CLI）

真正的难点不在加 header，而在于让所有 handler 都走同一套响应包装逻辑，且 sunset 时间能集中配置、自动注入——否则每次发版都靠人肉改，三个月后必然漏。