httpx

Documentation

Overview

Package httpx 提供各引擎共用的 HTTP Client 默认值（超时等）。

Index

• Constants
• Variables
• func AppendHTTPHooks(client *http.Client, opts ...HookOption) *http.Client
• func DoJSON(ctx context.Context, hc *http.Client, method, url, apiKey string, body []byte, ...) ([]byte, error)
• func NewRateLimitedClient(rps float64, burst int, timeout time.Duration) *http.Client
• func NewRetryClient(maxRetries int, timeout time.Duration) *http.Client
• func OrDefault(c *http.Client, defaultTimeout time.Duration) *http.Client
• func UploadFile(ctx context.Context, hc *http.Client, url, apiKey, fieldName, filePath string, ...) ([]byte, error)
• func UploadReader(ctx context.Context, hc *http.Client, url, apiKey, fieldName, fileName string, ...) ([]byte, error)
• func WithHTTPHooks(client *http.Client, opts ...HookOption) *http.Client
• func WithResponseCapture(ctx context.Context, c *ResponseCapture) context.Context
• type HookOption
  • func WithRequestHooks(hooks ...RequestHook) HookOption
  • func WithResponseHooks(hooks ...ResponseHook) HookOption
• type HookTransport
  • func (t *HookTransport) RoundTrip(req *http.Request) (*http.Response, error)
• type RateLimitTransport
  • func (t *RateLimitTransport) RoundTrip(req *http.Request) (*http.Response, error)
• type RequestHook
• type ResponseCapture
  • func NewResponseCapture(opts ...ResponseCaptureOption) *ResponseCapture
  • func ResponseCaptureFromContext(ctx context.Context) *ResponseCapture
  • func (c *ResponseCapture) Records() []ResponseRecord
• type ResponseCaptureHook
  • func (ResponseCaptureHook) AfterResponse(resp *http.Response) error
• type ResponseCaptureOption
  • func WithResponseCaptureLimits(maxRecords, maxValueLen int) ResponseCaptureOption
  • func WithResponseHeaderNames(names ...string) ResponseCaptureOption
  • func WithResponseHeaderPrefixes(prefixes ...string) ResponseCaptureOption
• type ResponseHook
• type ResponseRecord
• type RetryTransport
  • func (t *RetryTransport) RoundTrip(req *http.Request) (*http.Response, error)

Constants

const DefaultTimeout = 90 * time.Second

DefaultTimeout 为未显式配置 Timeout 时的默认请求超时（含连接+TLS+首包+整体）。

Variables

var ErrNilHookRequest = errors.New("httpx: request hook returned nil request")

Functions

func AppendHTTPHooks

func AppendHTTPHooks(client *http.Client, opts ...HookOption) *http.Client

AppendHTTPHooks returns a shallow clone of client with hooks appended. If the client already uses HookTransport, hooks are appended to the existing transport instead of nesting another HookTransport.

func DoJSON

func DoJSON(ctx context.Context, hc *http.Client, method, url, apiKey string, body []byte, prefix string) ([]byte, error)

DoJSON sends a JSON request and returns the response body. It sets Authorization (Bearer) and Content-Type headers automatically. Non-2xx responses are converted to *aigoerr.Error.

func NewRateLimitedClient

func NewRateLimitedClient(rps float64, burst int, timeout time.Duration) *http.Client

NewRateLimitedClient creates an *http.Client with a token-bucket rate limiter. rps is requests per second; burst is the maximum burst size.

func NewRetryClient

func NewRetryClient(maxRetries int, timeout time.Duration) *http.Client

NewRetryClient creates an *http.Client with automatic retry for 429/5xx.

func OrDefault

func OrDefault(c *http.Client, defaultTimeout time.Duration) *http.Client

OrDefault 返回可用的 *http.Client：nil 或 Timeout==0 时使用 defaultTimeout。 若 c 已有 Timeout>0，原样返回 c。

func UploadFile

func UploadFile(ctx context.Context, hc *http.Client, url, apiKey, fieldName, filePath string, extra map[string]string, prefix string) ([]byte, error)

UploadFile uploads a file via multipart/form-data. fieldName is the form field name for the file; extra adds additional string fields.

func UploadReader

func UploadReader(ctx context.Context, hc *http.Client, url, apiKey, fieldName, fileName string, r io.Reader, extra map[string]string, prefix string) ([]byte, error)

UploadReader uploads data from an io.Reader via multipart/form-data.

func WithHTTPHooks

