新系统上线三个月，业务处的人开始抱怨：报表里的车辆数跟老系统差了一百多台，两边都说自己对。

查下去才发现，接口是通的，数据每天也在传，问题出在映射上——老系统里「停用」这个状态，新系统没有对应字段，全部落成了「未知」。一百多台车的差额，就这么积了三个月。

系统对接接口这件事，「通」和「对」是两个层次。项目验收通常只验前者：调一次，返回成功，就算过了。后者要一套指标才说得清。

为什么对接总在验收后出事

对接工作的性质决定了它容易被低估。写接口是几天的事，定字段是几周的事，跑一致性是几个月的事。

实施方按合同交付，合同里写的是「完成与某某系统的数据对接」。这句话能验收的最低标准是：数据能过来。至于过来之后对不对、错了能不能发现、改了字段谁通知谁，合同里往往没有。

于是验收单上签了字，问题留给了运维。运维又把它归到「数据问题」，数据问题再归到「业务口径不一致」，到头来谁都不认。

要跳出这个循环，只有一条路：把对接质量拆成可测的指标，在验收阶段就摆到桌面上。

第一组：接口本身好不好用

这一组看的是接口的运行状态，偏技术，最容易测，也最容易被当成全部。

可用率这一项，要注意统计口径。是按自然日算，还是按工作时间算？夜间批量任务失败算不算？口径不同，同一个接口能差出一个百分点。

响应时长要区分单条与批量。一条查询接口 500 毫秒是合格的，一个一万条的批量同步接口，500 毫秒根本不可能，得按「每秒处理条数」来约定。

异常返回可读性听起来虚，实际最影响运维。返回一个「-1」和返回一个「车辆标识格式不符，第 3 位应为字母」，处理时间差十倍。这一项在验收时抽二十条看，五分钟能看完。

第二组：数据过来之后对不对

这一组是真正的分水岭。技术指标全绿，数据仍然可能是错的。

字段映射完整率必须做到 100%，做不到的字段要单独列表。前面那一百多台车的差额，就是这一个字段没做对应，事后补起来要翻三个月的流水。

主数据一致率测的是「同一个对象两边描述是否一致」。车辆的主键、名称、状态、归属，任一项不一致都算差异。抽一万条比一次，能看出映射规则是不是真的对上了。

每日对账差异条数是最有用的一个指标，也是最容易被跳过的。做法很简单：每天固定时点，两边各出一份汇总，按维度比对，差异写成清单。清单要能追到具体记录，不能只有一个总数。

差异数不该追求零。真实系统里，时序差异、在途数据、删除标记都会造成少量差异，关键是两点：数量稳定，且每一条都能解释。差异突然从 3 条变成 300 条，说明某一环坏了。

第三组：改的时候会不会出事

前两组测的是「现在好不好」，第三组测的是「以后会不会坏」。这一组几乎没人验，出的事却最多。

变更通知是最容易失守的一环。上游系统加了一个状态值，没通知下游，下游按旧规则解析，把新状态全落成「未知」。这种事在政企项目里一年能遇上两三次，每次都靠人发现。

问题定位时长考验的是日志。接口出错时，能不能在半小时内判断是发送方、传输、还是接收方的问题，取决于三处日志是否都留了同一个流水号。没有流水号，两边各自查各自的，一天也定位不了。

回归验证覆盖率听着像测试团队的事，实际要写进合同。上游改一个字段，下游的解析、入库、报表、导出四条链路都要跑一遍，少跑一条，问题就留到生产上。

这一组的三项，责任划分比数值更重要。变更通知的责任在上游，回归验证的责任在下游，问题定位的责任在双方。三方各管一段，中间任何一段松了，另外两段都白做。

监管方在这件事上的位置很特殊：既不是上游也不是下游，但两条系统都归它管。它能用的手段不是技术，是通报——把变更通知及时率写进月度通报，比在协调会上强调十次有用。数据出问题时，第一个被问的也是它。

第一次对账怎么跑

九项指标里，对账是最需要动手的一项。第一次跑，往往最难，因为两边的数据从未逐条比对过。

