httpx

package module
v0.8.12 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 7, 2026 License: MIT Imports: 40 Imported by: 0

README

httpx

高级 HTTP 客户端——服务发现/熔断/重试/指标/链路透传

🌐 项目主页：https://oekit.github.io/ · 名称由来：Open Easy Kit（开源 · 易用 · 工具集合） 🤖 AI Agent：本仓规范与硬规则见 AGENTS.md；机器可读索引见 llms.txt（接口签名以源码为准）。

安装

go get github.com/oekit/httpx@v0.8.11

这个仓库做什么

httpx 是基于 Hertz Client 的高级 HTTP 客户端：把服务发现、熔断、重试、指标、 链路透传这些“每次都要手写一遍”的东西变成构造选项。

核心能力

  • WithNNS：对接 NNS 服务发现（实例列表自动刷新）
  • WithCircuitBreaker：熔断（per-service，错误可判定 ErrCircuitOpen）
  • WithRetryConfig：指数退避 + 抖动重试（Hertz 官方引擎，连接池感知）
  • WithMetrics：Prometheus 弹性指标（熔断/重试计数）
  • WithTracePropagation：OTel 链路透传
  • WithDialFunc / WithHertzOption：拨号层/原生 Hertz 选项透传（出站 SSRF 防护）
  • WithStream：流式响应预设（关读超时、保留拨号超时，SSE/代理/WS 适用）
  • DoDetail：返回 status + 原始 body（2xx 也带 body，区别于 DoJSON）
  • DoOnce：client 可注入的低阶一次性请求原语（共享 *http.Client + 轻量骨架的收敛点，无重试/熔断——弹性语义单点在引擎层）
  • 实例权重贯通：注册中心的权重配置真实生效于负载均衡

快速使用

import "github.com/oekit/httpx"

c, err := httpx.NewClient("payment-svc", httpx.WithTimeout(5*time.Second))
if err != nil {
    return err // 构造失败显式返回（静态合法配置可用 httpx.MustNewClient）
}
var out Result
err = c.GetJSON(ctx, "/api/v1/pay", &out)

需要原始响应（状态码 + body）时用 DoDetail：

status, body, err := c.DoDetail(ctx, http.MethodPost, "/api/v1/pay", req)
// 2xx: err == nil，body 为原始响应体
// 非 2xx: status、body 仍有值，err 为 *ServiceError

超时与流式响应

默认注入 30s 拨号/读超时——只适合短请求。读超时对响应是「30s 内读完」 的硬顶，SSE 转发、k8s proxy 长连接、WS 升级这类流式响应会被静默掐断 （症状是连接被远端/代理切断，极难归因到客户端读超时）。流式场景必须 显式关读超时：

// WithStream：关读超时 + 保留拨号超时（流式的总时长预算由调用方经 ctx 控制）
c, err := httpx.NewClient("k8s-proxy", httpx.WithStream())

超时语义族（#87/#90/#92）：

意图 写法
拨号+读取各以 d 为上限（WithTimeout 语义） WithTimeout(d)
只调读超时、保留 30s 拨号 WithHertzOption(client.WithClientReadTimeout(d))
只调拨号超时 WithHertzOption(client.WithDialTimeout(d))
写超时 WithHertzOption(client.WithWriteTimeout(d))
流式（关读超时、保留拨号） WithStream()

出站 SSRF 防护

调用方 URL 来自不受信输入时（用户配置的回调/推送地址、任意外链抓取、 开放平台跳转等），用 pkg/urlguard 原语 + 本仓胶水，一行接入：

import (
    "github.com/oekit/httpx"
    pkgurlguard "github.com/oekit/pkg/urlguard"
)

// URL 层字面量校验（请求前）：私网/loopback/云元数据段、.internal/.local 域名、非 http(s) scheme
if err := pkgurlguard.IsBlockedURL(callbackURL); err != nil {
    return err
}

// 拨号层（建连时）：解析 IP 预检 + 实际端点核对（闭合 DNS rebinding 的重解析窗口，
// Happy-Eyeballs 胜出路径同样被核对）
c, err := httpx.NewClient("user-callback", httpx.WithSafeDial())

豁免走构造态 option（无进程级全局开关）：测试打本机 mock 用 httpx.WithSafeDial(pkgurlguard.WithAllowPrivate())；内网 webhook 端点豁免 WithSafeDial(pkgurlguard.WithAllowCIDRs("10.20.0.0/16"))；域名豁免 WithAllowDomains。判定规则（阻断网段清单、IPv4-mapped IPv6 归一等）见 pkg/urlguard。

v0.7.0 曾内置独立实现 httpx/urlguard（IsBlockedIP/GuardAddr/ SetAllowPrivateForTest 全局开关），与 pkg v0.15.0 重叠，v0.8.0 起收敛删除： 判定规则单源在 pkg，本仓只保留 hertz network.DialFunc 形态的胶水 （SafeDialFunc / SafeDialFuncWith / WithSafeDial）。

尚未封装的 Hertz 原生能力用 WithHertzOption(opts ...config.ClientOption) 逃生舱透传。

边界

  • 轻量 WebSocket/NATS 等不经过服务发现的场景 → network
  • 服务治理语义（实例缓存/多级降级）在 nns

矩阵总览（24 活跃模块，自动生成）

