请求绑定
Bind(...).Data / Query / URI / Header 的统一绑定与校验
请求绑定
xUtil 通过统一入口 Bind 提供 4 种绑定方法，分别覆盖请求体、查询参数、路径参数与请求头。
import xUtil "github.com/bamboo-services/bamboo-base-go/common/utility"统一行为
四种绑定方法都遵循同一套行为：
- 绑定成功：返回传入的
data指针。 - 绑定失败：调用
xVaild.HandleValidationError(ctx, err)，执行ctx.Abort()，并返回nil。 - 调用方拿到
nil时，应立即return，避免重复写响应。
API 结构
func Bind[T any](ctx *gin.Context, data *T) *pack.Binding[T]
func (u *Binding[T]) Data() *T
func (u *Binding[T]) Query() *T
func (u *Binding[T]) URI() *T
func (u *Binding[T]) Header() *T使用示例
1) JSON 请求体：Data
type CreateUserRequest struct {
Username string `json:"username" binding:"required,min=3,max=32"`
Email string `json:"email" binding:"required,email"`
Password string `json:"password" binding:"required,min=8"`
}
func CreateUser(ctx *gin.Context) {
req := xUtil.Bind(ctx, &CreateUserRequest{}).Data()
if req == nil {
return
}
// req 已完成绑定和校验
xResult.Success(ctx, "创建成功")
}2) Query 参数：Query
type ListUserQuery struct {
Page int64 `form:"page" binding:"omitempty,min=1"`
Size int64 `form:"size" binding:"omitempty,min=1,max=200"`
}
func ListUsers(ctx *gin.Context) {
query := xUtil.Bind(ctx, &ListUserQuery{}).Query()
if query == nil {
return
}
xResult.SuccessHasData(ctx, "查询成功", query)
}3) URI 参数：URI
type UserURI struct {
UserID int64 `uri:"user_id" binding:"required,min=1"`
}
func GetUser(ctx *gin.Context) {
uri := xUtil.Bind(ctx, &UserURI{}).URI()
if uri == nil {
return
}
xResult.SuccessHasData(ctx, "查询成功", gin.H{"user_id": uri.UserID})
}4) Header 参数：Header
type TraceHeader struct {
RequestID string `header:"X-Request-UUID" binding:"required"`
}
func GetProfile(ctx *gin.Context) {
header := xUtil.Bind(ctx, &TraceHeader{}).Header()
if header == nil {
return
}
xResult.SuccessHasData(ctx, "ok", gin.H{"request_id": header.RequestID})
}与手动绑定对比（以 Query 为例）
手动写法：
var query ListUserQuery
if err := ctx.ShouldBindQuery(&query); err != nil {
xVaild.HandleValidationError(ctx, err)
ctx.Abort()
return
}使用 Bind(...).Query()：
query := xUtil.Bind(ctx, &ListUserQuery{}).Query()
if query == nil {
return
}注意事项
Data使用 JSON 绑定，适用于请求体场景。Query/URI/Header分别用于 query、路径参数与 header。- 返回
nil代表请求已被中止，调用方应立即return。 - 需要完全自定义错误处理时，可保留手动绑定流程。