4. 数据契约的 Schema 定义：字段命名规范、数据类型定义、约束条件

好，咱们进入正题。上一章聊了数据契约的整体结构，这一章我们聚焦在最核心、也最容易踩坑的部分——Schema 定义。

说白了，Schema 就是数据契约的“骨架”。你想想看，如果连字段叫什么都说不清楚，数据类型都模棱两可，那后面的校验、监控、消费全都会乱套。我在项目中见过太多次因为 Schema 定义不严谨，导致实时特征上线后数据质量一塌糊涂的案例。

所以，这一章我会把我在实战中沉淀下来的经验，掰开了揉碎了讲给你听。

4.1 字段命名规范：别让名字毁了你的数据

字段命名这件事，看起来简单，但往往是团队协作中最大的痛点。我个人的习惯是，命名规范必须在数据契约的第一版就定下来，不然后面改起来成本极高。

4.1.1 命名风格统一

我建议团队统一使用 snake_case（小写字母+下划线）。为什么？因为大多数实时计算引擎（Flink、Spark Streaming）和消息队列（Kafka、Pulsar）对大小写敏感，而 snake_case 可读性好，也不容易出错。

4.1.2 命名语义化

字段名要能“自解释”。我看到过太多像 f1、col_001 这样的命名，说实话，这种命名除了增加沟通成本，没有任何好处。

我建议遵循以下原则：

• 业务含义优先：order_status 比 status 好，payment_method 比 method 好
• 避免缩写歧义：usr_id 不如 user_id 清晰，amt 不如 amount 直观
• 层级关系用前缀：比如 address_city、address_zip，而不是 city、zip 散落在各处

4.1.3 保留字与特殊字符

这个必须单独拎出来说。很多实时计算引擎有自己的保留字，比如 timestamp、date、value。如果你直接用这些做字段名，SQL 查询时就得加反引号，非常麻烦。

4.2 数据类型定义：精确到每一个字节

数据类型定义是 Schema 里最容易出问题的地方。我记得有一次，一个团队把金额字段定义成了 FLOAT，结果在聚合计算时出现了精度丢失，导致对账不平。嗯，这里要注意，金融相关的字段，必须用高精度类型。

4.2.1 常见数据类型选择

业务场景	推荐类型	不推荐类型	说明
用户ID、订单ID	STRING	INT	ID 可能包含字母或前缀，用 STRING 更安全
金额、价格	DECIMAL(18,2)	FLOAT / DOUBLE	避免浮点精度问题
状态码、枚举值	INT 或 STRING	BOOLEAN	BOOLEAN 只有两种状态，扩展性差
时间戳	BIGINT (毫秒) 或 TIMESTAMP	STRING	STRING 格式不统一，解析成本高
JSON 对象	MAP<STRING, STRING> 或 STRUCT	STRING	尽量结构化，避免嵌套 JSON 解析

4.2.2 时间字段的“坑”

时间字段是实时特征里最常用的字段之一，也是最容易出问题的。我见过太多因为时区、格式不一致导致的数据质量问题。

我个人的做法是：

• 统一使用 UTC 时间，消费端自行转换时区
• 时间戳用 BIGINT 存储毫秒数，避免字符串格式解析歧义
• 如果必须用字符串，强制使用 ISO 8601 格式：2025-01-15T10:30:00Z

4.3 约束条件：给数据上“紧箍咒”

约束条件就是数据契约里的“规则”。没有约束，数据质量就是一句空话。我习惯把约束条件分为三类：非空约束、唯一约束、枚举约束。

4.3.1 非空约束 (NOT NULL)

这个最简单，但也最容易被忽略。很多团队只在主键字段上加非空约束，但实际业务中，很多关键字段也不应该为空。

我建议对以下字段强制非空：

• 业务主键：如 user_id、order_id
• 时间字段：如 event_timestamp、process_time
• 核心业务字段：如 order_amount、payment_status

4.3.2 唯一约束 (UNIQUE)

唯一约束在实时场景下比较特殊。因为实时数据流通常是 append-only 的，很难像数据库那样做全局唯一性检查。但有些场景确实需要保证唯一性，比如去重后的用户行为特征。

我通常的做法是：

• 在数据契约里声明唯一键，但不强制在写入时做全量校验
• 在消费端做幂等处理，比如用 Flink 的 deduplicate 算子
• 定期做离线对账，检查是否有重复数据

4.3.3 枚举约束 (ENUM)

枚举约束是我个人非常看重的一个点。很多数据质量问题，根源就在于枚举值不规范。

举个例子，订单状态这个字段，有的系统用 0, 1, 2，有的用 pending, paid, shipped，还有的用 PENDING, PAID, SHIPPED。一旦混用，下游消费时就得做各种映射转换，非常容易出错。

我建议的做法是：

• 在数据契约里明确定义枚举值列表，包括每个值的含义
• 使用 STRING 类型存储枚举值，可读性更好
• 在 Schema 校验层做枚举值白名单检查，不在列表里的值直接拒绝

// 数据契约中的枚举定义示例
{
  "field": "order_status",
  "type": "STRING",
  "constraints": {
    "enum": ["pending", "paid", "shipped", "cancelled", "refunded"]
  },
  "description": "订单状态：pending-待支付, paid-已支付, shipped-已发货, cancelled-已取消, refunded-已退款"
}

4.4 Schema 定义的整体流程

说了这么多，咱们来梳理一下 Schema 定义的整体流程。下面这张图是我在项目中常用的 Schema 定义流程，你可以参考一下。

这个流程看起来简单，但每一步都有很多细节。我建议你在实际项目中，把每一步的产出物都文档化，并且通过自动化工具来保证一致性。

4.5 实战中的避坑指南

最后，分享几个我在实战中总结的避坑经验：