endpoint

package module
v0.3.6 Latest Latest
Warning

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

 Go to latest Published: Nov 13, 2026 License: MIT Imports: 24 Imported by: 0

README

nns-endpoint

端点工厂——服务发现+熔断+换实例重试封装成一个函数

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

安装

go get github.com/oekit/nns-endpoint@v0.3.5

这个仓库做什么

nns-endpoint 是端点工厂：把「服务发现 + per-service 熔断 + 失败换实例重试 + gRPC 连接池」封装成一个可调用的 Endpoint 函数。

熔断语义（重点）

  • 熔断按服务分片，4xx 不计熔断失败（调用方参数错误与对端健康无关）
  • 5xx / 网络错误计失败；open 状态错误用 errors.Is(err, endpoint.ErrCircuitOpen) 判定
  • HTTP 端点失败自动换实例重试；gRPC 端点不做重试（streaming/非幂等语义复杂）

快速使用

import endpoint "github.com/oekit/nns-endpoint"

factory := endpoint.NewHTTPEndpointFactory(nnsc.ServiceClient())
ep, _ := factory.MakeEndpoint("payment-svc")

resp, err := ep(ctx, req) // 背后：发现 + 熔断 + 换实例重试

gRPC 调用

import (
	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials/insecure"

	endpoint "github.com/oekit/nns-endpoint"
)

grpcFactory := endpoint.NewGRPCEndpointFactory(nnsc.ServiceClient())
ep, _ := grpcFactory.MakeEndpoint("user-svc",
	grpc.WithTransportCredentials(insecure.NewCredentials())) // 传输凭据必须显式传入（#77）

reply := &userv1.GetUserReply{}
_, err := ep(ctx, endpoint.GRPCRequest{
	GrpcServiceName: "userv1.UserService",
	Method:          "GetUser",
	Request:         &userv1.GetUserRequest{Id: 42},
	Reply:           reply, // 类型化响应指针，端点返回值即它（#71/#73）
})
  • 传输凭据不设默认值（#77）：明文必须显式声明 grpc.WithTransportCredentials(insecure.NewCredentials())，TLS 场景传对应 TransportCredentials；缺凭据直接得到 grpc 的 no transport security set 错误，绝不静默降级明文。
  • Reply 必填（proto.Message 指针）：默认 proto codec 无法向裸 any 解码，响应解码目标是调用方传入的类型化指针（#71/#73）。
  • 单次调用超时：GRPCRequest.Timeout > 服务治理 readTimeout（毫秒）> 兜底 30s——两级均缺配不再立即 DeadlineExceeded（#75）。

边界

  • 依赖 nns 的 ServiceClient()、httpx 的发现/负载均衡
  • 历史注记：原为 nns 门面的 MakeHTTPEndpoint，拆分后独立成仓

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

