zhttp

package module
v0.0.0-...-98ce542 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 13, 2023 License: Apache-2.0 Imports: 21 Imported by: 0

README

zhttp

zhttp 是一个对 net/http 标准库的封装,参考了 python 中著名的 requests 库,支持标准库中的连接池,支持dns缓存,支持流式文件上传,支持多种body格式,很多代码及思路来自grequests

PkgGoDev

Installation

go get github.com/greyh4t/zhttp

Usage

直接使用默认client
import "github.com/greyh4t/zhttp"

func main() {
	resp, err := zhttp.Get("http://www.example.com/", nil)
	if err != nil {
		return
	}
	resp.Close()
}
更改默认client配置
import "github.com/greyh4t/zhttp"

func main() {
	zhttp.InitDefaultClient(&zhttp.HTTPOptions{
		Proxies: zhttp.MustProxy(zhttp.M{
			"http":  "http://127.0.0.1:8080",
			"https": "http://127.0.0.1:8080",
		}),
	})

	resp, err := zhttp.Get("http://www.example.com/", nil)
	if err != nil {
		return
	}
	resp.Close()
}
创建独立的client使用
import "github.com/greyh4t/zhttp"

func main() {
	z := zhttp.New(&zhttp.HTTPOptions{
		Proxies: zhttp.MustProxy(zhttp.M{
			"http":  "http://127.0.0.1:8080",
			"https": "http://127.0.0.1:8080",
		}),
	})

	resp, err := z.Get("http://www.example.com/", nil)
	if err != nil {
		return
	}
	resp.Close()
}

Example

如下为简单示例,更多使用方法请参考godoc

package main

import (
	"log"
	"net/url"
	"os"
	"time"

	"github.com/greyh4t/zhttp"
	"github.com/greyh4t/zhttp/tools"
)

