Skip to content

api.md

Latest commit

 

History

History
303 lines (214 loc) · 6.94 KB

api.md

File metadata and controls

303 lines (214 loc) · 6.94 KB
Raw

API 参考

类型

Client

主客户端结构，封装 http.Client、http.Transport、重试、日志、中间件等。

type Client struct { ... }

不可直接构造，使用 httpc.New(opts ...Option) 创建。

RequestBuilder

请求构建器，通过 client.GET(url) 等方法创建，支持链式配置。

type RequestBuilder struct { ... }

Option

配置选项函数类型：

type Option func(*Client)

RetryOptions

重试配置：

type RetryOptions struct {
    MaxAttempts   int           // 最大重试次数 (不含首次)
    BaseDelay     time.Duration // 基础延迟
    MaxDelay      time.Duration // 最大延迟
    RetryStatuses []int         // 触发重试的 HTTP 状态码
    Jitter        bool          // 是否启用抖动
}

默认值：

  • MaxAttempts: 2
  • BaseDelay: 100ms
  • MaxDelay: 1s
  • RetryStatuses: [429, 500, 502, 503, 504]
  • Jitter: false

ProtocolsConfig

HTTP 协议版本配置：

type ProtocolsConfig struct {
    Http1           bool // 启用 HTTP/1.1
    Http2           bool // 启用 HTTP/2 (TLS)
    Http2_Cleartext bool // 启用 H2C (非加密 HTTP/2)
    ForceH2C        bool // 强制 H2C (排斥其他协议)
}

注意： 当 ForceH2C 为 true 时，会禁用 HTTP/1.1 和加密 HTTP/2，仅启用非加密 HTTP/2。这是基于 Go 1.24+ 标准库 Transport.Protocols 的行为。

BufferPool

缓冲池接口：

type BufferPool interface {
    Get() *bytes.Buffer
    Put(*bytes.Buffer)
}

RoundTripperFunc

函数适配器，允许普通函数作为 http.RoundTripper：

type RoundTripperFunc func(req *http.Request) (*http.Response, error)

MiddlewareFunc

中间件函数类型：

type MiddlewareFunc func(next http.RoundTripper) http.RoundTripper

DumpLogFunc

日志记录函数类型：

type DumpLogFunc func(ctx context.Context, log string)

HTTPError

结构化 HTTP 错误，当状态码 >= 400 时返回：

type HTTPError struct {
    StatusCode int         // HTTP 状态码
    Status     string      // 状态文本 (如 "Not Found")
    Header     http.Header // 响应头 (副本)
    Body       []byte      // 响应体前缀 (最多 1KB)
}

实现 error 接口，body 预览最多 200 字符。

SSEEvent

表示一个已解析或待渲染的 SSE 事件：

type SSEEvent struct {
    Event string
    Data  string
    Id    string
    Retry string
}

func (e *SSEEvent) Render(w io.Writer) error

将事件编码为 SSE 线格式，输出与 touka 的服务端 SSE 事件格式兼容。

SSEStream

表示一个已建立的 SSE 流连接：

type SSEStream struct { ... }

方法

func (s *SSEStream) Next() (*SSEEvent, error)
func (s *SSEStream) Close() error
func (s *SSEStream) Response() *http.Response
  • Next() 逐帧读取并解析下一个 SSE 事件
  • Close() 关闭底层响应体
  • Response() 返回建立连接时的原始 HTTP 响应

导出变量

var (
    ErrRequestTimeout     // 请求超时
    ErrMaxRetriesExceeded // 超过最大重试次数
    ErrDecodeResponse     // 响应解码失败
    ErrInvalidURL         // 无效 URL
    ErrInvalidSSEStream   // 非法 SSE 流或错误 Content-Type
    ErrNoResponse         // 无响应
)

函数

New(opts ...Option) *Client

创建客户端实例。应用所有 Option 后返回。

见 客户端配置。

Client 方法

请求快捷方法

func (c *Client) GET(urlStr string) *RequestBuilder
func (c *Client) POST(urlStr string) *RequestBuilder
func (c *Client) PUT(urlStr string) *RequestBuilder
func (c *Client) DELETE(urlStr string) *RequestBuilder
func (c *Client) PATCH(urlStr string) *RequestBuilder
func (c *Client) HEAD(urlStr string) *RequestBuilder
func (c *Client) OPTIONS(urlStr string) *RequestBuilder

请求构建

func (c *Client) NewRequestBuilder(method, urlStr string) *RequestBuilder
func (c *Client) NewRequest(method, urlStr string, body io.Reader) (*http.Request, error)

执行

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

标准库兼容

func (c *Client) Get(url string) (*http.Response, error)
func (c *Client) GetContext(ctx context.Context, url string) (*http.Response, error)
func (c *Client) GetSSE(ctx context.Context, url string) (*SSEStream, error)
func (c *Client) Post(ctx context.Context, url string, body io.Reader) (*http.Response, error)
func (c *Client) PostJSON(ctx context.Context, url string, body any) (*http.Response, error)
func (c *Client) PostXML(ctx context.Context, url string, body any) (*http.Response, error)
func (c *Client) PostGOB(ctx context.Context, url string, body any) (*http.Response, error)
func (c *Client) Put(ctx context.Context, url string, body io.Reader) (*http.Response, error)
func (c *Client) PutJSON(ctx context.Context, url string, body any) (*http.Response, error)
func (c *Client) PutXML(ctx context.Context, url string, body any) (*http.Response, error)
func (c *Client) PutGOB(ctx context.Context, url string, body any) (*http.Response, error)
func (c *Client) Delete(ctx context.Context, url string) (*http.Response, error)

动态设置

func (c *Client) SetRetryOptions(opts RetryOptions)
func (c *Client) SetDumpLogFunc(dumpLog DumpLogFunc)
func (c *Client) SetTimeout(timeout time.Duration)

RequestBuilder 方法

上下文与配置

func (rb *RequestBuilder) WithContext(ctx context.Context) *RequestBuilder
func (rb *RequestBuilder) NoDefaultHeaders() *RequestBuilder

Header

func (rb *RequestBuilder) SetHeader(key, value string) *RequestBuilder
func (rb *RequestBuilder) AddHeader(key, value string) *RequestBuilder
func (rb *RequestBuilder) SetHeaders(headers map[string]string) *RequestBuilder

Query

func (rb *RequestBuilder) SetQueryParam(key, value string) *RequestBuilder
func (rb *RequestBuilder) AddQueryParam(key, value string) *RequestBuilder
func (rb *RequestBuilder) SetQueryParams(params map[string]string) *RequestBuilder

Body

func (rb *RequestBuilder) SetBody(body io.Reader) *RequestBuilder
func (rb *RequestBuilder) SetRawBody(body []byte) *RequestBuilder
func (rb *RequestBuilder) SetJSONBody(body any) (*RequestBuilder, error)
func (rb *RequestBuilder) SetXMLBody(body any) (*RequestBuilder, error)
func (rb *RequestBuilder) SetGOBBody(body any) (*RequestBuilder, error)

执行与解码

func (rb *RequestBuilder) Build() (*http.Request, error)
func (rb *RequestBuilder) Execute() (*http.Response, error)
func (rb *RequestBuilder) SSE() (*SSEStream, error)
func (rb *RequestBuilder) DecodeJSON(v any) error
func (rb *RequestBuilder) DecodeXML(v any) error
func (rb *RequestBuilder) DecodeGOB(v any) error
func (rb *RequestBuilder) Text() (string, error)
func (rb *RequestBuilder) Bytes() ([]byte, error)