go接口版本化依赖路径前缀/v1、独立chi.router实例挂载及结构体字段标签三要素，而非语言特性或请求头；/v1路径支持nginx灰度、prometheus打点、swagger分组文档；结构体新增字段用指针+omitempty，删字段先json:"-"注释，类型变更需双字段过渡；废弃接口须返回200+x-deprecated头并监控调用量衰减后下线。
Go 没有 interface version 语法，所谓“接口版本化”本质是人为约束的工程实践——不靠语言特性兜底，靠路径、结构体、路由分组和字段标签共同守住兼容性底线。
为什么必须用 /v1 路径前缀而不是 X-API-Version 头
Go 的 net/http 和主流路由库（chi、gin、gorilla/mux）不解析请求头做路由匹配。硬用 X-API-Version 就得在每个中间件里手动提取、校验、注入 context，一漏就走错逻辑；Accept 头更糟：浏览器不带、curl 默认不带、CDN 可能丢弃、mime.ParseMediaType 还可能因参数（如 charset=utf-8）解析失败。
-
/v1路径天然支持 Nginxlocation /v1/灰度转发、Prometheus 按path="/v1/xxx"打点、cURL 直接测curl /v2/users - Swagger 工具（如
swag）能自动为@router /v1/users和@router /v2/users生成分组文档 - 日志里一眼看出流量分布：
GET /v1/tasksvsGET /v2/tasks，不用翻中间件代码找版本分支
chi.NewRouter() 怎么隔离 v1/v2 而不互相污染
常见错误是把所有 handler 写进同一个 router：比如 r.Get("/v1/users", ...) 和 r.Get("/v2/users", ...) —— 这会让路由树扁平化，中间件、panic 恢复、限流策略全部混在一起，v2 加个新鉴权逻辑，v1 就跟着被套上。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 每个版本用独立
chi.Router实例：v1 := chi.NewRouter()、v2 := chi.NewRouter() - 用
r.Mount("/v1", v1)和r.Mount("/v2", v2)挂载，不是r.Get("/v1/xxx") - v1/v2 的中间件必须分开注册，比如 v2 需要 JWT 校验，就只在
v2.Use(jwtMiddleware)里加 - handler 函数名带版本标识：
v1GetUsersHandler、v2GetUsersHandler，禁止共用一个函数再 if 判版本
结构体字段变更怎么让旧客户端不崩
Go 的 json.Unmarshal 对未知字段默认忽略，但对缺失字段或类型不匹配会静默失败或赋零值——旧客户端发请求时没传新字段，服务端却把它当必填，结果 UpdatedAt time.Time 变成 Unix 纪元时间，业务逻辑直接错乱。
- 新增字段一律用指针或
omitempty：UpdatedAt *time.Time `json:"updated_at,omitempty"` - 删字段先改
json:"-"并注释说明已弃用，等下线窗口期过后再物理删除 - 类型变更必须双字段过渡：比如
Count int升级为CountStr string，同时保留CountInt int `json:"count"`和CountStr string `json:"count_str,omitempty"`，在 Unmarshal 后做转换 - 禁用
json:",required"—— Go 的encoding/json根本不识别这个 tag，写了等于没写
废弃接口怎么安全下线而不伤老用户
直接删掉 GetUser() 方法？旧客户端立刻 panic。真要废弃，得让调用方感知到、有迁移窗口、且服务端仍能响应成功。
- 方法体返回
errors.New("deprecated: use GetUserV2 instead")，HTTP 状态码仍用 200，响应结构保持原样 - 加
X-Deprecated: true响应头，方便客户端团队通过日志定位调用方 - 在 Swagger 文档里用
deprecated: true标记，配合description写清替代方案 - 记录访问日志，监控调用量衰减趋势，确认无流量后再物理删除
最危险的是在 handler 里用 if 分支判断版本——它让测试难覆盖、灰度无法单独控制、中间件策略无法按版本隔离。路径前缀 + 独立 router + 字段标签，这三者缺一不可，少一个，兼容性就变成赌运气。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
