把一套系统的数据传到另一套系统,关键不只是请求能否成功返回。同样叫“数量”“状态”或“金额”的字段,在不同系统里可能代表不同的业务含义。字段映射表应记录这些约定,而不只是两列字段名称。
先确定同一条业务记录如何识别
订单号是否跨门店唯一?退货单和原订单是什么关系?测试数据与正式数据是否可能使用相同编号?这些问题会影响主键与去重规则。可把来源系统、业务类型和业务编号组合为识别依据,并约定编号产生和修改的责任方。
如果使用数据库唯一约束阻止重复记录,需检查约束覆盖的列以及空值行为。数据库约束可以帮助限制重复,但完整业务处理还需要事务和明确的状态规则。参考:PostgreSQL 约束说明
写清类型、单位与空值
金额以元还是分传输,是否含税;时间使用哪个时区,是否允许只传日期;数量是否允许小数,单位是件还是箱,都应写进映射表。
还要区分没有传字段、空字符串、零和空值各自的含义。例如,更新接口中“未传联系电话”可能代表保持原值,而传空值可能代表清除原值。双方约定不一致,就可能在同步时误删原有数据。
状态与异常也属于接口契约
双方状态通常不能逐字对应。可以逐项写出允许的状态转换,以及取消、退回、部分完成等特殊情况。遇到未知状态时,应进入可见的异常流程,避免默默转换成默认值。
同步失败后,哪些错误可以重试、重试使用什么业务标识、谁负责处理最终失败记录,也应在联调前约定。接口返回成功后,仍可通过定期对账发现漏单与差异。
用样例验证约定
字段表至少配上正常数据、边界数据和错误数据。联调不仅验证一条成功记录,还应覆盖重复推送、缺失字段、无权限、业务已取消等情况。只有双方对这些输入给出一致的处理结果,字段映射才真正成为可执行的约定。