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 Loginif 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后需要重新编译程序