qs #

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

Installation

go get github.com/sonh/qs

Utilisation

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

Le package qs exporte la fonction NewEncoder() pour créer un encodeur.

L'encodeur met en cache les informations des structures pour accélérer le processus d'encodage, l'utilisation d'une seule instance est fortement recommandée.

Utilisez la fonction WithTagAlias() pour enregistrer un alias de tag personnalisé (par défaut c'est qs)

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

L'encodeur dispose des fonctions Values() et Encode() pour encoder des structures en url.Values.

Types de données supportés :

• tous les types de base (bool, uint, string, float64,...)
• struct
• slice, array
• pointer
• time.Time
• type personnalisé

Exemple

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"

Format booléen

Utilisez l'option int pour encoder un booléen en entier

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"

Format de l'heure

Par défaut, le package encode les valeurs time.Time au format RFC3339.

Inclure l'option "second" ou "millis" pour indiquer que le champ doit être encodé en secondes ou en millisecondes.

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"

Format Tranche/Tableau

Les tranches et tableaux sont encodés par défaut en plusieurs valeurs URL du même nom de valeur.

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"

Incluant l’option comma pour indiquer que le champ doit être codé comme une seule valeur délimitée par des virgules.

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"

Inclure l'option bracket pour indiquer que les multiples valeurs URL doivent avoir "[]" ajoutés au nom de la valeur.

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"

L'option index ajoutera un numéro d'index entre crochets au nom de la valeur.

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"

Structures imbriquées

Toutes les structures imbriquées sont encodées, y compris le nom de la valeur parente avec des crochets pour la portée.

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"

Par défaut, il utilise les crochets, ajoutez l’option dot à un champ de structure imbriqué pour délimiter ses enfants avec . :

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

L'option dot s'applique uniquement au champ sur lequel elle est déclarée ; imbriquez-la à nouveau sur un champ de structure plus profond pour continuer à utiliser des points (sinon ce niveau revient aux crochets).

Type personnalisé

Implémentez les fonctions :

• EncodeParam pour encoder lui-même en paramètre de requête.
• IsZero pour vérifier si un objet est nul afin de déterminer s'il doit être omis lors de l'encodage.

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"

Limitation

• si les éléments dans slice/array sont du type de données struct, l'imbrication multi-niveaux est limitée
• pas encore de décodeur

_Sera amélioré dans les versions futures_

Licence

Distribué sous licence MIT, veuillez consulter le fichier de licence dans le code pour plus de détails.

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