第4章 属性字段完整性校验：必填字段清单、字段类型检查、默认值回填规则

属性字段是埋点事件的核心载体，字段的完整性直接决定下游数据可用性。本章重点讲解如何通过三个维度的校验——必填字段清单完整性、字段类型精确匹配、默认值回填规则生效性——来保证埋点属性数据的结构正确和语义一致。

适用场景

• 新埋点事件上线前的集成测试阶段
• 已有事件Schema升级后回归测试
• 数据迁移或属性变更后的全量校验
• 自动化CI流水线的埋点质量检查步骤

前置条件

1. 埋点事件定义文档已评审通过，包含所有属性的名称、类型、默认值、是否必填等元信息。
2. 测试环境已部署最新版本的SDK或数据采集服务，并能正常发送模拟事件。
3. 测试数据生成工具可以构造包含所有属性组合（缺失、类型错误、空值等）的测试事件。
4. 校验脚本或测试框架已准备就绪，能够解析事件JSON并对照schema逐字段比对。

操作步骤

1. 收集元数据：从埋点定义文档或Schema Registry中导出当前版本所有属性的定义清单。
2. 构建完整测试矩阵：根据必填字段清单、字段类型规则、默认值回填规则，设计至少覆盖以下场景的测试事件：正常完整事件、缺失必填字段、可选字段缺失、字段类型错误、字段值为Null但期望非空、字段值超过长度/精度、默认值未生效等。
3. 执行必填字段检查：对于每条测试事件，遍历必填字段清单，确认事件中是否存在且值不为空/Null。记录缺失或空值字段。
4. 执行字段类型检查：对照schema中每个字段的期望类型（String、Integer、Float、Boolean、JSON Object、Array等），使用精确类型断言判断实际值类型是否匹配。注意数字类型的边界值和浮点精度。
5. 执行默认值回填检查：对于非必填字段且在事件中未显式传入时，确认采集端或ETL层是否依照定义规则填充了正确的默认值（如0、空字符串、固定枚举值等）。
6. 汇总校验报告：将每项检查结果（通过/失败、失败详情、实际值、期望值）写入报告，并通过可视化图表展示通过率。

输入输出物

类型	名称	说明
输入	埋点Schema定义	包含所有属性的名称、类型、默认值、必填标志等元数据（JSON/YAML格式）
输入	测试事件数据集	人工构造或工具生成的多条符合/不符合规则的模拟事件
输出	字段完整性校验报告	每项检查的通过/失败列表、统计指标、失败样本截图或日志
输出	缺陷推送记录	明确失败的埋点及原因，生成Jira或对应工单

责任边界

• 数据产品经理：提供并维护最新埋点Schema定义，包括必填字段清单、类型和默认值。
• 前端/后端开发：确保SDK或采集接口实现符合schema，正确打包字段并处理默认值回填。
• 质量测试人员：设计测试矩阵，执行校验步骤，输出报告并推动缺陷闭环。
• 数据治理/运维：维护Schema Registry，提供自动化校验工具的部署与运行环境。

记录材料

每次校验需归档以下文件：

1. 使用的Schema定义文件（带版本号）
2. 测试事件数据集（带构造脚本或种子文件）
3. 校验脚本可执行文件或配置文件
4. 生成的校验报告PDF或Excel
5. 缺陷工单截图或列表

记录保存至项目交付验收后至少6个月。

异常处理

验收标准

1. 所有必填字段在事件中100%存在且值非空/NonNull。
2. 字段类型匹配准确率100%（允许精度的浮点误差由PM认可）。
3. 所有非必填字段在缺失时，默认值回填规则正确生效，回填后的数据类型符合schema。
4. 校验报告数据完整，缺陷工单已创建并标明修复优先级。