c.ShouldBind 默认只绑定请求体（body），不处理 URL query 参数，需用 c.ShouldBindQuery 显式绑定；若需同时接收 query 和 body，应分别调用 ShouldBindQuery 和 ShouldBindJSON 并手动合并字段。
为什么 c.ShouldBind 有时拿不到 query 参数
因为 c.ShouldBind 默认只绑定请求体（body），比如 JSON 或表单数据，对 URL 中的 query 参数（如 ?id=123）完全不处理。很多人误以为它能“自动识别所有来源”，结果调试半天发现变量一直是零值。
正确做法是：明确指定绑定目标来源——用 c.ShouldBindQuery 处理 query，c.ShouldBindJSON 处理 JSON body，c.ShouldBindForm 处理 application/x-www-form-urlencoded。
- 如果接口同时支持 query + JSON body，得分开调用，不能只靠一个
ShouldBind -
ShouldBindQuery不会读 body，ShouldBindJSON也不会读 URL，二者互不干扰 - 若结构体字段没加
form或jsontag，默认按字段名匹配，但大小写敏感且不兼容下划线转驼峰
如何让一个 struct 同时接收 query 和 body 参数
Gin 不支持单次调用自动合并多个来源，但可以手动组合：先定义结构体，再分别绑定并合并字段。更稳妥的做法是拆成两个结构体，或用 map 做中间层。
例如，想接收 ?page=1&size=20 + {"name":"foo"}：
立即学习“go语言免费学习笔记（深入）”；
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
type SearchReq struct {
Page int `form:"page" binding:"required"`
Size int `form:"size" binding:"required"`
}
type CreateReq struct {
Name string `json:"name" binding:"required"`
}
// 分开绑定
var q SearchReq
if err := c.ShouldBindQuery(&q); err != nil {
c.AbortWithStatusJSON(400, gin.H{"error": err.Error()})
return
}
var b CreateReq
if err := c.ShouldBindJSON(&b); err != nil {
c.AbortWithStatusJSON(400, gin.H{"error": err.Error()})
return
}
// 合并逻辑在 handler 内处理
- 别给同一个 struct 同时加
form和jsontag，容易混淆来源且验证行为不可控 - 如果必须共用结构体，用
binding:"-"显式禁用不需要的字段绑定 -
ShouldBind的内部逻辑依赖Content-Type，当 header 缺失或错误时会静默 fallback 到 form 绑定，导致 query 被忽略
c.Bind 和 c.ShouldBind 的关键区别在哪
c.Bind 遇到错误会直接中止请求并返回 400；c.ShouldBind 则把错误交给你自己处理，适合需要自定义错误响应或做降级逻辑的场景。
- 对外 API 建议用
ShouldBind，便于统一记录日志、返回 i18n 错误信息 - 内部服务或 CLI 工具类接口可用
Bind，省去显式判错 - 二者底层都调用相同的解析器，性能无差异，选哪个纯看错误控制粒度需求
- 注意：
Bind返回 error 时，handler 函数仍会继续执行后续代码，除非你手动return—— 这点常被忽略
query 参数含数组或嵌套结构怎么办
Gin 默认支持 ?ids=1&ids=2&ids=3 绑定为 []int，但不支持 ?filter[name]=foo&filter[age]=25 这类嵌套语法（那是某些前端库的扩展，非标准）。
标准 query 数组写法只有两种：
- 重复 key：
?tag=golang&tag=web→Tags []string `form:"tag"` - 方括号语法：
?ids[]=1&ids[]=2→IDs []int `form:"ids[]"`（需 Gin v1.9+）
如果后端必须接收类似 filter.name 的扁平化参数，只能用 map[string]string 手动解析，或借助 c.Request.URL.Query() 拿原始值再做字符串切分。
容易踩的坑：ShouldBindQuery 对空字符串、布尔值、数字的类型转换很严格，?active= 会报错，?active=false 才能转成 bool；?num= 无法转 int，会触发 binding error。
