基于Gin框架在Go语言中实现基于Header的API版本控制

实现思路 #

通过自定义中间件读取请求头Accept-version的值，动态修改请求URL的路径前缀，将请求转发到对应版本的路由分组中。客户端只需调用统一的API路径，无需在URL中显式指定版本。

完整代码实现 #

package main

import (
	"fmt"
	"net/http"

	"github.com/gin-gonic/gin"
)

// 模拟配置模块获取版本头名称，实际项目可替换为你的配置逻辑
func GetVersionHeader() string {
	return "Accept-version"
}

func VersionMiddleware() gin.HandlerFunc {
	return func(c *gin.Context) {
		// 从请求头读取版本标识
		version := c.Request.Header.Get(GetVersionHeader())
		// 处理未指定版本的情况，默认路由到v1
		if version == "" {
			version = "v1"
		}

		// 构造带版本前缀的新请求路径
		path := fmt.Sprintf("/%s%s", version, c.Request.URL.Path)
		// 修改请求路径，让后续路由匹配对应版本的接口
		c.Request.URL.Path = path
		c.Next()
	}
}

func main() {
	router := gin.Default()

	// 根路由全局应用版本控制中间件，所有请求先经过版本解析
	router.Use(VersionMiddleware())

	// v1版本路由分组，实现v1接口逻辑
	v1 := router.Group("/v1")
	v1.GET("/user/:id", func(c *gin.Context) {
		c.String(http.StatusOK, "This is the v1 API, user ID: %s", c.Param("id"))
	})

	// v2版本路由分组，实现v2接口逻辑
	v2 := router.Group("/v2")
	v2.GET("/user/:id", func(c *gin.Context) {
		c.String(http.StatusOK, "This is the v2 API, user ID: %s", c.Param("id"))
	})

	// 启动服务
	router.Run(":8080")
}

关键说明 #

• 中间件核心逻辑：读取Accept-version头信息，无指定版本时默认使用v1；通过拼接版本前缀修改请求路径，让路由系统自动匹配对应版本的接口。
• 路由分组设计：分别维护/v1和/v2两个版本的路由分组，各自实现独立的业务逻辑，避免版本间代码耦合。
• 客户端调用示例：
  • 调用v1版本：请求头添加Accept-version: v1，访问http://localhost:8080/user/123
  • 调用v2版本：请求头添加Accept-version: v2，访问http://localhost:8080/user/123

扩展建议 #

• 可添加版本合法性校验，若请求头携带未定义的版本值，直接返回400 Bad Request错误。
• 版本头名称可通过配置文件统一管理，提升代码可维护性。

内容的提问来源于stack exchange，提问作者juan