模块 内容 矩阵内依赖
pkg 微工具集 24 合 1（errors/bloomx/contextx/container/stringx/slicex/enumx/convert/encoding/jsonrepair/httpjson/mathx/pathx/pagination/ptrx/shellx/timex/cache/bufiox/strmap/singleflighttest/urlguard/cli/pack；v0.10.0 起 uidgen/validator 拆至 kitx）；errors（v0.12.0 起）New/As/Is/Unwrap 与 stdlib 同型透传——下游哨兵/As 判定单 import 即可，类型同一性红线可完整执行；cache（v0.4.0 起）含缓存接口 CacheAside + BatchGetter 批量能力（MGet）+ LocalCache/SingleFlightCache + cachetest 契约（Run 真实时间 + RunWithClock 假时钟确定性 TTL 边界）+ Checker；LocalCache 时钟可注入（LocalConfig.Now——TTL/NullTTL 全路径确定性测试，v0.13.0 起）；v0.16.0 起 LocalCache 可选形状——NoBackgroundSweep 关闭后台清扫 goroutine（嵌入式/短命进程，公开 Sweep 手动清扫口）、CloneOnRead 读命中返回副本（调用方可改写不污染缓存）、EvictPolicy 可选 LRU（默认 FIFO 不变）、GetEx 区分未命中与值为 nil（新增能力以可选接口 Sweeper/HitGetter 外置，不破坏其它后端）；v0.23.0 起补 Peek 非删除式读（可选接口 PeekGetter 外置——读到过期条目只算不命中、不删除它，stale-if-error 兜底需要那份过期真值留在表内；SingleFlightCache 包装 LocalCache 时曾因前置检查走 Get 惰性删除而静默废掉 StaleIfError，#72）；container（v0.9.0 起，收编原 collectionx）泛型容器 Set/Ring/Queue/SafeMap + Map（sync.Map 背书）/Slice（并发安全）；mathx/jsonrepair（v0.11.0）Unstable 单边向上抖动 Upward / 宽松解析 UnmarshalLenient / 抽对象与抽数组对称原语 ExtractObject·ExtractArray（v0.18.0 起——多段数组与散文含 '{' 的数组文本不再整段作废，取首个口径与对象面一致）；timex/stringx（v0.7.0 起）时间段边界 BeginningOf/EndOf 七对（分/时/日/周/月/季/年，周起始显式参数）+ trie 多模式替换器 Replacer（最长匹配）/ NewMask 敏感词遮罩；stringx Masker（v0.16.0 起）正则脱敏——按形态分类打码（形态标签进掩码供审计读）+ 保留首尾各 ≤4 字符定位线索且不可复原（保留位封顶不随长度变化），规则表由调用方完全提供；singleflighttest（v0.8.0 起）singleflight 共享契约测试套件（internal 与 concurrency 双侧引用）；urlguard（v0.15.0 起）出站 SSRF 防护原语——CheckURL 字面量校验（私网/loopback/链路本地含云元数据 169.254.169.254/CGNAT/ULA/组播保留、.internal·.local·localhost 域名、scheme 白名单、IPv4-mapped IPv6 归一）+ DialFunc 拨号层预解析校验与实际 RemoteAddr 端点核对闭合 TOCTOU（Happy-Eyeballs 覆盖），构造态豁免 WithAllowPrivate/WithAllowCIDRs/WithAllowDomains，与 httpx WithDialFunc 一行组合（httpx#11）；cli（v0.16.0 起）框架无关可单测的子命令分发原语——App/Command + 退出码 0/1/2 写死在包里、usage 按 Summary 自动生成、不读 os.Args 不调 os.Exit（输出流全由调用方给）；pack（v0.16.0 起）迁移包容器原语——zip + manifest（格式版本/条数/每文件 SHA-256）+ JSONL 流式读写 + Inspect 体检一次列全问题并区分包损坏与版本不认识 —
concurrency 并发与流控原语（async/gopool/group/singleflight/progress/syncx/ratelimit/retry）+ window 滑动窗口 / breaker 自适应熔断（规范哨兵 ErrCircuitOpen）/ shedding CPU 自适应降载 / batch 攒批执行器（满条数/满字节/窗口去重）/ timewheel 单级时间轮；v0.5.0 起 retry 指数退避+抖动（MaxDelay 封顶/溢出饱和）、loop 周期原语（忙时丢 tick/单轮 panic 收编/FirstDelay 可打断）、async labeled RunSafe（panic 按任务标签上报）、syncx.FanInErr 逐槽错误（panic 槽显式标记）、KeyedLimiter 增强（容量护栏/RetryAfter/速率热更）并接入 pkg/singleflighttest 契约测试；v0.8.0 起 singleflight DoShared 折叠可观测（Result.Waiters）、async panic 统一收编 typed *PanicError（errors.As 可辨、携带栈）+ 实例级 Runner panic 路由、retry DelayHint（服务端 Retry-After 建议优先）+ JitterRatio 比例抖动 + retry/httpx Retryable 可重试性判定；v0.9.0 起 breaker 显式三态状态机 closed/open/half-open——冷却（WithProbeTimeout 缺省 1m）期满首个放行即半开探测、探测成功关闸清窗/失败重开、失联超时自动回收 + AbandonGen 显式放弃，GenBreaker 代绑定（AllowGen/SuccessGen/FailureGen/AbandonGen：代仅在探测放行自增、陈旧代回报整体作废、开放期失败不后移冷却）；v0.10.0 起 WithCooldown 独立业务冷却期（缺省回落 probeTimeout）+ WithConsecutiveFailures 连续失败计数触发（与速率型并联，补低 QPS 信号，对齐 Envoy consecutive_5xx）；v0.11.0 起 ratelimit Lockout 防爆破锁（fail2ban 形态：滑窗失败计数→阈值锁定拒绝 LockDuration→成功 Reset 清零/到期自解，CheckLocked 返回剩余时长）；v0.12.0 起 retry/httpx RetryableWithHeaders（403 + Retry-After/X-RateLimit-Remaining 头感知可重试判定，HeaderSource 零依赖抽象）、syncx FanInLimit 受限并发扇出（固定 worker 防下游过载）+ FanInLimitCtx（v0.14.0，ctx 感知：ctx 已取消未启动项 fn 一次不调、剩余槽快速排空 Canceled、在飞项照常落槽）、ratelimit WithTokenClock 时钟注入；v0.13.0 起 breaker 熔断期收敛到探测级（forcePass 强制探活 + 冷却期满半开探测，其余拒绝——SRE 公式退役为 closed→open 触发器，WithConsecutiveFailures 触发后流量真停）+ State()/State 枚举可观测出口；v0.16.0 起 ratelimit NewKeyedLimiterByFunc[K]——factory func(K) Limiter 按 key 定配额（一个管理器按接口维度分档位，NewKeyedLimiterOf 零破坏随迁；未登记 key 拿 factory 兜底档的坑已在 doc 点名，#31）；v0.17.0 起 KeyedLimiter.Create 护栏内原子登记（表满先回收空闲与 Allow 同路、仍满拒绝计 OverCapHits、已存在不覆盖——热更走 Replace；解决 ByFunc factory 库锁内调用致消费方锁序倒置，#33）；v0.18.0 起 retry.DoValue 泛型伴生——带返回值的重试（DoValue[T](ctx, cfg, fn func(attempt int) (T, error))；Do 改为委托给 DoValue——退避序列/抖动/MaxDelay 封顶/DelayHint 优先/Retryable 门控/ctx 取消只有一份实现，杜绝「同一个仓里两份实现」；失败返回零值与最后一次错误） pkg
logx 统一日志门面（多后端可替换 + caller 归属；Sink 已迁嵌套模块 logx/sink，根包纯 stdlib）；WithFilter 脱敏/丢弃包装（FilterKey 命中键替换 ***/FilterFunc 丢整条，子 logger 保持规则）、Slogger/SlogHandler 正向桥（三方 slog 直接消费 logx 生态）、TraceHandler 任意 slog.Handler 自动注入 trace_id、NewAuditLogger 审计留痕（级别锁 Info，不受 LOG_LEVEL 降级）、LevelEnabler 热路径提前判级、ParseLogLevel 返回 (Level, error) + ParseLogLevelOr 配错退默认（v0.7.0）；优雅关停正身在 core/lifecycle.Manager（logx/shutdown 仅余 Deprecated 别名）；桥接子包 hlog/hertzlog/kitexlog 为嵌套模块按需引入 core
core 应用基建件——governance 治理 schema、config 配置加载（LoadBootstrap/LoadDotEnv/Get* 系、default/env/range/options tag 校验、OverlaySource 多源叠加热更、ApplyEnvOverlay env 优先 12-factor 形态）、transport 协议无关传输上下文（Transporter/Header/Server·Client ctx 存取，仅标准库）、chain 中间件链（Handler/Middleware/Chain/Recovery/Timeout，与 nns-endpoint.Endpoint 同形）、lifecycle 契约 + Manager 优雅关停（自 logx/shutdown 迁入，日志 *slog.Logger——core 不再依赖 logx）、network IP 工具、version；v0.9.0 起 config FieldSet 显式提供集合（yaml 显式 port:0 不再被 default/env 覆盖——LoadBootstrap 默认接线，免全量指针化）+ require tag（必须 yaml/env 提供，缺失列全并附 env 提示）+ v0.9.1 修 yaml:,inline 字段在 FieldSet 下漏标记（inline 叶子显式零值曾被 default 覆盖）；v0.9.2 env 卫生改纯静态（仅格式/重名，移除依赖进程环境的拼写冒烟检查——误报 PATH/HOME、漏无人设置的真拼错，core#8），命名一致性走 LintEnvNaming 诊断 / WithEnvNamingLint 可选 fail-closed / ignorederived="true" 豁免；v0.10.0 起 config 严格模式——LoadBootstrap[T](envFlag string, opts ...LoadOption) 传 config.WithStrict() 开启：未知键拒载（不再静默忽略），错误带嵌套路径 + 该层合法键清单 + 近似拼写建议（UnknownKeyError）；默认行为不变，严格模式显式开启；v0.11.0 起 config 加载入口按来源拆开——LoadFile（任意路径：CLI -config 路径、容器内固定挂载位）+ Unmarshal（字节源：API 下发 / 模板渲染 / 测试夹具），与 LoadBootstrap（etc/ 约定）共享同一条解码线，因此严格模式诊断面（嵌套路径 / 合法键清单 / 拼写建议）与来源无关；LoadBootstrap 行为与错误文案逐字不变 —
kitx 标识与校验——uidgen（Snowflake 全局单例+Extract 元数据、手写 RFC 4122 v4 UUID 零第三方依赖、RandomHex/RandomString 拒绝采样随机串）+ validator（go-playground/validator v10 接口化门面：struct tag 校验/自定义规则注册/ValidationError Unwrap 为 BizError 400 对接 middleware.Fail）+ hash（v0.2.0 起非密码学哈希助手 Md5Hex/Md5Bytes——缓存键/幂等键/短唯一 code，格式稳定承诺，pkg 2026-09-15 治理移除弱哈希后 kitx 侧收编 pkg#10），自 pkg v0.10.0 拆出 pkg
metrics Prometheus 门面 + 弹性指标族 core
tracing OpenTelemetry 追踪 + trace_id 真相源（v0.3.0 起 OTLP 双协议导出：gRPC 缺省 / HTTP，Config.Protocol + Headers，切换协议不丢传播器/指标/旧 provider 关闭） logx
registry 注册发现核心（provider 无关 SPI：Registrar/Discoverer/Subscriber/ConfigStore + 实例模型 + netutil）+ sdbridge + registrymocks——根仓零第三方依赖；Nacos 实现与 Nacos 配置源已拆成嵌套模块（v0.5.0 起：registry/nacosimpl、registry/nacos——nacos-sdk-go 重依赖隔离在此，实测单独引入即拖 63 个第三方模块，不隔离时只要 SPI 接口的消费方也会被连带拖入） core
data 数据访问门面——复刻 ekit data/ 能力面：cache/rediscache/crud/distlock/gormx/redisx/timertask/cachetest 八子包 re-export（类型同一，实现住 pkg 与各子仓）+ cached 缓存读写编排（写后失效/事务提交后失效/查询缓存版本号失效/GetByIDs 批量点读 MGet 快路径/bloom 防穿透）+ twolevel 两级缓存与跨实例失效广播（v0.7.0 起本仓唯二非 re-export 实现）；v0.15.0 起壳跟随源仓演进——cache 壳补 LocalCache 可选形状（EvictPolicy/Sweeper/HitGetter）、cachetest 壳补 5 个契约套件入口（套件 8 → 13 场景）、v0.18.0 起 cache 壳补 PeekGetter 别名 + cachetest 壳补 2 个 stale-if-error 契约入口（套件 13 → 15 场景）、timertask 壳的 Redis 形态随源仓 v0.2.0 迁至嵌套模块 timertask/redis（壳不再转发 RedisBackend/ShardManager，Redis 形态直接依赖该嵌套模块）；all/ 聚合模块已废弃 retract concurrency、gormx、logx、pkg、redisx、timertask
gormx SQL/GORM 全家——连接池增强、框架无关 CRUD Service、仓储（原 oekit/gorm，v0.3.0 更名） logx、pkg
redisx Redis 全家——客户端封装（根包）、分布式缓存 cache/、分布式锁 distlock（Locker 同形可互换；Renew 手动续期（false=锁丢失，不进 Locker 接口保 etcdx 互换）+ WithAutoRenew 覆盖 TryLock 自动续期（v0.8.0 feat!：此前组合不续期）；Semaphore ZSET 槽位信号量（v0.8.0：Acquire 同 identifier 幂等刷新 + Lua 内原子清过期槽崩溃自愈、Renew 仅未过期槽可续、Cleanup 返条数、无 Redis 降级 fail-fast））、分布式限流 ratelimit（Lua 三态 + 故障本地兜底）；v0.9.0 起 distlock Lockout 分布式防爆破锁（Redis 侧 fail2ban：滑窗失败计数→阈值锁定 Penalty→Reset 清零，与 concurrency/ratelimit.Lockout 进程内孪生——多实例共享计数是存在理由；惩罚只按首次触发计算、nil client fail-fast 不降级，#6） concurrency、logx、pkg
etcdx etcd 全家——客户端封装（根包：生产默认值/Health 探活/Close(ctx) 幂等）、registry 注册发现实现（SPI 对接 registry/nacos 链路：Lease KeepAlive 注册 + 丢约指数退避自动重注册、prefix Watch 订阅推送、ConfigStore KV 配置监听）、distlock 分布式锁（Session+concurrency.Mutex 公平排队，接口与 redisx/distlock.Locker 同形可互换，可选无 etcd 降级放行） concurrency、logx、registry
httpx HTTP 客户端 + 负载均衡——服务发现/熔断（规范哨兵 ErrCircuitOpen）/重试/指标/OTel 透传；loadbalance Selector 形态（RoundRobin/Random/Weighted/一致性哈希权重感知虚拟副本/p2c 自适应——EWMA 经 DoneFunc 回写建立、Err 计 1s 惩罚；WithFilter 按元数据过滤；v0.4.0 起 Balancer 全家族删除无兼容路径）；codec 注册制编解码器（json 内置 + form 表单，DoCodec 请求按 codec 序列化、响应按 Content-Type 反查回退请求 codec）；v0.6.0 起 net/http 桥接层 NewRoundTripper/StdClient——存量标准库外呼一行 Transport 接入熔断/重试/指标/链路（重试缺省关显式开、非 2xx 非错误、hop-by-hop 隔离，#8）；v0.8.0 起 SafeDialFunc/WithSafeDial 出站 SSRF 防护胶水（判定单源 pkg/urlguard v0.15.0：解析 IP 全量预检 + 实际 RemoteAddr 端点核对闭合重解析 TOCTOU、Happy-Eyeballs 覆盖，构造态豁免；v0.7.0 内置的独立 httpx/urlguard 实现收敛删除，#11） concurrency、logx、metrics、pkg、registry、tracing
network 轻量网络客户端——WebSocket/NATS/MQ 抽象、连接与流工具 concurrency、logx、tracing
timertask 分片定时任务（FNV-1a、心跳续约）；v0.1.5 起可选可靠投递 DeliveryAtLeastOnce（租约 + Ack + 可见性超时；过期租约回扫重投/死信、停机 best-effort 收租，v0.1.7 接入生命周期真正生效）；v0.2.0 起 Redis 后端迁至嵌套模块 timertask/redis（根包不再引 go-redis/logx/concurrency，require 仅 pkg——import timertask 与 import timertask/local 的模块依赖面均无 redis，纯 stdlib 嵌入式场景可用）+ 新增 local 子包 cron 调度器 Scheduler（表达式复用 pkg/timex/cron 不另写一份；并发度/CatchUp 补跑/退出语义明确，FakeClock 假时钟驱动、触发点序列可确定性断言） pkg
middleware Hertz 标准中间件栈（模块根 mw，双层目录已收平）+ contrib 桥接 + hmw + SheddingMiddleware 自适应降载 + chainmw 子包（transport 感知框架无关中间件，基于 core/chain+transport：Recovery 带 panic 隔离上报钩子 WithRecoveryReporter、AccessLog skip+redact+自定义字段、MetadataPropagate——kitex 经 kitex/chainmw.ToKitex 复用同一实现，根包 Recovery/AccessLog 已薄壳化复用 chainmw 内核、下游 handler 可经 transport.FromServerContext 读协议无关传输信息）；v0.6.0 起 accesslog 凭证路径脱敏（WithAccessLogRedactPathPrefixes）、ratelimit 默认 KeyFunc 去端口（连接桶→地址桶）；v0.11.0 起 WithAccessLogSink 落库 sink（AccessRecord{Method,Path,Status,Latency,ClientIP,UserAgent,TraceID} 与日志同源、c 同传可读业务键、error/panic 只记 Warn 不影响主链路、SkipPaths 命中不触发）+ chainmw.WithSink 内核同构（kitex 随 ToKitex 获得）+ StackConfig.DisableResponseWrap 响应自管一键形态（TraceID→Recovery→AccessLog）与 AccessLogOptions 透传 + doc/README「适用边界」段（响应契约统一 vs handler 自管的推荐组合，#18）；v0.12.0 起 AccessLog panic 恢复点产出记录（AccessRecord.Panic 标记 + Err 摘要，Hertz status 按 Recovery 缺省 500）后按原值重抛——panic 请求不再零访问记录，sink/kitex 桥接同步留痕，#20；v0.13.0 起 accesslog 内建日志可关闭/改道（WithAccessLogSilent 只采不写、WithAccessLogLogger 注入宿主 logger 避免双写；静默下 skip/redact/sink/panic 记录照常），内核 chainmw.WithSilent 同构（kitex 随 ToKitex 获得），#38 concurrency、core、logx、metrics、pkg、registry、tracing
k8s Kubernetes 客户端封装——RESTConfig/Clientset/DynamicClient 构建（显式 kubeconfig → in-cluster 自动 → KUBECONFIG/~/.kube/config 逐级回退，QPS/Burst 限流默认 50/100）+ leaderelection 子包 Lease 选主简化封装（OnStartedLeading/OnStoppedLeading/OnNewLeader 回调，主备单活，仅要求 Lease CRUD 权限） logx
nns NNS 服务治理客户端——provider 无关发现/配置/实例缓存 concurrency、core、logx、registry
nns-endpoint NNS 端点工厂——per-service 熔断、换实例重试、gRPC 池 httpx、logx、metrics、nns、registry
bootstrap 应用生命周期引导——New(WithServiceName/WithShutdownTimeout/WithBeforeServe) + Run(fn) + healthz；App.Ready/ReadyChan/IsReady 就绪门（幂等并发安全）——嵌套 bootstrap/nacos 自 v0.3.0 起 NNS 注册延迟到 Ready 之后（server 就绪 → userFn 触发 Ready → 才进注册中心）、关停序 nns 反注册先于 server 关闭；就绪门漏接时可观测——nacos 看门狗超时打 ERROR 点明「服务不会注册到注册中心」（WithReadyTimeout 可调）+ NNSComponent.RegistrationState() 暴露注册阶段（pending/registered/failed/skipped/shutdown）；Metrics/Tracing 在嵌套模块 bootstrap/obs concurrency、core、logx
hertz Hertz 运行时集成（模块根扁平化）——日志桥接、生命周期、SSE/health/metrics、适配器、OTel、crudh/validatorh（基于 kitx/validator）/versionh（原 handler 微库收编）；RunServer 变参就绪门 WithOnReady（全部 HostPort TCP 探活可建连后回调，探活超时按启动失败优雅关机；缺省超时 5s 经 WithReadyProbeTimeout 调整——探活目标是 server 自动取到的全部 HostPort，无探活地址覆盖选项（kitex 侧才有 WithReadyAddr）），配合 bootstrap Ready 实现 NNS 延迟注册；transportx（hertz→core/transport 同构适配器）+ chainmw 桥接 bootstrap、concurrency、core、gormx、kitx、logx、metrics、middleware、nns、pkg、registry、tracing
kitex Kitex 生态——日志桥接、治理热更、生命周期、BizError 桥接、kitexotel、istio（xDS 动态熔断，原 istio 微库收编）；RunServer 变参就绪门（WithOnReady/WithReadyAddr/WithReadyProbeTimeout）+ chainmw.ToKitex（core/chain.Middleware → kitex 中间件，与 hertz 共享 middleware/chainmw 实现）+ transportx bootstrap、concurrency、core、logx、metrics、nns、pkg、registry
workflow 组合式流程编排——串行/并行/异步/条件分支 + Hook AOP concurrency、logx
kitex-examples Kitex echo 示例——client/server + IDL + 治理配置 bootstrap、core、kitex、logx、tracing

