concurrency

README

concurrency

并发与流控原语——GoSafe safe-go/协程池/重试/键控闸门/令牌桶/滑动窗口统计/自适应熔断/CPU 自适应降载

🌐 项目主页：https://oekit.github.io/ · 名称由来：Open Easy Kit（开源 · 易用 · 工具集合） 🤖 AI Agent：本仓规范与硬规则见 AGENTS.md；机器可读索引见 llms.txt（接口签名以源码为准）。

安装

go get github.com/oekit/concurrency@v0.15.0

这个仓库做什么

concurrency 是并发与流控原语集：把 Go 并发开发里最容易出事的部分—— 裸 goroutine 的 panic、无界重试、无界并发、限流、并发去重——封装成开箱即用且经过生产验证的原语。

核心能力

包	做什么
async	GoSafe 系列 safe-go：GoSafe/GoSafeWithErr/GoWithContext/GoSafeWithContext/GoSafeWithErrChannel/RunSafe，以及带任务归属标签的 RunSafeLabeled/GoSafeLabeled（panic 日志 task=…，可按任务聚合告警）。panic 自动 recover + 可注入 panic 上报。全矩阵禁止裸 go func 的替代品
gopool	自适应协程池：惰性拉起 worker、队列满回退直接 go（不丢任务）、空闲按 WorkerMaxAge 老化退出、Close(ctx) 优雅排空。高频突发任务的并发数软上限（v0.2.0 吸收自 cloudwego/gopkg）
retry	Do(ctx, cfg, fn) 重试/轮询：次数、固定/线性/指数退避（Exponential + 可选 Jitter 抖动、MaxDelay 封顶）、可重试判定；子包 retry/httpx（零依赖，不引 net/http）：HTTP 可重试性判定 Retryable（429/5xx）/RetryableWithHeaders（403 头感知——GitHub 次级限流 Retry-After / 主限流耗尽 Remaining:0，v0.12.0 起）、RetryAfterHint 服务端退避建议提取、IsTransportRetryable ctx 门
loop	周期任务循环原语：ctx 感知 + 单轮 panic 收编 + 忙时丢 tick + 排水（Wait/Done）。过期清理/心跳/快照落盘等手搓循环的收编件
syncx	键控闸门（同一 key 串行）、扇出收集 FanIn/FanInErr（按 index 写槽免锁、panic 进槽 *async.PanicError）+ 受限并发变体 FanInLimit（n 槽 w worker，goroutine O(w) 防下游过载；v0.12.0 起）+ ctx 感知变体 FanInLimitCtx（取消后未启动项 fn 一次不调、整批一次遍历快速排空 Canceled、在飞项跑完落槽；v0.14.0 起）
ratelimit	令牌桶/滑动窗口限流 + 按 key 隔离的 KeyedLimiter（泛型 key、容量护栏 WithMaxEntries、空闲回收、AllowWithRetryAfter 不消耗探测、Replace 速率热更、令牌桶时钟可注入 WithTokenClock——假时钟确定性测试与 Retry-After 精确回填）+ 防爆破锁 Lockout（fail2ban 形态：滑窗失败计数达阈值 → 锁定 L 秒拒绝态（剩余秒可查）→ 成功 Reset 清零；时钟可注入、容量护栏 fail-open + OverCapHits 观测、锁定条目免于空闲回收；v0.11.0 起）——登录/API Key 防爆破与匿名接口防枚举的收编件
window	滑动窗口统计容器（v0.3.0 移植自 go-zero collection.RollingWindow）：泛型桶 BucketInterface + 默认 Bucket{Sum, Count}、惰性重置、Reduce 聚合、IgnoreCurrentBucket；时间源可注入 WithWindowClock——熔断/降载的数据源
breaker	自适应熔断 + 显式三态状态机（v0.3.0 移植自 go-zero googleBreaker；v0.9.0 起 closed/open/half-open；v0.10.0 起冷却/计数双扩展；v0.13.0 起熔断期收敛到探测级）：SRE 公式为 closed→open 触发器（40×250ms 窗口）；open 态 = forcePass 强制探活（缺省 1s）+ 冷却期满半开探测，其余一律拒绝——公式愈合不再恢复放行，状态与流量不再失配；冷却期（WithCooldown）与探测失联时限（WithProbeTimeout）可独立配置（缺省同值）；可选计数型触发 WithConsecutiveFailures（连续失败 n 次即熔断，缺省关闭，与速率型并联补足低 QPS 信号）；State()/State 枚举可观测出口；GenBreaker 代绑定扩展接口（陈旧探测回报作废、冷却不被开放期失败延长），panic 记失败后 re-panic；ErrCircuitOpen 全库规范哨兵（httpx/nns-endpoint 别名共用）；v0.15.0 起缺省值导出（DefaultWindow/DefaultBuckets/DefaultForcePass/DefaultProbeTimeout 供下游引用而非复制魔法数字）+ GetBreaker 同名异参冲突回调 WithBreakerConflictHandler（静默丢弃参数变可观测，同名共享语义不变）——下游保护的执行件
shedding	CPU 自适应降载（v0.3.0 移植自 go-zero adaptiveshedder）：maxPass×minRt 的 Little's Law 并发上限、CPU 过载因子夹 [0.1,1]、avgFlying 滞后 EMA、1s 冷却期；CPU 采样纯标准库（/proc/stat + cgroup v1/v2 配额感知），非 linux 自动禁用全放行；ErrServiceOverloaded 哨兵——本机过载保护的入口件
singleflight	并发去重（同 key 合并为一次调用）
group	并发分组编排
progress	多阶段进度追踪

