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には構造体をurl.ValuesにエンコードするためのValues()およびEncode()関数があります。

サポートされているデータ型：

• すべての基本型（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"

Bool 形式

ブール値を整数にエンコードするには 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 ---