模块 内容 矩阵内依赖
pkg 微工具集 31 合 1（errors/bloomx/contextx/ctxscope/container/stringx/slicex/enumx/convert/encoding/jsonrepair/httpjson/mathx/pathx/pagination/ptrx/secretx/shellx/timex/cache/bufiox/strmap/singleflighttest/urlguard/webhook/cli/pack/procx/config/tarx/resumable；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 体检一次列全问题并区分包损坏与版本不认识；config/tarx（v0.42.0 起）启动期静态配置加载管线（yaml+env 覆盖+必填汇总校验+敏感字段脱敏 dump，#329）+ 目录 tar 传输三件套（同口径预扫 Scan/流式写出 Write/防御式解包 Extract 跳过并点名 Zip Slip 穿越条目 + sha256 manifest 自证，#326）；v0.43.0 起三处收口——cache.Checker 构造期 fail-fast（nil refresh panic/WithClock(nil) 回退默认，#356）+ 刷新跑在 WithoutCancel 上（leader 断开不再把取消缓存成 failTTL 传染等待者，瞬态 Canceled 不入缓存，#352）+ SingleFlightCache 按调用注入路径不再按 key 合并（source 不可比较，合并即串味/丢 TTL/强刷退化；Refresh 与 load 分键，#353）；container.Ring 逻辑序归基（32 位平台高频写入不再回绕出负下标 panic，#354）；cache/pack/urlguard 三个裸 Option 改名 CheckerOption/WriterOption/GuardOption（#355，禁裸 Option 仓规收尾）；v0.44.0 起三面补齐——shellx 词法事实面 Analyze（tokenize：普通词/重定向运算符+目标/动态词三类事实分离 + HasRedirect/HasDynamic/按控制符分段，前缀规则判据不再被「git status > /etc/passwd」整类绕过，判不了就报错不尽力解析，#358）+ procx 子进程内存上限原语（WithMemoryLimit/MemGroup：cgroup v2 memory.max 创建·设置·清理 + MemoryLimitCapable 问询面，兑现失败 fail closed 拒绝执行不静默不限、OOM-kill 与非零退出可辨、换出面一并封死、非 Linux 如实降级，#359）+ resumable 分片上传/断点续传会话面（新包：会话创建/分片登记/断点查询/完成/中止/Sweep 状态机，CAS 进度·合并抢占·双源对账·孤儿清扫四坑单点化，纯内存状态面 + ChunkStore 接口化存储后端，#361） —
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 应用基建件——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 行为与错误文案逐字不变 pkg
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 拆出 logx、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、pkg、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、pkg、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 → KUBECONFIG 显式意图 → in-cluster 自动 → ~/.kube/config 逐级回退，QPS/Burst 限流默认 50/100、负值=禁用客户端限流）+ leaderelection 子包 Lease 选主简化封装（OnStartedLeading/OnStoppedLeading/OnNewLeader 回调，主备单活，仅要求 Lease CRUD 权限；失权与 ctx 取消并存时失权优先上抛 ErrLostLeadership，续约失败与取消同窗不掩蔽） 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、pkg
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、tracing
workflow 组合式流程编排——串行/并行/异步/条件分支 + Hook AOP concurrency、logx、pkg
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 endpoint 定义了统一的服务调用端点抽象，封装负载均衡、熔断和连接池等基础设施。

核心类型 Endpoint 是一个函数签名，接收 context 和请求并返回响应，使上层逻辑与具体协议解耦。 HTTPEndpointFactory 和 GRPCEndpointFactory 分别为 HTTP 和 gRPC 协议创建 Endpoint， 内部集成负载均衡选择实例、gRPC 连接池复用连接、以及基于 gobreaker 的断路器保护。

Index

Constants

This section is empty.

Variables

View Source 
var ErrCircuitOpen = httpx.ErrCircuitOpen

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

与 httpx.ErrCircuitOpen 是同一 sentinel：endpoint 工厂与 httpx.Client 的 熔断行为共用一个可判定错误，消费方 errors.Is 任一别名均可识别， 不必同时 import 两个包。

View Source 
var ErrFactoryClosed = errors.New("nns-endpoint: endpoint factory closed")

ErrFactoryClosed 表示端点工厂已 Close（终结操作）后仍调用其端点（#148）。 errors.Is 可判定；Close 后存量端点闭包一律短路返回本哨兵（包装为 localError——本地确定性错误，不计熔断样本、不做节点 EWMA 惩罚）， 不再触达底层连接池。优雅停机窗口在途请求、双路关停竞态下未同步的 消费方都拿到明确错误，而不是静默复活池里的连接。

View Source 
var ErrPoolClosed = errors.New("nns-endpoint: grpc pool closed")

ErrPoolClosed 表示连接池已 Close（终结操作）后再取连接（#148）。 errors.Is 可判定；Close 后 Get/Acquire 一律返回本哨兵，不再静默新建 连接——新建连接进入已终结的池后无人再调 pool.Close，连接及其 gRPC channel/子连接只能泄漏到进程退出。

Functions

This section is empty.

Types

type Endpoint 

type Endpoint func(ctx context.Context, request any) (any, error)

Endpoint 端点函数类型，接收上下文和请求，返回响应和错误。

type EndpointFactoryOption 

type EndpointFactoryOption func(*factoryConfig)

EndpointFactoryOption 是端点工厂（HTTP/gRPC）的配置函数类型。

func WithBreakerSettings 

func WithBreakerSettings(tmpl gobreaker.Settings) EndpointFactoryOption

WithBreakerSettings 设置 per-service 熔断器的参数模板。

数值字段（MaxRequests/Interval/Timeout）整体取模板值——0 是 gobreaker 的合法显式语义（如 Interval 0 = 计数器跨窗口累计），不做零值回填； 函数字段（ReadyToTrip/OnStateChange/IsSuccessful）为 nil 时沿用工厂默认。

