📚 课程目录第2章埋点规范

2、埋点规范：从命名到评审，把数据地基打牢

埋点这件事，说白了就是给用户行为装个「摄像头」。但摄像头装歪了、命名乱了、文档丢了，拍回来的数据就是一堆垃圾。我见过太多团队，数据跑出来对不上，最后发现是埋点规范没统一。

这一章，咱们就把规范聊透。从事件命名、参数命名，到文档怎么写、评审怎么过，一条龙讲清楚。

2.1 事件命名规范：一眼看懂，别猜谜

事件命名是埋点的身份证。我个人的习惯是：看到名字，就知道谁、在哪儿、干了什么。

2.1.1 命名原则

可读性优先：用英文单词，别用拼音缩写。比如 click_login_button 比 djl_btn 好一百倍。
层级清晰：用下划线分隔，不要驼峰。驼峰在数据分析工具里经常被截断，你想想看，clickLoginButton 和 click_login_button，哪个更容易被搜索到？
全局唯一：同一个事件，全公司只能有一个名字。别 iOS 叫 page_view_home，Android 叫 home_page_view。

2.1.2 命名模板

我推荐用这个模板：

{行为类型}_{对象}_{场景/位置}

举个例子：

行为类型	对象	场景	完整事件名
click	login_button	login_page	`click_login_button_login_page`
page_view	home	-	`page_view_home`
search	product	search_page	`search_product_search_page`
purchase	order	checkout_page	`purchase_order_checkout_page`

我的小技巧：行为类型尽量控制在 10 个以内。比如 click、page_view、search、purchase、add_to_cart、remove_from_cart、share、login、logout、register。多了就乱了。

2.1.3 避坑指南

我曾经接手过一个项目，事件名叫 event_001、event_002…… 你猜猜 event_042 是啥？没人知道。后来我们花了整整两周，对着代码反推，才把映射关系理清楚。嗯，从那以后，我再也不允许用数字编号命名事件了。

2.2 参数命名规范：让数据自带说明书

事件是骨架，参数才是血肉。参数命名如果乱来，数据根本没法用。

2.2.1 参数分类

我习惯把参数分成三类：

公共参数：每个事件都带，比如用户ID、设备ID、时间戳、网络环境、App版本。
业务参数：跟具体事件相关，比如商品ID、价格、数量、搜索关键词。
技术参数：页面加载耗时、接口响应码、错误堆栈。

2.2.2 命名规则

参数命名跟事件命名一样，用下划线、全小写。但有个区别：参数名要尽量短，因为每次上报都带着，太长浪费流量。

参数类型	推荐命名	不推荐命名
用户ID	`user_id`	`uid`、`userId`
商品ID	`product_id`	`pid`、`goodsId`
页面来源	`refer_page`	`from`、`source`
搜索关键词	`search_keyword`	`kw`、`q`

注意：参数值类型必须固定。比如 price 永远是数字，别今天传 19.99，明天传 "19.99"。字符串和数字混着来，分析的时候你会想哭的。

2.3 埋点文档撰写：写清楚，别靠猜

文档是埋点的「法律条文」。没有文档，后面的人只能靠猜。我见过最离谱的，是文档里只写了个事件名，连参数列表都没有。结果新来的同事对着代码看了三天，才搞明白每个参数是干嘛的。

2.3.1 文档结构

一份合格的埋点文档，至少包含这些：

事件列表：所有事件名、描述、所属模块。
参数字典：每个参数的名称、类型、取值范围、示例值。
事件-参数映射：每个事件携带哪些参数。
版本变更记录：谁、什么时候、改了啥。

2.3.2 文档模板示例

我个人习惯用 Markdown 写，然后自动生成 HTML 或 PDF。下面是一个事件定义的模板：

## 事件：click_login_button_login_page

### 描述
用户在登录页面点击「登录」按钮。

### 触发时机
用户点击登录按钮后，发起登录请求前。

### 携带参数
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| user_id | string | 是 | 用户唯一标识 | "u_12345" |
| login_type | string | 是 | 登录方式 | "password" / "sms" / "wechat" |
| is_success | bool | 是 | 登录是否成功 | true / false |
| error_code | int | 否 | 失败时的错误码 | 1001 |

### 版本记录
- v1.0 (2024-01-15)：初始定义，张三
- v1.1 (2024-03-01)：新增 error_code 参数，李四

我的习惯：文档跟代码放同一个仓库，用 Git 管理版本。每次埋点变更，都要走 PR 评审。这样谁改了啥，一目了然。

2.4 埋点评审流程：别让错误上线

埋点评审，是最后一道防线。我见过太多线上事故，都是因为埋点没评审就上线了。数据跑出来全是 null，或者事件重复上报，把后端打挂了。

2.4.1 评审流程

我推荐这个流程：

产品提需求：产品经理写清楚，要追踪什么用户行为，分析什么指标。
数据工程师设计：根据需求，设计事件和参数，写文档。
技术评审：前端/后端工程师确认技术可行性，有没有性能问题。
数据评审：数据分析师确认，埋点能不能满足分析需求。
测试验证：QA 同学写用例，验证埋点触发时机、参数值是否正确。
上线确认：所有评审通过，才能合并代码、发布上线。

2.4.2 评审检查清单

我每次评审都会过一遍这个清单：

事件名是否符合规范？
参数名是否跟参数字典一致？
参数类型是否明确？
有没有遗漏必填参数？
触发时机是否跟文档一致？
有没有重复上报的风险？
性能影响评估过没有？

我曾经踩过的坑：有一次评审没仔细看，上线后发现 page_view 事件在页面切换时触发了两次。原因是前端代码里，一个路由变化触发了两个埋点调用。后来我们加了一条规则：每个事件在每个页面生命周期内，只能触发一次。评审时重点检查这个。

2.5 知识体系总览

下面这张图，把埋点规范的四个核心模块串起来了。你可以把它当成一个检查清单，每次做埋点都过一遍。

嗯，规范这东西，一开始大家觉得麻烦。但等你真正跑数据的时候，就会发现：规范省下的时间，比写规范花的时间多十倍。我这些年带过的团队，凡是前期在规范上花功夫的，后期数据质量都稳得很。反过来，那些急着上线、跳过规范的，最后都在补数据、修 bug 上浪费了更多时间。

所以，别嫌麻烦。把规范立起来，后面就顺了。