Documentation
¶
Overview ¶
Package loadbalance 提供与具体服务发现实现解耦的节点选择抽象（Selector， 参照 go-kratos selector）。
v0.4.0 起 Selector 全面替代 v0.3.x 的 Balancer：
- Node 携带完整实例信息（地址/权重/服务名/Metadata）；
- Select 支持 WithFilter 按 Metadata 过滤候选、WithKey 一致性选点键；
- 调用结束经 DoneFunc 回写结果（DoneInfo），配合 WithDoneHook 采集， 为 P2C/EWMA 等自适应算法预留数据入口。
支持的策略（NewSelector 按名创建，别名自动归一）：
- roundrobin（轮询）
- random（随机）
- weighted（加权随机）
本包不 import 任何实例类型或框架——registry.Instance 等由调用方经 NodesFrom 泛型适配器（字段闭包映射）构造 Node。nns-endpoint 等上层包 与 httpx 根包复用本实现。
Package loadbalance 提供节点选择抽象（Selector，参照 go-kratos selector）。
相比 v0.3.x 的 Balancer（仅地址+权重的索引选择），Selector 携带完整节点 元数据（Version 经 Metadata）、支持按 Metadata 过滤候选、并在调用结束后 经 DoneFunc 回写结果（P2C/EWMA 等自适应算法的数据入口）。
与具体注册中心解耦：Node 经 NodesFrom 泛型适配器从任意实例类型构造， 本包不 import 任何 provider 或框架。
Index ¶
Constants ¶
const ( StrategyRoundRobin = "roundrobin" StrategyRandom = "random" StrategyWeighted = "weighted" // StrategyP2C 是自适应选择策略（Power of Two Choices，#6）： // 依据 DoneFunc 回写的调用时长 EWMA，把流量从慢/故障节点撬走。 StrategyP2C = "p2c" )
负载均衡策略名称常量（与 nns/metadata 中配置字符串保持一致）。
Variables ¶
var ErrNoAvailable = errors.New("loadbalance: no available node")
ErrNoAvailable 表示无可选节点（候选为空或全部被过滤）。
Functions ¶
func FilterOf ¶ added in v0.4.0
func FilterOf(opts []SelectOption) func(Node) bool
FilterOf 提取过滤函数（未设置返回 nil）。
func Key ¶ added in v0.4.0
func Key(opts []SelectOption) string
Key 提取 SelectOption 列表中的选点键（未设置返回空串）。 供自定义 Selector 实现（如一致性哈希）读取。
func NormalizeSelectorName ¶ added in v0.4.0
NormalizeSelectorName 将历史别名归一为规范策略名：
"round_robin" → "roundrobin" "weighted_round_robin" → "weighted" 其他名称原样返回
Types ¶
type DoneInfo ¶ added in v0.4.0
type DoneInfo struct {
// Err 是本次调用的最终错误（nil = 成功）。
Err error
// BytesSent/BytesReceived 标记是否发生了发送/接收（保留字段）。
BytesSent bool
BytesReceived bool
}
DoneInfo 是调用结束时的回写信息。
type Node ¶ added in v0.4.0
type Node interface {
// Address 是节点地址（host:port 或 scheme://host:port）。
Address() string
// Weight 是调度权重（<=0 视为 1）。
Weight() float64
// ServiceName 是节点所属服务名。
ServiceName() string
// Metadata 是节点元数据（版本、区域、集群等）。
Metadata() map[string]string
}
Node 是参与选择的节点，携带完整实例信息。
func Filtered ¶ added in v0.4.0
func Filtered(nodes []Node, opts []SelectOption) []Node
Filtered 返回经选项过滤后的候选节点。
type SelectOption ¶ added in v0.4.0
type SelectOption func(*selectOptions)
SelectOption 配置单次 Select。
func WithFilter ¶ added in v0.4.0
func WithFilter(fn func(Node) bool) SelectOption
WithFilter 过滤候选节点（如同 Group/Cluster 优先）；全部被过滤时返回 ErrNoAvailable。
func WithKey ¶ added in v0.4.0
func WithKey(key string) SelectOption
WithKey 提供一致性选点键（一致性哈希类 Selector 使用；roundrobin 等忽略）。
type Selector ¶ added in v0.4.0
type Selector interface {
// Select 从候选节点中选择一个。候选为空或全被过滤返回 ErrNoAvailable；
// 成功时 selected 与 done 均非 nil。
Select(ctx context.Context, nodes []Node, opts ...SelectOption) (selected Node, done DoneFunc, err error)
}
Selector 是可回写调用结果的节点选择器。
func NewSelector ¶ added in v0.4.0
func NewSelector(name string, opts ...SelectorOption) (Selector, error)
NewSelector 按策略名创建 Selector。接受规范名或别名（自动归一）； 空名称回退为 roundrobin；未知名称报错。
type SelectorOption ¶ added in v0.4.0
type SelectorOption func(*selectorConfig)
SelectorOption 配置 Selector 实例级行为。
func WithDoneHook ¶ added in v0.4.0
func WithDoneHook(fn func(ctx context.Context, n Node, di DoneInfo)) SelectorOption
WithDoneHook 订阅每次调用的结果回写（采集入口；本期只采集不参与决策， 为 P2C/EWMA 预留）。
Source Files