hasaki

README

Hasaki

HTTP Request Library for Go

---

Features

• Buffer Pool
• Trace the Error Stack
• Build-In JSON / XML / WWWForm / Protobuf / YAML Codec
• Request Before and After Middleware
• Export cURL Command in Debug Mode

Install

go get -v github.com/lxzan/hasaki

Usage

Get

// GET https://api.example.com/search
// Send get request with path parameters. Turn on data compression.

resp := hasaki.
    Get("https://api.example.com/%s", "search").
    SetHeader("Accept-Encoding", "gzip, deflate").
    Send(nil)

// GET https://api.example.com/search?q=hasaki&page=1
// Send get request, with Query parameter, encoded with url.Values

resp := hasaki.
    Get("https://api.example.com/search").
    SetQuery(url.Values{
      "q":    []string{"hasaki"},
      "page": []string{"1"},
    }).
    Send(nil)

Post

// POST https://api.example.com/search
// Send post request, encoded with json

type Req struct {
    Q    string `json:"q"`
    Page int    `json:"page"`
}
resp := hasaki.
    Post("https://api.example.com/search").
    Send(Req{
        Q:    "hasaki",
        Page: 1,
    })

// POST https://api.example.com/search
// Send post request, encoded with www-form

resp := hasaki.
    Post("https://api.example.com/search").
    SetEncoder(hasaki.FormEncoder).
    Send(url.Values{
        "q":    []string{"hasaki"},
        "page": []string{"1"},
    })

Stream

// POST https://api.example.com/upload
// Send a put request, using a byte stream

var reader io.Reader
encoder := hasaki.NewStreamEncoder(hasaki.MimeStream)
resp := hasaki.
    Put("https://api.example.com/upload").
    SetEncoder(encoder).
    Send(reader)

Error Stack

// Print the error stack
data := make(map[string]any)
err := hasaki.
    Post("https://api.example.com/upload").
    Send(nil).
    BindJSON(&data)
if err != nil {
    log.Printf("%+v", err)
}

Middleware

Very useful middleware, you can use it to do something before and after the request is sent.

The middleware is a function, it receives a context and a request or response object, and returns a context and an error.

Under code is a simple middleware example , record the request latency.

// You can use the before and after middleware to do something before and after the request is sent

before := hasaki.WithBefore(func(ctx context.Context, request *http.Request) (context.Context, error) {
    return context.WithValue(ctx, "t0", time.Now()), nil
})

after := hasaki.WithAfter(func(ctx context.Context, response *http.Response) (context.Context, error) {
    t0 := ctx.Value("t0").(time.Time)
    log.Printf("latency=%s", time.Since(t0).String())
    return ctx, nil
})

var url = "https://api.github.com/search/repositories"
cli, _ := hasaki.NewClient(before, after)
cli.Get(url).Send(nil)

Documentation

Index

• Constants
• Variables
• func SetClient(c *Client)
• type AfterFunc
• type Any
• type BeforeFunc
• type BytesReadCloser
• type Client
  • func NewClient(options ...Option) (*Client, error)
  • func (c *Client) Delete(url string, args ...any) *Request
  • func (c *Client) Get(url string, args ...any) *Request
  • func (c *Client) Head(url string, args ...any) *Request
  • func (c *Client) Options(url string, args ...any) *Request
  • func (c *Client) Patch(url string, args ...any) *Request
  • func (c *Client) Post(url string, args ...any) *Request
  • func (c *Client) Put(url string, args ...any) *Request
  • func (c *Client) Request(method string, url string, args ...any) *Request
• type Codec
• type Decoder
• type Encoder
  • func NewStreamEncoder(contentType string) Encoder
• type Option
  • func WithAfter(fn AfterFunc) Option
  • func WithBefore(fn BeforeFunc) Option
  • func WithHTTPClient(client *http.Client) Option
  • func WithReuseBody() Option
• type Request
  • func Delete(url string, args ...any) *Request
  • func Get(url string, args ...any) *Request
  • func Head(url string, args ...any) *Request
  • func NewRequest(method string, url string, args ...any) *Request
  • func Options(url string, args ...any) *Request
  • func Patch(url string, args ...any) *Request
  • func Post(url string, args ...any) *Request
  • func Put(url string, args ...any) *Request
  • func (c *Request) Debug() *Request
  • func (c *Request) Send(body any) *Response
  • func (c *Request) SetAfter(f AfterFunc) *Request
  • func (c *Request) SetBefore(f BeforeFunc) *Request
  • func (c *Request) SetContext(ctx context.Context) *Request
  • func (c *Request) SetEncoder(encoder Encoder) *Request
  • func (c *Request) SetHeader(k, v string) *Request
  • func (c *Request) SetHeaders(headers http.Header) *Request
  • func (c *Request) SetQuery(query any) *Request
• type Response
  • func (c *Response) Bind(v any, decoder Decoder) error
  • func (c *Response) BindForm(v *url.Values) error
  • func (c *Response) BindJSON(v any) error
  • func (c *Response) BindXML(v any) error
  • func (c *Response) Context() context.Context
  • func (c *Response) Err() error
  • func (c *Response) ReadBody() ([]byte, error)

Constants

