3. 特征流数据模型设计：特征键、时间戳、特征值、元数据标签

实时特征流的数据模型是缺失巡检的“骨架”。一个设计不良的模型会导致巡检逻辑混乱、回溯困难、误报率飙升。本节将定义特征流中每条记录的核心四要素，并给出可直接落地的 Schema 规范。

3.1 四要素定义与职责

每条实时特征记录必须包含以下四个字段组，缺一不可：

3.2 数据模型 Schema 规范（Avro 示例）

生产环境推荐使用 Avro 作为序列化格式，兼顾强类型与 Schema 演化。以下为特征流记录的完整 Schema 定义：

{
  "namespace": "com.realtime.feature",
  "type": "record",
  "name": "FeatureRecord",
  "fields": [
    {"name": "feature_key",  "type": "string",  "doc": "特征唯一键，格式：{entity_type}:{entity_id}:{feature_name}"},
    {"name": "event_ts",    "type": "long",    "doc": "事件时间戳，毫秒 Unix 时间"},
    {"name": "feature_value","type": ["double", "null"], "doc": "特征值，允许 null 表示缺失"},
    {"name": "metadata",    "type": {
      "type": "map",
      "values": "string"
    }, "doc": "元数据标签，如 version=2.1, source=clickhouse, quality=high"}
  ]
}

3.3 特征键设计模式

特征键的粒度直接影响巡检效率。推荐采用 三级命名空间 模式：

• 实体类型（entity_type）：user / device / order / session
• 实体 ID（entity_id）：具体业务主键，如 user_12345
• 特征名称（feature_name）：如 click_rate_7d、avg_price_30m

最终特征键格式：user:user_12345:click_rate_7d。这种设计使得巡检系统可以按实体类型或特征名称进行前缀匹配扫描，快速定位缺失范围。

3.4 元数据标签最佳实践

元数据标签是缺失巡检的“侦探工具”。建议至少包含以下标签：

3.5 特征流数据模型结构图

下图展示了特征记录在 Kafka 主题中的完整结构，以及各字段在缺失巡检链路中的角色：

3.6 模型设计检查清单

在将特征流数据模型投入生产前，请逐项确认以下要点：

• 特征键唯一性：相同实体+特征在相同时刻不会产生两条不同记录
• 时间戳精度：统一使用毫秒级 Unix 时间戳，避免秒/毫秒混用
• 特征值类型：数值特征使用 double，类别特征使用 string，不允许使用 int 或 float 避免精度丢失
• 元数据必填：至少包含 version 和 source 两个标签，否则拒绝写入
• Schema 兼容性：使用 Avro Schema Registry，向后兼容模式避免消费端崩溃