跳到主要内容

标准事件定义规范

本文档定义数据中台中心侧标准事件模型的命名、字段、版本和变更规则。

1. 目标​

本规范用于回答三个问题：

  • 什么叫「标准事件」
  • eventName 由谁定义
  • 哪些字段属于稳定下游契约

适用对象：

  • 接入侧开发
  • 数据平台开发
  • 第三方分析平台 / BI / 客服后台接入方
  • 控制面和数据治理维护者

2. 核心原则​

  1. 标准事件定义由数据中台中心侧维护。
  2. 标准事件不是对上游 TLog 表名的直接透传约定。
  3. 下游系统以标准事件定义为准，不以 TLog 文件或原始字段为准。
  4. 一个标准事件必须具备明确业务语义、时间语义和主标识策略。
  5. 不兼容变更必须版本化。

3. 标准事件结构​

推荐基础结构：

  • eventName
  • eventVersion
  • eventTime
  • ingestTime
  • tenantId
  • gameId
  • region
  • zoneId
  • source
  • eventUuid
  • roleId
  • accountId
  • deviceId
  • properties

字段职责：

  • eventName: 事件业务标识
  • eventVersion: 事件结构版本
  • eventTime: 事件业务发生时间
  • ingestTime: 进入数据中台的时间
  • source: 内部来源标记，不属于业务主口径
  • properties: 事件扩展属性

4. eventName 命名规范​

4.1 命名来源​

eventName 由中心侧事件字典定义，不由上游文件名或上游表名直接决定。

允许场景：

  • 某些早期接入业务临时使用与 TLog 表名相同的事件名

但这只是迁移阶段兼容策略，不应成为长期约束。

4.2 命名规则​

建议规则：

  • 小写英文
  • 使用下划线分词
  • 体现业务语义，而不是上游实现细节

推荐示例：

  • user_login
  • role_create
  • order_paid
  • item_change

不推荐示例：

  • LoginLog
  • CreateRole
  • Table17
  • log_xxx

4.3 命名要求​

每个 eventName 必须具备：

  • 中文说明
  • 英文标识
  • 业务定义
  • 触发条件
  • 主体对象
  • 时间语义

5. 事件字段分类​

5.1 稳定公共字段​

这是下游可依赖的正式契约字段：

  • eventName
  • eventVersion
  • eventTime
  • ingestTime
  • tenantId
  • gameId
  • region
  • zoneId
  • eventUuid
  • roleId
  • accountId
  • deviceId

5.2 可选公共字段​

按业务需要补充：

  • channel
  • platform
  • country
  • serverId
  • clientVersion

5.3 扩展属性字段​

扩展字段统一进入 properties：

  • 不稳定
  • 业务特有
  • 低频查询
  • 迁移阶段暂未固化的字段

原则：

  • 高频、跨业务共用字段，最终应提升为公共字段
  • 其余字段保留在 properties

6. 时间语义规范​

必须区分两个时间：

  • eventTime: 业务发生时间
  • ingestTime: 数据进入中心时间

规则：

  1. 下游业务分析优先使用 eventTime
  2. 增量同步优先使用 ingestTime
  3. 补数时允许 eventTime 很旧而 ingestTime 很新

7. 主标识规范​

7.1 事件唯一标识​

推荐字段：

  • eventUuid

要求：

  • 若上游已提供稳定事件 ID，直接沿用
  • 若上游没有，数据中台负责内部生成稳定 ID

7.2 用户主体标识​

按优先级推荐：

  1. roleId
  2. accountId
  3. deviceId

具体分析系统接入时应明确「谁是主用户标识」。

7.3 会话标识​

暂不支持，业务侧无会话 ID。

  • 同一会话内稳定
  • 能跨事件复用
  • 不随导出或补数改变

8. 事件版本规范​

推荐字段：

  • eventVersion

版本变更触发条件：

  • 字段删除
  • 字段重命名
  • 字段含义变化
  • 主标识策略变化
  • 时间语义变化

处理原则：

  • 向后兼容的小改动：可保持版本不变
  • 不兼容改动：必须升版本

9. 事件字典维护要求​

每个标准事件应至少登记以下信息：

  • eventName
  • eventVersion
  • 中文名称
  • 英文名称
  • 业务说明
  • 事件主体
  • 必填字段
  • 可选字段
  • 示例 payload
  • 所属业务
  • 是否跨业务通用
  • 是否对下游开放

10. 下游可依赖范围​

下游可以依赖：

  • 标准公共字段
  • 已发布的标准事件名
  • 已发布的 dataset
  • 已声明的事件版本

下游不应依赖：

  • 原始 TLog 文件名
  • 原始 TLog 字段顺序
  • dc_tlog_* 兼容表结构
  • properties 中未经发布的临时字段

11. 变更流程​

建议流程：

  1. 新增或修改事件定义
  2. 审核业务语义和字段语义
  3. 更新事件字典
  4. 更新下游 dataset 定义
  5. 发布并通知下游
  6. 灰度验证

12. 一句话定义​

标准事件是：

由数据中台中心侧定义、与上游 TLog 解耦、可被下游稳定消费的正式事件契约。

加载评论中...