Documentation
¶
Overview ¶
Package httpjson stdlib-only 的 HTTP+JSON 调用纪律单源：ctx 感知构造请求 → 执行 → 限容读体（读错误不吞）→ 状态码检查（错误体 rune 安全截断，不腰斩 UTF-8）→ JSON 解码，外加可选的指数退避重试与服务端 Retry-After 建议捕获。
与 network/httpx 的分工（同名不同物）：那侧是 Hertz 底座的服务间调用基础 设施（服务发现/熔断/指标/追踪，编译期即拉 hertz+prometheus+gobreaker+otel 依赖链）；本包纯函数、调用方注入 *http.Client——被嵌入的 SDK 与外部 API 调用方（LLM 网关、第三方开放平台）复用，不把微服务全家桶拖进依赖树。 收编自 agentkit/httpx（v0.10.41 起单源在此，agentkit 侧消费本包）。
Index ¶
- Constants
- func DoJSON(ctx context.Context, client *http.Client, req Request, out any) error
- func DoJSONWithRetry(ctx context.Context, client *http.Client, reqFn func() (Request, error), ...) error
- func RetryAfterFrom(ctx context.Context) time.Duration
- func SelectRetryDelay(local, hint time.Duration) time.Duration
- func WithRetryAfterSink(ctx context.Context) context.Context
- type Request
- type RetryAfterTransport
- type RetryConfig
- type StatusError
Constants ¶
const MaxServerRetryAfter = 5 * time.Minute
MaxServerRetryAfter 服务端退避建议的可信上限：超过 5 分钟的建议不直接采信 （长时间限流应交由上层 failover/切换处置，而非原地等）。
Variables ¶
This section is empty.
Functions ¶
func DoJSON ¶
DoJSON 执行请求并把 2xx 响应体解码进 out。非 2xx 返回带状态码与响应体摘要 （rune 安全截断到 200 字符）的错误；解码失败返回包装后的解析错误。 错误不带包前缀返回，调用方以自己的包前缀包装一次。
func DoJSONWithRetry ¶
func DoJSONWithRetry(ctx context.Context, client *http.Client, reqFn func() (Request, error), cfg RetryConfig, out any) error
DoJSONWithRetry 带重试的 HTTP+JSON 调用。
reqFn 每次尝试重新构造 Request（请求体流不可重读，且调用方可能希望每轮 刷新签名头）；reqFn 自身报错视为调用方参数问题，立即返回不重试。 重试间指数退避 + Jitter 抖动；ctx 取消/超时立即返回 ctx.Err()。 配合 WithRetryAfterSink + RetryAfterTransport 可让 429 的服务端建议 参与退避取舍（调用方在 wait 前经 SelectRetryDelay(RetryAfterFrom(ctx)) 采信）。
func RetryAfterFrom ¶
RetryAfterFrom 读取最近一次 429 的服务端建议（0 = 无）。重试环在计算退避时调用。 sink 不随尝试清除：仅对本次失败确为限流的场景采信（陈旧建议不得套用到 非限流错误上），门控归调用方的重试策略。
func SelectRetryDelay ¶
SelectRetryDelay 退避取舍（「合理性钳制」）：服务端建议 >0 且 （≤MaxServerRetryAfter 或 < 本地曲线值）→ 采信建议；否则本地曲线。
Types ¶
type Request ¶
type Request struct {
// Method HTTP 方法（空 = GET）。
Method string
// URL 完整地址（含 query）。
URL string
// Body 请求体（nil = 无请求体；JSON 调用方自行 Marshal）。
Body []byte
// Header 鉴权/Content-Type 等请求头注入钩子（可 nil）。
Header func(h http.Header)
}
Request 一次 HTTP+JSON 调用的描述。
type RetryAfterTransport ¶
type RetryAfterTransport struct {
Base http.RoundTripper
}
RetryAfterTransport 透明捕获 429 的 Retry-After 头。响应体不做任何改写—— 上层错误构造不受影响。Base 为 nil 时用 http.DefaultTransport。
type RetryConfig ¶
type RetryConfig struct {
// MaxAttempts 总尝试次数（含首次；<1 视为 1）。
MaxAttempts int
// BaseDelay 首次重试延迟（<=0 取 200ms），按尝试轮次指数退避。
BaseDelay time.Duration
// MaxDelay 单次重试延迟上限（<=0 取 2s）。
MaxDelay time.Duration
// Jitter 随机抖动幅度（防惊群；<0 取 0）。
Jitter time.Duration
// Retryable 自定义可重试判定（nil = 默认：网络超时或 HTTP 5xx/429 可重试；
// 4xx 参数错、响应解析失败不重试）。
Retryable func(err error) bool
}
RetryConfig 一次重试策略（零值 = 仅执行一次，不重试）。
type StatusError ¶
StatusError 非 2xx 响应错误：供重试判定等按状态码分类（errors.As 提取）。
func (*StatusError) Error ¶
func (e *StatusError) Error() string
Source Files