知识小屋

    路径参数和查询参数

    接口参数常见两类：

    类型示例适合表达
    路径参数/users/1001资源 ID
    查询参数/users?page=1&keyword=tom筛选、分页、搜索

    一、路径参数

    路径里用 :id 定义参数：

    router.GET("/users/:id", func(c *gin.Context) {
	id := c.Param("id")

	c.JSON(200, gin.H{
		"id": id,
	})
})

    访问：

    GET /users/1001

    返回：

    {
  "id": "1001"
}

    注意：c.Param 返回的是字符串。如果需要数字，要自己转换。

    id, err := strconv.ParseInt(c.Param("id"), 10, 64)
if err != nil {
	c.JSON(400, gin.H{"message": "用户 ID 必须是数字"})
	return
}

    二、查询参数

    查询参数来自 URL 的 ? 后面：

    GET /users?page=1&keyword=tom

    读取：

    router.GET("/users", func(c *gin.Context) {
	page := c.DefaultQuery("page", "1")
	keyword := c.Query("keyword")

	c.JSON(200, gin.H{
		"page":    page,
		"keyword": keyword,
	})
})
    方法作用
    c.Query("keyword")没有参数时返回空字符串
    c.DefaultQuery("page", "1")没有参数时返回默认值

    三、查询参数绑定到结构体

    参数多时，不要一个一个手写读取。

    type UserQuery struct {
	Page     int    `form:"page"`
	PageSize int    `form:"pageSize"`
	Keyword  string `form:"keyword"`
}

    处理函数：

    func listUsers(c *gin.Context) {
	var query UserQuery
	if err := c.ShouldBindQuery(&query); err != nil {
		c.JSON(400, gin.H{"message": err.Error()})
		return
	}

	if query.Page <= 0 {
		query.Page = 1
	}
	if query.PageSize <= 0 {
		query.PageSize = 10
	}

	c.JSON(200, gin.H{"query": query})
}

    这里的 form 标签用于匹配查询参数名。

    四、通配符参数

    Gin 支持 *filepath 这种通配符：

    router.GET("/files/*filepath", func(c *gin.Context) {
	filepath := c.Param("filepath")
	c.JSON(200, gin.H{"filepath": filepath})
})

    访问：

    /files/images/avatar.png

    返回的 filepath 通常是：

    /images/avatar.png

    这种写法常用于静态文件或代理路径。