diff --git a/AI.md b/AI.md deleted file mode 100644 index d176490..0000000 --- a/AI.md +++ /dev/null @@ -1,21 +0,0 @@ -# AI 指导规则 (AI.md) - -## 模块信息 -- **模块名**: `http` -- **当前版本**: `v1.1.0` -- **核心意图**: 高性能 HTTP 客户端,支持泛型绑定、并行分段下载与线程安全的全局 Header 管理。 - -## AI 调用建议 -- **初始化**: 优先使用 `NewClient(timeout)`。 -- **结果解析**: - - 结构化数据:使用 `Bind[T](result)`。 - - 列表数据:使用 `result.Slice()` 或 `Bind[[]T](result)`。 - - 键值数据:使用 `result.Map()` 或 `Bind[map[string]T](result)`。 -- **并行下载**: 使用 `Download`,可通过 `client.MaxConnsPerHost` 调节并发。 -- **表单提交**: 使用 `PostMultipart` 处理带文件的多部分表单。 -- **全局配置**: 使用 `SetGlobalHeader(k, v)` 设置线程安全的全局头。 - -## 注意事项 -- **并发安全**: `Client` 的方法是并发安全的,但 `Result` 对象不是。 -- **内存池**: 内部使用 `sync.Pool` 优化了 Buffer 分配,在大负载下表现优异。 -- **Body 释放**: `Bind`, `String`, `Bytes`, `Map`, `Slice` 均会自动关闭 Body。`ManualDo` 需要手动关闭。 diff --git a/CHANGELOG.md b/CHANGELOG.md index 77a15fa..a3bda05 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,9 @@ # CHANGELOG +## v1.0.3 (2026-05-03) +- **API 变更**: 将泛型解析函数 `Bind[T]` 重命名为 `To[T]`,以保持与全局 API 风格一致。 +- **文档优化**: 移除冗余的 `AI.md`,更新 `README.md` 中的 API 示例。 + ## v1.0.2 (2026-05-03) - **Breaking Changes & API Renames**: - `ToT` 重命名为 `Bind` (泛型解析)。 diff --git a/README.md b/README.md index 2eccfc8..e8da437 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,6 @@ ## 核心特性 * **极致精简**: 屏蔽复杂的 `net/http` 配置,提供一键式调用(Get/Post/Put/Delete/Head)。 -* **泛型绑定**: 通过 `Bind[T](result)` 直接将响应内容绑定到指定类型的结构体或 Map。 * **智能重构**: 基于 `cast` 和 `convert` 模块实现零摩擦的数据映射。 * **并发下载**: 支持**并行多协程**分段下载大文件,内置自动重试机制。 * **Header 透传**: 自动处理微服务链路中常见的 `X-` 系列 Header 透传(如 `X-Request-ID`, `X-Real-IP`)。 @@ -15,7 +14,6 @@ ## 🤖 开发与 AI 指导 (Developer & AI Guidelines) 1. **推荐使用 NewClient**: 通过 `NewClient(timeout)` 创建带连接池的客户端。 -2. **善用泛型**: 优先使用 `Bind` 方法进行结果解析,避免手动反序列化。 3. **下载优化**: 可以通过 `client.MaxConnsPerHost` 控制下载并发度(默认为 4)。 4. **资源释放**: 使用 `ManualDo` 或直接访问 `Response.Body` 时,必须确保执行 `Close()`。 @@ -34,7 +32,7 @@ type User struct { } r := c.Get("https://api.example.com/user/1") -user, err := http.Bind[User](r) +user, err := http.To[User](r) if err == nil { fmt.Println(user.Name) } @@ -80,7 +78,7 @@ c.Download("local_file.zip", "https://example.com/large_file.zip", func(start, e - `func (rs *Result) To(v any) error`: 将响应体解析到对象。 - `func (rs *Result) Map() map[string]any`: 将响应体解析为 Map。 - `func (rs *Result) Slice() []any`: 将响应体解析为 Slice。 -- `func Bind[T any](rs *Result) (T, error)`: 泛型解析辅助函数。 +- `func To[T any](rs *Result) (T, error)`: 泛型解析辅助函数。 - `func (rs *Result) Save(filename string) error`: 将响应体保存到文件。 ## 许可证 diff --git a/TEST.md b/TEST.md index 0a82fdc..4d42ad0 100644 --- a/TEST.md +++ b/TEST.md @@ -1,20 +1,18 @@ -# Test Report +# 测试报告 -## 单元测试覆盖 -- `TestHttp`: 验证基础远程请求与泛型绑定 (PASS)。 -- `TestLocalServer`: 验证本地 Mock 服务、Header 传递与响应一致性 (PASS)。 -- `TestH2C`: 验证 HTTP/2 Cleartext 协议支持 (PASS)。 -- `TestManualDo`: 验证流式响应处理 (PASS)。 -- `TestDownload`: 验证分段下载与 `offsetWriter` 的正确性 (PASS)。 -- `TestMPost`: 验证 Multipart 表单提交功能 (PASS)。 +## 测试场景覆盖 +- **基础请求**: 验证了使用 `Get` 获取 JSON 响应并通过 `To[T]` 进行泛型绑定的功能。 +- **本地服务器**: 验证了客户端与本地测试服务器的交互。 +- **H2C 支持**: 验证了 H2C (HTTP/2 Cleartext) 的兼容性。 +- **手动请求**: 验证了通过 `ManualDo` 进行精细化控制的流程。 +- **文件下载**: 验证了使用 `Download` 进行并发分段下载的功能。 +- **多部分表单**: 验证了使用 `MPost` 上传文件和表单数据的正确性。 -## 性能基准 (Benchmark) -环境: Darwin amd64, Intel(R) Core(TM) i9-9980HK CPU @ 2.40GHz - -| 场景 | 次数 | 耗时 (ns/op) | -| :--- | :--- | :--- | -| **BenchmarkGet** (Local Server) | 16626 | 71549 | - -## 验证结论 -v1.1.0 版本引入了并行下载和 Buffer 池化优化,性能在基准测试中提升了约 5%,且解决了 API 命名的歧义问题。 -所有核心 API 均已通过并发安全验证。 +## 性能测试结果 (Benchmark) +``` +goos: darwin +goarch: amd64 +pkg: apigo.cc/go/http +cpu: Intel(R) Core(TM) i9-9980HK CPU @ 2.40GHz +BenchmarkGet-16 15244 79100 ns/op +``` diff --git a/client.go b/client.go index 4bc8b2c..32935cc 100644 --- a/client.go +++ b/client.go @@ -560,10 +560,9 @@ func (rs *Result) To(v any) error { return err } -// Bind 使用泛型获取结果 -func Bind[T any](rs *Result) (T, error) { +// To 使用泛型获取结果 +func To[T any](rs *Result) (T, error) { var v T err := rs.To(&v) return v, err } - diff --git a/client_test.go b/client_test.go index bc2d40c..0dfbbaa 100644 --- a/client_test.go +++ b/client_test.go @@ -28,7 +28,7 @@ func TestHttp(t *testing.T) { type HttpBinGet struct { Url string } - res, err := ah.Bind[HttpBinGet](r) + res, err := ah.To[HttpBinGet](r) if err != nil { t.Errorf("Bind failed: %v", err) } @@ -203,5 +203,3 @@ func TestMPost(t *testing.T) { t.Errorf("expected foo=bar,file=baz, got %s", r.String()) } } - -