依赖严格自底向上；微库已合并为 pkg，旧微库仓已删除。

本仓在矩阵中的位置与依赖见上表「矩阵内依赖」列。历史沿革：源自 ekit 单体库 （git.enjoye.top/enjoydream/ekit v0.34.0，冻结维护），2026-10 拆分为独立 module。

License

MIT — 见 LICENSE

Documentation

Overview

Package httpx 提供 JSON HTTP 客户端。

所有 enjoydream 后端服务共享此包，统一 HTTP 调用方式。

核心特性

  • JSON 请求/响应自动序列化
  • Prometheus 指标采集
  • 熔断器（gobreaker）
  • 指数退避重试
  • OpenTelemetry 追踪
  • 文件上传（multipart/form-data）
  • DoDetail：status + 原始 body（2xx 也返回）
  • net/http 桥接层：NewRoundTripper/StdClient——存量标准库调用方一行 Transport 即接入熔断/重试/指标/链路（重试缺省关、显式开）
  • WithDialFunc/WithHertzOption：拨号层拦截与 Hertz 原生选项透传（SSRF 防护）
  • WithStream：流式响应预设（关读超时、保留拨号超时）
  • DoOnce：client 可注入的低阶一次性请求原语（构造→发出→读尽→返回 status/body；无重试/熔断，弹性语义单点在引擎层）

