README
¶
go-requests
一个轻量级的、受 Python requests 启发的 Go HTTP 客户端。API 采用函数优先设计，使用小型可组合选项。旨在覆盖最常见的用例（核心 80%），避免过度抽象。
特性
- 简单的
Get/Post/Put/Patch/Delete/Head/Options辅助函数 - 基于选项的请求配置（headers, query, body, timeout, proxy, redirect）
- 响应辅助函数：
Bytes,Text,JSON - 清晰的错误语义，带有类型化错误
- 可选的
Session用于设置默认值 - 可选的 gzip 自动解压
安装
go get github.com/CareyWang/go-requests
快速开始
package main
import (
"fmt"
"log"
requests "github.com/CareyWang/go-requests"
)
func main() {
resp, err := requests.Get("https://httpbin.org/get",
requests.WithQuery(map[string]string{"q": "golang"}),
requests.WithHeader("X-Trace", "abc"),
)
if err != nil {
log.Fatal(err)
}
text, _ := resp.Text()
fmt.Println(text)
}
使用示例
POST JSON
resp, err := requests.Post("https://httpbin.org/post",
requests.WithJSON(map[string]any{"name": "alice"}),
)
if err != nil {
log.Fatal(err)
}
fmt.Println(resp.StatusCode)
表单数据
resp, err := requests.Post("https://httpbin.org/post",
requests.WithForm(map[string]string{"a": "1", "b": "2"}),
)
原始请求体
body := strings.NewReader("raw payload")
resp, err := requests.Post("https://httpbin.org/post",
requests.WithBody(body),
requests.WithHeader("Content-Type", "text/plain"),
)
超时
resp, err := requests.Get("https://httpbin.org/delay/2",
requests.WithTimeout(1*time.Second),
)
if errors.Is(err, requests.ErrTimeout) {
log.Println("timeout")
}
gzip 自动解压
resp, err := requests.Get("https://example.com",
requests.WithHeader("Accept-Encoding", "gzip"),
requests.WithDecompressGzip(),
)
text, _ := resp.Text()
重定向控制
// max=0 禁用重定向
resp, err := requests.Get("https://httpbin.org/redirect/1",
requests.WithRedirect(0),
)
代理
resp, err := requests.Get("https://example.com",
requests.WithProxy("http://127.0.0.1:8080"),
)
Session 默认值
s := requests.NewSession(
requests.WithHeader("User-Agent", "httpclient"),
requests.WithTimeout(5*time.Second),
)
resp, err := s.Get("https://httpbin.org/get")
API 文档
顶级方法
func Get(url string, opts ...Option) (*Response, error)
func Post(url string, opts ...Option) (*Response, error)
func Put(url string, opts ...Option) (*Response, error)
func Patch(url string, opts ...Option) (*Response, error)
func Delete(url string, opts ...Option) (*Response, error)
func Head(url string, opts ...Option) (*Response, error)
func Options(url string, opts ...Option) (*Response, error)
Session
type Session struct{}
func NewSession(opts ...Option) *Session
func (s *Session) Get(url string, opts ...Option) (*Response, error)
func (s *Session) Post(url string, opts ...Option) (*Response, error)
func (s *Session) Put(url string, opts ...Option) (*Response, error)
func (s *Session) Patch(url string, opts ...Option) (*Response, error)
func (s *Session) Delete(url string, opts ...Option) (*Response, error)
func (s *Session) Head(url string, opts ...Option) (*Response, error)
func (s *Session) Options(url string, opts ...Option) (*Response, error)
Options
type Option func(*Request)
func WithHeader(key, value string) Option
func WithHeaders(h map[string]string) Option
func WithQuery(q map[string]string) Option
func WithTimeout(d time.Duration) Option
func WithDecompressGzip() Option
func WithJSON(v any) Option
func WithForm(values map[string]string) Option
func WithBody(body io.Reader) Option
func WithCookies(cookies ...*http.Cookie) Option
func WithProxy(rawURL string) Option
func WithRedirect(max int) Option
Response
type Response struct {
Raw *http.Response
StatusCode int
Headers http.Header
}
func (r *Response) Bytes() ([]byte, error)
func (r *Response) Text() (string, error)
func (r *Response) JSON(v any) error
错误
var (
ErrRequest = fmt.Errorf("request error")
ErrNetwork = fmt.Errorf("network error")
ErrTimeout = fmt.Errorf("timeout")
ErrStatus = fmt.Errorf("unexpected status")
ErrResponse = fmt.Errorf("response error")
ErrResponseNil = fmt.Errorf("nil response")
ErrNoContent = fmt.Errorf("empty response body")
)
type StatusError struct {
StatusCode int
Response *Response
}
错误处理说明
- 非 2xx 响应返回
*StatusError，errors.Is(err, ErrStatus)为 true - 超时返回
errors.Is(err, ErrTimeout) - 其他传输故障返回
errors.Is(err, ErrNetwork) Response.JSON在空响应体时返回ErrNoContentResponse.Bytes在响应或响应体为 nil 时返回ErrResponseNilResponse.Bytes在读取或解压失败时返回ErrResponseResponse.JSON在解码失败时返回ErrResponse
许可证
MIT
Documentation
¶
Index ¶
- Variables
- type Option
- func WithBody(body io.Reader) Option
- func WithCookies(cookies ...*http.Cookie) Option
- func WithDecompressGzip() Option
- func WithForm(values map[string]string) Option
- func WithHeader(key, value string) Option
- func WithHeaders(h map[string]string) Option
- func WithJSON(v any) Option
- func WithProxy(rawURL string) Option
- func WithQuery(q map[string]string) Option
- func WithRedirect(max int) Option
- func WithTimeout(d time.Duration) Option
- type Request
- type Response
- func Delete(ctx context.Context, url string, opts ...Option) (*Response, error)
- func Get(ctx context.Context, url string, opts ...Option) (*Response, error)
- func Head(ctx context.Context, url string, opts ...Option) (*Response, error)
- func Options(ctx context.Context, url string, opts ...Option) (*Response, error)
- func Patch(ctx context.Context, url string, opts ...Option) (*Response, error)
- func Post(ctx context.Context, url string, opts ...Option) (*Response, error)
- func Put(ctx context.Context, url string, opts ...Option) (*Response, error)
- type Session
- func (s *Session) Delete(ctx context.Context, url string, opts ...Option) (*Response, error)
- func (s *Session) Get(ctx context.Context, url string, opts ...Option) (*Response, error)
- func (s *Session) Head(ctx context.Context, url string, opts ...Option) (*Response, error)
- func (s *Session) Options(ctx context.Context, url string, opts ...Option) (*Response, error)
- func (s *Session) Patch(ctx context.Context, url string, opts ...Option) (*Response, error)
- func (s *Session) Post(ctx context.Context, url string, opts ...Option) (*Response, error)
- func (s *Session) Put(ctx context.Context, url string, opts ...Option) (*Response, error)
- type StatusError
Constants ¶
This section is empty.
Variables ¶
View Source
var ( // ErrRequest indicates a request build or configuration error. ErrRequest = fmt.Errorf("request error") // ErrNetwork indicates a transport/network error. ErrNetwork = fmt.Errorf("network error") // ErrTimeout indicates a timeout error. ErrTimeout = fmt.Errorf("timeout") // ErrStatus indicates a non-2xx HTTP status. ErrStatus = fmt.Errorf("unexpected status") // ErrResponse indicates a response read or decode error. ErrResponse = fmt.Errorf("response error") // ErrResponseNil indicates a nil response or body. ErrResponseNil = fmt.Errorf("nil response") // ErrNoContent indicates an empty response body. ErrNoContent = fmt.Errorf("empty response body") )
Functions ¶
This section is empty.
Types ¶
type Option ¶
type Option func(*Request)
Option mutates a Request.
func WithBody ¶
WithBody sets a raw body reader. Note: the reader is used as-is; do not reuse it across concurrent requests.
func WithCookies ¶
WithCookies adds cookies to the request.
func WithDecompressGzip ¶ added in v1.0.1
func WithDecompressGzip() Option
WithDecompressGzip enables gzip auto-decompression for response bodies.
func WithHeader ¶
WithHeader sets a single header value (overwrites existing).
func WithHeaders ¶
WithHeaders sets multiple headers (overwrites existing keys).
func WithRedirect ¶
WithRedirect sets max redirects. max=0 disables redirects.
type Request ¶
type Request struct {
// contains filtered or unexported fields
}
Request holds request state built from options.
type Response ¶
type Response struct {
Raw *http.Response
StatusCode int
Headers http.Header
// contains filtered or unexported fields
}
Response wraps http.Response with convenience helpers.
func (*Response) Bytes ¶
Bytes reads and caches the response body and returns ErrResponseNil on nil responses.
type Session ¶
type Session struct {
// contains filtered or unexported fields
}
Session holds default options for requests.
func NewSession ¶
NewSession creates a new session with default options.
type StatusError ¶
StatusError is returned for non-2xx responses.
func (*StatusError) Error ¶
func (e *StatusError) Error() string
func (*StatusError) Unwrap ¶
func (e *StatusError) Unwrap() error
Source Files
Click to show internal directories.
Click to hide internal directories.