未传 IsSuccessful 时默认判定为"4xx 不计熔断失败"（调用方请求错误与 对端健康无关）；显式传入则完全接管失败判定。

func WithMetrics 

func WithMetrics(reg prom.Registerer, namespace string) EndpointFactoryOption

WithMetrics 启用弹性指标（熔断状态/迁移/拒绝 + 重试尝试）。 reg 为 nil 时回退到 oekit/metrics 的平台 Registry（metrics.Registry， 平台 /metrics 端点暴露的自定义 registry，与 metrics#50 后 resilience.NewMetrics 的 nil 口径一致）；确需进 prom 默认全局 registry 的调用方显式传 prom.DefaultRegisterer。namespace 为空时用 "nns_endpoint"。多个工厂共享同一 Registry + namespace 时复用已注册 collector。

注意：本仓与 httpx.WithMetrics 的 nil 语义**不同**（#144）——httpx 在调 NewMetrics 之前自行把 nil 回填为 prom.DefaultRegisterer，本仓把 nil 原样透传给 resilience.NewMetrics（回退 metrics.Registry）。两仓 nil 落 不同 registry，调用方跨仓对齐口径时以此为准。

func WithSelector added in v0.2.0 

func WithSelector(sel loadbalance.Selector) EndpointFactoryOption

WithSelector 注入节点选择器（loadbalance.Selector），覆盖服务治理配置 中的 lb 策略；nil 被忽略。未注入时按服务配置的 Lb 字段经 loadbalance.NewSelector 构造（不可识别回退 roundrobin）。

type GRPCEndpointFactory 

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

GRPCEndpointFactory gRPC 端点工厂，负责创建 gRPC 端点并管理连接池和熔断器。

balancer 与熔断器均按服务名分片：balancer 缓存避免有状态策略（轮询）因 计数器重置失效；熔断器按服务隔离，避免单个依赖故障熔断全工厂。 balancer/熔断器均在端点闭包内按调用获取（balancerCache 读锁命中，开销可忽略）， 配置热更新（ResetBalancer）对已创建的端点同样生效。服务配置（超时等）在每次 调用时从内存读取，支持 WatchService 热更新。

func NewGRPCEndpointFactory 

func NewGRPCEndpointFactory(c *nnsclient.ServiceClient, opts ...EndpointFactoryOption) *GRPCEndpointFactory

NewGRPCEndpointFactory 根据服务客户端创建 gRPC 端点工厂实例。 opts 定制 per-service 熔断参数（WithBreakerSettings）等行为。 注意：gRPC 端点不做换实例重试——streaming/非幂等 RPC 的重试语义 复杂（需 header/ trailers 透传配合），如需重试在业务层按方法粒度实现。

func (*GRPCEndpointFactory) Close 

func (f *GRPCEndpointFactory) Close()

Close 关闭 gRPC 端点工厂持有的资源：先登记终态（此后存量端点闭包 短路返回 ErrFactoryClosed，#148），再注销构造期在 client 上注册的 配置变更回调（#135，不注销则 client 经回调闭包长持已废弃工厂、配置 事件继续打在死工厂上），最后关闭连接池。OffConfigChange 与 pool.Close 均幂等，Close 可安全重复调用。

func (*GRPCEndpointFactory) MakeEndpoint 

func (f *GRPCEndpointFactory) MakeEndpoint(serviceName string, opts ...grpc.DialOption) (Endpoint, error)

MakeEndpoint 为指定服务创建 gRPC 端点，包含负载均衡、连接池和熔断逻辑。 balancer 与熔断器在闭包内按调用获取，ResetBalancer/配置热更对存量端点生效。

传输安全（#77）：opts 必须显式包含传输凭据——明文传 grpc.WithTransportCredentials(insecure.NewCredentials())，TLS 传对应 TransportCredentials。连接池不再默认注入 insecure 凭据，缺凭据的 调用会得到 grpc 的 "no transport security set" 错误（此前是静默明文）。

func (*GRPCEndpointFactory) ResetSelector added in v0.2.0 

func (f *GRPCEndpointFactory) ResetSelector(serviceName string)

ResetSelector 清除指定服务的节点选择器缓存，下次调用时按最新配置重建。

type GRPCPool 

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

