3. 样本数据结构：标准样本字段定义、JSON/Protobuf格式选择、字段类型与约束

在实时风控网关中，样本数据结构是校验引擎与决策系统之间的通信契约。一个设计良好的样本结构，能够同时满足高吞吐解析、低延迟传输和强类型校验三大要求。本节将围绕标准字段定义、序列化格式选型以及字段类型与约束展开，帮助你在架构层面建立样本数据的规范基线。

3.1 标准样本字段定义

一个通用的风控样本通常包含以下五类字段，它们共同构成了风险决策的原始输入。下表列出了核心字段及其语义说明：

3.2 JSON 与 Protobuf 格式选择

实时风控网关对序列化格式的核心诉求是：解析速度快、数据体积小、Schema 可演进。JSON 和 Protobuf 是目前最主流的两种选择，它们在以下维度存在显著差异：

下面是一个典型的 Protobuf 样本定义示例：

syntax = "proto3";

package risk.sample.v1;

message RiskSample {
  // 请求标识
  string request_id = 1;
  int64 timestamp = 2;
  string source = 3;

  // 用户画像
  string user_id = 4;
  string device_fingerprint = 5;

  // 行为上下文
  ActionType action_type = 6;
  string ip_address = 7;

  // 业务载荷
  double amount = 8;
  string target_account = 9;

  // 扩展字段
  map<string, string> extras = 10;

  enum ActionType {
    UNKNOWN = 0;
    LOGIN = 1;
    PAY = 2;
    REGISTER = 3;
    WITHDRAW = 4;
  }
}

3.3 字段类型与约束

字段类型的选择直接影响校验引擎的计算效率和存储开销。以下是实时风控场景中常用的字段类型及其约束规则：

• string：用于标识类字段（request_id、user_id）。必须设置最大长度限制（如 64 字符），防止超长字符串导致内存溢出。
• int64 / uint64：用于时间戳、ID 等数值。推荐使用 int64 而非 string 存储时间，便于直接做范围比较。
• double：用于金额、概率等浮点数值。注意精度问题，金额建议以“分”为单位使用 int64 存储。
• enum：用于有限枚举值（action_type、risk_level）。枚举值必须从 0 开始，且保留 0 为 UNKNOWN 占位。
• map<K, V>：用于动态扩展字段。建议限制 map 的键值对数量（如不超过 20 对），防止恶意构造超大 map 导致解析性能下降。
• repeated：用于列表数据（如历史行为序列）。必须设置最大元素个数（如 max 100），避免无限增长。

下面的 SVG 图展示了样本数据从接入到校验的完整字段流转路径，以及各阶段对字段类型与约束的检查点：

3.4 字段约束清单与校验规则

为了在网关层实现高效的样本校验，建议为每个字段定义明确的约束规则。以下是一份可直接落地的字段约束清单：