README
¶
constants（常量域）
默认值、归一化——零依赖的共享基准源
这个域干什么
constants 提供两类零依赖的共享基准：协议常量与默认值、appID/namespace/groupID
归一化；路由上下文的构建与传播见独立的 routing 包（routing → constants 单向
依赖，原子归一化函数收口于此）
核心概念
| 概念 | 说明 |
|---|---|
| 归一化 | NormalizeAppID / NormalizeNamespace / NormalizeGroupID：构造 Redis key 前统一口径（自定义大写内容保持原样） |
| 路由默认值 | DefaultAppID / DefaultNamespace / DefaultGroupID（route.go，"__" 前缀系统保留） |
| gRPC metadata key | MetadataKeyAppID 等（metadata.go）：跨节点路由信封的 header 名 |
| Bitmap 常量 | GlobalBitmapNS / DefaultMaxBitmapOffset / DefaultKeyBucketCount（bitmap.go） |
| 其余默认值 | 准入水位、整形速率、合并容量、慢消费者阈值、消息 deadline 等（delivery.go） |
怎么用
package main
import (
"context"
"github.com/kamalyes/go-wsc/constants"
"github.com/kamalyes/go-wsc/routing"
)
// 归一化：进 Redis key 构造前必做（Go 层归一，Lua 不兜底）
appID := constants.NormalizeAppID("App-1")
ns := constants.NormalizeNamespace("NS-1")
// 路由构建与注入在 routing 包（链式构建器，每个维度显式命名）
ctx = routing.NewRoute().WithAppID(appID).WithNamespace(ns).WithGroup("group-a").Inject(ctx)
// 下游随时取
got := routing.RoutingFromContext(ctx)
groups := routing.GroupIDsFromContext(ctx)
端口与依赖
- 零依赖：不 import 任何域包（方向永远是自己 ← 别人）
- 被 routing 单向依赖：routing.NormalizeRoute 收口调用本包原子归一化
- 归一化是构造 Redis key 的强制前置（REFACTORING_DESIGN 硬约束：Go 层归一，脚本不兜底）
性能与陷阱
- 常量集中在此、config 引用在此——避免「常量与 config 各养一份默认值」的双头维护
- 归一化保持幂等：输入已归一化时零开销返回，别重复分配
- 陷阱：在 Lua / SQL 里做归一化兜底——归一化必须在 Go 层一次做对
后端绑定
无纯常量与纯函数
Documentation
¶
Overview ¶
@Author: kamalyes 501893067@qq.com
@Date: 2026-08-23 00:00:00
@LastEditors: kamalyes 501893067@qq.com
@LastEditTime: 2026-08-23 00:00:00
@FilePath: \go-wsc\constants\bitmap.go
@Description: Bitmap 分层常量（用户在线状态判定层，位即真相） *
L0 Bitmap 判定层(SETBIT/GETBIT) + L1 uid→offset 映射，位即真相，无 ZSET 兜底
GlobalBitmapNS 为全局广播 bitmap 的 ns 段，与 DefaultNamespace 区分 *
热点 key 分桶：uid_map/all_users/type 按 hash(userID)%256 分桶，
消除亿级用户下单 key 写热点（详见 adapter/redis 的 keyBucket） *
Copyright (c) 2026 by kamalyes, All Rights Reserved.
@Author: kamalyes 501893067@qq.com
@Date: 2026-08-09 20:00:00
@LastEditors: kamalyes 501893067@qq.com
@LastEditTime: 2026-09-10 21:30:00
@FilePath: \go-wsc\constants\delivery.go
@Description: 送达分级与控制通道常量 —— 分级送达保证体系的单一事实源 *
Copyright (c) 2026 by kamalyes, All Rights Reserved.
@Author: kamalyes 501893067@qq.com
@Date: 2026-08-20 00:00:00
@LastEditors: kamalyes 501893067@qq.com
@LastEditTime: 2026-08-20 00:00:00
@FilePath: \go-wsc\constants\doc.go
@Description: go-wsc 系统级常量（单一真相源，无依赖底层包） *
抽离到独立 constants 包的目的：
- routing 与 models 互不依赖（routing 是底层包，不能 import models；
models 引用 routing 的同时，routing 不应反向依赖 models）
- 任何包（routing/models/hub/handler/业务方）均可直接 import constants，
用 constants.XXX 引用，无需别名重导出，无循环依赖 *
文件组织：
- route.go 路由隔离维度默认值（DefaultAppID/DefaultNamespace/DefaultGroupID）
- metadata.go gRPC metadata 键名（跨节点传播路由元数据）
- system_group.go 系统保留组常量（__agents__/__observers__ 等）
- normalize.go 路由维度空值归一化 helper（NormalizeAppID/Namespace/GroupID）
- redis_key.go Redis key 前缀默认值（各模块默认前缀）
- bitmap.go Bitmap 分层常量（GlobalBitmapNS + 默认配置） *
Copyright (c) 2026 by kamalyes, All Rights Reserved.
@Author: kamalyes 501893067@qq.com
@Date: 2026-08-20 00:00:00
@LastEditors: kamalyes 501893067@qq.com
@LastEditTime: 2026-08-20 13:56:32
@FilePath: \go-wsc\constants\metadata.go
@Description: gRPC metadata 键名常量（跨节点传播路由元数据） *
groupIDs 以逗号分隔存入单个 metadata 值，避免 repeated header 开销 *
Copyright (c) 2026 by kamalyes, All Rights Reserved.
*
@Author: kamalyes 501893067@qq.com
@Date: 2026-08-23 00:00:00
@LastEditors: kamalyes 501893067@qq.com
@LastEditTime: 2026-08-23 00:00:00
@FilePath: \go-wsc\constants\normalize.go
@Description: 路由隔离维度空值兜底统一入口 *
统一收口 AppID/Namespace/GroupID 三维空值归一化逻辑，
各层（读取层 getter / 注册入口 handleRegister / 落库层 repository.Upsert）
统一调用本文件 helper，避免散落 if 兜底导致的不一致与遗漏 *
Copyright (c) 2026 by kamalyes, All Rights Reserved.
@Author: kamalyes 501893067@qq.com
@Date: 2026-08-23 00:00:00
@LastEditors: kamalyes 501893067@qq.com
@LastEditTime: 2026-08-23 00:00:00
@FilePath: \go-wsc\constants\redis_key.go
@Description: Redis key 前缀默认值（跨模块共享） *
统一管理各模块 Redis key 默认前缀，避免散落在 repository 各文件。
repository 层引用 constants.DefaultXxxKeyPrefix 构造 key，调用方可覆盖。 *
Copyright (c) 2026 by kamalyes, All Rights Reserved.
@Author: kamalyes 501893067@qq.com
@Date: 2026-08-20 00:00:00
@LastEditors: kamalyes 501893067@qq.com
@LastEditTime: 2026-08-20 00:00:00
@FilePath: \go-wsc\constants\route.go
@Description: 路由隔离维度默认值常量 *
隔离层次：AppID(应用) > Namespace(租户) > GroupID(平台) > UserID
空值在入口层（HTTP 升级、HubMessage 注入、客户端注册）归一化为这些默认值，
下游过滤层无需处理空值，避免"空=全局共享"与"空=默认"两种语义并存 *
Copyright (c) 2026 by kamalyes, All Rights Reserved.
@Author: kamalyes 501893067@qq.com
@Date: 2026-08-20 00:00:00
@LastEditors: kamalyes 501893067@qq.com
@LastEditTime: 2026-08-20 13:02:32
@FilePath: \go-wsc\constants\system_group.go
@Description: 系统保留组常量（`__` 前缀为系统组，业务组名禁止以此开头） *
agent 连接时自动加入 __agents__，observer 连接时自动加入 __observers__
本地分片索引（agentShards/observerShards）仍保留做 O(1) 缓存，
Redis 系统组用于跨节点共享成员关系与显式广播 *
Copyright (c) 2026 by kamalyes, All Rights Reserved.
Index ¶
Constants ¶
const ( // GlobalBitmapNS 全局广播 bitmap 的 ns 段 // 路由信封 ns="" 表示全局广播，bitmap 用专用 ns 段(__global__)避免与 DefaultNamespace(__default_ns__) 混淆 // Lua 脚本(luaBatchSetClientsOnline/Offline)硬编码 "__global__" 须与本常量同值，修改时同步 GlobalBitmapNS = "__global__" // DefaultMaxBitmapOffset offset 默认上限（1000 万，bitmap 约 1.25MB） DefaultMaxBitmapOffset = 10_000_000 // DefaultMaxCachedUIDs 本地 offset 缓存默认容量上限 DefaultMaxCachedUIDs = 2_000_000 // DefaultBitmapTTLSeconds bitmap EXPIRE 兜底秒数（TTL 未配置时使用； // 正常路径 bitmapTTL 对齐 client TTL，见 repository.loadBitmapTTL） DefaultBitmapTTLSeconds = 60 // DefaultKeyBucketCount 热点 key 分桶数（2 的幂，按 hash(userID) 位与取桶） // uid_map/all_users/type 三类 key 按此分桶：亿级用户下单 key 写频从数百万 ops/s // 降至数千 ops/s，Redis Cluster 下桶天然散落到不同 slot DefaultKeyBucketCount = 256 // DefaultCleanupBatchCount 在线状态清理轮转批数 // CleanupExpired 每次只清 bucketCount/batchCount 个桶（256/8=32 桶）， // 单次 Lua 原子块命令量从 500+ 降至 ~70（约 20ms → 3ms，valkey SLOWLOG 实测）， // batchCount 个清理周期全覆盖所有桶；过期数据以 score 过期戳兜底，晚清语义无损 DefaultCleanupBatchCount = 8 )
const ( MetadataKeyAppID = "x-routing-app-id" // 应用ID（最上层隔离维度） MetadataKeyNamespace = "x-routing-namespace" // 命名空间 MetadataKeyGroupIDs = "x-routing-group-ids" // 群组ID列表（逗号分隔） )
gRPC metadata 键名（跨节点传播路由元数据）
const ( // DefaultOnlineKeyPrefix 在线状态默认 key 前缀 DefaultOnlineKeyPrefix = "wsc:online:" // DefaultWorkloadKeyPrefix 负载管理默认 key 前缀 DefaultWorkloadKeyPrefix = "wsc:workload:" // DefaultQueueKeyPrefix 消息队列默认 key 前缀 DefaultQueueKeyPrefix = "wsc:queue:" // DefaultStatsKeyPrefix 统计信息默认 key 前缀 DefaultStatsKeyPrefix = "wsc:stats:" // DefaultGroupKeyPrefix 群组默认 key 前缀 DefaultGroupKeyPrefix = "wsc:group:" )
Redis Key 前缀默认值（各模块默认前缀，调用方可覆盖）
const ( DefaultAppID = "__default_app__" // DefaultAppID 默认应用ID（最上层隔离维度） DefaultNamespace = "__default_ns__" // DefaultNamespace 默认命名空间ID（类似 k8s namespace） DefaultGroupID = "__default_gp__" // DefaultGroupID 默认群组ID（P2P 消息归一化用） )
路由隔离维度默认值（"__" 前缀为系统保留值，业务侧禁止使用）
const ( SystemGroupAgents = "__agents__" // SystemGroupAgents 客服系统组（每命名空间一个，ns:__agents__） SystemGroupObservers = "__observers__" // SystemGroupObservers 观察者系统组（全局 namespace="" 或命名空间级） SystemGroupPrefix = "__" // SystemGroupPrefix 系统组前缀，业务组名禁止以此开头 )
系统保留组常量
const ClientWriteBatchSize = 64
ClientWriteBatchSize 写泵单批最大帧数（writev 合批） 首条直写（无积压时 1 次 syscall 低延迟）后非阻塞排空积压合并写出： 突发 N 条 → 2 次 syscall（原 N 次）
const ClientWriteTimeout = 10 * time.Second
ClientWriteTimeout 写泵单批写超时（整批共享一次 deadline） 突发场景 N 次期限设置收敛为 1 次
const CtrlChanCapacity = 16
CtrlChanCapacity 控制通道（CtrlCh）默认容量 控制消息量级低（连接生命周期事件），16 足以吸收瞬时突发； 满时走 SendControl 的降级语义（KickOut/Close 直接断链），不阻塞投递方
const DefaultAdmissionCooldownLevels = 3
DefaultAdmissionCooldownLevels 过载降级所需的连续低水位周期数（防抖动）
const DefaultAdmissionEvalInterval = "500ms"
DefaultAdmissionEvalInterval 准入闸门评估周期（水位判定 + AIMD 调整）
const DefaultAdmissionHighWatermark = 8000
DefaultAdmissionHighWatermark 准入闸门默认高水位线（在途消息数） backlog = 业务入队数 - 已完成写出数；超过高水位触发过载升级（L++） 基准：单节点万级连接 × 每连接 SendChan 256 缓冲的合理在途量级
const DefaultAdmissionLowWatermark = 2000
DefaultAdmissionLowWatermark 准入闸门默认低水位线（在途消息数） 连续 3 个评估周期低于低水位触发过载降级（L--，防抖动）
const DefaultAggregatorBatchSize = 64
DefaultAggregatorBatchSize 消息聚合器单群组窗口攒批上限（条） 超限新消息直通降级（单发，性能降级不丢消息）；500ms 窗口 × 10条/s/人 = 5 条/窗口， 64 覆盖 6 倍突发；数组单帧推送后每连接帧率 = 窗口频率（内核友好）
const DefaultAggregatorDrainInterval = 500 * time.Millisecond
DefaultAggregatorDrainInterval 消息聚合器 drain 窗口节拍 每窗口 Flush 一次全部群组（每群组产出一条数组帧）；每连接帧率 = 1/该值， 弹幕端到端延迟上限 ≈ 窗口节拍 + 扇出耗时；与 go-config Aggregator.DrainInterval 默认同源
const DefaultAggregatorMaxGroups = 65536
DefaultAggregatorMaxGroups 消息聚合器群组数上限（并发活跃发言群组） 空群组在 Flush 换出空批时惰性删除；上限防群组风暴（恶意/爬虫建群）内存膨胀
const DefaultBroadcastShaperRate = 10000
DefaultBroadcastShaperRate 广播出向整形默认速率（条/秒） 每条广播消息消耗 1 个令牌（非每客户端）；洪峰时平滑扇出速率，填谷靠 AIMD 恢复
const DefaultCoalescerCapacity = 4096
DefaultCoalescerCapacity 高频合并器默认容量（同 key 并存的最大消息数）
const DefaultGRPCBatchMaxItems = 32
DefaultGRPCBatchMaxItems 跨节点 gRPC 微批单批累计上限（达到即触发立即 flush，优先于窗口）
const DefaultGRPCBatchWindow = 2 * time.Millisecond
DefaultGRPCBatchWindow 跨节点 gRPC 微批合帧窗口 窗口内发往同一节点的多消息合并为单次 BatchDispatch RPC，RPC 次数 O(消息数) → O(批次数)； 窗口越小排队延迟越低、越大合帧率越高；0 表示禁用微批（逐消息单发，延迟敏感场景）
const DefaultGroupInvalidationFlushInterval = 100 * time.Millisecond
DefaultGroupInvalidationFlushInterval 群拓扑失效广播聚合窗口 窗口内多次拓扑写（如上线风暴的注册入组）合并为单条批量广播，广播量 O(写次数) → O(群组数/窗口)
const DefaultGroupMemberCacheEntries = 1024
DefaultGroupMemberCacheEntries 群组成员拓扑缓存默认条目上限（LRU 容量）
const DefaultGroupMemberCacheMaxMembers = 10000
DefaultGroupMemberCacheMaxMembers 群组成员拓扑缓存单条目成员数预算默认上限 超出则该群组不入缓存：100w 成员大群单条可达数十 MB，缓存反而挤爆内存，回源保持两段 Pipeline
const DefaultGroupMemberCacheNegativeTTL = 5 * time.Second
DefaultGroupMemberCacheNegativeTTL 群组成员拓扑缓存负缓存（确认无实例条目）默认存活期 短于正缓存：压缩"解散后误投"边界窗口的同时，控制无效群组的重复回源频率
const DefaultGroupMemberCacheTTL = 30 * time.Second
DefaultGroupMemberCacheTTL 群组成员拓扑缓存默认存活期 群消息投递热路径 0 回源的一致性窗口：本地写路径即时逐出，跨节点写最多滞后一个 TTL
const DefaultMessageDeadline = "0s"
DefaultMessageDeadline 普通级消息默认过期时间上限（0=不过期） 入队前 deadline-aware 检查用；高频级由 latest-wins 合并天然去旧
const SlowConsumerConsecutiveThreshold = 3
SlowConsumerConsecutiveThreshold 慢消费者驱逐所需的连续超阈值次数
const SlowConsumerThresholdRatio = 0.9
SlowConsumerThresholdRatio 慢消费者判定的队列利用率阈值（BacklogRatio 超过即计一次）
Variables ¶
This section is empty.
Functions ¶
func NormalizeAppID ¶
NormalizeAppID 归一化 appID：空值兜底为 DefaultAppID appID 无广播语义（必填），任何入口的空 appID 都应归一化为默认值
func NormalizeGroupID ¶
NormalizeGroupID 归一化 groupID：空值兜底为 DefaultGroupID（P2P 场景补默认） 保证 Redis 队列 key 与 MySQL group_id 维度一致
func NormalizeNamespace ¶
NormalizeNamespace 归一化 namespace：空值兜底为 DefaultNamespace 注意：广播场景 namespace 故意留空表示全命名空间，调用方需按语义判断是否调用本函数
Types ¶
This section is empty.
Source Files