fetcher

package module
v0.0.0-...-7e0d14e Latest Latest
Warning

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

 Go to latest Published: Mar 1, 2022 License: MIT Imports: 12 Imported by: 16

README

Fetcher HTTP请求库

一个易于配置和扩充的HTTP请求库。

主要目的为

  • 创建易于标准化配置和加载的客户端以及访问点
  • 提供一个构建请求的标准化框架

Fetcher 请求配置

每一个Fetcher对象包括了创建一个HTTP请求必须的参数，包括：

  • URL 请求的地址
  • Method 请求的方式
  • Header 请求头
  • Body 请求正文
  • Builders 其他在http.Request对象创建后进一步设置的构建器

原则上在使用本库时不应该手工创建Fetch数据

通过Fetcher.Raw方法可以将Fetcher转化为http.Request对象和Doer请求器。

Command 请求命令

请求命令的作用是修改Fethcer的配置参数，最后确定创建出的http请求。 大部分的扩展功能应该以Command的形式来实现

常用命令

本库定义了一些常用命令如下

  • URL 请求地址命令
  • Method 请求方式命令
  • Replace 替换地址中路径部分命令
  • PathPrefix 将路径加入指定前缀命令
  • PathSuffix 将路径加入指定后缀命令
  • PathJoin 将路径Join后续目录的命令
  • Body 指定请求正文命令
  • JSONBody 将对象以JSON格式序列化为正文命令
  • Header 添加请求头命令
  • SetDoer 设置请求器命令
  • SetQuery 设置查询字符串命令
  • BasicAuth 设置Basic auth命令
  • RequestBuilder 设置请求构建器命令
  • HeaderBuilder 设置请求头构建器命令
  • MethodBuilder 设置请求方式建器命令
  • MultiPartWriter 加入MultiPart,上传文件的命令。注意，使用时需要手动Close

Preset 预设

Preset是一系列有书虚的命令的集合。 Preset提供了一系列快速操作的方法以便维护。 Preset应该是使用本库的主要方式。

配置

本库预先提供了两种常用的易与反序列化的配置结构

  • ServerInfo 通过URL，Method,Header来定义需要创建的请求。
  • Server 通过ServerInfo和Client来定义需要创建的请求。

Response响应

Response结构是对 http.Response的简单封装。

提供了BodyContent方法来供反复读取数据。

提供了直接作为error对象的能力

能够通过传入一个code参数，直接生成带code的api错误。

Parser 解析器

解析器是能够对响应结果进行进一步处理的接口。

能够在正常的请求形式中快速的解析需要的数据。

当解析过程中出错时，则认为整个请求都出错。

预定义的解析器
  • Should200 判断请求状态码是否为200.不是的的话将请求当错误抛出。是的话继续执行传入的解析器
  • ShouldSuccess 判断请求状态码是否为成功(<300).不是的的话将请求当错误抛出。是的话继续执行传入的解析器
  • ShouldNoError 判断请求状态码是否不是服务器错误(<500).不是的的话将请求当错误抛出。是的话继续执行传入的解析器
  • AsBytes 将响应内容当成字节切片读出
  • AsString 将响应内容当成字符串读出
  • AsJSON 将响应内容按JSON格式反序列化

Doer 请求器

用于发起请求的接口，为空时使用http.DefaultClient发起请求

Client

一个易于反序列化的请求起配置结构

可配置属性如下:

  • TimeoutInSecond 按秒计算的超时属性，默认120
  • MaxIdleConns 最大空闲链接，默认20
  • IdleConnTimeoutInSecond 以秒计算的空闲超时，默认120
  • TLSHandshakeTimeoutInSecond int64 TLS握手超时
  • Proxy URL形式的代理地址

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	//Post http POST method Command.
	Post = Method("POST")
	//Get http GET method Command.
	Get = Method("GET")
	//Put http PUT method Command.
	Put = Method("PUT")
	//Delete http DELETE method Command.
	Delete = Method("DELETE")
)
View Source 
var DefaultDoer = func() Doer {
	return http.DefaultClient
}