快速接入

创建客户端（构造失败显式返回 error，与 gormx.Open 等家族构造器一致， #83）： 

client, err := ehttp.NewClient("user-service",
    ehttp.WithBaseURL("http://user-service:8080"),
    ehttp.WithTimeout(5*time.Second),
    ehttp.WithTracePropagation(),
)
if err != nil {
    return err
}

构造参数静态合法时可用 MustNewClient 一行接入。

GET 请求： 

var users []User
err = client.GetJSON(ctx, "/api/users", &users)

POST 请求： 

var result CreateUserResp
err := client.PostJSON(ctx, "/api/users", req, &result)

需要状态码与原始响应体时用 DoDetail（2xx 也返回 body；非 2xx 额外返回 *ServiceError）： 

status, body, err := client.DoDetail(ctx, http.MethodPost, "/api/users", req)

流式响应与超时语义

默认配置注入 30s 拨号/读超时——**只适合短请求**。读超时是「响应必须 在 30s 内读完」的硬顶，对流式响应（SSE 转发、k8s proxy 长连接、WS 升级、chunked 大响应）会静默掐断长流（症状是连接被远端/代理切断， 极难归因到客户端读超时）。流式场景必须显式关读超时： 

client, err := ehttp.NewClient("k8s-proxy",
    ehttp.WithStream(), // 关读超时 + 保留拨号超时（#87）
)

超时语义族：WithTimeout(d) 同时覆盖拨号与读取（各以 d 为独立上限， 非全生命周期总预算）；仅调读/拨号单项经 WithHertzOption (client.WithClientReadTimeout / WithDialTimeout)；写超时经 WithHertzOption(client.WithWriteTimeout)。流式的总时长预算由调用方经 ctx 控制。

出站 SSRF 防护

调用方 URL 来自不受信输入时做两层检查：URL 层字面量拒绝内网 IP/主机名； 拨号层用 WithDialFunc 在建连前校验解析后的 IP（防 DNS rebinding）。 详见 README「出站 SSRF 防护套路」。

监控集成

使用 WithMetrics 启用 Prometheus 指标： 

client, err := ehttp.NewClient("user-service",
    ehttp.WithMetrics(metrics.Registry, "myservice"),
)

指标包括（namespace 未显式指定时前缀为 http_client）：

  • {ns}_requests_total{service, target, method, status_code}
  • {ns}_request_duration_seconds{service, target, method}
  • {ns}_requests_in_flight{service, target, method}

同一 Registry + namespace 下创建多个 Client 是安全的：同名指标自动复用 已注册的 collector。禁止 host/IP/port/path 等高基数 label。

熔断器

使用 WithCircuitBreaker 启用熔断保护： 

client := ehttp.NewClient("user-service",
    ehttp.WithCircuitBreaker("user-service", gobreaker.Settings{
        MaxRequests: 3,
        Interval:    10 * time.Second,
        Timeout:     30 * time.Second,
    }),
)

熔断器状态变化会自动记录到日志。

错误处理

返回 ServiceError 类型，包含服务名、操作、状态码和响应体： 

var svcErr *ehttp.ServiceError
if errors.As(err, &svcErr) {
    log.Printf("service: %s, action: %s, code: %d, message: %s",
        svcErr.Service, svcErr.Action, svcErr.Code, svcErr.Message)
}

Index

Constants

View Source 
const MetadataKeyScheme = "scheme"

