Documentation
¶
Overview ¶
Package loadbalance 提供通用的负载均衡算法原语,不绑定任何 RPC/服务发现框架。
四个算法:
- ConsistentHash:一致性哈希(虚拟节点 + maphash),按 key 路由到稳定节点, 支持权重与副本,适合"会话粘性 / 带状态分片"场景;
- WeightedRoundRobin:平滑加权轮询(nginx SWRR),按权重比例均匀分发, 避免低权重节点被连续命中,适合"按容量分配流量"场景;
- RoundRobin:无权重轮询,atomic 游标,无锁高吞吐,适合节点等价的场景;
- P2C:Power of Two Choices + EWMA(见 p2c.go),按实时延迟/在途数选更优节点, 需结果反馈(Pick 返回 done 回调),压长尾、避慢节点,适合动态负载差异大的场景。
节点由调用方提供,实现 Node 接口(ID 用于虚拟节点命名,Weight 用于权重计算)。 算法本身是纯计算,并发安全:ConsistentHash 构建后只读;WeightedRoundRobin 的 Next 内部加锁;RoundRobin 用 atomic 游标无锁。
零值不可用,用 NewConsistentHash / NewWeightedRoundRobin / NewRoundRobin 构造。
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ConsistentHash ¶
type ConsistentHash[T any] struct { // contains filtered or unexported fields }
ConsistentHash 一致性哈希负载均衡器。构建后只读,并发安全。 零值不可用,用 NewConsistentHash 构造。
func NewConsistentHash ¶
func NewConsistentHash[T any](nodes []T, opts ...ConsistentHashOption[T]) *ConsistentHash[T]
NewConsistentHash 创建一致性哈希。nodes 为空时返回空 Balancer(Get 返回零值)。
func (*ConsistentHash[T]) Get ¶
func (c *ConsistentHash[T]) Get(key string) (T, bool)
Get 按 key 返回主节点。key 为空或无节点时返回零值 + false。
func (*ConsistentHash[T]) GetReplicas ¶
func (c *ConsistentHash[T]) GetReplicas(key string, n int) []T
GetReplicas 按 key 返回主节点 + 顺时针方向的不重复后续节点,共 n 个(不足则返回实际数量)。 n <= 0 时等价于 Get。
type ConsistentHashOption ¶
type ConsistentHashOption[T any] func(*consistentHashConfig)
ConsistentHashOption 是一致性哈希的配置选项。
func WithReplica ¶
func WithReplica[T any](n uint32) ConsistentHashOption[T]
WithReplica 设置查询时返回的副本数(含主节点,默认 0=只返回主节点)。 副本用于主节点不可达时的备选,按环上顺时针方向取不重复的后续节点。
func WithVirtualFactor ¶
func WithVirtualFactor[T any](n uint32) ConsistentHashOption[T]
WithVirtualFactor 设置每个真实节点的虚拟节点倍数(默认 100)。 值越大,负载越均匀,但内存与构建成本越高。
func WithWeighted ¶
func WithWeighted[T any](weighted bool) ConsistentHashOption[T]
WithWeighted 启用按权重放大:虚拟节点数 = Weight × VirtualFactor(默认启用)。 关闭后各节点虚拟节点数 = VirtualFactor,忽略权重。
type P2C ¶ added in v0.3.0
type P2C[T any] struct { // contains filtered or unexported fields }
===== P2C + EWMA =====
P2C(Power of Two Choices)+ EWMA:随机取两个节点、选"负载"更低的那个;负载由每节点的 延迟 EWMA(指数加权移动平均,带时间衰减)与在途请求数共同决定。相比轮询/加权,它能感知 实时快慢与堆积,自动避开慢/过载节点,显著压低长尾——是 gRPC/Finagle/Kratos 的现代默认策略。
与本包其它算法不同,P2C 需要"结果反馈":Pick 返回节点与一个 done 回调,调用方在请求结束时 调用 done(err),用本次耗时与成败更新该节点的 EWMA。用法:
node, done, ok := lb.Pick()
if !ok { /* 无可用节点 */ }
err := call(node)
done(err)
算法数学参考自 beauty 的 gRPC balancer(pkg/client/grpcclient,策略名 p2c_ewma): load = sqrt(lag+1) * (inflight+1);EWMA 权重 w = exp(-Δt/decay);另有 forcePick 防饥饿 (长时间未被选中的节点会被强制选一次)与健康度阈值。并发安全。零值不可用,用 NewP2C 构造。
type RoundRobin ¶
type RoundRobin[T any] struct { // contains filtered or unexported fields }
RoundRobin 无权重轮询。atomic 游标自增取模,读路径无锁高吞吐; nodes 快照用 RWMutex 保护,以支持 Update 与 Next 并发(服务列表热更新场景)。 适合节点等价(无权重区分)的场景。并发安全。零值不可用,用 NewRoundRobin 构造。
func NewRoundRobin ¶
func NewRoundRobin[T any](nodes []T) *RoundRobin[T]
NewRoundRobin 创建轮询。nodes 为空时 Next 返回零值 + false。
func (*RoundRobin[T]) Next ¶
func (r *RoundRobin[T]) Next() (T, bool)
Next 返回下一个节点(轮询)。无节点时返回零值 + false。
func (*RoundRobin[T]) Update ¶
func (r *RoundRobin[T]) Update(nodes []T)
Update 用新节点列表替换。适用于服务列表变化(节点增删)。
type WeightedRoundRobin ¶
type WeightedRoundRobin[T any] struct { // contains filtered or unexported fields }
WeightedRoundRobin 平滑加权轮询(nginx SWRR)。 算法:每轮所有节点 current += weight,选 current 最大者,选中者 current -= totalWeight。 结果是按权重比例均匀分布,且避免低权重节点被连续命中。 并发安全。零值不可用,用 NewWeightedRoundRobin 构造。
func NewWeightedRoundRobin ¶
func NewWeightedRoundRobin[T any](nodes []T) *WeightedRoundRobin[T]
NewWeightedRoundRobin 创建加权轮询。weight<=0 的节点被忽略。 节点为空时 Next 返回零值 + false。
func (*WeightedRoundRobin[T]) Next ¶
func (w *WeightedRoundRobin[T]) Next() (T, bool)
Next 返回下一个节点(SWRR)。无节点时返回零值 + false。
func (*WeightedRoundRobin[T]) Nodes ¶
func (w *WeightedRoundRobin[T]) Nodes() []T
Nodes 返回所有节点(构建时的快照)。
func (*WeightedRoundRobin[T]) Reset ¶
func (w *WeightedRoundRobin[T]) Reset()
Reset 清空内部 current 状态,回到初始轮次。
func (*WeightedRoundRobin[T]) Update ¶
func (w *WeightedRoundRobin[T]) Update(nodes []T)
Update 用新节点列表重建权重表。适用于服务列表变化(节点增删/权重变更)。 重建后 current 状态清零,从新一轮开始。weight<=0 的节点被忽略。
Source Files