4. 自动采集与手动埋点：声明式埋点、命令式埋点、混合模式的最佳实践

埋点怎么落地？这是每个团队都会吵起来的问题。

有人觉得全自动采集最省事，有人坚持手动调用最可控。我经历过几个项目，从一端走到另一端，最后发现——没有银弹，只有合适的混合策略。

这一章，我把三种模式掰开揉碎讲清楚。你听完就能判断：什么场景用声明式，什么场景必须命令式，怎么搭出最稳的混合方案。

4.1 三种埋点模式的核心差异

先看一张对比表，心里有个底。

维度	声明式（data-*）	命令式（API）	自动采集
触发方式	HTML 属性声明	JS 代码调用	框架/浏览器事件拦截
埋点成本	低，模板加属性即可	中，需写调用逻辑	极低，几乎零侵入
灵活性	中，只能绑定标准事件	高，可携带任意上下文	低，只能采集通用数据
可维护性	高，属性与视图绑定	中，散落在业务代码中	高，集中配置
适用场景	按钮点击、链接跳转	异步操作、复杂业务逻辑	PV、页面停留、基础交互

说白了，声明式是“贴标签”，命令式是“打电话”，自动采集是“装监控”。各有各的用处，别指望一种模式打天下。

4.2 声明式埋点：data-* 属性的正确用法

我个人最喜欢声明式埋点。为什么？因为它把埋点和视图绑在一起，前端重构时不容易漏掉。

4.2.1 标准属性约定

先定一套命名规范。我习惯这样设计：

<button
  data-track="click"
  data-track-category="user"
  data-track-action="login"
  data-track-label="wechat"
  data-track-value="1"
>
  登录
</button>

这里每个属性的含义：

• data-track：事件类型，click / submit / scroll
• data-track-category：业务分类，user / product / order
• data-track-action：具体动作，login / addCart / pay
• data-track-label：额外标识，wechat / alipay
• data-track-value：数值，比如金额、数量

4.2.2 自动绑定引擎

声明式埋点需要一段引擎代码来解析属性。我写过一个轻量版本，核心逻辑就这些：

class DeclarativeTracker {
  constructor() {
    this.init();
  }

  init() {
    document.addEventListener('click', (e) => {
      const target = e.target.closest('[data-track]');
      if (!target) return;

      const eventData = {
        type: target.dataset.track,
        category: target.dataset.trackCategory,
        action: target.dataset.trackAction,
        label: target.dataset.trackLabel,
        value: target.dataset.trackValue,
        url: location.href,
        timestamp: Date.now()
      };

      this.send(eventData);
    });
  }

  send(data) {
    // 使用 sendBeacon 或 Image 打点
    navigator.sendBeacon?.('/track', JSON.stringify(data));
  }
}

new DeclarativeTracker();

这段代码做了几件事：

• 事件委托到 document，不用每个按钮单独绑定
• 用 closest 向上查找，支持嵌套结构
• 自动收集页面 URL 和时间戳
• 用 sendBeacon 发送，页面关闭也不丢数据

4.3 命令式埋点：API 调用的设计原则

声明式搞不定的场景，就得靠命令式。比如：

• 异步请求成功/失败
• 表单校验通过/不通过
• 视频播放进度
• 自定义业务逻辑的中间状态

4.3.1 统一的 API 入口

我建议只暴露一个全局方法：

// 全局埋点 API
window.$track = function(eventName, payload = {}) {
  const baseData = {
    event: eventName,
    page: location.pathname,
    timestamp: Date.now(),
    sessionId: getSessionId(),
    userId: getUserId()
  };

  const fullData = { ...baseData, ...payload };

  // 加入发送队列
  TrackerQueue.enqueue(fullData);
};

// 使用示例
$track('order_submit', {
  orderId: 'ORD20241001',
  amount: 299.00,
  paymentMethod: 'wechat'
});

为什么只暴露一个方法？因为：

• 团队不用记多个 API，降低心智负担
• 统一处理公共字段，不会漏掉 sessionId 和 userId
• 方便做队列和批量发送

4.3.2 异步场景的埋点陷阱

我在项目中遇到过一个问题：接口返回后埋点，但用户已经跳转了页面。数据发不出去。

解决方案是：在请求发起时就生成埋点 ID，请求完成后再关联。

async function submitOrder(data) {
  const trackId = generateTrackId();
  
  // 先发一个“请求中”事件
  $track('order_submit_pending', { trackId, ...data });

  try {
    const result = await api.createOrder(data);
    
    // 成功后关联之前的 trackId
    $track('order_submit_success', { trackId, orderId: result.id });
  } catch (err) {
    $track('order_submit_fail', { trackId, error: err.message });
  }
}

这样做的好处是：即使页面跳转，pending 事件已经发出。后续的成功/失败事件即使丢失，也能通过 pending 事件知道“有人尝试下单”。

4.4 混合模式：怎么搭才不打架？

你想想看，一个页面里既有声明式埋点，又有命令式调用，还有自动采集。它们会不会冲突？

会的。我曾经在一个项目里看到同一个点击事件被上报了三次——自动采集一次，声明式一次，业务代码里又手动调了一次。

4.4.1 分层策略

我现在的做法是三层分离：

1. 自动采集层：只负责 PV、页面停留、基础滚动。不采集点击事件。
2. 声明式层：负责所有 UI 交互事件，按钮点击、Tab 切换、链接跳转。
3. 命令式层：负责业务逻辑事件，接口调用、状态变更、异常捕获。

三层之间互不重叠。自动采集不碰交互，声明式不碰业务，命令式不碰 UI。

4.4.2 去重机制

即使分层了，也难免有边界模糊的情况。我加了一个简单的去重：

const sentSet = new Set();

function sendTrack(data) {
  // 用 event + page + timestamp 的前三位做 key
  const key = `${data.event}_${data.page}_${Math.floor(data.timestamp / 1000)}`;
  
  if (sentSet.has(key)) {
    console.warn(`[Tracker] 重复事件已过滤: ${key}`);
    return;
  }
  
  sentSet.add(key);
  // 实际发送逻辑
}

这个去重不完美，但能挡住 99% 的重复上报。时间窗口是 1 秒，同一页面同一事件每秒只发一次。

4.5 最佳实践清单

最后，我总结了一份 checklist。每次新项目接入埋点，我都会拿出来过一遍：

实践项	说明	优先级
统一事件命名规范	category_action_label 三段式，全小写+下划线	P0
声明式优先	能用 data-* 解决的，不要写 JS 调用	P0
命令式统一入口	只暴露一个 $track 方法	P0
自动采集只做基础	PV、停留、滚动，不碰交互事件	P1
事件去重	时间窗口去重，防止重复上报	P1
异步埋点预生成 ID	请求前生成 trackId，关联后续事件	P1
埋点自检工具	开发环境打印所有埋点事件，方便 QA 验证	P2

4.6 本章小结

三种模式没有优劣之分，只有合不合适。

• 按钮点击、链接跳转 → 声明式，data-* 属性搞定
• 异步请求、业务逻辑 → 命令式，统一 $track 调用
• 页面浏览、基础行为 → 自动采集，零侵入

混合模式的关键是分层清晰、命名统一、去重兜底。做到这三点，埋点系统就不会变成一团乱麻。