比较稳的顺序是这样：先小范围试。取一个区、一个分公司、或者一个月的记录，按主键匹配，把结果分成三类——两边都有且一致、两边都有但不一致、只有一边有。三类各自计数，逐类抽样看原因。

第一类不用管，看比例。第二类逐字段看，通常集中在状态、归属、时间三类字段上。第三类最费劲，因为它意味着一条记录在某一边根本不存在，可能是在途，可能是删除标记，也可能是采集漏了。

跑完一轮，出一份差异说明。说明里不要只写数字，要写原因分类和各自占比。这份说明拿去和业务方对，往往能在一小时内敲定口径，比开三次会有效。

之后把对账做成日任务。每天固定时点跑，差异清单自动生成，超过阈值自动提醒。做到这一步，系统对接才算进入可持续的状态。

合格线怎么定才不吵架

九项指标列出来，接下来是最难的一步：定合格线。

三条经验。

一是基准取自现状，不取自理想。 先把现有系统跑一个月，把九项指标的实际值测出来，作为基线。新系统的目标定在基线之上，而不是定在一个漂亮的整数上。基线 96% 的系统，要求新系统 99.9%，等于逼着双方在验收时扯皮。

二是分级约定。 核心接口（车辆、人员、资金这类）用严线，辅助接口（统计、字典这类）用宽线。全部按严线要求，成本会失控；全部按宽线，关键数据没人管。

三是留整改窗。 首次验收不达标，给 30 天整改期，整改后复验。复验仍不达标的，按缺陷等级扣款。这一条比「必须达标」四个字有用，因为它给了双方一个明确的动作。

写进合同的几句话

行业软件项目里，对接条款通常只有一句「完成数据对接」。建议改成下面这样，不用很长。

一、明确字段清单作为附件，含字段名、类型、是否必填、无对应时的处理方式。

二、明确九项指标中的核心项与辅助项，各自的目标值与统计口径。

三、明确对账机制：谁出清单、什么时点出、差异清单包含哪些字段、多久内必须解释完。

四、明确变更流程：谁通知、提前几天、通知不到造成的问题由谁承担。

五、明确日志要求：三处日志共用流水号，保留期限不少于一年。

这五句加上去，合同厚了两页，验收时省两个月。

换成自研系统时更要注意

有些单位不用采购成品，改用定制开发。这时候对接指标不但不能省，反而要更细，因为开发方没有现成经验，全靠在需求里写清楚。

定制开发项目里，常见三个坑。一是接口文档事后补，代码写完再倒推文档，字段含义解释不清。二是接口版本没规划，改一次加一堆参数，旧调用方陆续失效。三是没有台账，哪个系统调了哪个接口、谁在用，没人说得清。

第三个坑最要命。出问题时找不到调用方，只能逐个问。做法是建一份接口台账：接口名、版本、提供方、调用方、责任岗位、变更记录，和运维迭代记录放在一起。这份台账在系统上线三年后价值最高，那时候原班人马大多已经调岗。

烟台众海智能科技有限公司做行业软件时，把这类台账作为交付物的一部分，和移动端、小程序这些入口一起写进实施清单。管理软件的价值不只在功能多少，也在这些看着琐碎的记录能不能留下来。

一个容易被忽略的前提

所有指标都建立在一个前提上：字段字典是共同的。

两家系统对「车辆状态」的理解不一样，接口写得再规范，数据也是错的。做法是先出一份共同的字段字典，把每个字段的取值、含义、边界写清，双方签字。这份东西通常在需求分析阶段就该有，实际项目里十有八九被跳过。

跳过它的代价会在半年后出现，而且以「数据不准」的面目出现，让人以为是对接没做好，实际是口径没对齐。

字段字典不用写得像国标，一页纸足够：字段名、含义、取值范围、为空时的含义、谁负责维护。双方各留一份，改动时同步更新。这份纸的成本大约是一天，省下的争议往往以月计。

做行业软件的人都清楚，数据孤岛不是靠接口打通的，是靠字段对齐打通的。接口只是管道，管道里流的东西得先定义清楚。这句话说出来简单，落到项目里，往往就是那最容易被压缩掉的一周。