Resource Guide
数据接口与样例数据准备清单
摘要：这份清单用于数据大屏、BI驾驶舱和软件系统在项目启动、原型确认与接口联调前，逐项核对来源系统、负责人、访问方式、鉴权、字段主键、时间规则、更新频率、历史数据量、样例、空值异常、网络白名单、预计就绪时间和临时 Mock 边界。重点是把“接口还没好”拆成可跟踪的具体条件。
这份清单什么时候使用
项目启动时即可建立接口清单，即使接口地址尚未开放，也应先明确来源系统、业务对象、负责人、字段样例和预计时间。进入正式联调前，再补齐鉴权、网络、环境、错误码、刷新机制和测试数据。表格既适用于 API，也适用于数据库视图、文件交换、消息队列和人工导入。
“有接口”不等于“可以联调”
只提供一个地址通常不足以开始开发。联调至少需要确认访问环境、协议、鉴权、请求参数、返回字段、主键、时间字段、分页、错误码、频率限制和责任人。涉及内网、VPN、白名单或测试账号时，网络和权限准备往往比接口代码本身更早成为阻塞项。
字段语义和时间规则要先统一
同名字段可能使用不同单位、统计范围或状态码。每个业务对象应说明唯一标识、增量判断方式、业务时间与更新时间、时区、空值、重复、撤销和补传规则。没有这些约定，页面即使取到数据，也可能在去重、趋势和同比环比上产生错误。
样例数据要覆盖异常，不只给一行正常值
建议提供经过授权或脱敏的代表性样例，覆盖正常、空值、零值、重复、超长文本、异常状态、跨日或跨月、分页边界和历史修订。样例不得包含非必要的真实个人信息、生产密钥或未授权数据，正式数据的访问范围应单独确认。
Mock 数据必须标记适用边界
接口未就绪时可以用 Mock 或静态数据推进页面结构，但要记录字段版本、生成规则、哪些结果尚未验证以及替换正式接口的条件。演示数据不能被当作真实业务结果，基于 Mock 通过的页面验收也不能替代正式数据联调和异常测试。
建议按什么顺序填写
- 按来源系统和业务对象建立接口、表、文件或消息清单。
- 确定业务负责人、技术负责人、访问方式和预计就绪日期。
- 补齐主键、时间、字段、单位、状态码、刷新与历史范围。
- 准备授权样例和异常样例，确认测试环境与网络白名单。
- 记录当前阻塞、Mock 方案、正式替换条件和联调结论。
- 用正式或约定数据核对数量、口径、异常和页面结果。
哪些准备项必须可验证
| 准备组 | 核对重点 | 完成标准 |
|---|---|---|
| 责任与访问 | 业务和技术负责人、环境、协议、鉴权、账号和网络 | 测试账号能在约定环境完成一次有效请求 |
| 字段与语义 | 主键、时间、类型、单位、状态码、空值和重复规则 | 字段说明与样例一致，关键口径有确认人 |
| 更新与历史 | 刷新频率、增量方式、分页、补传、修订和历史数据量 | 能够解释数据何时更新以及如何追溯 |
| 样例与异常 | 正常、空值、异常、边界和脱敏数据 | 页面关键状态均有可测试输入 |
| 阻塞与替代 | 预计就绪日期、当前阻塞、Mock 版本和替换条件 | 临时方案不被误认为正式数据验收 |
如何判断可以进入正式联调
关键接口应具备责任人、可访问环境、鉴权方式、字段说明、代表性样例和明确的错误处理；页面依赖的主键、时间和口径没有悬空；网络、测试账号和白名单已经验证；尚未就绪的项目有关闭条件和计划时间。非关键接口可以分批进入，但必须明确对页面和验收的影响。
参考依据与适用边界
数据完整性、准确性、一致性和时效性等质量考虑，可参考国家标准全文公开系统中的 GB/T 25000.12-2017《数据质量模型》；系统与软件质量需求可参考 GB/T 25000.10-2016。具体接口协议、数据授权、安全要求和验收方式仍以实际系统、合同与适用制度为准。
常见问题
接口地址还没有，能先填写吗？
可以。先填写来源系统、业务对象、负责人、字段样例、预计日期和当前阻塞，等环境开放后再补地址、鉴权和联调结果。
只有 Excel 导出数据算接口吗？
它可以作为阶段性数据交换方式，但应记录导出责任、字段版本、更新频率、文件命名、重复导入和错误处理边界。
样例数据需要使用真实生产数据吗？
不一定。应优先使用经过授权、脱敏且能覆盖关键状态的样例，不应为了联调暴露非必要个人信息、密钥或生产数据。
Mock 页面通过是否可以直接验收？
通常不能。Mock 可以验证结构和交互，正式验收仍需按约定完成真实接口、口径、异常状态和刷新机制验证。
下载与相关资料
继续阅读 接口没准备好时，数据大屏项目怎么启动，并配合 数据可视化大屏需求调研表 和 BI指标口径评审清单使用。网站内容责任与审核边界见 公司与网站信息。