GRPCPool gRPC 连接池，复用 gRPC 客户端连接。 连接数超过 maxSize 时先全局驱逐空闲超龄条目，仍满则拒绝创建新连接。 空闲超过 idleTTL 的连接在 Get 时自动驱逐（同地址命中与满池创建两条 路径都会驱逐）；有在途引用（Acquire 后未 Release）的连接不参与驱逐 （#99）——conn.Close 会终止其上全部活跃 RPC。

借还口径：Get 是无引用借出（与 v0.2.x 行为一致，适合短平快的一元 调用）；长生命周期流式 RPC 必须用 Acquire/Release 配对——在途期间 连接不会被任何驱逐路径关闭。

实例一次性（#148）：Close 是终结操作，Close 后 Get/Acquire 一律返回 ErrPoolClosed——不静默重建连接（否则新建连接进入已终结的池，此后无人 再 Close ⇒ 连接与 gRPC channel/子连接泄漏）。对齐矩阵 #124 以来 「停机后调用显式报错，不静默哑火」的纪律（timertask 同场景返回 ErrBackendStopped）。

传输凭据（#77）：池**不注入**默认凭据——调用方必须经 opts 显式传入 grpc.WithTransportCredentials(insecure.NewCredentials())（明文）或 TLS 凭据。缺凭据时 grpc.NewClient 返回 "no transport security set" 错误 （fail-closed），不再静默降级明文。

func NewGRPCPool 

func NewGRPCPool(maxSize ...int) *GRPCPool

NewGRPCPool 创建一个新的 gRPC 连接池实例。

maxSize 可省略（缺省 defaultMaxPoolSize）；显式传入 ≤0 的值同样回退 默认值（原 NewGRPCPoolWithSize 的守卫语义）。两个构造器除 maxSize 外 逐行相同、且带尺寸形态全工作区仅测试使用（#134）——合并为单一构造器， 公开面少一个入口。

func (*GRPCPool) Acquire added in v0.3.0 

func (p *GRPCPool) Acquire(ctx context.Context, addr string, opts ...grpc.DialOption) (*grpc.ClientConn, error)

Acquire 从连接池借出指定地址的 gRPC 连接并记在途引用（#99）。 与 Get 的差别只在引用记账：借出期间（直到 Release）该连接不会被任何 空闲驱逐路径关闭——lastUsed 的「借出时刻」口径覆盖不了「借出后仍在 用」的长生命周期流式 RPC。调用方用毕必须 Release(addr, conn) 配对归还； 未归还的连接永不被空闲驱逐（至多被 Shutdown 替换或池 Close 终结）。 池 Close 后调用返回 ErrPoolClosed（#148，终结语义：不静默重建连接）。

func (*GRPCPool) Close 

func (p *GRPCPool) Close()

Close 关闭连接池中的所有 gRPC 连接。 Close 是终结操作：有在途引用的连接同样关闭（其上活跃 RPC 会终止）， 与「显式关停」语义一致。Close 后 Get/Acquire 一律返回 ErrPoolClosed （#148）——不静默重建连接，存量端点在工厂 Close 后的调用同样被闸拒绝。

func (*GRPCPool) Get 

func (p *GRPCPool) Get(ctx context.Context, addr string, opts ...grpc.DialOption) (*grpc.ClientConn, error)

Get 从连接池获取指定地址的 gRPC 连接，不存在、已关闭或空闲超时时创建新连接。 opts 透传给 grpc.NewClient；必须包含传输凭据（明文 insecure / TLS）， 缺凭据时返回 grpc 的 no transport security set 错误（#77）。 池 Close 后调用返回 ErrPoolClosed（#148，终结语义：不静默重建连接）。

Get 是**无引用借出**：不记在途引用，适合调用时长远小于 idleTTL 的 一元调用（端点工厂内部即此形态，超时上限有界）。调用时长可能超过 idleTTL 的长生命周期流式 RPC 必须改用 Acquire/Release（#99）——否则 借出后连接仍可能因空闲判据（按「借出时刻」计）被驱逐关闭，终止 在途 RPC。

并发安全说明：读锁读取 entry 与写锁校验之间存在窗口，期间该 entry 可能被 并发驱逐（Close 后删除）或替换。因此返回前必须在写锁内校验 p.conns[addr] 仍等于该 entry，否则重试——绝不把一个可能已被 Close 的连接返回给调用方。