快速使用

import (
    "github.com/oekit/concurrency/async"
    "github.com/oekit/concurrency/gopool"
    "github.com/oekit/concurrency/retry"
)

// 替代裸 go func：panic 被 recover，可注入 panic 上报
async.GoSafe(func() { serve() })

// 高频突发任务走池：worker 数软上限，panic 汇入 logx
gopool.SetPanicHandler(func(ctx context.Context, r any, stack []byte) {
    logx.Error("gopool panic", "error", r, "stack", string(stack))
})
gopool.Go(func() { process(item) })

p := gopool.NewPool("ingest", gopool.PoolOption{MaxIdleWorkers: 64})
p.CtxGo(ctx, func() { handle(req) })
defer p.Close(ctx) // 优雅排空

// 带重试的调用
err := retry.Do(ctx, retry.Config{}, func(attempt int) error {
    return callDownstream()
})

边界

• 需要日志记录 panic → 配合 logx 的 SetPanicHandler
• 需要进程内缓存/去重合并的高级组合 → data
• 本仓为 L0 基础件：零矩阵内依赖（第三方仅 golang.org/x/time）

矩阵总览（24 活跃模块，自动生成）

模块	内容	矩阵内依赖
pkg	微工具集 20 合 1（errors/bloomx/contextx/container/stringx/slicex/enumx/convert/encoding/jsonrepair/httpjson/mathx/pathx/pagination/ptrx/timex/cache/bufiox/strmap/singleflighttest；v0.10.0 起 uidgen/validator 拆至 kitx）；errors（v0.12.0 起）New/As/Is/Unwrap 与 stdlib 同型透传——下游哨兵/As 判定单 import 即可，类型同一性红线可完整执行；cache（v0.4.0 起）含缓存接口 CacheAside + BatchGetter 批量能力（MGet）+ LocalCache/SingleFlightCache + cachetest 契约（Run 真实时间 + RunWithClock 假时钟确定性 TTL 边界）+ Checker；LocalCache 时钟可注入（LocalConfig.Now——TTL/NullTTL 全路径确定性测试，v0.13.0 起）；container（v0.9.0 起，收编原 collectionx）泛型容器 Set/Ring/Queue/SafeMap + Map（sync.Map 背书）/Slice（并发安全）；mathx/jsonrepair（v0.11.0）Unstable 单边向上抖动 Upward / 宽松解析 UnmarshalLenient；timex/stringx（v0.7.0 起）时间段边界 BeginningOf/EndOf 七对（分/时/日/周/月/季/年，周起始显式参数）+ trie 多模式替换器 Replacer（最长匹配）/ NewMask 敏感词遮罩；singleflighttest（v0.8.0 起）singleflight 共享契约测试套件（internal 与 concurrency 双侧引用）	—
concurrency	并发与流控原语（async/gopool/group/singleflight/progress/syncx/ratelimit/retry）+ window 滑动窗口 / breaker 自适应熔断（规范哨兵 ErrCircuitOpen）/ shedding CPU 自适应降载 / batch 攒批执行器（满条数/满字节/窗口去重）/ timewheel 单级时间轮；v0.5.0 起 retry 指数退避+抖动（MaxDelay 封顶/溢出饱和）、loop 周期原语（忙时丢 tick/单轮 panic 收编/FirstDelay 可打断）、async labeled RunSafe（panic 按任务标签上报）、syncx.FanInErr 逐槽错误（panic 槽显式标记）、KeyedLimiter 增强（容量护栏/RetryAfter/速率热更）并接入 pkg/singleflighttest 契约测试；v0.8.0 起 singleflight DoShared 折叠可观测（Result.Waiters）、async panic 统一收编 typed *PanicError（errors.As 可辨、携带栈）+ 实例级 Runner panic 路由、retry DelayHint（服务端 Retry-After 建议优先）+ JitterRatio 比例抖动 + retry/httpx Retryable 可重试性判定；v0.9.0 起 breaker 显式三态状态机 closed/open/half-open——冷却（WithProbeTimeout 缺省 1m）期满首个放行即半开探测、探测成功关闸清窗/失败重开、失联超时自动回收 + AbandonGen 显式放弃，GenBreaker 代绑定（AllowGen/SuccessGen/FailureGen/AbandonGen：代仅在探测放行自增、陈旧代回报整体作废、开放期失败不后移冷却）；v0.10.0 起 WithCooldown 独立业务冷却期（缺省回落 probeTimeout）+ WithConsecutiveFailures 连续失败计数触发（与速率型并联，补低 QPS 信号，对齐 Envoy consecutive_5xx）；v0.11.0 起 ratelimit Lockout 防爆破锁（fail2ban 形态：滑窗失败计数→阈值锁定拒绝 LockDuration→成功 Reset 清零/到期自解，CheckLocked 返回剩余时长）；v0.12.0 起 retry/httpx RetryableWithHeaders（403 + Retry-After/X-RateLimit-Remaining 头感知可重试判定，HeaderSource 零依赖抽象）、syncx FanInLimit 受限并发扇出（固定 worker 防下游过载）+ FanInLimitCtx（v0.14.0，ctx 感知：ctx 已取消未启动项 fn 一次不调、剩余槽快速排空 Canceled、在飞项照常落槽）、ratelimit WithTokenClock 时钟注入；v0.13.0 起 breaker 熔断期收敛到探测级（forcePass 强制探活 + 冷却期满半开探测，其余拒绝——SRE 公式退役为 closed→open 触发器，WithConsecutiveFailures 触发后流量真停）+ State()/State 枚举可观测出口	pkg
logx	统一日志门面（多后端可替换 + caller 归属；Sink 已迁嵌套模块 logx/sink，根包纯 stdlib）；WithFilter 脱敏/丢弃包装（FilterKey 命中键替换 ***/FilterFunc 丢整条，子 logger 保持规则）、Slogger/SlogHandler 正向桥（三方 slog 直接消费 logx 生态）、TraceHandler 任意 slog.Handler 自动注入 trace_id、NewAuditLogger 审计留痕（级别锁 Info，不受 LOG_LEVEL 降级）、LevelEnabler 热路径提前判级、ParseLogLevel 返回 (Level, error) + ParseLogLevelOr 配错退默认（v0.7.0）；优雅关停正身在 core/lifecycle.Manager（logx/shutdown 仅余 Deprecated 别名）；桥接子包 hlog/hertzlog/kitexlog 为嵌套模块按需引入	—
core	应用基建件——governance 治理 schema、config 配置加载（LoadBootstrap/LoadDotEnv/Get* 系、default/env/range/options tag 校验、OverlaySource 多源叠加热更、ApplyEnvOverlay env 优先 12-factor 形态）、transport 协议无关传输上下文（Transporter/Header/Server·Client ctx 存取，仅标准库）、chain 中间件链（Handler/Middleware/Chain/Recovery/Timeout，与 nns-endpoint.Endpoint 同形）、lifecycle 契约 + Manager 优雅关停（自 logx/shutdown 迁入，日志 *slog.Logger——core 不再依赖 logx）、network IP 工具、version	—
kitx	标识与校验——uidgen（Snowflake 全局单例+Extract 元数据、手写 RFC 4122 v4 UUID 零第三方依赖、RandomHex/RandomString 拒绝采样随机串）+ validator（go-playground/validator v10 接口化门面：struct tag 校验/自定义规则注册/ValidationError Unwrap 为 BizError 400 对接 middleware.Fail）+ hash（v0.2.0 起非密码学哈希助手 Md5Hex/Md5Bytes——缓存键/幂等键/短唯一 code，格式稳定承诺，pkg 2026-09-15 治理移除弱哈希后 kitx 侧收编 pkg#10），自 pkg v0.10.0 拆出	pkg
metrics	Prometheus 门面 + 弹性指标族	core
tracing	OpenTelemetry 追踪 + trace_id 真相源	logx
registry	注册发现核心 + Nacos 实现 + Nacos 配置源 + sdbridge	core、logx
data	数据访问门面——复刻 ekit data/ 能力面：cache/rediscache/crud/distlock/gormx/redisx/timertask/cachetest 八子包 re-export（类型同一，实现住 pkg 与各子仓）+ cached 缓存读写编排（写后失效/事务提交后失效/查询缓存版本号失效/GetByIDs 批量点读 MGet 快路径/bloom 防穿透）+ twolevel 两级缓存与跨实例失效广播（v0.7.0 起本仓唯二非 re-export 实现）；all/ 聚合模块已废弃 retract	concurrency、gormx、logx、pkg、redisx、timertask
gormx	SQL/GORM 全家——连接池增强、框架无关 CRUD Service、仓储（原 oekit/gorm，v0.3.0 更名）	logx、pkg
redisx	Redis 全家——客户端封装（根包）、分布式缓存 cache/、分布式锁 distlock（Locker 同形可互换；Renew 手动续期（false=锁丢失，不进 Locker 接口保 etcdx 互换）+ WithAutoRenew 覆盖 TryLock 自动续期（v0.8.0 feat!：此前组合不续期）；Semaphore ZSET 槽位信号量（v0.8.0：Acquire 同 identifier 幂等刷新 + Lua 内原子清过期槽崩溃自愈、Renew 仅未过期槽可续、Cleanup 返条数、无 Redis 降级 fail-fast））、分布式限流 ratelimit（Lua 三态 + 故障本地兜底）	concurrency、logx、pkg
etcdx	etcd 全家——客户端封装（根包：生产默认值/Health 探活/Close(ctx) 幂等）、registry 注册发现实现（SPI 对接 registry/nacos 链路：Lease KeepAlive 注册 + 丢约指数退避自动重注册、prefix Watch 订阅推送、ConfigStore KV 配置监听）、distlock 分布式锁（Session+concurrency.Mutex 公平排队，接口与 redisx/distlock.Locker 同形可互换，可选无 etcd 降级放行）	concurrency、core、logx、registry
httpx	HTTP 客户端 + 负载均衡——服务发现/熔断（规范哨兵 ErrCircuitOpen）/重试/指标/OTel 透传；loadbalance Selector 形态（RoundRobin/Random/Weighted/一致性哈希权重感知虚拟副本/p2c 自适应——EWMA 经 DoneFunc 回写建立、Err 计 1s 惩罚；WithFilter 按元数据过滤；v0.4.0 起 Balancer 全家族删除无兼容路径）；codec 注册制编解码器（json 内置 + form 表单，DoCodec 请求按 codec 序列化、响应按 Content-Type 反查回退请求 codec）；v0.6.0 起 net/http 桥接层 NewRoundTripper/StdClient——存量标准库外呼一行 Transport 接入熔断/重试/指标/链路（重试缺省关显式开、非 2xx 非错误、hop-by-hop 隔离，#8）	concurrency、core、logx、metrics、registry、tracing
network	轻量网络客户端——WebSocket/NATS/MQ 抽象、连接与流工具	concurrency、logx、tracing
timertask	分片定时任务（FNV-1a、心跳续约）；v0.1.5 起可选可靠投递 DeliveryAtLeastOnce（租约 + Ack + 可见性超时；过期租约回扫重投/死信、停机 best-effort 收租，v0.1.7 接入生命周期真正生效）	concurrency、logx
middleware	Hertz 标准中间件栈（模块根 mw，双层目录已收平）+ contrib 桥接 + hmw + SheddingMiddleware 自适应降载 + chainmw 子包（transport 感知框架无关中间件，基于 core/chain+transport：Recovery 带 panic 隔离上报钩子 WithRecoveryReporter、AccessLog skip+redact+自定义字段、MetadataPropagate——kitex 经 kitex/chainmw.ToKitex 复用同一实现，根包 Recovery/AccessLog 已薄壳化复用 chainmw 内核、下游 handler 可经 transport.FromServerContext 读协议无关传输信息）；v0.6.0 起 accesslog 凭证路径脱敏（WithAccessLogRedactPathPrefixes）、ratelimit 默认 KeyFunc 去端口（连接桶→地址桶）	concurrency、core、logx、metrics、pkg、registry、tracing
k8s	Kubernetes 客户端封装——RESTConfig/Clientset/DynamicClient 构建（显式 kubeconfig → in-cluster 自动 → KUBECONFIG/~/.kube/config 逐级回退，QPS/Burst 限流默认 50/100）+ leaderelection 子包 Lease 选主简化封装（OnStartedLeading/OnStoppedLeading/OnNewLeader 回调，主备单活，仅要求 Lease CRUD 权限）	logx
nns	NNS 服务治理客户端——provider 无关发现/配置/实例缓存	concurrency、core、logx、registry
nns-endpoint	NNS 端点工厂——per-service 熔断、换实例重试、gRPC 池	concurrency、core、httpx、logx、metrics、nns、registry
bootstrap	应用生命周期引导——New(WithServiceName/WithShutdownTimeout/WithBeforeServe) + Run(fn) + healthz；App.Ready/ReadyChan/IsReady 就绪门（幂等并发安全）——嵌套 bootstrap/nacos 自 v0.3.0 起 NNS 注册延迟到 Ready 之后（server 就绪 → userFn 触发 Ready → 才进注册中心）、关停序 nns 反注册先于 server 关闭；Metrics/Tracing 在嵌套模块 bootstrap/obs	concurrency、logx
hertz	Hertz 运行时集成（模块根扁平化）——日志桥接、生命周期、SSE/health/metrics、适配器、OTel、crudh/validatorh（基于 kitx/validator）/versionh（原 handler 微库收编）；RunServer 变参就绪门 WithOnReady（全部 HostPort TCP 探活可建连后回调，探活超时按启动失败优雅关机；缺省超时 5s 经 WithReadyProbeTimeout 调整/WithReadyAddr 探活地址），配合 bootstrap Ready 实现 NNS 延迟注册；transportx（hertz→core/transport 同构适配器）+ chainmw 桥接	bootstrap、concurrency、core、gormx、kitx、logx、metrics、middleware、nns、pkg、registry、tracing
kitex	Kitex 生态——日志桥接、治理热更、生命周期、BizError 桥接、kitexotel、istio（xDS 动态熔断，原 istio 微库收编）；RunServer 变参就绪门（WithOnReady/WithReadyAddr/WithReadyProbeTimeout）+ chainmw.ToKitex（core/chain.Middleware → kitex 中间件，与 hertz 共享 middleware/chainmw 实现）+ transportx	bootstrap、concurrency、core、logx、metrics、nns、pkg、registry
workflow	组合式流程编排——串行/并行/异步/条件分支 + Hook AOP	concurrency、logx
kitex-examples	Kitex echo 示例——client/server + IDL + 治理配置	bootstrap、concurrency、core、kitex、logx、metrics、nns、pkg、registry、tracing

依赖严格自底向上；微库已合并为 pkg，旧微库仓已删除。

本仓在矩阵中的位置与依赖见上表「矩阵内依赖」列。历史沿革：源自 ekit 单体库 （git.enjoye.top/enjoydream/ekit v0.34.0，冻结维护），2026-10 拆分为独立 module。

License

MIT — 见 LICENSE