golang开发-定时与防抖工具包(dt)设计与实现

定时与防抖工具包core/pkg/dt设计与实现1. 包做什么dtdelay / timer封装与时间窗口相关的常用能力减少业务侧手写Timer/Ticker/ 竞态处理。API作用SetTimeout延迟执行一次支持取消SetInterval按固定间隔重复执行直到取消Debounce每次调用将执行时刻推迟到nowinterval全局轮询到点后执行一次并Remove keyTrailingDebounce同一 key 连续触发时取消上次未到期任务仅在「最后一次触发」后再静默duration执行尾部防抖Throttle同一 key 在滑动duration窗口内仅首次调用立即执行窗口内其余丢弃前缘节流ThrottleFixedGridTrailing从首次调用建立epoch按固定period对齐分槽每槽右边界执行该槽内最后一次call空闲时Remove key并带周期清理术语口语里「节流 / 防抖」常混用。本包中首触限频用Throttle末触合并用TrailingDebounce或Debounce对齐时间轴、按槽尾执行用ThrottleFixedGridTrailing。2. 各函数语义与实现要点2.1SetTimeout到期执行f一次返回cancel提前调用则停止Timer并在必要时 drain减轻计时器残留。2.2SetIntervalTicker循环执行f直至cancel首帧在第一个interval之后与常见setInterval一致非立即首帧。2.3Debounce(uniqueId, interval, call)debounceMaps存ExecTime now intervaldebounceRunner约10ms步进扫描到点go call()并Remove(uniqueId)。空槽不执行每次调用都会重置截止时间。2.4TrailingDebounce(uniqueId, duration, call)trailingDebounceMaps存*throttledTypeCancelCall每次调用取消旧SetTimeout再排新的duration。定时器回调用entry 指针与 map 内现条目比对避免被替换后旧定时器误执行新回调。2.5Throttle(uniqueId, duration, call)每 keythrottleEntrysync.MutexlastExecnow.Sub(lastExec) duration则丢弃。与TrailingDebounce对照节流保首次尾部防抖保末次。2.6ThrottleFixedGridTrailing(uniqueId, period, call)epoch该 key 首次成功入队时的now之后槽为[epochk·period, epoch(k1)·period)。同槽多次调用只更新pendingCall在槽右边界epoch(k1)·period由AfterFunc触发onSlotTimerFire锁内 flush锁外go call()。跨槽若新调用槽号大于当前pendingSlot且仍有未执行 pending先Stop 定时器再同步补跑上一槽最后一次再为当前槽重排期。map 清理tryRemoveFixedGridEntryIfIdle当pendingCallnil且timernil、且 map 中仍指向本 entry 时RemoveonSlotTimerFire末尾会调用另有10s一次的throttleFixedGridIdleRunner兜底。并发ThrottleFixedGridTrailing在持entry.mu后再次Get校验ventry不匹配则解锁重试避免已删键仍操作entry。键被移除后同一uniqueId再次调用会重新建立 epoch新时间轴。通俗的说10.2s内我执行了100次我传入了500毫秒为一个执行周期实际上只会触发执行21次等于说无论我调用多少次只会在开始时间开始计时500毫秒为一个周期执行这个周期内的最后一次调用尾部不足500ms的内容会在10.5s执行总共执行了21次。3. 时序示意3.1TrailingDebounce尾部防抖TimertrailingDebounceMaps调用方TimertrailingDebounceMaps调用方TrailingDebounce(k,d,f1)启动 d 后回调TrailingDebounce(k,d,f2)取消上一 Timer重新 d到期且 entry 仍为当前指针仅执行 f23.2Throttle前缘节流throttleMaps调用方throttleMaps调用方Throttle(k,d,f)go f()窗口首次Throttle(k,d,f)窗内丢弃3.3Debounce防抖debounceRunnerdebounceMaps调用方debounceRunnerdebounceMaps调用方Debounce(k,i,f) 推迟 ExecTimetick ExecTimego f()Remove(k)3.4ThrottleFixedGridTrailing固定栅格尾部节流AfterFuncthrottleFixedGridMaps调用方AfterFuncthrottleFixedGridMaps调用方本槽内多次更新 pendingCall槽右边界 onSlotTimerFirego call()空闲则 Remove(k)4. 并发与依赖Mapgithub.com/orcaman/concurrent-map。Throttlesync.Mutex每 entry。TrailingDebounce/ThrottleFixedGridTrailingentry 级互斥 指针或 map 二次校验。回调多为go call()异步执行业务回调内需自行保证并发安全。5. 使用建议SetTimeout、SetInterval与javascript类似场景推荐 API延迟执行SetTimeout固定周期执行SetInterval停止调用后后执行最后一次调用TrailingDebounce停止调用后后执行第一次调用Throttle周期性执行周期内最后一次调用ThrottleFixedGridTrailing依赖全局10ms粒度执行Debounce同一业务 key 避免混用多套语义不同的 API。6. 测试说明core/pkg/dt/dt_test.go测试函数覆盖点TestSetTimeout_CancelSkipsCallback取消后无回调TestSetInterval_FiresMultipleTimesBeforeCancel周期触发至少 2 次TestDebounce_ResetsDeadlineOnRepeatCall推迟截止、最终 1 次TestTrailingDebounce_MergesToSingleExecution末触合并TestTrailingDebounce_ReplacedScheduleDoesNotFireStaleentry 指针竞态TestThrottle_LeadingEdgeOncePerWindow前缘节流 窗后可再触发TestThrottleFixedGridTrailing_SlotCountMatchesTimeline约 102ms/50ms → 3 次TestThrottleFixedGridTrailing_RemovesIdleKeyFromMap执行后 map 无 keyTestThrottleFixedGridTrailing_LastCallWinsInSlot同槽闭包覆盖运行gotest./core/pkg/dt/...-race7. 小结dt将定时、防抖、节流与固定栅格槽尾执行统一到少数 APITrailingDebounce与Throttle解决多数末触 / 首触问题ThrottleFixedGridTrailing适合整段对齐周期、且需控制 map 生长的长连接/报表类场景Debounce适合能接受全局轮询步长的轻量推迟执行。