使用URL路径版本控制最直观，如/v1/users和/v2/users，结合gorilla/mux按版本分组路由；也可通过Accept头实现，但调试不便；推荐按handlers/v1、models/v2等目录结构组织代码，保持逻辑分离；需制定弃用策略并返回X-API-Version头，确保兼容性与可维护性。
在构建长期维护的RESTful服务时，API版本管理是必不可少的一环。Golang因其高性能和简洁的语法，非常适合用来开发可扩展的API服务。实现版本管理的关键在于清晰地分离不同版本的路由与处理逻辑，同时保持代码结构整洁。以下是几种常见的实现方式。
使用URL路径进行版本控制
最常见的方式是在URL路径中包含版本号，例如 /v1/users 和 /v2/users。这种方式直观、易于理解，也便于缓存和调试。
在Golang中，可以使用标准库 net/http 或第三方路由库如 gorilla/mux 来实现：
- 为每个版本注册独立的路由组
- 将不同版本的处理器放在各自的包或目录中
- 通过前缀统一管理版本路径
示例代码：
立即学习“go语言免费学习笔记（深入）”；
router := mux.NewRouter()
v1 := router.PathPrefix("/v1").Subrouter()
v1.HandleFunc("/users", v1GetUsers).Methods("GET")
v2 := router.PathPrefix("/v2").Subrouter()
v2.HandleFunc("/users", v2GetUsers).Methods("GET")
使用请求头进行版本控制
另一种方式是通过HTTP请求头（如 Accept 或自定义头）来指定API版本。例如：
Accept: application/vnd.myapp.v1+json
这种方式隐藏了版本信息，使URL更“干净”，但对调试和测试不够友好，且不利于CDN缓存。
在Golang中，可以在中间件中解析请求头并路由到对应版本的处理器：
- 编写中间件读取版本标识
- 根据版本动态调用不同的处理函数
- 注意默认版本和错误处理（如版本未支持）
按模块组织代码结构
良好的项目结构有助于维护多个版本。建议按版本或功能划分目录：
handlers/v1/user_handler.go handlers/v2/user_handler.go routes/v1.go routes/v2.go models/v1/user.go models/v2/user.go
这样可以避免逻辑混杂，也方便团队协作。每个版本的处理器独立，互不影响。
版本兼容性与弃用策略
版本管理不仅仅是技术实现，还包括策略层面：
- 明确标注已弃用的接口（可通过响应头或文档）
- 保留旧版本一段时间，给予客户端迁移时间
- 使用自动化测试确保新版本不破坏已有行为
可以在响应中加入版本信息，帮助客户端调试：
router.Use(func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("X-API-Version", "1.0")
next.ServeHTTP(w, r)
})
})
基本上就这些。选择哪种方式取决于团队习惯和系统需求。URL路径版本控制更直观，适合大多数场景；请求头方式更隐蔽，适合对URL语义要求高的系统。关键是保持一致性，并做好文档说明。
