Documentation
¶
Overview ¶
Package loadbalance 提供通用的负载均衡算法原语,不绑定任何 RPC/服务发现框架。
三个算法:
- ConsistentHash:一致性哈希(虚拟节点 + maphash),按 key 路由到稳定节点, 支持权重与副本,适合"会话粘性 / 带状态分片"场景;
- WeightedRoundRobin:平滑加权轮询(nginx SWRR),按权重比例均匀分发, 避免低权重节点被连续命中,适合"按容量分配流量"场景;
- RoundRobin:无权重轮询,atomic 游标,无锁高吞吐,适合节点等价的场景。
节点由调用方提供,实现 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 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