4、属性命名规范：小驼峰、公共与私有、类型与枚举

属性命名这件事，说实话，是埋点规范里最容易「吵起来」的地方。我见过不少团队，埋点体系搭得挺全，结果一看属性名，有的用下划线、有的用大写、有的干脆拼音缩写——最后数据清洗阶段直接崩溃。

我个人习惯是：先把命名原则定死，再谈别的。原则不统一，后面全是坑。

4.1 命名原则：小驼峰（camelCase）

为什么选小驼峰？说白了，它在前端和后端代码里都是主流写法。你想想看，JSON 字段、JavaScript 变量、Java 属性，绝大多数场景默认就是小驼峰。埋点数据最终要落到这些系统里，命名风格保持一致，能省掉一堆转换逻辑。

规则很简单：

• 首字母小写
• 后续每个单词首字母大写
• 禁止使用下划线、连字符、空格
• 禁止使用拼音或无意义缩写

pageName        // 页面名称
buttonText      // 按钮文案
fromSource      // 来源渠道
previousPage    // 上一页
isLogin         // 是否登录

page_name       // 下划线，禁止
PageName        // 首字母大写，禁止
btnTxt          // 无意义缩写，禁止
laiyuan         // 拼音，禁止

我在项目中遇到过一件事：有个同事坚持用下划线，说「可读性更好」。结果数据接入数仓时，Hive 表字段自动转成了小驼峰，两边对不上，整整花了两天做映射。嗯，从那以后，我们团队就把小驼峰写进了规范里，谁都不许改。

4.2 公共属性与私有属性

属性不能一锅炖。我建议分成两类：公共属性和私有属性。

为什么要区分？

• 公共属性保证全局数据一致性。比如 platform 字段，iOS 和 Android 必须统一命名，不能一个叫 os，一个叫 platformType。
• 私有属性给业务方灵活空间。但要注意，私有属性也要遵循命名规范，不能乱来。

4.3 属性值类型定义

属性名定好了，值类型也得说清楚。不然你传字符串，我传数字，最后统计「页面停留时长」时，有的字段是 "3.5"，有的是 3.5，聚合函数直接报错。

我常用的类型定义：

4.4 枚举值规范

枚举值是最容易被忽视的坑。你想想看，同样是「支付成功」，有人传 "success"，有人传 "SUCCESS"，还有人传 "1"——数据一汇总，直接裂开。

我建议的枚举规范：

• 统一使用小写字母 + 下划线（snake_case），与属性名的小驼峰区分开
• 语义清晰，不要用数字代替含义
• 必须维护枚举字典，每个枚举值都要有中文说明

// 支付状态
pay_success    // 支付成功
pay_failed     // 支付失败
pay_pending    // 支付处理中
pay_cancelled  // 支付取消

// 页面类型
page_home      // 首页
page_detail    // 详情页
page_cart      // 购物车
page_mine      // 个人中心

我曾经在项目中踩过一个坑：有个枚举值叫 "other"，结果业务方把所有无法归类的数据都扔进去，最后这个值占比超过 40%，完全失去了分析意义。所以，枚举值要尽量穷举，实在无法穷举的，用 unknown 而不是 other，至少能提醒你「这里需要补充」。

4.5 知识体系总览

下面这张图把属性命名的核心逻辑串起来了，你可以对照着看：

这张图把四个核心模块串在了一起。你从中心出发，沿着四条线走，就能覆盖属性命名的全部要点。我个人建议你把这张图打印出来贴在工位上，每次定义新属性时扫一眼，基本不会出错。

4.6 避坑总结

最后，我把自己踩过的坑整理成几条原则，你直接拿去用：

• 命名原则先定死：小驼峰，不接受反驳。团队里如果有人想用下划线，让他看看数据清洗的代价。
• 公共属性越少越好：10 个以内，多了就是负担。每次新增都要全量发版，成本很高。
• 值类型要严格：string 就传 string，int 就传 int，别搞隐式转换。数据质量是分析的基础。
• 枚举值要穷举：实在穷举不了用 unknown，别用 other。前者提醒你补充，后者让你麻痹。
• 维护一份属性字典：所有属性名、类型、枚举值、说明，统一放在一个文档里。新同学入职，先看字典再写代码。