qs #

Zero-dependencies package to encodes structs into url.Values.

Installation

go get github.com/sonh/qs

用法

import (
    "github.com/sonh/qs"
)

包 qs 导出 NewEncoder() 函数用于创建编码器。

编码器缓存结构体信息以加速编码过程，强烈推荐使用单个实例。

使用 WithTagAlias() 函数注册自定义标签别名（默认是 qs）。

encoder = qs.NewEncoder(
    qs.WithTagAlias("myTag"),
)

Encoder 有 Values() 和 Encode() 函数用于将结构体编码为 url.Values。

支持的数据类型：

• 所有基本类型（bool、uint、string、float64 等）
• struct
• slice，array
• pointer
• time.Time
• 自定义类型

示例

type Query struct {
    Tags   []string  qs:"tags"
    Limit  int       qs:"limit"
    From   time.Time qs:"from"
    Active bool      qs:"active,omitempty"  //omit empty value
    Ignore float64   qs:"-"                 //ignore
}
query := &Query{
    Tags:   []string{"docker", "golang", "reactjs"},
    Limit:  24,
    From:   time.Unix(1580601600, 0).UTC(),
    Ignore: 0,
}
encoder := qs.NewEncoder()
values, err := encoder.Values(query)
if err != nil {
    // Handle error
}
fmt.Println(values.Encode()) //(unescaped) output: "from=2020-02-02T00:00:00Z&limit=24&tags=docker&tags=golang&tags=reactjs"

布尔格式

使用 int 选项将布尔值编码为整数

type Query struct {
    DefaultFmt bool qs:"default_fmt"
    IntFmt     bool qs:"int_fmt,int"
}
query := &Query{
    DefaultFmt: true, 
    IntFmt:     true,
}
values, _ := encoder.Values(query)
fmt.Println(values.Encode()) // (unescaped) output: "default_fmt=true&int_fmt=1"

时间格式

默认情况下，包将 time.Time 值编码为 RFC3339 格式。

包含 "second" 或 "millis" 选项以表示该字段应编码为秒或毫秒。

type Query struct {
    Default time.Time   qs:"default_fmt"
    Second  time.Time   qs:"second_fmt,second" //use second option
    Millis  time.Time   qs:"millis_fmt,millis" //use millis option
}
t := time.Unix(1580601600, 0).UTC()
query := &Query{
    Default: t,
    Second:  t,
    Millis:  t,
}
encoder := qs.NewEncoder()
values, _ := encoder.Values(query)
fmt.Println(values.Encode()) // (unescaped) output: "default_fmt=2020-02-02T00:00:00Z&millis_fmt=1580601600000&second_fmt=1580601600"

切片/数组格式

切片和数组默认编码为多个具有相同值名称的 URL 值。

type Query struct {
    Tags []string qs:"tags"
}
values, _ := encoder.Values(&Query{Tags: []string{"foo","bar"}})
fmt.Println(values.Encode()) //(unescaped) output: "tags=foo&tags=bar"

包括 comma 选项，用于指示该字段应编码为单个逗号分隔的值。

type Query struct {
    Tags []string qs:"tags,comma"
}
values, _ := encoder.Values(&Query{Tags: []string{"foo","bar"}})
fmt.Println(values.Encode()) //(unescaped) output: "tags=foo,bar"

包括 bracket 选项，用于指示多个 URL 值应在值名称后附加 "[]"。

type Query struct {
    Tags []string qs:"tags,bracket"
}
values, _ := encoder.Values(&Query{Tags: []string{"foo","bar"}})
fmt.Println(values.Encode()) //(unescaped) output: "tags[]=foo&tags[]=bar"

index 选项将在值名称后附加带括号的索引号。

type Query struct {
    Tags []string qs:"tags,index"
}
values, _ := encoder.Values(&Query{Tags: []string{"foo","bar"}})
fmt.Println(values.Encode()) //(unescaped) output: "tags[0]=foo&tags[1]=bar"

嵌套结构体

所有嵌套结构体都会被编码，包括带有括号用于作用域限定的父值名称。

type User struct {
    Verified bool      qs:"verified"
    From     time.Time qs:"from,millis"
}
type Query struct {
    User User qs:"user"
}
query := Query{
    User: User{
        Verified: true,
        From: time.Now(),
    },
}
values, _ := encoder.Values(query)
fmt.Println(values.Encode()) //(unescaped) output: "user[from]=1601623397728&user[verified]=true"

默认情况下，它使用括号，添加 dot 选项到 嵌套结构体字段以用 . 来限定其子字段：

type Query struct {
    User User qs:"user,dot"
}
values, _ := encoder.Values(query)
fmt.Println(values.Encode()) //(unescaped) output: "user.from=1601623397728&user.verified=true"

dot 选项仅适用于声明它的字段；如果想继续使用点语法，请在更深层的结构体字段上再次嵌套（否则该层将回退到使用括号）。

自定义类型

实现函数：

• EncodeParam 将自身编码为查询参数。
• IsZero 检查对象是否为零值，以确定编码时是否应省略该字段。

type NullableName struct {
	First string
	Last  string
}
func (n NullableName) EncodeParam() (string, error) {
	return n.First + n.Last, nil
}
func (n NullableName) IsZero() bool {
	return n.First == "" && n.Last == ""
}
type Struct struct {
    User  NullableName qs:"user"
    Admin NullableName qs:"admin,omitempty"
}
s := Struct{
    User: NullableName{
        First: "son",
        Last:  "huynh",
    },
}
encoder := qs.NewEncoder()
values, err := encoder.Values(&s)
if err != nil {
    // Handle error
    fmt.Println("failed")
    return
}
fmt.Println(values.Encode()) //(unescaped) output: "user=sonhuynh"

限制

• 如果 slice/array 中的元素是 struct 数据类型，多层嵌套有限制
• 还没有解码器

_未来版本将会改进_

许可

根据 MIT 许可证分发，更多详情请参见代码中的许可文件。

--- Tranlated By Open Ai Tx | Last indexed: 2026-07-29 ---