const (
	MimeJson     = "application/json;charset=utf-8"
	MimeYaml     = "application/x-yaml;charset=utf-8"
	MimeXml      = "application/xml;charset=utf-8"
	MimeProtoBuf = "application/x-protobuf"
	MimeForm     = "application/x-www-form-urlencoded"
	MimeStream   = "application/octet-stream"
	MimeJpeg     = "image/jpeg"
	MimeGif      = "image/gif"
	MimePng      = "image/png"
	MimeMp4      = "video/mpeg4"
)

Variables

var (
	JsonCodec = new(jsonCodec)
	FormCodec = new(formCodec)
	XmlCodec  = new(xmlCodec)
)

Functions

func SetClient

func SetClient(c *Client)

SetClient 设置全局客户端 Setting the global client

Types

type AfterFunc

type AfterFunc func(ctx context.Context, response *http.Response) (context.Context, error)

type Any

type Any map[string]any

type BeforeFunc

type BeforeFunc func(ctx context.Context, request *http.Request) (context.Context, error)

type BytesReadCloser

type BytesReadCloser interface {
	io.ReadCloser
	Bytes() []byte
}

type Client

type Client struct {
	// contains filtered or unexported fields
}

func NewClient

func NewClient(options ...Option) (*Client, error)

NewClient 新建一个客户端 Create a new client

func (*Client) Delete

func (c *Client) Delete(url string, args ...any) *Request

func (*Client) Get

func (c *Client) Get(url string, args ...any) *Request

func (*Client) Head

func (c *Client) Head(url string, args ...any) *Request

func (*Client) Options

func (c *Client) Options(url string, args ...any) *Request

func (*Client) Patch

func (c *Client) Patch(url string, args ...any) *Request

func (*Client) Post

func (c *Client) Post(url string, args ...any) *Request

func (*Client) Put

func (c *Client) Put(url string, args ...any) *Request

func (*Client) Request

func (c *Client) Request(method string, url string, args ...any) *Request

type Codec

type Codec interface {
	Encoder
	Decoder
}

type Decoder

type Decoder interface {
	Decode(r io.Reader, v any) error
}

type Encoder

type Encoder interface {
	Encode(v any) (io.Reader, error)
	ContentType() string
}

func NewStreamEncoder

func NewStreamEncoder(contentType string) Encoder

type Option

type Option func(c *config)

func WithAfter

func WithAfter(fn AfterFunc) Option

WithAfter 设置请求后中间件 Setting up post-request middleware

func WithBefore

func WithBefore(fn BeforeFunc) Option

WithBefore 设置请求前中间件 Setting up pre-request middleware

func WithHTTPClient

func WithHTTPClient(client *http.Client) Option

WithHTTPClient 设置HTTP客户端 Setting the HTTP client

func WithReuseBody

func WithReuseBody() Option

WithReuseBody 开启Body可重复读; Response.Body可以被断言为BytesReadCloser, 调用Bytes()方法重复读取. Turn on Body repeatable read; Response.Body can be asserted as BytesReadCloser, call Bytes() method to repeat reads.

type Request

type Request struct {
	// contains filtered or unexported fields
}

func Delete

func Delete(url string, args ...any) *Request

func Get

func Get(url string, args ...any) *Request

func Head

func Head(url string, args ...any) *Request

func NewRequest

func NewRequest(method string, url string, args ...any) *Request

NewRequest 新建一个请求 Create a new request

func Options

func Options(url string, args ...any) *Request

func Patch

func Patch(url string, args ...any) *Request

func Post

func Post(url string, args ...any) *Request

func Put

func Put(url string, args ...any) *Request

func (*Request) Debug

func (c *Request) Debug() *Request

Debug 开启调试模式, 打印CURL命令 Enable debug mode, print CURL commands

func (*Request) Send

func (c *Request) Send(body any) *Response

Send 发送请求 Send http request

func (*Request) SetAfter

func (c *Request) SetAfter(f AfterFunc) *Request

SetAfter 设置请求后中间件 Setting up post-request middleware

func (*Request) SetBefore

func (c *Request) SetBefore(f BeforeFunc) *Request

SetBefore 设置请求前中间件 Setting up pre-request middleware

func (*Request) SetContext

func (c *Request) SetContext(ctx context.Context) *Request

SetContext 设置请求上下文 Set Request context

func (*Request) SetEncoder

func (c *Request) SetEncoder(encoder Encoder) *Request

SetEncoder 设置编码器 Set request body encoder

func (*Request) SetHeader

func (c *Request) SetHeader(k, v string) *Request

SetHeader 设置请求头 Set Request Header

func (*Request) SetHeaders

func (c *Request) SetHeaders(headers http.Header) *Request

SetHeaders 批量设置请求头 Set Request Header

func (*Request) SetQuery

func (c *Request) SetQuery(query any) *Request

SetQuery 设置查询参数, 详情请参考 https://github.com/go-playground/form To set the query parameters, please refer to https://github.com/go-playground/form for details.

type Response

type Response struct {
	*http.Response
	// contains filtered or unexported fields
}

func (*Response) Bind

func (c *Response) Bind(v any, decoder Decoder) error

func (*Response) BindForm

func (c *Response) BindForm(v *url.Values) error

func (*Response) BindJSON

func (c *Response) BindJSON(v any) error

func (*Response) BindXML

func (c *Response) BindXML(v any) error

func (*Response) Context

func (c *Response) Context() context.Context

func (*Response) Err

func (c *Response) Err() error

func (*Response) ReadBody

func (c *Response) ReadBody() ([]byte, error)