4. 规则元数据模型设计

规则元数据是数据质量治理的“骨架”。在灰度发布场景下，元数据模型不仅要描述规则本身，还必须承载灰度策略、生效范围与版本控制信息。本节定义核心字段及其设计意图，确保后续API对接与灰度执行有统一的数据契约。

4.1 核心字段定义

4.2 字段设计详解

4.2.1 规则ID与规则名称

规则ID是全局唯一标识，建议使用不可变ID（如UUID短码），避免因名称修改导致历史数据关联断裂。规则名称允许业务方按需调整，但ID一旦生成永不改变。

4.2.2 规则类型与规则表达式

规则类型决定了表达式的解析器与执行引擎。常见类型映射如下：

• NOT_NULL：表达式仅包含目标字段列表
• UNIQUE：表达式包含组合字段列表与去重策略
• RANGE：表达式包含 min/max 或允许值集合
• REGEX：表达式包含正则模板与匹配模式
• CUSTOM：表达式为可执行脚本（Groovy/JavaScript）

// 规则表达式示例（RANGE类型）
{
  "field": "order_amount",
  "operator": "between",
  "min": 0.01,
  "max": 999999.99,
  "inclusive": true
}

4.2.3 生效范围

生效范围采用层级JSON结构，支持从数据源到行级标签的逐级过滤：

{
  "datasource": "mysql://prod-order",
  "table": "t_order",
  "partition": "dt=2025-04-01",
  "tags": ["core_business", "high_priority"]
}

4.2.4 灰度策略

灰度策略是元数据模型中最具动态性的字段。它控制规则在“生效范围”内的实际执行比例与条件：

• 流量比例：0~100整数，表示灰度流量百分比
• 白名单：指定用户ID、商户ID或IP段全量执行
• 金丝雀参数：按随机哈希或模运算分配灰度组
• 回滚标记：当灰度异常时自动切换为“仅记录不阻断”

// 灰度策略示例（10%流量 + 白名单）
{
  "ratio": 10,
  "whitelist": ["user_1001", "user_1002"],
  "canary": {
    "type": "hash_mod",
    "key": "user_id",
    "mod_base": 100,
    "target_set": [0, 9]
  },
  "rollback_mode": "log_only"
}

4.3 元数据模型关系图

下图展示规则元数据与灰度策略、生效范围之间的核心关联：

4.4 灰度策略字段设计要点

灰度策略是元数据模型中最易出错的部分，以下为关键设计原则：

• 策略可叠加：白名单优先级高于流量比例，金丝雀参数仅在比例范围内生效
• 策略版本化：每次灰度策略变更应生成新版本号，便于回滚与审计
• 策略热加载：灰度策略存储在配置中心（如Nacos/Etcd），规则引擎实时监听变更
• 策略默认值：当灰度策略为空时，规则在全量范围按正常模式执行

4.5 元数据模型与API对接的映射

在API对接时，元数据字段直接映射为请求/响应体的JSON属性。以下为创建规则API的请求示例：

POST /api/v1/quality/rules
Content-Type: application/json

{
  "ruleId": "DQ_a3f2c8e1",
  "ruleName": "订单金额非负校验",
  "ruleType": "RANGE",
  "expression": {
    "field": "order_amount",
    "operator": "gte",
    "value": 0
  },
  "scope": {
    "datasource": "mysql://prod-order",
    "table": "t_order",
    "tags": ["core_business"]
  },
  "grayStrategy": {
    "ratio": 10,
    "whitelist": ["user_1001"],
    "canary": {
      "type": "hash_mod",
      "key": "user_id",
      "mod_base": 100,
      "target_set": [0, 9]
    },
    "rollbackMode": "log_only"
  }
}

响应中应返回完整的元数据对象，并附带版本号与创建时间戳，供调用方确认规则已正确注册。

4.6 元数据模型版本管理

规则元数据本身也需要版本管理，以支持灰度发布过程中的逐步推进与回滚：