README
¶
nns-endpoint
端点工厂——服务发现+熔断+换实例重试封装成一个函数
🌐 项目主页：https://oekit.github.io/ · 名称由来：Open Easy Kit（开源 · 易用 · 工具集合） 🤖 AI Agent：本仓规范与硬规则见 AGENTS.md；机器可读索引见 llms.txt（接口签名以源码为准）。
安装
go get github.com/oekit/nns-endpoint@v0.1.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) // 背后：发现 + 熔断 + 换实例重试
边界
矩阵总览（24 活跃模块，自动生成）
| 模块 | 内容 | 矩阵内依赖 |
|---|---|---|
| pkg | 微工具集 19 合 1（errors/bloomx/contextx/container/stringx/slicex/enumx/convert/encoding/jsonrepair/httpjson/mathx/pathx/pagination/ptrx/timex/cache/bufiox/strmap；v0.10.0 起 uidgen/validator 拆至 kitx）；cache（v0.4.0 起）含缓存接口 CacheAside + BatchGetter 批量能力（MGet）+ LocalCache/SingleFlightCache + cachetest 契约 + Checker；container（v0.9.0 起，收编原 collectionx）泛型容器 Set/Ring/Queue/SafeMap + Map（sync.Map 背书）/Slice（并发安全）；timex/stringx（v0.7.0 起）时间段边界 BeginningOf/EndOf 七对（分/时/日/周/月/季/年，周起始显式参数）+ trie 多模式替换器 Replacer（最长匹配）/ NewMask 敏感词遮罩；singleflighttest（v0.8.0 起）singleflight 共享契约测试套件（internal 与 concurrency 双侧引用） | — |
| concurrency | 并发与流控原语（async/gopool/group/singleflight/progress/syncx/ratelimit/retry）+ window 滑动窗口 / breaker 自适应熔断（规范哨兵 ErrCircuitOpen）/ shedding CPU 自适应降载 / batch 攒批执行器（满条数/满字节/窗口去重）/ timewheel 单级时间轮 | pkg |
| logx | 统一日志门面（多后端可替换 + Sink + caller 归属）+ 优雅关停；桥接子包 hlog/hertzlog/kitexlog 为嵌套模块按需引入 | — |
| core | 应用基建件（governance 治理 schema / config 配置加载 + default/env/range/options tag 校验 / lifecycle 契约 / network IP 工具 / version） | — |
| kitx | 标识与校验——uidgen（Snowflake 全局单例+Extract 元数据、手写 RFC 4122 v4 UUID 零第三方依赖、RandomHex/RandomString 拒绝采样随机串）+ validator（go-playground/validator v10 接口化门面：struct tag 校验/自定义规则注册/ValidationError Unwrap 为 BizError 400 对接 middleware.Fail），自 pkg v0.10.0 拆出 | pkg |
| metrics | Prometheus 门面 + 弹性指标族 | core |
| tracing | OpenTelemetry 追踪 + trace_id 真相源 | logx |
| registry | 注册发现核心 + Nacos 实现 + Nacos 配置源 + sdbridge | core、logx |
| data | 数据访问门面——复刻 ekit data/ 能力面：cache/rediscache/crud/distlock/gormx/redisx/timertask/cachetest 八子包 re-export（类型同一，实现住 pkg 与各子仓）+ cached 缓存读写编排（写后失效/事务提交后失效/查询缓存版本号失效/GetByIDs 批量点读 MGet 快路径/bloom 防穿透）+ twolevel 两级缓存与跨实例失效广播（v0.7.0 起本仓唯二非 re-export 实现）；all/ 聚合模块已废弃 retract | concurrency、gormx、logx、pkg、redisx、timertask |
| gormx | SQL/GORM 全家——连接池增强、框架无关 CRUD Service、仓储（原 oekit/gorm，v0.3.0 更名） | logx、pkg |
| redisx | Redis 全家——客户端封装（根包）、分布式缓存 cache/、分布式锁 distlock、分布式限流 ratelimit（Lua 三态 + 故障本地兜底） | 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、core、logx、registry |
| httpx | HTTP 客户端 + 负载均衡——服务发现/熔断（规范哨兵 ErrCircuitOpen）/重试/指标/OTel 透传/一致性哈希（权重感知虚拟副本） | concurrency、core、logx、metrics、registry、tracing |
| network | 轻量网络客户端——WebSocket/NATS/MQ 抽象、连接与流工具 | concurrency、logx、tracing |
| timertask | 分片定时任务（FNV-1a、心跳续约） | concurrency、logx |
| middleware | Hertz 自研标准中间件栈 + contrib 桥接 + hmw + SheddingMiddleware 自适应降载 | 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 池 | concurrency、core、httpx、logx、metrics、nns、registry |
| bootstrap | 应用生命周期引导——bootstrap.Run 骨架 + healthz | concurrency、logx |
| hertz | Hertz 运行时集成——日志桥接、生命周期、SSE/health/metrics、适配器、OTel、crudh/validatorh/versionh（原 handler 微库收编） | bootstrap、concurrency、core、gormx、kitx、logx、metrics、middleware、nns、pkg、registry、tracing |
| kitex | Kitex 生态——日志桥接、治理热更、生命周期、BizError 桥接、kitexotel、istio（xDS 动态熔断，原 istio 微库收编） | bootstrap、concurrency、core、logx、metrics、nns、pkg、registry |
| workflow | 组合式流程编排——串行/并行/异步/条件分支 + Hook AOP | concurrency、logx |
| kitex-examples | Kitex echo 示例——client/server + IDL + 治理配置 | bootstrap、concurrency、core、kitex、logx、metrics、nns、pkg、registry、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 ¶
var ErrCircuitOpen = httpx.ErrCircuitOpen
ErrCircuitOpen 表示熔断器处于打开状态、请求被拒绝。
与 httpx.ErrCircuitOpen 是同一 sentinel：endpoint 工厂与 httpx.Client 的 熔断行为共用一个可判定错误，消费方 errors.Is 任一别名均可识别， 不必同时 import 两个包。
Functions ¶
This section is empty.
Types ¶
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 启用弹性指标（熔断状态/迁移/拒绝 + 重试尝试）， 形态对齐 httpx.WithMetrics。reg 为 nil 时用全局 DefaultRegisterer； namespace 为空时用 "nns_endpoint"。多个工厂共享同一 Registry + namespace 时复用已注册 collector。
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 端点工厂持有的连接池资源。
func (*GRPCEndpointFactory) MakeEndpoint ¶
func (f *GRPCEndpointFactory) MakeEndpoint(serviceName string, opts ...grpc.DialOption) (Endpoint, error)
MakeEndpoint 为指定服务创建 gRPC 端点，包含负载均衡、连接池和熔断逻辑。 balancer 与熔断器在闭包内按调用获取，ResetBalancer/配置热更对存量端点生效。
func (*GRPCEndpointFactory) ResetBalancer ¶
func (f *GRPCEndpointFactory) ResetBalancer(serviceName string)
ResetBalancer 清除指定服务的负载均衡器缓存，下次调用时按最新配置重建。
type GRPCPool ¶
type GRPCPool struct {
// contains filtered or unexported fields
}
GRPCPool gRPC 连接池，复用 gRPC 客户端连接。 连接数超过 maxSize 时拒绝创建新连接。 空闲超过 idleTTL 的连接在 Get 时自动驱逐。
func NewGRPCPoolWithSize ¶
NewGRPCPoolWithSize 创建指定最大连接数的 gRPC 连接池。
func (*GRPCPool) Get ¶
func (p *GRPCPool) Get(ctx context.Context, addr string, opts ...grpc.DialOption) (*grpc.ClientConn, error)
Get 从连接池获取指定地址的 gRPC 连接，不存在、已关闭或空闲超时时创建新连接。
并发安全说明：读锁读取 entry 与写锁校验之间存在窗口，期间该 entry 可能被 并发驱逐（Close 后删除）或替换。因此返回前必须在写锁内校验 p.conns[addr] 仍等于该 entry，否则重试——绝不把一个可能已被 Close 的连接返回给调用方。
type GRPCRequest ¶
type GRPCRequest struct {
ServiceName string
GrpcServiceName string
Method string
Request any
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 在本工厂场景未启用，故此处无资源可释放； 保留方法以满足工厂统一 Close 契约。
func (*HTTPEndpointFactory) MakeEndpoint ¶
func (f *HTTPEndpointFactory) MakeEndpoint(serviceName string) (Endpoint, error)
MakeEndpoint 为指定服务创建 HTTP 端点。
重试语义（消费服务配置 ServiceBasic.Retry，Nacos 配置缺省 3）： 失败时换实例重试，最多额外 Retry 次尝试；5xx 与网络错误重试， 4xx 不重试（确定性请求错误）。熔断 Execute 包住整组尝试—— 一次调用计一次熔断样本（与 httpx.WithCircuitBreaker + WithRetryConfig 的层次结构一致），避免单次调用的多次尝试 撑爆连续失败计数。每次尝试独立 per-attempt 超时，最坏总耗时 为 (1+Retry) × ReadTimeout。
func (*HTTPEndpointFactory) ResetBalancer ¶
func (f *HTTPEndpointFactory) ResetBalancer(serviceName string)
ResetBalancer 清除指定服务的负载均衡器缓存。
Source Files