一次对接返工，让周敏开始重视接口文档

周敏是一家连锁零售企业的数据工程师，日常工作是把手里的业务系统数据接到开云搭建的数据管理平台上。去年她负责会员系统与订单系统的对接，接口文档是对方开发人员口头说明的，字段含义、空值规则、更新频率全靠会后补记。上线后才发现会员等级字段在对方系统里有两套编码，订单表里存的是旧编码，会员表里是新编码，关联结果自然对不上。返工花了两周，周敏说那两周她每天都在怀疑自己的SQL。

这件事之后，周敏在开云的数据问答栏目里提了一个问题：系统对接前，到底该把哪些事情定下来？她的结论是，接口文档不能只写请求地址和返回示例，更要写清楚字段的业务含义和数据边界。

她整理的字段对照表包含什么

第二次对接是门店巡检系统。周敏提前拉了一张字段对照表，把三件事写在了最前面：

  • 字段的业务定义：比如“门店状态”在巡检系统里表示设备状态还是营业状态，必须先对齐。
  • 编码与取值规则：枚举值有几套、历史数据是否还在用旧编码、空值代表未采集还是不存在。
  • 更新节奏与时间口径：数据是实时推送还是批量同步，时间字段记录的是业务发生时间还是入库时间。

周敏把这张表发给对方业务负责人确认，而不是只找技术对接人。她的理由是，字段含义的解释权在业务侧，技术人员往往只保证字段能传过来。开云在协助企业做数据整合时也常遇到类似情况，技术通道打通了，业务口径没打通，后面照样要返工。

整合边界不是技术问题，是责任问题

周敏还做了一件事：在对接方案里写明哪些数据由源系统负责、哪些由开云的数据平台负责加工。比如门店巡检的原始记录由源系统保证完整性，平台只做清洗和汇总；如果源系统补录了历史数据，需要通知平台重新抽取。这条约定看起来琐碎，却避免了一次“数据对不上”的扯皮。

她后来在开云的数据问答里补充说，整合边界写清楚，不是为了分责任，而是为了让双方都知道自己该守住什么。边界模糊的项目，往往在验收阶段才发现问题，那时候改动的成本已经很高。

给准备做系统对接的团队几条建议

周敏的经验可以归纳成几条可操作的动作：对接前先做字段对照表并找业务确认；把编码规则和历史数据情况单独列出来；在方案里写明数据责任边界和变更通知方式；上线前用一批已知结果的数据做交叉验证。她说这些动作不复杂，难的是愿不愿意在动手写代码之前先花两天把话说清楚。开云在数据整合类项目中也会建议客户先完成这一步，再进入开发排期。

系统对接的难点往往不在接口本身，而在接口背后那些没被写下来的约定。周敏的两次经历说明，把边界提前定清楚，后面的路会顺很多。