MetadataKeyScheme 是实例协议的元数据键（#90）：注册中心实例经此声明 对外协议，取值 "http"/"https"（大小写不敏感）；缺省或取值不认识时 回落 "http"（与历史 endpoint 形态一致）。修复前地址硬编码 "http://"， https 服务无法经 WithNNS 接入（无论元数据如何都被以明文 http 拨号）。

Variables

View Source 
var ErrCircuitOpen = breaker.ErrCircuitOpen

ErrCircuitOpen 表示熔断器处于打开状态，请求被拒绝。

规范哨兵定义于 concurrency/breaker（错误消息逐字为 "circuit breaker is open"）， httpx 此处仅别名它：gobreaker 熔断路径与 adaptive 熔断器（concurrency/breaker） 拒绝时返回同一 sentinel，errors.Is 全链统一判定。判定一律用 errors.Is。

Functions

func DoOnce added in v0.8.12 

func DoOnce(ctx context.Context, hc *http.Client, req *http.Request) (status int, body []byte, err error)

DoOnce 一次性低阶请求原语：发出请求 → 读尽响应体 → 返回 (status, body, err)（#91）。

定位：服务里「共享 *http.Client（自定义 Transport：SSRF 拨号/链路透传） + 轻量请求骨架」的形态此前没有库级原语，各服务自收敛一份，收敛点又因 client 不可注入被绕开（openclaw 实录：需要不挂 urlguard 的 loopback 客户端时整份 NewRequest/Do/ReadAll/状态码判定重新手搓）。

语义与边界：

  • client 由调用方注入：hc 为 nil 时用 http.DefaultClient。挂不挂 SSRF 防护（Transport 包 urlguard）、什么连接池、什么超时，都是宿主决策—— 本原语不做任何拨号/传输假设；
  • 不做重试/熔断/负载均衡：弹性语义单点在 NewClient 引擎层，本原语与 引擎层组合会造成复合重试；需要弹性时直接用 Client；
  • 非 2xx 不是错误（标准库语义）：调用方自行判定 status；body 仅在 err == nil 时有效（读 body 中途出错时 status 仍返回、body 为 nil）；
  • ctx 非 nil 时覆盖 req 自带的 context（req.WithContext）；总时长 预算经 ctx 控制；
  • 响应体总是读尽并关闭（body Close 后返回），适合 JSON/文本等可控 体量的响应；超大响应的流式消费不要经本原语缓冲。

func NewRoundTripper added in v0.6.0 

func NewRoundTripper(service string, opts ...ClientOption) http.RoundTripper

NewRoundTripper 把 httpx Client 装进标准 http.RoundTripper（#8）。 service 与 opts 语义同 NewClient。

构造失败（含静态端点与动态 resolver 互斥等构造期冲突）直接 panic—— 桥接层为「一行 Transport 接入」保留无错误签名，panic 发生在初始化期、 携带完整原因，不是请求路径上的运行期 panic。配置来自外部输入、需要 显式判错的调用方用 NewRoundTripperE。

func NewRoundTripperE added in v0.8.12 

func NewRoundTripperE(service string, opts ...ClientOption) (http.RoundTripper, error)

NewRoundTripperE 是 NewRoundTripper 的显式错误版本（#83）：构造失败 返回 error 而非 panic。语义同 NewRoundTripper。

func NodesFromEndpoints added in v0.4.0 

func NodesFromEndpoints(endpoints []string) []loadbalance.Node

NodesFromEndpoints 把字符串端点列表合成为等权节点（权重 1、无元数据）。

func SafeDialFunc added in v0.7.0 

func SafeDialFunc(next network.DialFunc) network.DialFunc

SafeDialFunc 包装 network.DialFunc：出站 SSRF 防护（缺省配置，全阻断）。 next 为 nil 时使用 standard 拨号器裸拨（30s 超时；#74：不用 DefaultDialer—— netpoll 构建下它是 netpoll 拨号器，返回的连接不支持 TLS 后续包装，https 目标会在补握手一步 fail-fast）。需要豁免（测试打本机 mock、内网 webhook 端点）用 SafeDialFuncWith / WithSafeDial 传构造态 option。

https 目标受支持：经 httpx.WithDialFunc/WithSafeDial 装配时拨号器是 TLS 感知的（见 tlsAwareDialer）——裸拨后按 tlsConfig 补握手。直接用 hertz 原生 client.WithDialFunc 装配本函数会踩 hertz customDialer 丢 tlsConfig 的坑 （明文打 443），应经本仓装配。

func SafeDialFuncWith added in v0.8.0 

func SafeDialFuncWith(opts []pkgurlguard.Option, next network.DialFunc) network.DialFunc

SafeDialFuncWith 同 SafeDialFunc，但接受 pkg/urlguard 的构造态 Option： 

httpx.SafeDialFuncWith([]urlguard.Option{urlguard.WithAllowPrivate()}, next) // 测试打本机 mock
httpx.SafeDialFuncWith([]urlguard.Option{urlguard.WithAllowCIDRs("10.20.0.0/16")}, next) // 内网端点豁免

CIDR 文法非法时返回的拨号函数一律报错（fail-fast，不带病运行）。

func SelectorNodes added in v0.4.0 

func SelectorNodes(insts []registry.Instance) []loadbalance.Node

SelectorNodes 把注册中心实例切片适配为 Selector 节点（字段闭包映射， 地址 scheme 从实例 Metadata 取（键 MetadataKeyScheme），缺省 "http"）。

func StdClient added in v0.6.0 

func StdClient(service string, opts ...ClientOption) *http.Client

StdClient 返回装好 Transport 的标准 http.Client（Timeout 留零—— 超时边界由 httpx 层管理：缺省 dial/read 30s，可经 WithTimeout/WithHertzOption 调整）。 构造失败语义同 NewRoundTripper（panic）；需显式判错用 NewRoundTripperE。

func WithPriority 

func WithPriority(ctx context.Context, priority Priority) context.Context

WithPriority 将优先级注入 context。

Types

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client 是封装了 Hertz HTTP 客户端的高层 HTTP 调用器，支持服务发现、负载均衡、熔断和指标。

func MustNewClient added in v0.8.12 

func MustNewClient(service string, opts ...ClientOption) *Client

MustNewClient 是 NewClient 的 panic 版本：构造失败直接 panic（携带 NewClient 返回的完整错误信息）。仅用于构造参数静态合法的场景（硬编码 配置、初始化期组装）；配置来自外部输入时一律用 NewClient 显式判错。

func NewClient 

func NewClient(service string, opts ...ClientOption) (*Client, error)

NewClient 创建 HTTP 客户端实例，应用指定的配置选项。

构造失败显式返回 error（#83）：与家族同级构造器契约一致（gormx.Open、 core/config.LoadFile 均为 error 显式返回），出站 HTTP 客户端用在 webhook/工具调用等场景，构造失败不应升级为进程死亡。失败来源：

  • WithHertzOption 逃生舱透传的非法 Hertz client 配置项；
  • 构造期配置冲突（如 WithEndpoints 与 WithNNS/WithServiceResolver 互斥，#89）。

BREAKING（0.x minor 改签名，先例 gormx v0.9.0 参数序 breaking）：签名从 `NewClient(...) *Client` 改为 `NewClient(...) (*Client, error)`。旧代码 

c := httpx.NewClient("svc", ...)

迁移为 

c, err := httpx.NewClient("svc", ...)
if err != nil {
    return err
}

确认构造参数静态合法、不愿逐处判错的调用方用 MustNewClient。

func (*Client) Close 

func (c *Client) Close()

Close 关闭客户端，释放资源：停止 EndpointManager 刷新循环，并关闭底层 Hertz client 的空闲连接池（hostClient 连接与清理协程随之收敛，#84）。

说明：钉住的 hertz v0.10.6 *client.Client 没有 Close() error，可用的 释放口是 CloseIdleConnections()——关闭全部 hostClient 的空闲连接后， hertz 的连接清理协程按 ShouldRemove 逐个回收 hostClient 并退出。 Close 幂等，可安全重复调用。

func (*Client) DoCodec added in v0.4.0 