func WithHTTPHooks(client *http.Client, opts ...HookOption) *http.Client

WithHTTPHooks returns a shallow clone of client whose transport applies the supplied request/response hooks.

func WithResponseCapture

func WithResponseCapture(ctx context.Context, c *ResponseCapture) context.Context

WithResponseCapture attaches a response header collector to ctx.

Types

type HookOption

type HookOption func(*hookOptions)

HookOption configures request/response hooks for HookTransport.

func WithRequestHooks

func WithRequestHooks(hooks ...RequestHook) HookOption

WithRequestHooks appends hooks that run before the underlying transport.

func WithResponseHooks

func WithResponseHooks(hooks ...ResponseHook) HookOption

WithResponseHooks appends hooks that run after the underlying transport returns a response.

type HookTransport

type HookTransport struct {
	Base          http.RoundTripper
	RequestHooks  []RequestHook
	ResponseHooks []ResponseHook
}

HookTransport applies request and response hooks around an underlying RoundTripper.

func (*HookTransport) RoundTrip

func (t *HookTransport) RoundTrip(req *http.Request) (*http.Response, error)

type RateLimitTransport

type RateLimitTransport struct {
	Base    http.RoundTripper
	Limiter *rate.Limiter
}

RateLimitTransport wraps an http.RoundTripper with a token-bucket rate limiter.

func (*RateLimitTransport) RoundTrip

func (t *RateLimitTransport) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip implements http.RoundTripper. It waits for rate limit clearance before forwarding the request to the base transport.

type RequestHook

type RequestHook interface {
	BeforeRequest(*http.Request) (*http.Request, error)
}

RequestHook can inspect or replace an outbound HTTP request before it is sent. Implementations must not mutate the input request in place unless they own it; clone the request when changing headers, URL, or body.

type ResponseCapture

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

ResponseCapture stores response header records for requests sharing a context.

func NewResponseCapture

func NewResponseCapture(opts ...ResponseCaptureOption) *ResponseCapture

NewResponseCapture creates an empty response header collector.

func ResponseCaptureFromContext

func ResponseCaptureFromContext(ctx context.Context) *ResponseCapture

ResponseCaptureFromContext returns the collector attached to ctx, if any.

func (*ResponseCapture) Records

func (c *ResponseCapture) Records() []ResponseRecord

Records returns a snapshot of captured response records.

type ResponseCaptureHook

type ResponseCaptureHook struct{}

ResponseCaptureHook records response headers when the request context has a ResponseCapture attached.

func (ResponseCaptureHook) AfterResponse

func (ResponseCaptureHook) AfterResponse(resp *http.Response) error

AfterResponse implements ResponseHook.

type ResponseCaptureOption

type ResponseCaptureOption func(*ResponseCapture)

ResponseCaptureOption configures response header capture behavior.

func WithResponseCaptureLimits

func WithResponseCaptureLimits(maxRecords, maxValueLen int) ResponseCaptureOption

WithResponseCaptureLimits overrides record count and header value length limits. Non-positive values keep the default limit.

func WithResponseHeaderNames

func WithResponseHeaderNames(names ...string) ResponseCaptureOption

WithResponseHeaderNames replaces the exact response header allowlist. Header names are matched case-insensitively.

func WithResponseHeaderPrefixes

func WithResponseHeaderPrefixes(prefixes ...string) ResponseCaptureOption

WithResponseHeaderPrefixes replaces the response header prefix allowlist. Prefixes are matched case-insensitively.

type ResponseHook

type ResponseHook interface {
	AfterResponse(*http.Response) error
}

ResponseHook can inspect a response returned by the wrapped transport. Returning an error makes the client call fail after the response is received; observer hooks should return nil.

type ResponseRecord

type ResponseRecord struct {
	Method     string              `json:"method"`
	URL        string              `json:"url"`
	StatusCode int                 `json:"status_code"`
	Headers    map[string][]string `json:"headers"`
}

ResponseRecord captures response headers observed by a wrapped HTTP client.

type RetryTransport

type RetryTransport struct {
	Base       http.RoundTripper
	MaxRetries int           // default: 3
	BaseDelay  time.Duration // default: 1s
	MaxDelay   time.Duration // default: 30s
}

RetryTransport wraps an http.RoundTripper and retries on 429/5xx responses. Only GET requests (and other idempotent methods) are retried by default.

func (*RetryTransport) RoundTrip

func (t *RetryTransport) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip implements http.RoundTripper with automatic retry logic.