qs #

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

Installation

go get github.com/sonh/qs

Uso

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

El paquete qs exporta la función NewEncoder() para crear un codificador.

El codificador almacena en caché la información de la estructura para acelerar el proceso de codificación, se recomienda usar una única instancia.

Use la función WithTagAlias() para registrar un alias de etiqueta personalizado (el predeterminado es qs)

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

El codificador tiene funciones Values() y Encode() para codificar estructuras en url.Values.

Tipos de datos soportados:

• todos los tipos básicos (bool, uint, string, float64,...)
• struct
• slice, array
• puntero
• time.Time
• tipo personalizado

Ejemplo

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"

Formato bool

Use la opción int para codificar bool a entero

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"

Formato de hora

Por defecto, el paquete codifica los valores time.Time en formato RFC3339.

Incluyendo la opción "second" o "millis" para indicar que el campo debe codificarse como segundo o milisegundo.

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"

Formato de Slice/Array

Slice y Array predeterminadamente se codifican en múltiples valores URL con el mismo nombre de valor.

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"

Incluyendo la opción comma para indicar que el campo debe codificarse como un único valor delimitado por comas.

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"

Incluyendo la opción bracket para indicar que los múltiples valores de URL deben tener "[]" añadidos al nombre del valor.

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"

La opción index añadirá un número de índice entre corchetes al nombre del valor.

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"

Estructuras anidadas

Todas las estructuras anidadas se codifican incluyendo el nombre del valor padre con corchetes para el ámbito.

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"

Por defecto, utiliza los corchetes, agrega la opción dot a un campo de estructura anidada para delimitar sus hijos con .:

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

La opción dot se aplica solo al campo en el que se declara; anídala nuevamente en un campo de estructura más profundo para seguir usando puntos (de lo contrario, ese nivel vuelve a corchetes).

Tipo Personalizado

Implemente funciones:

• EncodeParam para codificarse a sí mismo en un parámetro de consulta.
• IsZero para verificar si un objeto es cero y determinar si debe omitirse al codificar.

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"

Limitación

• si los elementos en slice/array son del tipo de dato struct, el anidamiento multinivel está limitado
• aún no hay decodificador

_Mejorará en futuras versiones_

Licencia

Distribuido bajo la Licencia MIT, por favor consulte el archivo de licencia en el código para más detalles.

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