快速开始

安装

go get github.com/cybergodev/httpc

基本请求

无需创建客户端，直接使用包级函数：

package main

import (
    "fmt"
    "log"

    "github.com/cybergodev/httpc"
)

func main() {
    result, err := httpc.Get("https://httpbin.org/get")
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(result.StatusCode()) // 200
    fmt.Println(result.Body())       // 响应内容
}

支持的 HTTP 方法：Get、Post、Put、Patch、Delete、Head、Options。

创建客户端

需要自定义配置时，创建客户端实例：

client, err := httpc.New()
if err != nil {
    log.Fatal(err)
}
defer client.Close()

result, err := client.Get("https://httpbin.org/get")

预设配置

配置	用途	特点
DefaultConfig()	通用场景	安全默认值，SSRF 防护开启
SecureConfig()	安全敏感场景	禁用自动重定向，严格超时
PerformanceConfig()	高吞吐场景	大连接池，长超时，启用 Cookie
TestingConfig()	测试环境	禁用安全检查与 HTTP/2，启用 Cookie
MinimalConfig()	轻量请求	无重试，无重定向

cfg := httpc.DefaultConfig()
cfg.Timeouts.Request = 60 * time.Second

client, err := httpc.New(cfg)

响应处理

result, err := client.Get("https://httpbin.org/json")
if err != nil {
    log.Fatal(err)
}

// 状态检查
result.StatusCode()     // 200
result.IsSuccess()      // true (2xx)
result.IsClientError()  // false (4xx)
result.IsServerError()  // false (5xx)

// JSON 解析
var data map[string]any
if err := result.Unmarshal(&data); err != nil {
    log.Fatal(err)
}

发送数据

// JSON
result, err := client.Post("https://httpbin.org/post",
    httpc.WithJSON(map[string]any{"name": "test"}),
)

// 表单
result, err := client.Post("https://httpbin.org/post",
    httpc.WithForm(map[string]string{"username": "admin"}),
)

// 带认证
result, err := client.Get("https://api.example.com/data",
    httpc.WithBearerToken("my-token"),
)

错误处理

HTTPC 区分网络层错误和 HTTP 状态码：

result, err := client.Get("https://api.example.com/data")
if err != nil {
    var clientErr *httpc.ClientError
    if errors.As(err, &clientErr) {
        log.Printf("错误代码: %s", clientErr.Code())
    }
    log.Fatal(err)
}

// HTTP 状态码需手动检查
switch {
case result.IsSuccess():
    // 2xx 成功
case result.IsClientError():
    log.Printf("客户端错误：%d", result.StatusCode())
case result.IsServerError():
    log.Printf("服务端错误：%d", result.StatusCode())
}

TIP

4xx/5xx 不会作为 error 返回，需通过 result.IsSuccess() 等方法检查。详见 错误处理。

下一步

• 实战教程 - 30 分钟构建 GitHub API 客户端
• 请求与响应 - 完整的请求选项和响应处理
• 基础示例 - GET/POST/中间件等实际用例
• 速查表 - 常用操作快速参考
• 安全 - 安全最佳实践