func (c *Client) DoCodec(ctx context.Context, codecName, method, path string, body any, out any) error

DoCodec 使用指定编解码器发送请求：body 经 codec.Marshal 序列化并设置 对应 Content-Type；响应按其 Content-Type 反查 codec 反序列化到 out （查不到回退请求 codec）。

func (*Client) DoDetail 

func (c *Client) DoDetail(ctx context.Context, method, path string, body any) (int, []byte, error)

DoDetail 使用指定的 HTTP 方法发送请求，返回状态码与原始响应体。 与 DoJSON/DoRaw 不同：2xx 也返回原始 body（DoJSON 只把 body 解到 out， DoRaw 仅在成功时返回 body），非 2xx 同时返回 status、body 与 *ServiceError，调用方可自行判定如何处理响应内容。 传输层失败时 status 为 0、body 为 nil。

func (*Client) DoJSON 

func (c *Client) DoJSON(ctx context.Context, method, path string, body any, out any) error

DoJSON 使用指定的 HTTP 方法发送 JSON 请求（等价 DoCodec(codec.DefaultName, ...)）。

func (*Client) DoRaw 

func (c *Client) DoRaw(ctx context.Context, method, path string, body any) ([]byte, error)

DoRaw 使用指定的 HTTP 方法发送 JSON 请求，返回原始响应字节数据。

func (*Client) GetJSON 

func (c *Client) GetJSON(ctx context.Context, path string, out any) error

GetJSON 发送 GET 请求并将响应反序列化到 out。

func (*Client) Hertz 

func (c *Client) Hertz() *client.Client

Hertz 返回底层 Hertz Client 实例，用于直接操作。

func (*Client) PostJSON 

func (c *Client) PostJSON(ctx context.Context, path string, body any, out any) error

PostJSON 发送 POST 请求。

func (*Client) SetTarget 

func (c *Client) SetTarget(target string)

SetTarget 运行时更新 target label。

func (*Client) UploadBytes 

func (c *Client) UploadBytes(ctx context.Context, path string, data []byte, fieldName, fileName string, extraFields map[string]string, out any) error

UploadBytes 上传字节数据 (multipart/form-data)。

func (*Client) UploadFile 

func (c *Client) UploadFile(ctx context.Context, path, filePath, fieldName string, extraFields map[string]string, out any) error

UploadFile 上传本地文件 (multipart/form-data)：读取 filePath 全部内容 作为文件 part（filename 取 filepath.Base(filePath)——不带本地目录， 避免泄漏服务器目录结构），额外表单字段经 extraFields 透传（#86）。 内存中的字节用 UploadBytes。

type ClientOption 

type ClientOption func(*Client)

ClientOption 是 Client 的配置函数类型。

func WithBaseURL 

func WithBaseURL(u string) ClientOption

WithBaseURL 设置客户端的基础 URL。

func WithBasicAuth 

func WithBasicAuth(user, password string) ClientOption

WithBasicAuth 为所有请求设置 Basic Auth 认证。

func WithBearerToken 

func WithBearerToken(token string) ClientOption

WithBearerToken 为所有请求设置 Bearer Token 认证。

func WithCircuitBreaker 

func WithCircuitBreaker(name string, settings gobreaker.Settings) ClientOption

WithCircuitBreaker 为客户端启用熔断器，使用指定的名称和配置。

func WithCookieJar 

func WithCookieJar(jar http.CookieJar) ClientOption

WithCookieJar 为客户端设置 Cookie Jar。 通过 base 中间件在请求前注入 Cookie、响应后回收 Set-Cookie， 对全部请求路径生效（含裸 Hertz().Do）。

func WithDebug 

func WithDebug() ClientOption

WithDebug 开启调试日志。 Hertz client 不支持运行时调试开关（日志由 hlog 全局控制），此选项留作占位。

func WithDialFunc 

func WithDialFunc(fn network.DialFunc, dialers ...network.Dialer) ClientOption

WithDialFunc 注入自定义拨号函数（#74）。 典型用途是出站 SSRF 防护的拨号层拦截：在真正建连前校验 addr 解析出的 IP 是否落在内网/黑名单（URL 层字面量检查挡不住 DNS rebinding）。 dialers 可选，用于覆盖基础拨号器（缺省 DefaultDialer()）。

不再透传 Hertz 的 client.WithDialFunc：hertz 的 customDialer 在有 dialFunc 时 **完全丢弃 tlsConfig**（pkg/app/client/option.go 的 DialConnection 直接 `return m.dialFunc(address)`）——https 目标的 TLS 握手链路就此断裂， WithSafeDial 形态把明文请求静默打到 443 端口（症状是服务端 400，极难排障）。 本仓改为自行装配 TLS 感知拨号器 tlsAwareDialer：dialFunc 拨通裸连接后按 hertz 传入的 tlsConfig 是否为 nil 决定是否补 TLS 握手（见 ssrf.go 实现说明）。

装配时机是 NewClient 的**末位兜底**（不再入 hzOpts）：hertz 的 client.WithTLSConfig 会无条件覆盖 o.Dialer——WithTLSSkipVerify 排在本选项 之后时自定义拨号函数会被静默丢弃（SSRF 防护一并失效）。末位 append 保证 WithDialFunc/WithSafeDial 的装配面赢。逃生舱 WithHertzOption 自带 client.WithDialer 的例外：本选项未使用时不装配、不覆盖逃生舱的拨号器。

func WithEndpoints 

func WithEndpoints(endpoints ...string) ClientOption

WithEndpoints 设置静态 endpoint 列表。

与动态服务发现（WithNNS/WithServiceResolver）互斥（#89）：组合使用时 静态端点会被动态刷新循环在下一个刷新周期覆盖（或静态端点被静默丢弃）， 行为随 option 顺序漂移且无告警——组合直接构造期报错（NewClient 返回 error）。一个 Client 只能有一种端点来源；需要静态兜底 + 动态发现的 组合语义由 EndpointManager 的缓存降级提供（resolver 失败时保留快照）。

func WithHertzOption 

func WithHertzOption(opts ...config.ClientOption) ClientOption

WithHertzOption 透传任意 Hertz client 配置项（逃生舱）。 优先使用语义化选项（WithTimeout/WithDialFunc/WithRetryConfig 等）； 仅当某项 Hertz 能力尚未封装时使用，按传入顺序追加到 client.NewClient 的选项列表尾部。

func WithMetrics 

func WithMetrics(registry prom.Registerer, namespace string) ClientOption

WithMetrics 为客户端启用 Prometheus 指标采集。

func WithNNS 

func WithNNS(serviceName string, nnsClient NNSClient) ClientOption

WithNNS 启用 NNS 服务发现。

func WithOnBeforeRequest 

func WithOnBeforeRequest(fn func(ctx context.Context, req *protocol.Request) error) ClientOption

WithOnBeforeRequest 注册请求前置钩子。 ⚠️ Breaking: 签名从 func(*req.Client, *req.Request) 改为 func(ctx context.Context, req *protocol.Request)（hertz protocol 类型）。

func WithPriorityQueue 

func WithPriorityQueue(capacity int) ClientOption

WithPriorityQueue 启用请求优先级队列。 capacity 是每级准入容量，必须 >= 1——0/负数在构造期 panic 并指明原因 （0 会造成所有请求阻塞到 ctx 取消的死锁，见 NewPriorityQueue，#88）； 配置值缺省时请显式传 1。

func WithRefreshInterval 

func WithRefreshInterval(d time.Duration) ClientOption

WithRefreshInterval 设置 endpoint 刷新间隔。

func WithRetryConfig 

func WithRetryConfig(maxAttempts uint, initDelay, maxDelay, maxJitter time.Duration) ClientOption

WithRetryConfig 配置请求重试策略,走 Hertz 官方 client.WithRetryConfig。 参数语义:

  • maxAttempts:总尝试次数(>=1,含首次请求);0 = 走 Hertz 默认 1 次
  • initDelay:首次重试前的等待时间(指数退避基数,对应 retry.Config.Delay)
  • maxDelay:重试延迟上限(避免退避无界增长,retry.Delay 内部封顶)
  • maxJitter:随机抖动上限(避免雪崩,对应 retry.Config.MaxJitter)

