📚 课程目录第4章事件模型设计

4. 事件模型设计：事件类型定义、事件属性、事件时间戳

好，咱们进入事件模型设计。这部分说白了，就是给系统里流动的「消息」定规矩。你想想看，如果连事件长什么样都没说清楚，后面的模式匹配、窗口计算根本没法搞。

我在做推荐系统初期，踩过一个坑：事件定义太随意，导致上线后数据对不上，排查了三天才发现是事件属性名不统一。嗯，从那以后，我对事件模型的设计就格外较真。

4.1 事件类型定义

事件类型，就是给每类行为贴个标签。我习惯用枚举或字符串常量来定义，清晰且不易出错。

核心原则：事件类型必须唯一、语义明确、可扩展。

常见的推荐系统事件类型，我列个表给你看：

事件类型	含义	触发场景
`PAGE_VIEW`	页面浏览	用户打开首页或详情页
`ITEM_CLICK`	物品点击	用户点击推荐列表中的某个商品
`ADD_TO_CART`	加入购物车	用户将物品加入购物车
`PURCHASE`	购买	用户完成订单支付
`LIKE`	点赞	用户对内容点赞
`SHARE`	分享	用户将内容分享给好友

定义事件类型时，我建议用大写字母+下划线的命名风格。为什么？因为一眼就能看出这是事件常量，跟普通变量区分开。

小技巧：在代码里，我会把事件类型定义成枚举类，这样 IDE 能自动补全，避免手写字符串拼错。

4.2 事件属性

事件属性，就是描述这个事件「长什么样」的字段。每个事件类型都有自己的一套属性集。

我个人习惯把属性分成三类：

公共属性：所有事件都有的，比如事件ID、用户ID、时间戳
业务属性：跟具体业务相关的，比如商品ID、价格、品类
环境属性：设备信息、网络状态、地理位置等

举个例子，一个 ITEM_CLICK 事件的属性结构：

{
  "event_id": "evt_20240321123456_001",
  "event_type": "ITEM_CLICK",
  "user_id": "u_10086",
  "timestamp": 1711011200000,
  "properties": {
    "item_id": "i_9527",
    "item_category": "电子产品",
    "price": 2999.00,
    "position": 3,
    "page_id": "homepage_recommend",
    "device_type": "iOS",
    "network": "5G"
  }
}

这里要注意，属性值的数据类型要提前约定好。我在项目中遇到过一个问题：某个字段有时传字符串"123"，有时传数字123，导致CEP引擎解析报错。后来我们强制要求所有属性必须有明确的schema定义。

避坑指南：我曾经因为事件属性里混入了null值，导致窗口聚合函数直接崩溃。建议所有属性都设置默认值，或者用Optional包装。

4.3 事件时间戳

时间戳是事件模型里最容易被忽视、但又最关键的部分。你想想看，如果时间不对，窗口计算出来的结果全是错的。

事件时间戳通常有两种：

事件发生时间（Event Time）：用户实际行为发生的时间，由客户端生成
事件处理时间（Processing Time）：事件到达CEP引擎的时间，由服务端生成

我强烈建议优先使用事件发生时间。为什么？因为处理时间受网络延迟、系统负载影响，波动很大。比如用户凌晨3点点击了商品，但因为网络问题，事件到中午才到达服务器。如果用处理时间，这个点击就被算到了中午，完全失真。

时间戳的格式，我推荐用Unix毫秒时间戳（长整型）。原因很简单：

计算方便，直接做加减法
跨语言兼容，Java、Python、Go都支持
精度足够，毫秒级能满足绝大多数场景

重要：时间戳必须使用UTC时间，避免时区转换带来的混乱。显示时再转成当地时区。

还有一个坑：客户端生成的时间戳可能不准。用户手机时间调快了5分钟，那事件时间就比真实时间早了5分钟。怎么办？我一般会在服务端做时间戳校正：

记录客户端时间戳和服务器收到时间戳
计算两者的差值
如果差值超过阈值（比如10分钟），标记为异常事件
对于异常事件，可以选择丢弃或用服务器时间替代

4.4 事件模型整体结构

下面这张图，是我在项目中常用的事件模型结构，你可以参考：

4.5 实战中的事件模型设计流程

说了这么多理论，咱们来点实际的。我在项目中设计事件模型时，一般按这四步走：

梳理业务场景：跟产品经理、业务方一起，列出所有需要追踪的用户行为
定义事件类型：每个行为对应一个事件类型，命名要直观
设计属性结构：确定每个事件需要哪些字段，字段类型是什么
确定时间策略：选择事件时间还是处理时间，设置时间戳校正规则

举个例子，我之前做一个短视频推荐项目。业务方说想追踪「用户观看视频超过30秒」这个行为。我设计的事件模型是这样的：

事件类型: VIDEO_WATCH
属性:
  - user_id: string (用户ID)
  - video_id: string (视频ID)
  - watch_duration: int (观看时长，单位秒)
  - video_duration: int (视频总时长，单位秒)
  - watch_ratio: float (观看比例，watch_duration / video_duration)
  - device: string (设备类型)
时间戳: 事件发生时间（客户端生成，服务端校正）

这里有个细节：watch_ratio 是衍生属性，由服务端计算后填充。为什么不在CEP里实时算？因为计算逻辑简单，提前算好能减少CEP引擎的计算压力。

经验之谈：事件属性不是越多越好。我见过有人把几十个字段塞进一个事件里，结果大部分字段都是空的。建议只保留业务真正需要的字段，其他用扩展字段兜底。

好了，事件模型设计就聊到这儿。记住一句话：好的事件模型，能让后续的模式匹配和窗口计算事半功倍；坏的事件模型，会让你在排查问题上花掉双倍的时间。