📚 课程目录第4章数据采集层

数据采集层：前端埋点、后端日志、SDK设计原则

数据采集是整个用户行为流的起点。说白了，你后面所有的分析、画像、推荐，都依赖这一层的数据质量。我见过太多项目，算法模型建得漂漂亮亮，结果一上线发现数据采集漏了关键字段——嗯，那种感觉就像盖好了大楼才发现地基没打牢。

这一章我们聚焦三个核心问题：前端怎么埋？后端怎么记？SDK怎么设计才能让业务方用得顺手？

前端埋点：三种主流方案

前端埋点，说白了就是在用户交互的地方「安插眼线」。我个人习惯把方案分成三类，各有各的适用场景。

方案	原理	优点	缺点	适用场景
代码埋点	在事件回调中手动调用上报接口	精确、灵活、可携带任意上下文	侵入性强、维护成本高	核心转化路径、支付、注册
可视化埋点	通过圈选工具配置，自动生成埋点代码	无需开发介入，运营可自助	无法采集复杂交互、依赖页面结构	活动页、落地页、A/B测试
无埋点（全量采集）	自动监听所有DOM事件，全量上报	零侵入、不漏采	数据量大、噪音多、后端压力大	用户行为探索、热力图、漏斗分析

我的建议：不要迷信任何一种方案。我在项目中通常采用「代码埋点 + 无埋点」混合策略——核心路径用代码埋点保证精度，探索性分析用无埋点兜底。可视化埋点更适合运营团队临时加需求，但别让它成为主力。

后端日志：结构化与采样策略

后端日志跟前端埋点不同。前端关注「谁点了什么」，后端关注「系统发生了什么」。我见过很多团队把后端日志写成「散文」——自由格式、随意换行、字段名靠猜。这其实是个大坑。

我个人习惯要求后端日志必须满足三个条件：

结构化：统一使用JSON格式，字段名遵循snake_case
可追溯：每条日志携带全局traceId，串联上下游
可采样：支持按用户ID、按概率、按接口维度动态降级

举个例子，一个标准的后端行为日志长这样：

{
  "traceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "timestamp": 1712563200000,
  "event": "order.create",
  "userId": "u_10086",
  "deviceId": "d_abc123",
  "properties": {
    "orderId": "ord_202404081200",
    "amount": 299.00,
    "paymentMethod": "wechat"
  },
  "env": {
    "ip": "192.168.1.1",
    "userAgent": "Mozilla/5.0 ...",
    "referer": "https://m.xxx.com/cart"
  }
}

我曾经踩过的坑：有一次线上排查问题，发现某条日志的timestamp字段是字符串格式，另一条是数字格式，还有一条干脆没传。结果数据管道解析报错，整整丢了3小时的数据。从那以后，我强制所有日志字段必须有schema校验，上线前跑一遍「日志合规检查」。

采样策略：什么时候全量，什么时候抽检？

你想想看，如果每个用户每次点击都上报，日活1000万的产品一天能产生几十亿条事件。后端扛不住，存储也扛不住。所以采样是必须的。

我常用的采样策略分三级：

级别	采样率	适用事件	说明
核心事件	100%	支付、注册、下单、登录	涉及收入和安全，必须全量
行为事件	10% ~ 50%	浏览、点击、滑动、搜索	按用户ID哈希采样，保证同一用户行为完整
性能事件	1% ~ 5%	页面加载、API耗时、JS错误	按时间窗口采样，关注趋势而非个体

一个小技巧：采样时尽量按用户ID取模，而不是随机数。这样同一个用户的行为是完整的，分析漏斗和留存时不会出现「断片」。

SDK设计原则：让业务方「无感」接入

SDK是数据采集的「最后一公里」。设计得好，业务方一行代码就能接入；设计得烂，业务方得看三天文档还跑不通。我参与过三个SDK从零到一的设计，总结下来有五个核心原则。

原则一：最小侵入

SDK不应该影响业务代码的正常执行。我见过有些SDK在初始化时直接修改了全局的XMLHttpRequest，导致业务方的请求拦截器失效。嗯，这其实很危险。

正确的做法是：

使用观察者模式或AOP，不要重写原生方法
所有上报操作异步执行，不阻塞主线程
提供「安全模式」开关，异常时自动降级

原则二：离线缓存与重试

用户可能在电梯里、地铁上，网络随时可能断开。SDK必须内置离线缓存机制。

// 伪代码示例：离线缓存逻辑
class EventQueue {
  constructor() {
    this.queue = [];
    this.maxRetries = 3;
    this.storageKey = 'sdk_event_queue';
  }

  enqueue(event) {
    this.queue.push(event);
    this.persistToLocalStorage();
    this.flush();
  }

  async flush() {
    if (navigator.onLine === false) return;
    const batch = this.queue.splice(0, 20);
    try {
      await this.sendBatch(batch);
    } catch (e) {
      // 失败后放回队列，等待下次重试
      this.queue.unshift(...batch);
      this.persistToLocalStorage();
    }
  }

  persistToLocalStorage() {
    localStorage.setItem(this.storageKey, JSON.stringify(this.queue));
  }
}

原则三：配置驱动

不要硬编码任何行为。采样率、上报地址、事件开关、超时时间，全部通过远端配置下发。这样你可以在不发版的情况下动态调整。

我习惯的做法是：SDK启动时先请求一份配置，然后缓存到本地。后续每次启动优先使用缓存，同时异步拉取最新配置。这样即使配置中心挂了，SDK也能正常工作。

原则四：性能兜底

SDK不能成为性能瓶颈。有几个硬性指标我建议你写在设计文档里：

单次事件序列化耗时 < 1ms
内存占用峰值 < 5MB
批量上报间隔 500ms ~ 5s（可配置）
单次上报条数不超过 50 条

原则五：可观测性

SDK自己也要能被监控。我见过很多SDK出了问题，业务方完全不知道——数据丢了也没人发现。所以SDK必须暴露内部状态：

当前队列长度
上报成功率
最近一次错误
配置版本号

一句话总结：好的SDK，业务方接入后几乎感觉不到它的存在。只有当数据报表出问题时，他们才会想起「哦，原来我们有个SDK」。

数据采集层整体架构

下面这张图展示了数据采集层的完整链路。你可以看到前端SDK、后端日志、以及它们如何汇聚到数据管道中。

避坑指南：我踩过的三个坑

做数据采集这些年，我踩过不少坑。挑三个印象最深的分享给你：

坑一：事件命名混乱

我曾经接手过一个项目，同一个「点击购买」事件，iOS叫buy_click，Android叫click_buy，Web叫purchase.click。结果数据对不上，分析团队天天吵架。后来我强制要求所有端使用同一套事件字典，上线前必须过「事件命名评审」。

坑二：时间戳不一致

前端上报用客户端时间，后端日志用服务器时间。用户手机时间不准，导致事件顺序错乱。解决方案：统一使用服务器时间戳，前端只上报事件发生时的「客户端偏移量」，由后端校准。

坑三：SDK版本管理缺失

有一次线上问题排查，发现部分用户的数据格式跟其他人不一样。查了半天，原来是某个业务方私自升级了SDK，但没通知数据团队。从那以后，我要求每个事件必须携带SDK版本号，数据管道根据版本号做兼容处理。

小结

数据采集层看起来简单，但细节决定成败。前端埋点选型要结合业务场景，后端日志必须结构化，SDK设计要以「业务方无感」为目标。记住一句话：数据采集的质量，决定了你后续所有分析的天花板。