DelayPolicy 必须显式设置:hertz WithRetryConfig 的默认 DelayPolicy 是 retry.DefaultDelayPolicy(恒返回 0,参见 hertz pkg/app/client/retry/retry.go), 不设置的话 initDelay/maxDelay/maxJitter 三个参数全部无效、重试零等待。 ekit 固定注入 CombineDelay(BackOffDelayPolicy, RandomDelayPolicy): 每次重试延迟 = initDelay<<attempts + [0, maxJitter) 随机抖动,MaxDelay 封顶。

⚠️ 重试触发条件(与 Hertz 默认不同,带幂等方法门 #85): 

Hertz 官方 DefaultRetryIf 仅在幂等方法 + 网络错误时重试,不重试 5xx。
ekit WithRetryConfig 默认重试「幂等方法/无 body 请求」上的 5xx +
network error——比 Hertz 宽(补 5xx),比旧版「不看方法一律重试」严。
旧版默认对 POST 等**非幂等请求**的 5xx 无条件重放,网关恰好超时但
后端已实际写入时会重复下单/重复创建——「保持兼容」不等于「安全默认」。
需要放开旧语义(任何方法都重试)时,经 WithRetryIfFunc 显式声明。

官方依据:https://www.cloudwego.io/zh/docs/hertz/tutorials/basic-feature/client/ (Client 配置表 WithRetryConfig 示例明确列出 retry.WithDelayPolicy; 退避/抖动语义见 hertz pkg/app/client/retry 包:BackOffDelayPolicy = Delay<<attempts, RandomDelayPolicy = fastrand.Int63n(MaxJitter),CombineDelay 求和)

用法: 

cli, err := httpx.NewClient("my-svc",
    httpx.WithRetryConfig(3, 100*time.Millisecond, 1*time.Second, 50*time.Millisecond),
)

func WithRetryIfFunc 

func WithRetryIfFunc(fn func(req *protocol.Request, resp *protocol.Response, err error) bool) ClientOption

WithRetryIfFunc 覆盖 ekit 默认重试触发条件(幂等方法门 + 5xx + network error),由用户传自定义 predicate(更严格:只对特定方法/状态码; 更宽松:放开非幂等请求的重放)。 不调 WithRetryIfFunc 时,WithRetryConfig 注入默认条件。

**显式谓词永远赢，与 option 顺序无关**（#41）：即便本 option 写在 WithRetryConfig 之前也不会被默认谓词覆盖 ⇒ 不会再出现「以为收窄了重试、 实际 POST 仍被重放」这种静默失效。

func WithSafeDial added in v0.7.0 

func WithSafeDial(opts ...pkgurlguard.Option) ClientOption

WithSafeDial 一步启用出站 SSRF 防护，等价 WithDialFunc(SafeDialFuncWith(opts, nil))。 URL 层字面量校验请另调 pkg/urlguard 的 IsBlockedURL / Guard.CheckURL。 无参调用即缺省全阻断；豁免传 pkg/urlguard 的 Option（可变参，向后兼容无参形态）。

https 目标受支持（#74）：WithDialFunc 装配的是 TLS 感知拨号器，拨通后按 tlsConfig 补握手——防护在 TLS 之前生效（先校验解析 IP 再建连），握手在受 拨号超时约束下完成。

func WithSelector added in v0.4.0 

func WithSelector(sel loadbalance.Selector) ClientOption

WithSelector 设置节点选择器（roundrobin/random/weighted/一致性哈希等， 经 loadbalance.NewSelector 或 NewConsistentHashSelector 构造）。 v0.4.0 起替代 WithBalance。

func WithServiceResolver 

func WithServiceResolver(resolver ServiceResolver) ClientOption

WithServiceResolver 设置自定义服务发现解析器。

func WithStream added in v0.8.12 

func WithStream() ClientOption

WithStream 流式响应预设（#87）：关闭读超时（默认 30s 只适合短请求—— 读超时与流式语义直接冲突，30s 硬顶会把任何长流掐死，症状是连接被远端/ 代理静默切断、极难归因到客户端），保留拨号超时（建连阶段仍需兜底）。

适用面：SSE 转发、k8s proxy/长连接代理、WS 升级、chunked 大响应。 等价于 WithHertzOption(client.WithClientReadTimeout(0)) 的固化预设—— 把「流式要关什么」的知识固化进库，不必每个消费方自己拼逃生舱选项。

语义与边界：

  • 与 WithTimeout 按 option 顺序后者覆盖（都是 append 到 hzOpts）： 「预算拨号 + 不限读」写 WithTimeout(d), WithStream()； 「都不限」只写 WithStream()；
  • 流的总时长预算由调用方经 ctx 控制（context.WithTimeout），引擎层 不替流式请求做整段超时；
  • 引擎层 Client 的响应体是全量缓冲语义（GetJSON/DoRaw 返回时 body 已读尽）；真正的逐块消费经 net/http 桥接（StdClient + 本预设）， 或直接用注入低阶 client 的 DoOnce。

func WithTLSSkipVerify 

func WithTLSSkipVerify() ClientOption

WithTLSSkipVerify 跳过 TLS 证书验证。

func WithTarget 

func WithTarget(target string) ClientOption

WithTarget 设置指标 target label 的值。

func WithTimeout 

func WithTimeout(d time.Duration) ClientOption

WithTimeout 设置 HTTP 请求超时预算，同时覆盖**拨号**与**响应读取**两个 阶段（#90/#92）：`WithTimeout(3s)` 对不可达主机（黑洞路由/半开连接）在 拨号阶段即 3s 超时——修复前仅设读超时，拨号沿用 hertz 默认 30s，调用方 以为的 3s 实际可等 33s。

语义边界（超时语义族，另见 #87 的流式说明）：

  • 覆盖面 = DialTimeout + ReadTimeout，各以 d 为独立上限（不是串行叠加 的总预算；与标准库 http.Client{Timeout} 的全生命周期覆盖不同—— TLS 握手计入拨号阶段，写超时不单独设，可经逃生舱 WithHertzOption(client.WithWriteTimeout(d)) 补充）；
  • 仅想调读超时、保留 30s 拨号上限：WithHertzOption(client.WithClientReadTimeout(d))；
  • 仅想调拨号：WithHertzOption(client.WithDialTimeout(d))；
  • 流式响应（SSE/代理长连接/WS 升级）不能用整段读超时掐流，用 WithStream。

func WithTracePropagation 

func WithTracePropagation() ClientOption

WithTracePropagation 启用 OpenTelemetry 上下文透传(traceparent / tracestate / baggage), 走 Hertz client.UseAsLast 注入,在所有自定义中间件之后执行, 

避免 trace 头被其他中间件覆盖或重复。

propagator 通过 otel.GetTextMapPropagator() 读取(默认 W3C TraceContext + Baggage), 与 ekit observability/tracing 全局配置保持一致 — 调用方只需先初始化 tracer + propagator。

官方依据:https://www.cloudwego.io/zh/docs/hertz/tutorials/basic-feature/client/ (UseAsLast 章节:"中间件设置在 ctx.lastMiddleware 中,使用 Use 设置的中间件链存放在 ctx.mws 中,两者相对独立,只是在执行客户端中间件链的最后才执行 ctx.lastMiddleware")

type ConsistentHashOption 

type ConsistentHashOption func(*ConsistentHashSelector)

ConsistentHashOption ConsistentHashSelector 的可选参数。

func WithConsistentHashFunc 

func WithConsistentHashFunc(fn func([]byte) uint64) ConsistentHashOption

WithConsistentHashFunc 自定义哈希函数（默认 FNV-1a 64）。nil 被忽略。

func WithConsistentReplicas 

func WithConsistentReplicas(n int) ConsistentHashOption

WithConsistentReplicas 设置每个节点的虚拟副本数（默认 100）。 n <= 0 被忽略。

type ConsistentHashSelector added in v0.4.0 

type ConsistentHashSelector struct {
	// contains filtered or unexported fields
}

ConsistentHashSelector 一致性哈希选择器：同一 key 稳定路由到同一节点， 节点增减仅引起相邻键的重新映射。适合有状态粘滞路由（同用户/同租户 粘住同实例）且实例列表动态变化的场景。

key 取 SelectOption WithKey 值（httpx EndpointManager 默认传请求 PATH）； 节点权重按比例折算虚拟副本数（等权均值归一，clamp 到 [1, 4×base]）， 注册中心权重配置照常生效。

v0.4.0 起替代 ConsistentHashBalance（BalanceStrategy 形态已删除）。

func NewConsistentHashSelector added in v0.4.0 

func NewConsistentHashSelector(opts ...ConsistentHashOption) (*ConsistentHashSelector, error)

NewConsistentHashSelector 创建一致性哈希选择器。

func (*ConsistentHashSelector) Select added in v0.4.0 

func (b *ConsistentHashSelector) Select(ctx context.Context, nodes []loadbalance.Node, opts ...loadbalance.SelectOption) (loadbalance.Node, loadbalance.DoneFunc, error)

Select 按一致性哈希选择节点。

type EndpointManager 

type EndpointManager struct {
	// contains filtered or unexported fields
}

EndpointManager endpoint 管理器：动态刷新节点快照 + 缓存降级， 选择经 loadbalance.Selector 完成。

func NewEndpointManager 

func NewEndpointManager(resolver ServiceResolver, selector loadbalance.Selector, refreshInterval time.Duration) *EndpointManager

NewEndpointManager 创建 endpoint 管理器。 selector 为 nil 时回退 roundrobin；refreshInterval > 0 且 resolver 非空时 启动刷新循环。

func (*EndpointManager) GetNodes added in v0.4.0 

func (m *EndpointManager) GetNodes() []loadbalance.Node

GetNodes 获取节点快照（优先最新，降级缓存）。

func (*EndpointManager) Pick 

func (m *EndpointManager) Pick(ctx context.Context, key string) (string, loadbalance.DoneFunc, error)

Pick 选择一个节点地址，返回地址与结果回写句柄（调用结束后以最终 错误调用 done；done 为 nil 表示无需回写）。 key 用于一致性选点类 Selector（httpx 以请求 PATH 为默认键）。

func (*EndpointManager) SetEndpoints 

func (m *EndpointManager) SetEndpoints(endpoints []string)

SetEndpoints 设置静态端点列表（等权合成，停止动态刷新语义不变）。

func (*EndpointManager) SetNodes added in v0.4.0 

func (m *EndpointManager) SetNodes(nodes []loadbalance.Node)

SetNodes 直接设置节点快照。

func (*EndpointManager) Stop 

func (m *EndpointManager) Stop()

Stop 停止刷新。

type InstanceResolver added in v0.4.0 

type InstanceResolver interface {
	// ResolveInstances 解析服务名称，返回实例列表。
	ResolveInstances(ctx context.Context) ([]registry.Instance, error)
}

InstanceResolver 是 ServiceResolver 的可选增强接口：提供完整实例视图 （含权重与元数据）。EndpointManager 检测到 resolver 实现本接口时， 实例的权重与 Metadata 贯通到 Selector（加权策略与 WithFilter 生效）； 仅实现 ServiceResolver 的 resolver 等权合成（权重 1、无元数据）。

type NNSClient 

type NNSClient interface {
	GetInstances(ctx context.Context, serviceName string) ([]registry.Instance, error)
}

NNSClient NNS 客户端接口，与顶层 nns.NNSClient.GetInstances 签名一致。

type NNSResolver 

type NNSResolver struct {
	// contains filtered or unexported fields
}

NNSResolver NNS 服务发现解析器（实现 ServiceResolver 与 InstanceResolver）。

func NewNNSResolver 

func NewNNSResolver(serviceName string, nnsClient NNSClient) *NNSResolver

NewNNSResolver 创建 NNS 解析器。

func (*NNSResolver) Resolve 

func (r *NNSResolver) Resolve(ctx context.Context) ([]string, error)

Resolve 解析服务名称，返回地址列表（丢弃权重与元数据；地址 scheme 从 实例 Metadata 取，缺省 "http"，#90）。

func (*NNSResolver) ResolveInstances added in v0.4.0 

func (r *NNSResolver) ResolveInstances(ctx context.Context) ([]registry.Instance, error)

ResolveInstances 解析服务名称，返回实例列表（地址 scheme 从实例 Metadata 取，键 MetadataKeyScheme，缺省 "http"，#90）。 透传 context 到 NNS，保留超时和 trace_id 语义。

type Priority 

type Priority int

Priority 请求优先级。 

const (
	PriorityLow    Priority = 0
	PriorityNormal Priority = 1
	PriorityHigh   Priority = 2
)

func GetPriority 

func GetPriority(ctx context.Context) Priority

GetPriority 从 context 获取优先级。

type PriorityQueue 

type PriorityQueue struct {
	// contains filtered or unexported fields
}

PriorityQueue 分级准入控制队列。

注意语义：这是分级准入控制而非严格优先级队列——high/normal/low 三级 各自独立计数（同级 FIFO），不保证跨级抢占；高优先级请求不会抢占已获准的 低优先级请求，仅在自身级别容量内准入。未知优先级按 PriorityNormal 处理。

func NewPriorityQueue 

func NewPriorityQueue(capacity int) *PriorityQueue

NewPriorityQueue 创建优先级队列。

capacity 是每级（high/normal/low）的准入容量，必须 >= 1（#88）：

  • capacity == 0（配置值缺省的典型形态）会得到无缓冲 channel—— Acquire 的发送必须等 Release 接收，首个请求即死锁，所有请求卡在 Acquire 直到 ctx 超时/取消，症状是客户端全量超时，极难定位；
  • capacity < 0 直接 panic（make 的运行期 panic，无原因说明）。

非法值在构造期 panic 并指明原因，不等到运行期静默阻塞。

func (*PriorityQueue) Acquire 

func (q *PriorityQueue) Acquire(ctx context.Context, priority Priority) bool

Acquire 获取许可（按优先级）。

func (*PriorityQueue) Len 

func (q *PriorityQueue) Len() int

Len 返回队列长度。

func (*PriorityQueue) Release 

func (q *PriorityQueue) Release(priority Priority)

Release 释放许可。

priority 必须与 Acquire 时一致；未知优先级按 PriorityNormal 释放 （与 Acquire 的 default 分支对齐），避免静默泄漏许可。

type ServiceError 

type ServiceError struct {
	Service string
	Action  string
	Code    int
	Message string
}

ServiceError 表示 HTTP 服务调用返回的业务错误。

func (*ServiceError) Error 

func (e *ServiceError) Error() string

Error 实现 error 接口，返回格式化的错误信息。

type ServiceResolver 

type ServiceResolver interface {
	// Resolve 解析服务名称，返回可用的 endpoint 列表。
	Resolve(ctx context.Context) ([]string, error)
}

ServiceResolver 服务发现解析器接口。

type StaticResolver 

type StaticResolver struct {
	// contains filtered or unexported fields
}

StaticResolver 静态 endpoint 解析器。

func NewStaticResolver 

func NewStaticResolver(endpoints []string) *StaticResolver

NewStaticResolver 创建静态解析器。

func (*StaticResolver) Resolve 

func (r *StaticResolver) Resolve(ctx context.Context) ([]string, error)

Resolve 返回静态配置的 endpoint 列表。

Source Files

View all Source files

Directories

Path Synopsis
Package codec 提供请求/响应编解码器的注册制抽象（参照 go-kratos encoding）。
 Package codec 提供请求/响应编解码器的注册制抽象（参照 go-kratos encoding）。
Package loadbalance 提供与具体服务发现实现解耦的节点选择抽象（Selector， 参照 go-kratos selector）。
 Package loadbalance 提供与具体服务发现实现解耦的节点选择抽象（Selector， 参照 go-kratos selector）。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.