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)

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.