4. 埋点事件定义规范：事件命名规范、属性命名规范、枚举值规范

好，咱们进入埋点方案里最「磨人」的一环——定义规范。

说实话，我见过太多团队，埋点代码写得飞起，结果上线三个月后，数据对不上、指标算不清、新同学看不懂。为什么？说白了，就是一开始没定好规矩。

这一节，我把我在风控领域摸爬滚打这些年，沉淀下来的命名规范和枚举值规范，掰开了讲给你听。

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

事件命名，我个人的习惯是「三段式」：领域_动作_对象。

你想想看，一个事件如果叫 click_btn，三个月后你还能记得这是哪个页面的哪个按钮吗？反正我不行。

{业务域}_{行为类型}_{具体对象}

我在项目中遇到过一件事：有个同事把「用户点击风控申诉按钮」埋成了 click_appeal。结果后来产品要区分「申诉页面的点击」和「申诉结果的点击」，完全分不开。嗯，这就是命名的坑。

几个硬性规则：

• 全部小写，单词间用下划线连接
• 动词用过去式（如 submitted、triggered）
• 不要带版本号（如 v2、_new）
• 长度控制在 40 个字符以内

4.2 属性命名规范：统一、可扩展

属性是事件的「血肉」。事件名定了，属性如果乱写，数据质量一样完蛋。

我建议属性命名遵循 「驼峰式」，并且加上类型前缀。为什么？因为下游ETL同学看到属性名就能知道数据类型，不用再翻文档。

举个例子，一个「风控规则触发」事件，它的属性可能是这样：

{
  "event": "risk_rule_triggered",
  "properties": {
    "str_ruleId": "R001",
    "str_ruleName": "高频交易拦截",
    "num_score": 85,
    "is_blocked": true,
    "ts_triggered": 1695000000000,
    "enum_riskLevel": "high"
  }
}

你看，一眼就知道每个字段是什么类型、什么含义。这就是规范的力量。

4.3 枚举值规范：别让「其他」成为黑洞

枚举值，是埋点里最容易出幺蛾子的地方。

我记得有一次，一个「风控决策结果」字段，有人填了 pass，有人填了 PASS，还有人填了 通过。你猜最后数据清洗花了多久？整整两天。

我的建议：

• 全部使用小写英文，下划线连接
• 每个枚举值必须有明确的定义文档
• 预留一个 unknown 兜底，但不要滥用

举个例子，风控等级枚举：

enum RiskLevel {
  low      // 低风险，正常放行
  medium   // 中风险，需二次验证
  high     // 高风险，直接拦截
  critical // 严重风险，人工介入
  unknown  // 未知，兜底值
}

这里有个坑：unknown 只能用于「确实无法判断」的情况，不能因为偷懒不传值就填 unknown。我曾经在项目里发现，某个接口因为异常没返回结果，结果所有事件都变成了 unknown，导致整个风控报表失效。嗯，后来我们加了个告警：unknown 占比超过 5% 就报警。

4.4 知识体系总览

下面这张图，是我梳理的埋点事件定义规范的核心逻辑。你可以把它当作一个检查清单，每次新建事件时对照着走一遍。

公众号:蓝海资料掘金营，微信deep3321