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"),
)

인코더는 구조체를 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 형식

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 객체가 0값인지 확인하여 인코딩 시 생략할지 결정합니다.

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 ---