README
¶
ekit-nns-endpoint
NNS 端点工厂——per-service 熔断（4xx 不计失败）、HTTP 换实例重试、gRPC 连接池、弹性指标
本仓库是 ekit 拆分矩阵的成员（Round-4 微库化）。
安装
go get github.com/oekit/nns-endpoint@v0.1.0
包清单
- 根包
endpoint— HTTPEndpointFactory/GRPCEndpointFactory，经nns.ServiceClient()构造（Round-4 自 ekit-nns 分家）
依赖：ekit-nns（ServiceClient）、ekit-httpx、ekit-metrics、ekit-logx、ekit-registry、ekit-concurrency。
原 nns.MakeHTTPEndpoint/MakeGRPCEndpoint 门面 API 随本仓迁移：改用 endpoint.NewHTTPEndpointFactory(nnsClient.ServiceClient())。
License
见 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