新审计SDK架构解析

做迁移，第一件事不是写代码，而是看懂新SDK到底长什么样。我的经验是，很多人拿着文档就开干，结果跑到一半发现模块依赖搞错了，推倒重来。嗯，先停一下，我们把新架构的骨架摸清楚。

整体架构：三层一总线

新审计SDK抛弃了老版本那种“大泥球”式的单模块结构。我接手第一个迁移项目时，看到新架构的第一反应是——清爽。整体分为三层，再加一条内部事件总线。

• 采集层：负责埋点事件的生命周期管理。从业务层接收原始数据，做格式校验和脱敏。
• 缓冲层：暂存经过初步处理的事件，做去重、聚合、压缩。
• 上报层：与后端服务器通信，处理网络策略和重试逻辑。

三层之间不直接调用，全部通过内部事件总线通信。这样做的好处是——

为什么会这样设计？说白了，老SDK最大的痛是耦合。采集逻辑和上报逻辑混在一起，想改个重试策略都得牵一发动全身。新架构用总线解耦，各层只关心自己的接口协议。

核心模块拆解

把三层再往下拆，每个层里都有固定模块和可选插件。我习惯先画一个模块地图，再动手改代码。

层级	必选模块	可选插件
采集层	事件接收器、格式校验器、脱敏器	上下文注入器、采样过滤器
缓冲层	去重器、聚合器、内存队列	磁盘暂存、压缩适配器
上报层	网络客户端、重试控制器、响应处理器	域名动态切换、灰度上报策略

数据流走向

数据流你想想看，其实就三步：收集、缓冲、消费。但新SDK在每一步都加了钩子。

1. 业务侧调用：采集层收到事件后，先做格式校验。格式不对的直接丢进错误回调，不走主线。
2. 缓冲层排队：合法事件进入环形缓冲区，按优先级排序。紧急事件插队到前面——我记得在游戏项目中，登录事件必须优先上报，不然用户流失监测会延迟。
3. 上报层发送：聚合器把同类事件合并后再发出。网络失败时走指数退避，最大重试三次。

这里有一个很多人踩过的坑——

关键组件详解

挑三个最重要的组件说，它们直接关系到迁移成败。

1. 事件总线

不是真的消息队列，而是一个内存中的发布-订阅通道。每个模块注册自己的主题，总线负责分发。我建议你在做迁移时，先写一个总线监听器打印所有事件流——肉眼过一遍，比读文档管用。

2. 聚合器

把相同类型的多个事件合并成一个批次上报。比如用户连续点击三次按钮，聚合器只上报一条，附带count字段。这样能大幅减少网络请求数。聚合窗口默认500ms，可调。

// 聚合器配置示例
val aggregatorConfig = AggregatorConfig(
  windowMs = 500,          // 聚合时间窗口
  maxBatchSize = 50,       // 单批最大条数
  mergeKey = "eventType"   // 按事件类型合并
)

3. 重试控制器

新SDK不再用简单的固定间隔重试，改用指数退避加随机抖动。第一次失败等待1秒，第二次2秒，第三次4秒，最多等16秒。随机抖动避免同一时间大量请求重试打崩服务器。

模块间的依赖关系

说了这么多，你可能会觉得模块挺多，依赖复杂。其实归纳下来就这么几条硬约束——

• 采集层不依赖缓冲层和上报层：它只向总线写事件，不做同步等待。
• 缓冲层只能读总线，不能直接调用上报层。
• 上报层是纯消费者，不影响数据生产。

这个设计带来的直接好处是：你可以先跑通采集层和缓冲层，确认埋点数据能正确入队，再连上报层。分阶段验证，出问题好定位。