gin-binding

轻量级 Gin query 绑定增强库，提供两项能力：

• QueryArray：统一解析数组 query（重复 key / 逗号分隔）
• QueryEnum[T]：解析 protobuf enum（数字 / 名称 / 大小写无关）

环境要求

• Go 1.18+

安装

go get github.com/Zhang-Siyang/gin-binding

功能

1) QueryArray

将 query 值中的逗号分隔形式展开后再绑定。

等价输入：

• ?ids=1&ids=2&ids=3
• ?ids=1,2,3

2) QueryEnum[T]

用于 protobuf enum 的 query 解析。

支持：

• 数字：?kind=9
• 名称：?kind=TYPE_STRING
• 名称大小写无关：?kind=type_sTriNg

语义：

• 空字符串（或空白） => 未设置（Setted()==false）
• 非法值 => 返回绑定错误
• JSON 输出：未设置为 null，已设置为枚举名字符串（无名时为数字字符串）

快速使用

package main

import (
    "net/http"

    gbinding "github.com/Zhang-Siyang/gin-binding/binding"
    "github.com/gin-gonic/gin"
    "google.golang.org/protobuf/types/descriptorpb"
)

type listQuery struct {
    IDs  []int64  `form:"ids" json:"ids"`
    Tags []string `form:"tags" json:"tags"`
}

type enumQuery struct {
    Kind gbinding.QueryEnum[descriptorpb.FieldDescriptorProto_Type] `form:"kind" json:"kind"`
}

func main() {
    r := gin.Default()

    r.GET("/array", func(c *gin.Context) {
        var q listQuery
        if err := c.ShouldBindWith(&q, gbinding.QueryArray); err != nil {
            c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
            return
        }
        c.JSON(http.StatusOK, q)
    })

    r.GET("/enum", func(c *gin.Context) {
        var q enumQuery
        if err := c.ShouldBind(&q); err != nil {
            c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
            return
        }
        c.JSON(http.StatusOK, q)
    })

    _ = r.Run(":8080")
}

Example（Go Doc 风格）

示例采用 Go 官方文档约定，位于：

• binding/example_test.go

运行示例：

go test ./binding -run '^Example'

行为契约（用于重写/兼容）

• QueryArray

  • 统一展开逗号分隔值后再执行标准 form 绑定
  • 支持重复 key、逗号值、混合输入
  • 非切片字段保持标准绑定行为

• QueryEnum[T]

  • 支持 enum 数字与名称输入
  • 名称匹配大小写无关
  • 空值语义为“未设置”，而非错误
  • 非法值必须返回 error
  • JSON 中未设置为 null，已设置为字符串

测试

go test ./...