DefaultDoer default doer used to do http request if not setted.

View Source 
var DefaultIdleConnTimeout = 120 * time.Second

DefaultIdleConnTimeout default client idle conn timeout.

View Source 
var DefaultMaxIdleConns = 20

DefaultMaxIdleConns default client max idle conns

View Source 
var DefaultTLSHandshakeTimeout = 30 * time.Second

DefaultTLSHandshakeTimeout default client tls handshake time out.

View Source 
var DefaultTimeout = 120 * time.Second

DefaultTimeout default client timeout

View Source 
var ErrMsgLengthLimit = 512

ErrMsgLengthLimit max error message length

Functions

func CloneHeader 

func CloneHeader(h http.Header) http.Header

CloneHeader clone http header

func CloneRequestBuilders 

func CloneRequestBuilders(b []func(*http.Request) error) []func(*http.Request) error

CloneRequestBuilders clone request builders

func CompareAPIErrCode 

func CompareAPIErrCode(err error, code interface{}) bool

CompareAPIErrCode check if error is an ApiCodeErr with given api err code.

func CompareResponseErrStatusCode 

func CompareResponseErrStatusCode(err error, statuscode int) bool

CompareResponseErrStatusCode check if error is a ResponseErr with given status code.

func Exec 

func Exec(f *Fetcher, b ...Command) error

Exec exec given commands to fetcher by order. Return any error if raised

func GetAPIErrCode 

func GetAPIErrCode(err error) string

GetAPIErrCode get api error code form error. Return empty string if err is not an ApiCodeErr

func GetAPIErrContent 

func GetAPIErrContent(err error) string

GetAPIErrContent get api error code form error. Return empty string if err is not an ApiCodeErr

func IsResponseErr 

func IsResponseErr(err error) bool

IsResponseErr check if is response error

func MergeHeader 

func MergeHeader(dst http.Header, src http.Header)

MergeHeader merge src header to dst

func URLToProxy 

func URLToProxy(index string) func(*http.Request) (*url.URL, error)

URLToProxy Convert url to fixed proxy. Return proxy created and any error if raised.

Types

type APICodeErr 

type APICodeErr struct {
	//URI api uri.
	URI string
	//Code api error code.
	Code string
	//Method request method
	Method string
	//Content api response.
	Content []byte
}

APICodeErr api code error struct.

func NewAPICodeErr 

func NewAPICodeErr(url string, method string, code interface{}, content []byte) *APICodeErr

NewAPICodeErr create a new api code error with given url,method,code,and content.

func (*APICodeErr) Error 

func (r *APICodeErr) Error() string

Error used as a error which return request url,request status,erro code,request content. Error max length is ErrMsgLengthLimit.

func (*APICodeErr) ErrorPrivateRef 

func (r *APICodeErr) ErrorPrivateRef() string

ErrorPrivateRef error private ref

type Client 

type Client struct {
	//TimeoutInSecond timeout in secound
	//Default value is 120.
	TimeoutInSecond int64
	//MaxIdleConns max idel conns.
	//Default value is 20
	MaxIdleConns int
	//IdleConnTimeoutInSecond idel conn timeout in second.
	//Default value is 120
	IdleConnTimeoutInSecond int64
	//TLSHandshakeTimeoutInSecond tls handshake timeout in secound.
	//default value is 30.
	TLSHandshakeTimeoutInSecond int64
	//Proxy proxy url.
	//If set to empty string,clients will not use proxy.
	//Default value is empty string.
	Proxy string
	// contains filtered or unexported fields
}

Client http client config struct Value should not changed after first "DO" call.

func (*Client) Clone 

func (c *Client) Clone() *Client

Clone clone a new client.

func (*Client) CreateDoer 

func (c *Client) CreateDoer() (Doer, error)

CreateDoer create doer. Return doer createrd and any error if raised.

func (*Client) Do 

func (c *Client) Do(req *http.Request) (*http.Response, error)

Do create request ,client with given f.etcher and commands and fetch Return http response and any error if raised.

func (*Client) Exec 

func (c *Client) Exec(f *Fetcher) error

Exec exec command to modify fetcher. Return any error if raised.

func (*Client) SelfCheck 

func (c *Client) SelfCheck() error

SelfCheck self check. Return any error if raised.

type Command 

type Command interface {
	//Exec exec command to modify fetcher.
	//Return any error if raised.
	Exec(*Fetcher) error
}

Command fetch command interface which used to modify fetch

func BasicAuth 

func BasicAuth(username string, password string) Command

BasicAuth command which modify fetcher to set given basic auth info.

func Body 

func Body(body io.Reader) Command

Body command which modify fetcher body to given reader. 

func Header(h http.Header) Command

Header command which merge fetcher header by given reader.

func HeaderBuilder 

func HeaderBuilder(p HeaderBuilderProvier) Command

HeaderBuilder command which modify fetcher header by given header builder provider.

func JSONBody 

func JSONBody(v interface{}) Command

JSONBody command which modify fetcher body to given value as json. Fetcher body will set to nil if v is nil.

func MethodBuilder 

func MethodBuilder(p MethodBuilderProvider) Command

MethodBuilder command which modify fetcher method by given method builder provider.

func Params 

func Params(params url.Values) Command

Params command which modify fetcher to set given params.

func ParamsBuilder 

func ParamsBuilder(p ParamsBuilderProvier) Command

ParamsBuilder command which modify fetcher header by given params builder provider.

func ParsedURL 

func ParsedURL(u *url.URL) Command

ParsedURL create new command which modify fetcher url to given prased url

func Replace 

func Replace(placeholder string, value string) Command

Replace command which modify fetcher path by given placeholder and value.

func RequestBuilder 

func RequestBuilder(p RequestBuilderProvider) Command

RequestBuilder command which append given request builder to fetcher.

func SetDoer 

func SetDoer(d Doer) Command

SetDoer command which modify fetcher doer to given doer.

func SetHeader 

func SetHeader(key string, value string) Command

SetHeader command which set fetcher header by given key and value.

func SetQuery 

func SetQuery(name string, value string) Command

SetQuery command which modify fetcher to set given query.

func URL 

func URL(u string) Command

URL create new command which modify fetcher url to given url

type CommandFunc 

type CommandFunc func(*Fetcher) error

CommandFunc command func

func (CommandFunc) Exec 

func (f CommandFunc) Exec(e *Fetcher) error

Exec exec command to modify fetcher. Return any error if raised.

type Doer 

type Doer interface {
	Do(req *http.Request) (*http.Response, error)
}

Doer doer interface

type DoerFactory 

type DoerFactory interface {
	//CreateDoer create doer.
	//Return doer createrd and any error if raised.
	CreateDoer() (*Doer, error)
}

DoerFactory doer factory

type Fetcher 

type Fetcher struct {
	//URL http url used to create http request
	URL *url.URL
	//Header http header used to create http request
	Header http.Header
	//Method http method used to create http request
	Method string
	//Body request body
	Body io.Reader
	//Builders request builder which should called in order after http request created.
	Builders []func(*http.Request) error
	//Doer http client by which will do request
	Doer Doer
}

Fetcher http request fetcher struct. New fetcher should be created when new http request buildding. You should not edit Fetcher value directly,use Command and Preset instead.

func New 

func New() *Fetcher

New create new fetcher

func (*Fetcher) AppendBuilder 

func (f *Fetcher) AppendBuilder(b ...func(*http.Request) error)

AppendBuilder append request builders to fetcher. Fetcher builders will be cloned.

func (*Fetcher) Fetch 

func (f *Fetcher) Fetch() (*http.Response, error)

Fetch create http requuest and fetch. Return http response and any error if raised.

func (*Fetcher) Raw 

func (f *Fetcher) Raw() (*http.Request, Doer, error)

Raw create raw http request,doer and any error if raised.

type HeaderBuilderFunc 

type HeaderBuilderFunc func(http.Header) error

HeaderBuilderFunc header builde func

func (HeaderBuilderFunc) Exec 

func (b HeaderBuilderFunc) Exec(f *Fetcher) error

Exec exec command to modify fetcher. Return any error if raised.

type HeaderBuilderProvier 

type HeaderBuilderProvier interface {
	BuildHeader(http.Header) error
}

HeaderBuilderProvier header builde provider

type Host 

type Host string

Host command which modify fetcher url with given host

func (Host) Exec 

func (h Host) Exec(f *Fetcher) error

Exec exec command to modify fetcher. Return any error if raised.

type Method 

type Method string

Method command which modify fetcher method to given method

func (Method) Exec 

func (m Method) Exec(f *Fetcher) error

Exec exec command to modify fetcher. Return any error if raised.

type MethodBuilderFunc 

type MethodBuilderFunc func() (string, error)

MethodBuilderFunc method builder func

func (MethodBuilderFunc) Exec 

func (b MethodBuilderFunc) Exec(f *Fetcher) error

Exec exec command to modify fetcher. Return any error if raised.

type MethodBuilderProvider 

type MethodBuilderProvider interface {
	RequestMethod() (string, error)
}

MethodBuilderProvider method builder provider

type MultiPartWriter 

type MultiPartWriter struct {
	*multipart.Writer
	// contains filtered or unexported fields
}

MultiPartWriter multipart writer command

func NewMultiPartWriter 

func NewMultiPartWriter() *MultiPartWriter

NewMultiPartWriter create new MultiPartWriter command to upload file. You should close writer before exec it.

func (*MultiPartWriter) Exec 

func (w *MultiPartWriter) Exec(f *Fetcher) error

Exec exec command to modify fetcher. Return any error if raised.

func (*MultiPartWriter) WriteFile 

func (w *MultiPartWriter) WriteFile(fieldname, filename string, src io.Reader) error

WriteFile write file with given fieldname,filename and data

type ParamsBuilderFunc 

type ParamsBuilderFunc func(url.Values) error

ParamsBuilderFunc param builde func type

func (ParamsBuilderFunc) Exec 

func (b ParamsBuilderFunc) Exec(f *Fetcher) error

Exec exec command to modify fetcher. Return any error if raised.

type ParamsBuilderProvier 

type ParamsBuilderProvier interface {
	BuildParams(url.Values) error
}

ParamsBuilderProvier params builde provider

type Parser 

type Parser interface {
	//Parse parse response data.
	//Return Response and any error if raised.
	Parse(*Response) error
}

Parser response parser interface

func AsBytes 

func AsBytes(bytes *[]byte) Parser

AsBytes create parser which parse givn byte slice from response.

func AsJSON 

func AsJSON(v interface{}) Parser

AsJSON create parser which parse givn value from response a JSON format.

func AsString 

func AsString(str *string) Parser

AsString create parser which parse givn string from response.

func Download 

func Download(w io.Writer) Parser

Download create parser which parse givn byte slice from response. You SHOULD NOT use BodyContent if you parsed response with Download Parser. This parser is designed to download file.

func Should200 

func Should200(p Parser) Parser

Should200 parser that check if status code == 200. Give parser will parse responese if success or respnse will be returned as error.

func ShouldNoError 

func ShouldNoError(p Parser) Parser

ShouldNoError parser that check if status code < 500. Give parser will parse responese if success or respnse will be returned as error.

func ShouldSuccess 

func ShouldSuccess(p Parser) Parser

ShouldSuccess parser that check if status code < 300. Give parser will parse responese if success or respnse will be returned as error.

type ParserFunc 

type ParserFunc func(resp *Response) error

ParserFunc parser func type

func (ParserFunc) Parse 

func (p ParserFunc) Parse(resp *Response) error

Parse parse response data. Return Response and any error if raised.

type PathJoin 

type PathJoin string

PathJoin command which modify fetcher url join with given path

func (PathJoin) Exec 

func (p PathJoin) Exec(f *Fetcher) error

Exec exec command to modify fetcher. Return any error if raised.

type PathPrefix 

type PathPrefix string

PathPrefix command which modify fetcher url with given path prefix

func (PathPrefix) Exec 

func (p PathPrefix) Exec(f *Fetcher) error

Exec exec command to modify fetcher. Return any error if raised.

type PathSuffix 

type PathSuffix string

PathSuffix command which modify fetcher url with given path suffix

func (PathSuffix) Exec 

func (p PathSuffix) Exec(f *Fetcher) error

Exec exec command to modify fetcher. Return any error if raised.

type Preset 

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

Preset fetch preset.

func BuildPreset 

func BuildPreset(cmds ...Command) *Preset

BuildPreset build new preset with given commands

func Concat 

func Concat(cmds ...Command) *Preset

Concat create preset with given commands.

func MustPreset 

func MustPreset(f PresetFactory) *Preset

MustPreset create preset by given preset factory. Return preset created. Panic if any error raised.

func NewPreset 

func NewPreset() *Preset

NewPreset create new preset

func (*Preset) Append 

func (p *Preset) Append(presets ...*Preset) *Preset

Append clone and append preset with given presets in order.

func (*Preset) CloneWith 

func (p *Preset) CloneWith(cmds ...Command) *Preset

CloneWith clone preset with commands. Alias for Concat

func (*Preset) Commands 

func (p *Preset) Commands() []Command

Commands return preset commands.

func (*Preset) Concat 

func (p *Preset) Concat(cmds ...Command) *Preset

Concat concat preset with given commands

func (*Preset) EndPoint 

func (p *Preset) EndPoint(method string, suffix string) *Preset

EndPoint create new preset with given suffix and method.

func (*Preset) Exec 

func (p *Preset) Exec(f *Fetcher) error

Exec exec command to modify fetcher. Return any error if raised.

func (*Preset) Fetch 

func (p *Preset) Fetch(cmds ...Command) (*Response, error)

Fetch fetch request. Preset and commands will exec on new fetcher by which fetching response. Return http response and any error if raised.

func (*Preset) FetchAndParse 

func (p *Preset) FetchAndParse(preset Parser) (*Response, error)

FetchAndParse fetch request and prase response with given parser if no error raised. Return response fetched and any error raised when fetching or parsing.

func (*Preset) FetchWithBody 

func (p *Preset) FetchWithBody(body io.Reader) (*Response, error)

FetchWithBody fetch request with given body. Return http response and any error if raised.

func (*Preset) FetchWithBodyAndParse 

func (p *Preset) FetchWithBodyAndParse(body io.Reader, preset Parser) (*Response, error)

FetchWithBodyAndParse fetch request and prase response with given preset ,body and parser if no error raised. Return response fetched and any error raised when fetching or parsing.

func (*Preset) FetchWithJSONBodyAndParse 

func (p *Preset) FetchWithJSONBodyAndParse(body interface{}, preset Parser) (*Response, error)

FetchWithJSONBodyAndParse fetch request and prase response with given preset ,body as json and parser if no error raised. Return response fetched and any error raised when fetching or parsing.

func (*Preset) With 

func (p *Preset) With(cmds ...Command) *Preset

With clone preset with commands. Alias for Concat

type PresetFactory 

type PresetFactory interface {
	//CreatePreset create new preset.
	//Return preset created and any error raised.
	CreatePreset() (*Preset, error)
}

PresetFactory preset factory.

type RequestBuilderFunc 

type RequestBuilderFunc func(*http.Request) error

RequestBuilderFunc request builder func type

func (RequestBuilderFunc) Exec 

func (b RequestBuilderFunc) Exec(f *Fetcher) error

Exec exec command to modify fetcher. Return any error if raised.

type RequestBuilderProvider 

type RequestBuilderProvider interface {
	BuildRequest(*http.Request) error
}

RequestBuilderProvider request builder provider interface.

type Response 

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

Response fetch response struct

func ConvertResponse 

func ConvertResponse(resp *http.Response) *Response

ConvertResponse convert http response to fetch response

func Do 

