http/README.md

apigo.cc/go/http

apigo.cc/go/http 是一个极致精简、高性能且安全的 HTTP 客户端与工具集。它基于原生 net/http 构建，提供了更友好的 API、自动化的 Header 透传、并发下载支持以及泛型数据绑定。

核心特性

• 极致精简: 屏蔽复杂的 net/http 配置，提供一键式调用（Get/Post/Put/Delete/Head）。
• 泛型绑定: 通过 ToT[T](result) 直接将响应内容绑定到指定类型的结构体或 Map。
• 智能重构: 基于 cast 和 convert 模块实现零摩擦的数据映射。
• 并发下载: 支持分段并发下载大文件，内置自动重试机制。
• Header 透传: 自动处理微服务链路中常见的 X- 系列 Header 透传（如 X-Request-ID, X-Real-IP）。
• H2C 支持: 原生支持 HTTP/2 Cleartext (h2c) 协议。

🤖 开发与 AI 指导 (Developer & AI Guidelines)

1. 推荐使用 NewClient: 通过 NewClient(timeout) 创建带连接池的客户端。
2. 善用泛型: 优先使用 ToT 方法进行结果解析，避免手动反序列化。
3. Debug 模式: 开启 client.Debug = true 可通过内置 log 模块打印完整的请求与响应详情。
4. 资源释放: 使用 ManualDo 或直接访问 Response.Body 时，必须确保执行 Close()。

快速入门 (Quick Start)

1. 基础请求与泛型绑定

import "apigo.cc/go/http"

c := http.NewClient(time.Second * 5)

// 发起请求并解析 JSON
type User struct {
    ID   int
    Name string
}

r := c.Get("https://api.example.com/user/1")
user, err := http.ToT[User](r)
if err == nil {
    fmt.Println(user.Name)
}

2. Header 透传 (Discover Relay)

在处理外部请求时，自动从原请求中提取并续传关键 Header。

func MyHandler(w http.ResponseWriter, r *http.Request) {
    c := http.NewClient(time.Second)
    // 自动透传 X-Request-ID, X-Real-IP 等
    res := c.DoByRequest(r, "GET", "http://internal-service/api", nil)
    fmt.Println(res.String())
}

3. 并发下载

c := http.NewClient(0)
c.Download("local_file.zip", "https://example.com/large_file.zip", func(start, end int64, ok bool, finished, total int64) {
    fmt.Printf("Progress: %d/%d\n", finished, total)
})

🛠 API Reference

客户端创建

• func NewClient(timeout time.Duration) *Client: 创建标准 HTTP 客户端。
• func NewClientH2C(timeout time.Duration) *Client: 创建支持 H2C 的 HTTP 客户端。

请求方法

• func (c *Client) Get(url string, headers ...string) *Result
• func (c *Client) Post(url string, data any, headers ...string) *Result
• func (c *Client) Put(url string, data any, headers ...string) *Result
• func (c *Client) Delete(url string, data any, headers ...string) *Result
• func (c *Client) Head(url string, headers ...string) *Result
• func (c *Client) MPost(url string, formData map[string]string, files map[string]any, headers ...string) (*Result, []error): 多部分表单提交（支持文件与流）。

响应处理 (Result)

• func (rs *Result) String() string: 返回响应体字符串。
• func (rs *Result) Bytes() []byte: 返回响应体字节数组。
• func (rs *Result) To(v any) error: 将响应体解析到对象。
• func ToT[T any](rs *Result) (T, error): 泛型解析辅助函数。
• func (rs *Result) Save(filename string) error: 将响应体保存到文件。

许可证

本项目基于 MIT 许可证开源。