func main() {
	z := zhttp.New(&zhttp.HTTPOptions{
		UserAgent: "global-useragent",
		Headers: zhttp.M{
			"globalheader1": "value1",
			"globalheader2": "value2",
		},
		DNSCacheExpire:      time.Minute * 10,
		DNSServer:           "8.8.8.8:25",
		InsecureSkipVerify:  true,
		DialTimeout:         time.Second * 5,
		TLSHandshakeTimeout: time.Second * 5,
		KeepAlive:           time.Second * 10,
		MaxIdleConns:        10,
	})

	// 请求1
	resp, err := z.Get("http://www.example.com/", nil)
	if err != nil {
		log.Fatal(err)
	}
	log.Println(resp.StatusCode, resp.Status, resp.ContentLength)
	log.Println(resp.Headers.String())
	log.Println(resp.Cookies().String())
	log.Println(resp.DumpRequest())
	log.Println(resp.Body.String())
	resp.Close()

	// 请求2 post表单
	resp, err = z.Post("http://www.example.com/?query1=value3", &zhttp.ReqOptions{
		DisableRedirect: true,
		Timeout:         time.Second * 10,
		Proxies: zhttp.MustProxy(zhttp.M{
			"http":  "http://127.0.0.1:8080",
			"https": "http://127.0.0.1:8080",
		}),
		Headers: zhttp.M{
			"header1": "value1",
			"header2": "value2",
		},
		Cookies: zhttp.M{
			"k1": "v1",
			"k2": "v2",
		},
		Body: zhttp.Form(zhttp.M{
			"key1": "value1",
			"key2": "value2",
		}),
		Query: url.Values{
			"query1": {"value1"},
			"query2": {"value2"},
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	body := resp.Body.Bytes()
	if resp.Body.Err != nil {
		log.Fatal(resp.Body.Err)
	}
	resp.Close()
	log.Println(body)

	// 请求3 post表单
	resp, err = z.Post("http://www.example.com/?query1=value1&query2=value2", &zhttp.ReqOptions{
		Body: zhttp.FormString(`fk1=fv1&fk2=fv2`),
		Headers: zhttp.M{
			"Cookie": "k1=v1; k2=v2",
		},
		UserAgent: "zhttp-ua-test",
	})
	if err != nil {
		log.Fatal(err)
	}
	resp.Close()

	// 请求4 post json
	resp, err = z.Post("http://www.example.com/", &zhttp.ReqOptions{
		Body: zhttp.JSONString(`{"jk1":"jv","jk2":2}`),
		Headers: zhttp.M{
			"Cookie": "k1=v1; k2=v2",
		},
		UserAgent: "zhttp-ua-test",
		IsAjax:    true,
	})
	if err != nil {
		log.Fatal(err)
	}
	resp.Close()

	// 请求5 文件上传
	f, err := os.Open("test.txt")
	if err != nil {
		log.Fatal(err)
	}
	defer f.Close()

	resp, err = z.Post("http://www.example.com/", &zhttp.ReqOptions{
		Body:        zhttp.Reader(f),
		ContentType: "text/plain",
		Headers: zhttp.M{
			"h1": "v1",
			"h2": "v2",
		},
		Auth: zhttp.Auth{
			Username: "username",
			Password: "password",
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	resp.Close()

	// 请求6 文件上传
	file1, err := tools.FileFromDisk("file1.txt")
	if err != nil {
		log.Fatal(err)
	}

	file2, err := tools.FileFromDisk("file2.txt")
	if err != nil {
		log.Fatal(err)
	}

	resp, err = z.Post("http://www.example.com/", &zhttp.ReqOptions{
		Body: zhttp.Multipart([]*zhttp.File{file1, file2}, zhttp.M{
			"field1": "value1",
			"field2": "value2",
		}),
		Host: "file.example.com",
	})
	if err != nil {
		log.Fatal(err)
	}
	resp.Close()

	// 请求7 session的使用
	s := z.NewSession()
	resp, err = s.Post("http://www.example.com/login", &zhttp.ReqOptions{
		Body: zhttp.Form(zhttp.M{
			"username": "username",
			"password": "password",
		}),
		Timeout: time.Second * 10,
	})
	if err != nil {
		log.Fatal(err)
	}
	resp.Close()

	resp, err = s.Get("http://www.example.com/userinfo", nil)
	if err != nil {
		log.Fatal(err)
	}
	resp.Close()
}

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CookieMapFromRaw

func CookieMapFromRaw(rawCookie string) map[string]string

CookieMapFromRaw parse a cookie in string format to map[string]string

func InitDefaultClient

func InitDefaultClient(options *HTTPOptions)

InitDefaultClient initialization the default zhttp client with options

func MustProxy

func MustProxy(proxies map[string]string) map[string]*url.URL

MustProxy convert scheme and url string to map[string]*url.URL. If there have any error, will panic

Types

type Auth

type Auth struct {
	Username string
	Password string
}

Auth is used to perform HTTP Basic authentication

type Body

type Body interface {
	Content() (io.Reader, string, error)
}

Body is used to define the body part of the http request

func Bytes

func Bytes(body []byte) Body

Bytes used to create Body from []byte, need to set the Content-Type yourself

func Form

func Form(body map[string]string) Body

Form used to create Body from map, and set form Content-Type

func FormBytes

func FormBytes(body []byte) Body

FormBytes used to create Body from []byte, and set form Content-Type

func FormString

func FormString(body string) Body

FormString used to create Body from string, and set form Content-Type

func FormValues

func FormValues(body map[string][]string) Body

FormValues used to create Body from map, and set form Content-Type The difference with form is that it supports setting multiple parameters with the same name

func JSON

func JSON(body interface{}) Body

JSON used to create Body from map, struct and so on, and set json Content-Type

func JSONBytes

func JSONBytes(body []byte) Body

JSONBytes used to create Body from []byte, and set json Content-Type

func JSONString

func JSONString(body string) Body

JSONString used to create Body from string, and set json Content-Type

func Multipart

func Multipart(files []*File, form map[string]string) Body

Multipart used to create Body object

func MultipartStream

func MultipartStream(files []*File, form map[string]string) Body

MultipartStream used to create Body object Use streaming upload to prevent all files from being loaded into memory

func Reader

func Reader(body io.Reader) Body

Reader used to create Body from io.Reader, need to set the Content-Type yourself

func String

func String(body string) Body

String used to create Body from string, need to set the Content-Type yourself

func XML

func XML(body interface{}) Body

XML used to create Body from struct, and set xml Content-Type

func XMLBytes

func XMLBytes(body []byte) Body

XMLBytes used to create Body from []byte, and set xml Content-Type

func XMLString

func XMLString(body string) Body

XMLString used to create Body from string, and set xml Content-Type

type BytesBody

type BytesBody struct {
	ContentType string
	Body        []byte
}

func (*BytesBody) Content

func (body *BytesBody) Content() (io.Reader, string, error)

type Cookies

type Cookies []*http.Cookie

Cookies is a wrapper for []*http.Cookie

func (Cookies) Get

func (c Cookies) Get(name string) string

Get gets the cookie value with the given name. If there are no values associated with the name, Get returns "".

func (Cookies) Has

func (c Cookies) Has(name string) bool

Has will return whether the specified cookie is set in response.

func (Cookies) String

func (c Cookies) String() string

String return the cookies in string type. like key1=value1; key2=value2

type File

type File struct {
	// Name is the name of the file that you wish to upload.
	// We use this to guess the mimetype as well as pass it onto the server
	Name string

	// Contents is happy as long as you pass it a io.ReadCloser (which most file use anyways)
	Contents io.ReadCloser

	// FieldName is form field name
	FieldName string

	// Mime represents which mime should be sent along with the file.
	// When empty, defaults to application/octet-stream
	Mime string
}

type HTTPOptions

type HTTPOptions struct {
	// UserAgent allows you to set an arbitrary custom user agent
	UserAgent string

	// Cookie allows you to attach cookies to every request.
	Cookies map[string]string

	// Headers uses to set custom HTTP headers to every request
	// The header name is case-sensitive
	Headers map[string]string

	// Proxies is a map in the following format
	// *protocol* => proxy address e.g http => http://127.0.0.1:8080,
	Proxies map[string]*url.URL

	// InsecureSkipVerify is a flag that specifies if we should validate the
	// server's TLS certificate. It should be noted that Go's TLS verify mechanism
	// doesn't validate if a certificate has been revoked
	InsecureSkipVerify bool

	// RequestTimeout is the maximum amount of time a whole request(include dial / request / redirect) will wait
	RequestTimeout time.Duration

	// Timeout is the time that the client will wait between bytes sent from the server.
	Timeout time.Duration

	// DialTimeout is the maximum amount of time a dial will wait for a connect to complete
	DialTimeout time.Duration

	// TLSHandshakeTimeout specifies the maximum amount of time waiting to
	// wait for a TLS handshake. Zero means no timeout.
	TLSHandshakeTimeout time.Duration

	// KeepAlive specifies the interval between keep-alive
	// probes for an active network connection.
	// If zero, keep-alive probes are sent with a default value
	// (currently 15 seconds), if supported by the protocol and operating
	// system. Network protocols or operating systems that do
	// not support keep-alives ignore this field.
	// If negative, keep-alive probes are disabled.
	KeepAlive time.Duration

	// DisableKeepAlives, if true, disables HTTP keep-alives and
	// will only use the connection to the server for a single
	// HTTP request.
	//
	// This is unrelated to the similarly named TCP keep-alives.
	DisableKeepAlives bool

	// DisableCompression, if true, prevents the Transport from
	// requesting compression with an "Accept-Encoding: gzip"
	// request header when the Request contains no existing
	// Accept-Encoding value. If the Transport requests gzip on
	// its own and gets a gzipped response, it's transparently
	// decoded in the Response.Body. However, if the user
	// explicitly requested gzip it is not automatically
	// uncompressed.
	DisableCompression bool

	// MaxIdleConns controls the maximum number of idle (keep-alive)
	// connections across all hosts. Zero means no limit.
	MaxIdleConns int

	// MaxIdleConnsPerHost, if non-zero, controls the maximum idle
	// (keep-alive) connections to keep per-host. If zero,
	// DefaultMaxIdleConnsPerHost is used.
	MaxIdleConnsPerHost int

	// MaxConnsPerHost optionally limits the total number of
	// connections per host, including connections in the dialing,
	// active, and idle states. On limit violation, dials will block.
	//
	// Zero means no limit.
	MaxConnsPerHost int

	// IdleConnTimeout is the maximum amount of time an idle
	// (keep-alive) connection will remain idle before closing
	// itself.
	// Zero means no limit.
	IdleConnTimeout time.Duration

	// DNSCacheExpire is the timeout of dns cache , if zero, not use dns cache
	DNSCacheExpire time.Duration

	// DNSServer allows you to set an custom dns host, like 1.1.1.1:25, only effective in linux
	DNSServer string

	// NoUA is a flag that means do not set default UserAgent
	NoUA bool
}

HTTPOptions is the options for zhttp.Zhttp, it will effective on per request

type Headers

type Headers map[string][]string

Headers is a wrapper for http.Header

func (Headers) Get

func (h Headers) Get(key string) string

Get gets the value associated with the given key. If there are no values associated with the key, Get returns "". multiple header fields with the same name will be join with ", ". It is case insensitive; textproto.CanonicalMIMEHeaderKey is used to canonicalize the provided key. To access multiple values of a key, or to use non-canonical keys, access the map directly.

func (Headers) Has

func (h Headers) Has(key string) bool

Has will return information about whether a response header with the given name exists. If not exist, Has returns false. It is case insensitive;

func (Headers) String

func (h Headers) String() string

String return a header in wire format.

type JSONBody

type JSONBody struct {
	Body interface{}
}

func (*JSONBody) Content

func (body *JSONBody) Content() (io.Reader, string, error)

type M

type M map[string]string

M is short for map[string] string

type MultipartBody

type MultipartBody struct {
	Files  []*File
	Form   map[string]string
	Stream bool
}

func (*MultipartBody) Close

func (body *MultipartBody) Close()

func (*MultipartBody) Content

func (body *MultipartBody) Content() (io.Reader, string, error)

type P

type P map[string]*url.URL

P is short for map[string]*url.URL

type ReaderBody

type ReaderBody struct {
	ContentType string
	Body        io.Reader
}

func (*ReaderBody) Content

func (body *ReaderBody) Content() (io.Reader, string, error)

type ReaderWithCancel

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

func (*ReaderWithCancel) Close

func (r *ReaderWithCancel) Close() error

func (*ReaderWithCancel) Read

func (r *ReaderWithCancel) Read(p []byte) (n int, err error)

type ReqOptions

type ReqOptions struct {
	// RequestTimeout is the maximum amount of time a whole request(include dial / request / redirect) will wait.
	// if non-zero, overwrite HTTPOptions.Timeout in current request.
	RequestTimeout time.Duration

	// Timeout is the time that the client will wait between bytes sent from the server.
	Timeout time.Duration

	// ContentType allows you to set an arbitrary custom content type
	ContentType string

	// UserAgent allows you to set an arbitrary custom user agent
	UserAgent string

	// Proxies is a map in the following format
	// *protocol* => proxy address e.g http => http://127.0.0.1:8080,
	// If setted, overwrite HTTPOptions.Proxies in current request.
	Proxies map[string]*url.URL

	// DisableRedirect will disable redirect for request
	DisableRedirect bool

	// Query will be encode to query string that may be used within a GET request
	Query url.Values

	// Body is a interface{} that will eventually convert into the the body of a POST request
	Body Body

	// Cookie allows you to attach cookies to your request.
	// Only effective in current request
	Cookies map[string]string

	// Headers uses to set custom HTTP headers to the request
	// The header name is case-sensitive
	Headers map[string]string

	// Host allows you to set an arbitrary custom host
	Host string

	// HostIP allows you to set an custom dns resolution for current request.
	// The value should be an IP.
	// When proxy usable, this value does not take effect
	HostIP string

	// Auth allows you to specify a user name and password that you wish to
	// use when requesting the URL. It will use basic HTTP authentication
	// formatting the username and password in base64.
	Auth Auth

	// IsAjax is a flag that can be set to make the request appear
	// to be generated by browser Javascript.
	IsAjax bool

	// NoUA is a flag that means do not set default UserAgent
	NoUA bool
}

ReqOptions is the options for single request

type Response

type Response struct {
	StatusCode    int
	Status        string
	ContentLength int64
	Headers       Headers
	Body          *ZBody
	RawResponse   *http.Response
	// contains filtered or unexported fields
}

Response is a wrapper for *http.Response

func Delete

func Delete(url string, options *ReqOptions) (*Response, error)

func Get

func Get(url string, options *ReqOptions) (*Response, error)
func Head(url string, options *ReqOptions) (*Response, error)

func Options

func Options(url string, options *ReqOptions) (*Response, error)

func Patch

func Patch(url string, options *ReqOptions) (*Response, error)

func Post

func Post(url string, options *ReqOptions) (*Response, error)

func Put

func Put(url string, options *ReqOptions) (*Response, error)

func Request

func Request(method, url string, options *ReqOptions) (*Response, error)

func (*Response) Close

func (resp *Response) Close() error

Close close the http response body.

func (*Response) Cookies

func (resp *Response) Cookies() Cookies

Cookies parses and returns the cookies set in the Set-Cookie headers.

func (*Response) DumpRequest

func (resp *Response) DumpRequest() string

DumpRequest format the last http.Request to string. Notice, the order of headers is not strictly consistent

func (*Response) DumpResponse

func (resp *Response) DumpResponse() string

DumpResponse format the last http.Response to string. Notice, the order of headers is not strictly consistent

func (*Response) Err

func (resp *Response) Err() error

Err returns the first non-EOF error that was encountered by read body.

func (*Response) OK

func (resp *Response) OK() bool

OK validates that the server returned a 2xx code.

type Session

type Session struct {
	CookieJar *cookiejar.Jar
	// contains filtered or unexported fields
}

Session is a client used to send http requests. Unlike Zhttp, it handle session for all requests

func NewSession

func NewSession() *Session

NewSession generate an default client that will handle session for all requests

func (*Session) Delete

func (s *Session) Delete(url string, options *ReqOptions) (*Response, error)

func (*Session) Get

func (s *Session) Get(url string, options *ReqOptions) (*Response, error)

func (*Session) Head

func (s *Session) Head(url string, options *ReqOptions) (*Response, error)

func (*Session) Options

func (s *Session) Options(url string, options *ReqOptions) (*Response, error)

func (*Session) Patch

func (s *Session) Patch(url string, options *ReqOptions) (*Response, error)

func (*Session) Post

func (s *Session) Post(url string, options *ReqOptions) (*Response, error)

func (*Session) Put

func (s *Session) Put(url string, options *ReqOptions) (*Response, error)

func (*Session) Request

func (s *Session) Request(method string, url string, options *ReqOptions) (*Response, error)

type StringBody

type StringBody struct {
	ContentType string
	Body        string
}

func (*StringBody) Content

func (body *StringBody) Content() (io.Reader, string, error)

type XMLBody

type XMLBody struct {
	Body interface{}
}

func (*XMLBody) Content

func (body *XMLBody) Content() (io.Reader, string, error)

type ZBody

type ZBody struct {
	Err error
	// contains filtered or unexported fields
}

ZBody is a wrapper for http.Response.ZBody

func (*ZBody) Bytes

func (b *ZBody) Bytes() []byte

Bytes return the body with []byte type

func (*ZBody) ClearCache

func (b *ZBody) ClearCache()

ClearCache clear the cache of body

func (*ZBody) Close

func (b *ZBody) Close() error

Close close the body. Must be called when the response is used

func (*ZBody) Read

func (b *ZBody) Read(p []byte) (int, error)

Read is the implementation of the reader interface

func (*ZBody) ReadN

func (b *ZBody) ReadN(n int64) []byte

ReadN read and return n byte of body, and cache them

func (*ZBody) String

func (b *ZBody) String() string

String return the body in string type

type Zhttp

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

func New

func New(options *HTTPOptions) *Zhttp

New generate an *Zhttp client to send request

func NewWithDNSCache

func NewWithDNSCache(options *HTTPOptions, cache *dnscache.Cache) *Zhttp

NewWithDNSCache generate an *Zhttp client that uses an external DNSCache. This will ignore HTTPOptions.DNSCacheExpire and HTTPOptions.DNSServer

func (*Zhttp) Delete

func (z *Zhttp) Delete(url string, options *ReqOptions) (*Response, error)

func (*Zhttp) Get

func (z *Zhttp) Get(url string, options *ReqOptions) (*Response, error)

func (*Zhttp) Head

func (z *Zhttp) Head(url string, options *ReqOptions) (*Response, error)

func (*Zhttp) NewSession

func (z *Zhttp) NewSession() *Session

NewSession generate an client that will handle session for all requests

func (*Zhttp) Options

func (z *Zhttp) Options(url string, options *ReqOptions) (*Response, error)

func (*Zhttp) Patch

func (z *Zhttp) Patch(url string, options *ReqOptions) (*Response, error)

func (*Zhttp) Post

func (z *Zhttp) Post(url string, options *ReqOptions) (*Response, error)

func (*Zhttp) Put

func (z *Zhttp) Put(url string, options *ReqOptions) (*Response, error)

func (*Zhttp) Request

func (z *Zhttp) Request(method, url string, options *ReqOptions) (*Response, error)

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL