xhttp

Documentation

Index

• Constants
• func GetRioSign(token string) (timestamp string, signature string)
• func Init(cateName string) error
• func StripPassword(u *url.URL) string
• type HTTPAgent
  • func New() *HTTPAgent
  • func NewWithContext(ctx xcontext.XContext) *HTTPAgent
  • func (h *HTTPAgent) AddHeader(name, value string) *HTTPAgent
  • func (h *HTTPAgent) AddHeaders(headers map[string]string) *HTTPAgent
  • func (h *HTTPAgent) AddQueries(queries map[string]string) *HTTPAgent
  • func (h *HTTPAgent) AddQuery(name, value string) *HTTPAgent
  • func (h *HTTPAgent) ClearQuery(name string) *HTTPAgent
  • func (h *HTTPAgent) Delete(rawurl string) *HTTPAgent
  • func (h *HTTPAgent) Get(rawurl string) *HTTPAgent
  • func (h *HTTPAgent) IgnoreErrorOnFailureStatusCode() *HTTPAgent
  • func (h *HTTPAgent) Method(method string) *HTTPAgent
  • func (h *HTTPAgent) Post(rawurl string) *HTTPAgent
  • func (h *HTTPAgent) Put(rawurl string) *HTTPAgent
  • func (h *HTTPAgent) Request() (res *Res, err error)
  • func (h *HTTPAgent) RequestAsync(cb func(*Res, error))
  • func (h *HTTPAgent) ReturnResponseOnFailureStatusCode() *HTTPAgent
  • func (h *HTTPAgent) SetBodyBuffer(body *bytes.Buffer) *HTTPAgent
  • func (h *HTTPAgent) SetBodyBytes(body []byte) *HTTPAgent
  • func (h *HTTPAgent) SetBodyString(body string) *HTTPAgent
  • func (h *HTTPAgent) SetHeader(name, value string) *HTTPAgent
  • func (h *HTTPAgent) SetHeaders(headers map[string]string) *HTTPAgent
  • func (h *HTTPAgent) SetInsecureSkipVerify(skip bool) *HTTPAgent
  • func (h *HTTPAgent) SetQueries(queries map[string]string) *HTTPAgent
  • func (h *HTTPAgent) SetQuery(name, value string) *HTTPAgent
  • func (h *HTTPAgent) SetRioToken(token string) *HTTPAgent
  • func (h *HTTPAgent) SetTraceID(traceID string) *HTTPAgent
  • func (h *HTTPAgent) Timeout(timeoutInMs int) *HTTPAgent
  • func (h *HTTPAgent) Url(rawurl string) *HTTPAgent
  • func (h *HTTPAgent) WithContext(ctx xcontext.XContext) *HTTPAgent
• type RequestCallback
• type RequestCallbackArgs
• type Res
  • func (r *Res) Content() string
• type StatusError
  • func (e *StatusError) Error() string

Constants

const DefaultCateName = "xhttp"

DefaultCateName http请求日志Category

const LangHeaderKey = "Content-Language"

LangHeaderKey 从中获取 i18n 语言的HTTP请求头

const MaxOkStatus = 399

Functions

func GetRioSign

func GetRioSign(token string) (timestamp string, signature string)

GetRioSign 获取用于请求应用网关的签名

func Init

func Init(cateName string) error

Init 初始化

func StripPassword

func StripPassword(u *url.URL) string

StripPassword strip the password in URL

Types

type HTTPAgent

type HTTPAgent struct {
	URL *url.URL
	// contains filtered or unexported fields
}

HTTPAgent Http 请求帮助类 要创建实例，请使用 New() 方法

func New

func New() *HTTPAgent

New 创建默认的请求实例

func NewWithContext

func NewWithContext(ctx xcontext.XContext) *HTTPAgent

func (*HTTPAgent) AddHeader

func (h *HTTPAgent) AddHeader(name, value string) *HTTPAgent

AddHeader 追加新的 HTTP 头

func (*HTTPAgent) AddHeaders

func (h *HTTPAgent) AddHeaders(headers map[string]string) *HTTPAgent

AddHeaders 追加新的 HTTP 头

func (*HTTPAgent) AddQueries

func (h *HTTPAgent) AddQueries(queries map[string]string) *HTTPAgent

AddQueries 追加新的 QueryString

func (*HTTPAgent) AddQuery

func (h *HTTPAgent) AddQuery(name, value string) *HTTPAgent

AddQuery 追加新的 QueryString

func (*HTTPAgent) ClearQuery

func (h *HTTPAgent) ClearQuery(name string) *HTTPAgent

ClearQuery 清空 QueryString

func (*HTTPAgent) Delete

func (h *HTTPAgent) Delete(rawurl string) *HTTPAgent

func (*HTTPAgent) Get

func (h *HTTPAgent) Get(rawurl string) *HTTPAgent

func (*HTTPAgent) IgnoreErrorOnFailureStatusCode

func (h *HTTPAgent) IgnoreErrorOnFailureStatusCode() *HTTPAgent

IgnoreErrorOnFailureStatusCode 修改 Request() 方法响应码大于 MaxOkStatus 时的默认行为。

调用该方法后，Request() 方法在响应码大于 MaxOkStatus 时不再返回 error 对象，用户需要自行从 *xhttp.Res 中判断响应码进行处理。

该方法对服务端 panic、请求超时、服务端重定向的场景无效，仍然会返回 error。

func (*HTTPAgent) Method

func (h *HTTPAgent) Method(method string) *HTTPAgent

func (*HTTPAgent) Post

func (h *HTTPAgent) Post(rawurl string) *HTTPAgent

func (*HTTPAgent) Put

func (h *HTTPAgent) Put(rawurl string) *HTTPAgent

func (*HTTPAgent) Request

func (h *HTTPAgent) Request() (res *Res, err error)

Request 发起服务请求

默认行为：

• 当请求执行失败，如通信失败、请求超时、无法读取响应流等，将返回原始的 *net/url.Error 对象。
• 当请求执行成功，但响应码大于 399 时，将会返回 *xhttp.Error 对象。

-----------------------------

摘要逻辑：

golang 和 C# 的 http client 实现有区别：

• 在 golang 中，只要服务成功请求到，无论状态码是什么，都不会返回 error。
• 在 C# 中，满足 StatusCode <= 299 or (StatusCode<=399 && AllowAutoRedirect==false) 才不会抛出异常，否则会认定为接口错误。

为了屏蔽以上“开发人员习惯上的”差异，提供 IgnoreErrorOnFailureStatusCode 方法用于决定 error 的行为。也即，调用该方法之后，响应码大于 MaxOkStatus 时不会返回 error。

-----------------------------

参考：

在微软 C# HttpWebRequest 类中，根据响应码抛出异常的逻辑为：

• > 399 = fatal
• some of 3XX and AllowAutoRedirect==true will result into an exceptional respone ResponseStatusCode==HttpStatusCode.Ambiguous || // 300 ResponseStatusCode==HttpStatusCode.Moved || // 301 ResponseStatusCode==HttpStatusCode.Redirect || // 302 ResponseStatusCode==HttpStatusCode.RedirectMethod || // 303 ResponseStatusCode==HttpStatusCode.RedirectKeepVerb )) // 307
• SUCCESS Status is <= 299 or (<=399 && AllowAutoRedirect==false) will result into a normal (non exceptional) response https://referencesource.microsoft.com/#System/net/System/Net/HttpWebRequest.cs,5222 https://referencesource.microsoft.com/#System/net/System/Net/HttpWebRequest.cs,5885

本模块不支持对 3XX 重定向的自动重新请求，因此不考虑类似微软 C# 逻辑中的 AllowAutoRedirect 设置。

func (*HTTPAgent) RequestAsync

func (h *HTTPAgent) RequestAsync(cb func(*Res, error))

RequestAsync 发起异步请求

func (*HTTPAgent) ReturnResponseOnFailureStatusCode

func (h *HTTPAgent) ReturnResponseOnFailureStatusCode() *HTTPAgent

ReturnResponseOnFailureStatusCode 已废弃 Deprecated: 请使用 ReturnErrorByStatusCode

func (*HTTPAgent) SetBodyBuffer

func (h *HTTPAgent) SetBodyBuffer(body *bytes.Buffer) *HTTPAgent

SetBodyBuffer 设置请求体

func (*HTTPAgent) SetBodyBytes

func (h *HTTPAgent) SetBodyBytes(body []byte) *HTTPAgent

SetBodyBytes 设置请求体

func (*HTTPAgent) SetBodyString

func (h *HTTPAgent) SetBodyString(body string) *HTTPAgent

SetBodyString 设置请求体

func (*HTTPAgent) SetHeader

func (h *HTTPAgent) SetHeader(name, value string) *HTTPAgent

SetHeader 设置 HTTP 头，已存在的将被覆盖，不存在的将会追加上

func (*HTTPAgent) SetHeaders

func (h *HTTPAgent) SetHeaders(headers map[string]string) *HTTPAgent

SetHeaders 设置 HTTP 头，已存在的将被覆盖，不存在的将会追加上

func (*HTTPAgent) SetInsecureSkipVerify

func (h *HTTPAgent) SetInsecureSkipVerify(skip bool) *HTTPAgent

SetInsecureSkipVerify 设置跳过https安全证书

func (*HTTPAgent) SetQueries

func (h *HTTPAgent) SetQueries(queries map[string]string) *HTTPAgent

SetQueries 设置 QueryString，已存在的将被覆盖，不存在的将会追加上

func (*HTTPAgent) SetQuery

func (h *HTTPAgent) SetQuery(name, value string) *HTTPAgent

SetQuery 设置 QueryString，已存在的将被覆盖，不存在的将会追加上

func (*HTTPAgent) SetRioToken

func (h *HTTPAgent) SetRioToken(token string) *HTTPAgent

SetRioToken 设置应用网关 TOKEN，使得请求可以通过应用网关请求

func (*HTTPAgent) SetTraceID

func (h *HTTPAgent) SetTraceID(traceID string) *HTTPAgent

SetTraceID 设置 HTTP 请求的调用链跟踪 ID，将会被写入 HTTP HEAD 传递给下游接口。 请求头名称参见：xhttp.TraceIdKey

func (*HTTPAgent) Timeout

func (h *HTTPAgent) Timeout(timeoutInMs int) *HTTPAgent

Timeout 设置请求超时时间。单位：毫秒

func (*HTTPAgent) Url

func (h *HTTPAgent) Url(rawurl string) *HTTPAgent

func (*HTTPAgent) WithContext

func (h *HTTPAgent) WithContext(ctx xcontext.XContext) *HTTPAgent

type RequestCallback

type RequestCallback func(args RequestCallbackArgs)

RequestCallback 完成对外 http 请求调用之后的回调

var RequestCallbackHandler RequestCallback

RequestCallbackHandler 完成对外 http 请求调用之后的回调。

type RequestCallbackArgs

type RequestCallbackArgs struct {
	Req     *http.Request
	Res     *Res
	Elapsed time.Duration
	Err     error
}

RequestCallbackArgs 回调事件对象。 在回调中修改这些值是不安全的。

type Res

type Res struct {
	StatusCode int
	Body       *bytes.Buffer
	Headers    http.Header
}

Res http 请求响应对象

func (*Res) Content

func (r *Res) Content() string

Content 返回 Body 的字符串形式

type StatusError

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

StatusError xhttp 请求成功，但根据状态码从逻辑上认定为失败的错误

func (*StatusError) Error

func (e *StatusError) Error() string