Gin参数绑定需结构体字段加正确标签(如json:"name"、form:"name")、传指针调用ShouldBind系列方法,并按请求类型选用ShouldBindJSON、ShouldBind、ShouldBindQuery或ShouldBindUri,否则绑定失败且字段为零值。

你需要让Gin自动把HTTP请求里的数据填进Go结构体里,而不是手动从c.PostForm或c.Query挨个取值再类型转换——这一步做错,后续所有业务逻辑都会拿不到正确参数。
定义结构体时必须加字段标签
在结构体字段上写json:"xxx"或form:"xxx",否则ShouldBindJSON或ShouldBind根本找不到对应关系。比如客户端传{"username":"alice"},结构体字段没写json:"username",绑定后username字段永远是空字符串。
字段标签必须用反引号包裹,不能用双引号。写成json:"username"是对的,json:"username"(中文引号)或json:"username"(少了反引号)都会导致绑定失败且无提示。
【必须传指针】调用ShouldBindJSON(&v)时,&v是地址,不是v本身。传值进去绑定永远不生效,结构体字段全为零值。
JSON请求绑定:ShouldBindJSON最常用场景
前端发POST请求,Content-Type设为application/json,Body里是标准JSON对象。
第一步:声明结构体变量,字段带json:"field"和binding:"required"标签。
第二步:调用c.ShouldBindJSON(&req),返回error不为nil就说明JSON格式错误、字段名不匹配或校验失败。
第三步:错误时立即返回400响应,不要继续执行业务逻辑。这一步漏掉,程序可能用空字段去查数据库,导致意料外行为。
表单提交绑定:ShouldBind自动识别x-www-form-urlencoded
HTML表单直接submit、或者fetch用FormData提交时,Content-Type默认是application/x-www-form-urlencoded,这时不能用ShouldBindJSON。
方法一:结构体字段用form:"username"标签,然后调用c.ShouldBind(&req)。Gin会自动根据Content-Type选择form绑定器。
方法二:如果确定是表单,也可显式调用c.ShouldBindWith(&req, binding.Form),但通常没必要。
注意:表单字段值全是字符串,Gin会尝试转成结构体对应字段类型(如int、bool),但若前端传了age=abc,绑定失败会返回error,不会静默忽略。
查询参数绑定:ShouldBindQuery只读URL问号后的内容
GET请求的?name=jack&age=25这类参数,ShouldBindQuery专门处理它,不碰Body也不看Header。
结构体字段必须用form:"name"标签(不是json),因为查询参数本质是键值对,没有JSON嵌套概念。
调用c.ShouldBindQuery(&req)后,即使URL里缺了age参数,age字段也不会报错——它只是保持结构体初始零值。这点和ShouldBindJSON不同,后者缺required字段会直接报错。
URI路径参数绑定:ShouldBindUri用于RESTful风格
比如路由定义为r.GET("/user/:id/:role", handler),客户端访问/user/123/admin,id和role就是URI参数。
结构体字段要用uri:"id"和uri:"role"标签,否则ShouldBindUri找不到映射目标。
调用c.ShouldBindUri(&req),Gin会把路径段按顺序填进结构体。如果路径段数量和结构体字段数不一致,绑定直接失败返回error。


















