02路由配置与参数解析详解

Gin 路由配置与参数解析详解

1. 路由定义方式

// 基础路由示例
router.GET("/welcome", func(c *gin.Context) {
    firstName := c.DefaultQuery("firstname", "Guest")
    c.String(http.StatusOK, "Hello %s", firstName)
})

// RESTful 路由示例
router.POST("/users", createUser)
router.PUT("/users/:id", updateUser)
router.DELETE("/users/:id", deleteUser)

2. 参数获取规范

路径参数

router.GET("/users/:id", func(c *gin.Context) {
    id := c.Param("id")
    // 处理逻辑...
})

查询参数

// /welcome?firstname=John
c.Query("firstname") 
c.DefaultQuery("firstname", "Guest")

JSON 参数绑定

type Login struct {
    User     string `json:"user" binding:"required"`
    Password string `json:"password" binding:"required,min=6"`
}

router.POST("/login", func(c *gin.Context) {
    var login Login
    if err := c.ShouldBindJSON(&login); err != nil {
        c.JSON(400, gin.H{"error": err.Error()})
        return
    }
    // 认证逻辑...
})

3. 高级路由配置

路由分组

v1 := router.Group("/api/v1")
{
    users := v1.Group("/users")
    {
        users.GET("", listUsers)
        users.POST("", createUser)
        users.GET("/:id", getUser)
    }
}

正则表达式路由

router.GET("/users/:id([0-9]+)", func(c *gin.Context) {
    id := c.Param("id")
    // 处理数字ID...
})

4. 参数验证最佳实践

自定义验证规则

if v, ok := binding.Validator.Engine().(*validator.Validate); ok {
    v.RegisterValidation("phone", func(fl validator.FieldLevel) bool {
        return regexp.MustCompile(`^1[3-9]\d{9}$`).MatchString(fl.Field().String())
    })
}

// 使用示例
type User struct {
    Phone string `json:"phone" binding:"required,phone"`
}

错误处理标准流程

if err := c.ShouldBind(&param); err != nil {
    errors := err.(validator.ValidationErrors)
    errorMessages := make([]string, len(errors))
    for i, e := range errors {
        errorMessages[i] = fmt.Sprintf("参数 %s 校验失败：%s", e.Field(), e.Tag())
    }
    c.JSON(http.StatusBadRequest, gin.H{
        "code": 1001,
        "msg":  "参数校验失败",
        "errors": errorMessages,
    })
    return
}

5. 最佳实践建议

1. 路由版本控制方案
2. 统一响应格式规范
3. 敏感参数过滤处理
4. 请求频率限制中间件
5. 接口文档自动化生成方案

Swagger 集成规范

// 安装swag工具
// go install github.com/swaggo/swag/cmd/swag@latest

// 初始化Swagger配置（main.go顶部添加）
// @title Gin Web API
// @version 1.0
// @description RESTful API 文档
// @host localhost:8080
// @BasePath /api/v1

// API注释示例
// @Summary 用户登录
// @Tags auth
// @Accept  json
// @Produce json
// @Param   login body Login true "登录凭证"
// @Success 200 {object} Response
// @Router /login [post]

路由配置示例

// 添加docs路由（main函数内）
router.GET("/docs/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

// 配置swagger.json路径（初始化路由前添加）
router.StaticFile("/swagger.json", "./docs/swagger.json")

// 添加文档访问中间件
authMiddleware := gin.BasicAuth(gin.Accounts{
    "admin": "swagger123",
})
router.GET("/docs", authMiddleware, ginSwagger.WrapHandler(swaggerFiles.Handler))

生成命令说明

# 初始化swagger文档
swag init -g main.go -o ./docs --parseDependency

# 生成swagger.json后需要重新编译程序