func Do(f *Fetcher, b ...Command) (*Response, error)

Do create request ,client with given f.etcher and commands and fetch Return http response and any error if raised.

func DoAndParse 

func DoAndParse(doer Doer, preset *Preset, parser Parser) (*Response, error)

DoAndParse do request and prase response with given doer,preset and parser if no error raised. Return response fetched and any error raised when fetching or parsing.

func DoWithBodyAndParse 

func DoWithBodyAndParse(doer Doer, preset *Preset, body io.Reader, parser Parser) (*Response, error)

DoWithBodyAndParse do request and prase response with given doer,preset,body and parser if no error raised. Return response fetched and any error raised when fetching or parsing.

func DoWithJSONBodyAndParse 

func DoWithJSONBodyAndParse(doer Doer, preset *Preset, body interface{}, parser Parser) (*Response, error)

DoWithJSONBodyAndParse do request and prase response with given doer,preset,body as json and parser if no error raised. Return response fetched and any error raised when fetching or parsing.

func Fetch 

func Fetch(cmds ...Command) (*Response, error)

Fetch create new fetcher ,exec commands and fetch response. Return http response and any error if raised.

func FetchAndParse 

func FetchAndParse(preset *Preset, parser Parser) (*Response, error)

FetchAndParse fetch request and prase response with given preset and parser if no error raised. Return response fetched and any error raised when fetching or parsing.

func FetchWithBodyAndParse 

func FetchWithBodyAndParse(preset *Preset, body io.Reader, parser Parser) (*Response, error)

FetchWithBodyAndParse fetch request and prase response with given preset ,body and parser if no error raised. Return response fetched and any error raised when fetching or parsing.

func FetchWithJSONBodyAndParse 

func FetchWithJSONBodyAndParse(preset *Preset, body interface{}, parser Parser) (*Response, error)

FetchWithJSONBodyAndParse fetch request and prase response with given preset , body as json and parser if no error raised. Return response fetched and any error raised when fetching or parsing.

func NewResponse 

func NewResponse() *Response

NewResponse create new response

func (*Response) BodyContent 

func (r *Response) BodyContent() ([]byte, error)

BodyContent read and return body content from response. Response body will be closed after first read.

func (*Response) Error 

func (r *Response) Error() string

Error return response body content as error.

func (*Response) NewAPICodeErr 

func (r *Response) NewAPICodeErr(code interface{}) error

NewAPICodeErr make a api code error which contains a error code.

type Server 

type Server struct {
	ServerInfo
	Client Client
}

Server http server config struct

func (*Server) Clone 

func (s *Server) Clone() *Server

Clone clone a new server config

func (*Server) CreatePreset 

func (s *Server) CreatePreset() (*Preset, error)

CreatePreset create new preset. Return preset created and any error raised.

func (*Server) MergeURL 

func (s *Server) MergeURL(url string) *Server

MergeURL clone and merge with given url

func (*Server) MustJoin 

func (s *Server) MustJoin(urlpath string) *Server

MustJoin clone and join with given urlpath

type ServerInfo 

type ServerInfo struct {
	//URL server host url
	URL string
	//Header http header
	Header http.Header
	//Method http method
	Method string
}

ServerInfo server info struct

func (*ServerInfo) Clone 

func (s *ServerInfo) Clone() *ServerInfo

Clone clone a new serverinfo

func (*ServerInfo) CreatePreset 

func (s *ServerInfo) CreatePreset() (*Preset, error)

CreatePreset create new preset. Return preset created and any error raised.

func (*ServerInfo) IsEmpty 

func (s *ServerInfo) IsEmpty() bool

IsEmpty check if server info is empty IsEmpty will return true if equal nil or s.URL is empty string

func (*ServerInfo) MergeURL 

func (s *ServerInfo) MergeURL(url string) *ServerInfo

MergeURL clone and merge with given url

func (*ServerInfo) MustJoin 

func (s *ServerInfo) MustJoin(urlpath string) *ServerInfo

MustJoin clone and join with given urlpath

Source Files

View all Source files

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.