58 lines
5.4 KiB
Markdown
58 lines
5.4 KiB
Markdown
# v0.21 httpc 验收（2026-09-26）
|
||
|
||
目标：让普通项目直接配置代理、连接阶段与空闲池参数，带请求头完成有界 JSON 调用，同时保留标准 Do/Transport 扩展。没有加入业务服务规则，也没有修改业务项目或在线服务器。
|
||
|
||
## 功能与安全验证
|
||
|
||
- 代理：独立子进程验证环境代理缓存、默认/显式 environment、NO_PROXY；本地代理与本地目标验证固定代理/直连。配置错误不回显凭证。
|
||
- Transport：克隆池与进程默认池互不修改；可配置建连/keepalive/握手/响应头/100-continue/空闲参数，保留 TLS 证书验证。借用 Transport 不修改、不关闭，混合配置明确失败，typed nil 拒绝。
|
||
- 实际 socket：慢 TLS 握手、慢响应头、超时后恢复、12 并发下最多 2 条 HTTP/1.1 连接、空闲回收与关闭后的连接释放。
|
||
- 请求选项：24 个并发调用的认证头独立；WithHeaders 快照源 map、多值头与大小写规范化，重试不丢头，控制字符/分帧头拒绝，错误不会带 Token。
|
||
- JSON：单次响应限额不影响其他请求，已知/未知长度、chunked、自动 gzip 解压后的限制、空成功体、多 JSON 文档、状态错误、调用后关闭。
|
||
- 错误响应：已知小体复用连接；读取大小有上限；已知但缓慢的错误体最多花 25ms 尝试读取（标准 Transport 遵守 context），未知流直接关闭，不等完整 body。
|
||
- 生命周期：Close 不中断已开始的调用，拒绝新调用；借用 Transport 生命周期保持项目所有。既有重试、总超时、请求 body 拒绝时关闭、重定向不跟随测试保留。
|
||
- 日志不含 URL 路径、查询、URL 密码、Authorization 或响应体；标准返回的 URL 错误不承诺自动脱敏，项目应自行选择安全日志字段。
|
||
|
||
全量 `GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race ./...`：48 个测试包通过，包含实际生成项目回归。另验证 Go 1.22.12 的 httpc/示例、vet、build 与 managedService 生成检查。没有改动生成模板的兼容门槛；CLI 当前版本与最低模板版本分开，v0.20 的生成能力保持兼容。
|
||
|
||
请求头 Fuzz：30s / 4 worker，1104189 次执行，无失败，总收尾时间 31.293s。模糊输入上限 8 KiB，验证被接受的头可以由标准 Request writer 序列化；不等同形式化安全证明。
|
||
|
||
## 本机性能对比
|
||
|
||
Go 1.27.1 / darwin arm64 / Apple M2 Max，关闭请求日志；每项 500ms，三轮取中位数。基线源代码为 `068e85132f74edccb7657629b162505d038154f7`（v0.20 发布后文档提交），使用相同的基准函数。
|
||
|
||
前七项使用内存 RoundTripper 测量包装/JSON 开销；Pool 项使用本地 TCP 服务；Headers 项是新增选项。原始记录：[修改前](httpcBaselineBenchmark.txt)、[修改后](httpcBenchmark.txt)。列内单位依次为 ns/op、B/op、allocs/op。
|
||
|
||
| 场景 | 修改前 | 修改后 |
|
||
| --- | ---: | ---: |
|
||
| Client/128B/decode | 1681 / 2861 / 25 | 1408 / 2348 / 22 |
|
||
| Client/128B/discard | 1226 / 2856 / 25 | 1070 / 1836 / 21 |
|
||
| Client/4KiB/decode | 7590 / 17599 / 34 | 7650 / 17085 / 31 |
|
||
| Client/4KiB/discard | 2775 / 13480 / 33 | 1130 / 1836 / 21 |
|
||
| Client/64KiB/decode | 82261 / 214437 / 41 | 83673 / 213925 / 38 |
|
||
| Client/64KiB/discard | 17397 / 148648 / 40 | 2285 / 1836 / 21 |
|
||
| Client/Do | 843.6 / 1808 / 20 | 712.1 / 1296 / 17 |
|
||
| Pool/OK | 39726 / 7338 / 79 | 39598 / 6372 / 75 |
|
||
| Pool/Unauthorized | 42912 / 7333 / 83 | 41195 / 6503 / 77 |
|
||
| Headers | 新增能力 | 1761 / 3059 / 30 |
|
||
|
||
64 KiB discard 的分配从约 149 KB 降到 1.8 KB，不再为丢弃响应整体 ReadAll；普通 Do 少一次请求复制，也不在成功路径计算退避。大 JSON 解码耗时基本持平（4 KiB 约 +0.8%，64 KiB 约 +1.7%），分配略减；本轮没有更换 JSON 实现，也不宣称每个场景都更快。Headers 有独立快照/请求复制成本，见新增场景。
|
||
|
||
这些数字不是公网吞吐、冷 DNS、TLS 建连或高压容量承诺。连接容量与超时用确定性本地场景验证，未对线上资源施压。
|
||
|
||
## 兼容与使用
|
||
|
||
原 JSON 直接调用保持有效；自定义 interface/函数值中的 JSON 方法签名须补 variadic RequestOption。过去自定义 Transport 下被忽略的 MaxConnsPerHost，现在与其他代理/阶段选项一起明确拒绝混配；应配置借用 Transport 本身。
|
||
|
||
无新增第三方依赖。出站实现仍是标准 net/http，Do/Transport 保持通用扩展；HTTP 状态与业务响应码由调用项目解释。完整 [httpc 指南](../httpc/README.md)、[运行示例](../examples/httpClient/README.md)。
|
||
|
||
## 远程固定版本验收
|
||
|
||
`v0.21.0-preview` 固定在 `96e7d9629b5c8b78e9cfefbcb05da0ab702c242b`。空模块缓存安装远程 CLI，生成项目使用同一远程版本与 checksum，无本地 replace。验收耗时 64.15s，详见 [机器记录](httpcRemote.json)。
|
||
|
||
- 下载后的 httpc 源码全包 race 测试及 HTTP 示例通过，覆盖代理、超时、认证头隔离、连接池和错误体读取预算。
|
||
- 8 组真实生成消费者通过；入口运行/编译、重复生成与业务保留、初始化/监听失败清理、后台故障与分阶段关闭均通过。
|
||
- nethttp/native 信号退出、统一响应、404/405、上传下载、错误目录及 workspace/配置加载回归通过。
|
||
|
||
远程验收仍在本机临时目录和回环网络执行，验证的是发布产物，不是生产服务器容量。临时进程与目录均已清理；发布标签不因验收文档更新而移动。
|