func (*GRPCPool) Release added in v0.3.0 

func (p *GRPCPool) Release(addr string, conn *grpc.ClientConn)

Release 归还 Acquire 借出的连接（在途引用减一，#99）。 (addr, conn) 必须与 Acquire 的返回值配对：连接对应的条目已被替换/驱逐时 本次归还为 no-op（老条目的引用计数随其消亡，老连接必然已关闭或濒死， 无需保护）。归还即刷新 lastUsed——空闲计时从归还时刻起算。

type GRPCRequest 

type GRPCRequest struct {
	ServiceName     string
	GrpcServiceName string
	Method          string
	// Request 是请求消息，必须实现 proto.Message（默认 proto codec 只
	// 接受该类型）。不满足时端点在发起调用前直接报错，而不是让编解码
	// 失败发生在 Invoke 深处、错误形态晦涩。
	Request any
	// Reply 是接收响应的类型化消息指针，由调用方传入（如
	// &helloworld.HelloReply{}），端点的返回值就是它。必填。
	//
	// #71/#73：此前解码目标是 var reply any（&reply 是 *any），默认
	// proto codec 的 Unmarshal 要求 proto.Message，类型化响应永远拿
	// 不到——gRPC happy path 从未跑通过。
	Reply proto.Message
	// Timeout 是单次调用超时；0 时回退服务治理 ReadTimeout，两级均
	// 未配置时兜底 defaultCallTimeout（#75）。
	Timeout time.Duration
}

GRPCRequest gRPC 端点请求参数。

type HTTPEndpointFactory 

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

HTTPEndpointFactory HTTP 端点工厂，负责创建 HTTP 端点并管理 HTTP 客户端和熔断器。

func NewHTTPEndpointFactory 

func NewHTTPEndpointFactory(c *nnsclient.ServiceClient, opts ...EndpointFactoryOption) *HTTPEndpointFactory

NewHTTPEndpointFactory 根据服务客户端创建 HTTP 端点工厂实例。 opts 定制 per-service 熔断参数（WithBreakerSettings）、弹性指标 （WithMetrics）等行为。

func (*HTTPEndpointFactory) Close 

func (f *HTTPEndpointFactory) Close()

Close 关闭 HTTP 端点工厂持有的资源。 Hertz client 连接池无显式释放 API（随进程生命周期），httpx.Client 的 endpointManager 在本工厂场景未启用；此处注销构造期在 client 上 注册的配置变更回调（#135）——否则 client 经回调闭包长持已废弃工厂， selectorCache/breakers 无法回收，配置事件继续打在死工厂上。 OffConfigChange 幂等，Close 可安全重复调用。

func (*HTTPEndpointFactory) MakeEndpoint 

func (f *HTTPEndpointFactory) MakeEndpoint(serviceName string) (Endpoint, error)

MakeEndpoint 为指定服务创建 HTTP 端点。

重试语义（消费服务配置 ServiceBasic.Retry，Nacos 配置缺省 3）： 失败时换实例重试，最多额外 Retry 次尝试；5xx 与网络错误重试， 4xx 不重试（确定性请求错误）；本地确定性错误（序列化/解码/选点， #123）重试同一输入恒失败，同样不重试、不计熔断样本。熔断 Execute 包住整组尝试——一次调用计一次熔断样本（与 httpx.WithCircuitBreaker + WithRetryConfig 的层次结构一致），避免单次调用的多次尝试 撑爆连续失败计数。每次尝试独立 per-attempt 超时，最坏总耗时 为 (1+Retry) × ReadTimeout。

分层边界（#96/#98）：实例发现与 selector 首建在 Execute 之外—— 「无实例」与「配置中心故障」都不是目标后端的故障，不构成熔断样本 （与 gRPC 路径的分层一致）。

func (*HTTPEndpointFactory) ResetSelector added in v0.2.0 

func (f *HTTPEndpointFactory) ResetSelector(serviceName string)

ResetSelector 清除指定服务的节点选择器缓存（配置热更后强制重建）。

type HTTPRequest 

type HTTPRequest struct {
	Method  string
	Path    string
	Body    any
	Header  map[string]string
	Query   map[string]string
	Result  any
	Timeout time.Duration
}

HTTPRequest HTTP 端点请求参数。

Source Files

View all Source files

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.