4. 数据契约的 YAML/JSON 定义规范：契约结构、字段约束、元数据标签、SLA 定义

好，咱们进入正题。数据契约长什么样？怎么定义？

说白了，数据契约就是一个描述文件。它告诉所有人：这个数据集是什么、谁负责、字段怎么约束、服务质量怎么保证。我个人习惯用 YAML，可读性好，嵌套结构一目了然。JSON 也行，但 YAML 更清爽。

4.1 契约的顶层结构

一个完整的数据契约，我把它拆成四个核心部分：

• 元信息：契约名称、版本、所有者、描述
• Schema 定义：字段列表、类型、约束
• 元数据标签：分类、敏感度、业务域
• SLA 定义：可用性、延迟、一致性、备份策略

嗯，这里要注意：顺序不重要，但结构必须清晰。我在项目中见过有人把 SLA 塞到元信息里，结果后期解析时到处打补丁。

来看一个完整的 YAML 示例：

apiVersion: datacontract.io/v1
kind: DataContract
metadata:
  name: user-profile-contract
  version: "1.2.0"
  owner: "data-platform-team"
  description: "用户画像核心数据集，支撑推荐与风控"
  created: "2025-03-10T08:00:00Z"
  updated: "2025-03-15T14:30:00Z"

schema:
  fields:
    - name: user_id
      type: string
      constraints:
        required: true
        unique: true
        pattern: "^U\\d{8}$"
      description: "用户唯一标识"
    - name: user_name
      type: string
      constraints:
        required: true
        maxLength: 64
      description: "用户昵称"
    - name: email
      type: string
      constraints:
        required: false
        format: email
      description: "注册邮箱"
    - name: age
      type: integer
      constraints:
        minimum: 0
        maximum: 150
      description: "用户年龄"

tags:
  - domain: "user"
  - sensitivity: "PII"
  - lifecycle: "hot"
  - dataProduct: "user-profile"

sla:
  availability: "99.95%"
  maxLatencyMs: 500
  consistency: "eventual"
  backup:
    enabled: true
    retentionDays: 90
    schedule: "0 2 * * *"
  notification:
    - type: "email"
      recipient: "data-oncall@company.com"
    - type: "webhook"
      url: "https://hooks.company.com/datacontract-alerts"

4.2 字段约束：别让脏数据混进来

字段约束是契约的「守门员」。你想想看，如果上游突然塞进来一个 age: -5，下游模型直接崩掉。我曾经在金融项目中遇到过，一个金额字段没做最小值约束，结果跑批时出现负值交易，排查了整整两天。

常用的约束类型：

约束类型	说明	示例
required	字段是否必填	required: true
unique	字段值是否唯一	unique: true
minimum / maximum	数值范围	minimum: 0
minLength / maxLength	字符串长度	maxLength: 64
pattern	正则表达式	pattern: "^U\\d{8}$"
format	语义格式	format: email
enum	枚举值列表	enum: [active, inactive]

4.3 元数据标签：给数据打上「身份证」

元数据标签不是摆设。在多云环境下，标签决定了数据怎么路由、怎么加密、怎么归档。

我建议至少包含以下几类标签：

• 业务域：domain: user、domain: finance —— 方便按业务线检索
• 敏感度：sensitivity: PII、sensitivity: public —— 触发自动加密或脱敏
• 生命周期：lifecycle: hot、lifecycle: warm、lifecycle: cold —— 决定存储策略
• 数据产品：dataProduct: user-profile —— 关联数据产品目录

为什么会强调标签？因为多云环境下，数据可能同时存在于 AWS S3、GCP GCS、阿里云 OSS。标签就是统一的「寻址系统」。

4.4 SLA 定义：把承诺写进代码里

SLA 是数据契约的「法律条款」。它定义了数据提供方对消费方的承诺。

核心 SLA 指标：

指标	说明	典型值
availability	数据可用性百分比	99.95%
maxLatencyMs	最大延迟（毫秒）	500ms
consistency	一致性模型	eventual / strong
backup.enabled	是否启用备份	true
backup.retentionDays	备份保留天数	90
notification	告警通知方式	email / webhook

嗯，这里有个细节：consistency 字段。在实时数仓场景下，大部分用 eventual 就够了。但如果是金融交易对账，必须用 strong。我建议在契约里明确写出来，避免下游误判。

4.5 知识体系总览

下面这张图，把数据契约的核心结构串起来了。你可以把它当作「契约设计检查清单」。

4.6 实战建议：从模板开始

别从零开始写契约。我建议团队维护一个「契约模板仓库」，包含不同场景的模板：

• 实时流数据模板：侧重延迟和一致性
• 离线批数据模板：侧重可用性和备份
• API 数据模板：侧重请求频率和限流

每次新建契约时，复制模板，修改字段和 SLA 即可。这样既保证了结构统一，又降低了上手门槛。