大型后台管理系统如何把业务操作做可靠（11）：脚手架、接口契约与前后端联调
新同事用脚手架创建订单模块，第一天页面就能跑起来。第二天联调发现 Mock 把退款失败写成 200 加空对象，真实接口返回结构化错误。页面模板虽然生成得快，错误分支和权限上下文仍然需要重新写。
把项目默认行为做成共享入口
脚手架可以生成路由入口、业务目录、最小测试和一条能够跑通的示例查询。登录、租户上下文、请求错误分类和埋点通过共享包接入。后续修复共享包即可覆盖旧模块。只有项目初次需要且每次独立维护的内容适合复制，例如路由元信息和模块自己的映射代码。
示例模块可以从 route → query → mapper → view 走一遍。查询层传入租户和筛选条件，映射层把接口结构变成页面语义，页面明确渲染加载、空结果、拒绝和系统错误。仓库依赖检查阻止业务直接导入其他模块的私有文件。新项目和已有项目都应能运行同一个基础检查命令。
把联调分成协议、行为和环境
设计接口时先确认输入、输出和失败语义。以订单查询为例，指定分页游标是否透明、筛选条件如何序列化、字段可否缺省、空值表示什么。保存时再明确冲突、权限不足、结果未知的区别。Mock 使用相同契约，并为各失败路径提供稳定样例。真实服务验证这些返回形态和约束。
消费者期望
给定 订单 O42 处于已发货
当 POST 修改地址请求
则 返回约定的业务冲突与稳定错误码
提供方验证
用测试数据准备同样的订单状态
对实际处理入口发请求
检查状态码、错误码和消费者依赖的字段协议描述可以生成类型和基础样例，运行时仍需处理未知枚举和真实返回。消费者契约测试可以验证调用方依赖的消息结构。端到端联调继续覆盖登录、跨域、部署路径、测试租户、权限与实际状态变化。用明确的非生产账号和可重置数据，减少不同人抢占同一笔订单。Pact 契约测试文档
从新模块创建到第一次联调
以商品列表为例，生成器只创建业务模块目录、路由声明和一个可执行的查询样例。登录会话、权限上下文和错误格式由基础包提供。初始化后先用固定的假数据检查筛选、分页和错误反馈，再切换到可重置的测试租户。这一步能尽早发现模板没接入真实请求路径，或者测试环境缺少某个权限。
可以把项目约定整理成两张清单。一张说明生成的文件由业务维护，例如列表筛选和领域映射。另一张记录共享包提供的能力、最低兼容版本和升级方式。脚手架改进默认规则时，要能回答旧项目从哪里获得修复。对一次性生成的代码则提供迁移说明，避免只改善后来的项目。
契约要把失败的不同含义写进去
假设商品批量预览接受筛选条件，返回计划 ID 和可执行数量。客户端只依赖这两个字段和过期时间。测试样例应覆盖结果为空、权限不足和规则冲突。返回成功且可执行数量为零，与响应失败是两种业务状态，Mock 应能分别触发。
| 场景 | 示例结果 | 客户端行为 |
|---|---|---|
| 没有符合条件的商品 | 成功，数量为零 | 展示空结果，允许修改筛选 |
| 权限不足 | 访问拒绝和稳定错误码 | 展示受限提示 |
| 计划已过期 | 业务冲突和过期错误码 | 提供重新预览 |
| 等不到确认响应 | 结果未知 | 按原操作标识查询 |
协议测试固定消费者实际依赖的字段，提供方通过真实入口验证。对于动态值，应检查类型和必要约束，少把不相关的值写死。用环境联调验证网关、认证、部署前缀及真实权限组合。两个层次失败时由不同负责人排查。协议通过但真实请求进不了业务服务，优先检查部署链路，避免无意义地修改页面映射。
真实联调还需要数据复位。给失败用例准备独立订单或租户，测试结束按预定方式清理或重新生成。多人共享一个会变化的订单，很难区分契约错误和其他人已经修改了状态。
把差异变成下次能发现的检查
联调发现差异后，先确定哪一方违反了已确认的契约，或产品是否改变了业务语义。然后更新契约、提供方测试和对应 Mock，一起复跑。日志可用请求关联 ID 对照客户端和服务端，敏感报文按最小字段保留。新版本接口发布时，用已有客户端的契约验证兼容。
用一笔失败请求练习定位
假设测试环境的「修改地址」返回失败。先确认请求到达了哪个域名和服务版本，带的是哪个测试账号与租户，再核对请求路径、方法和正文。若网关返回通用访问拒绝，业务服务没有收到请求，先查环境配置和认证。若业务服务明确返回订单已发货，则比较页面是否正确识别业务错误码。两种问题的页面反馈和负责人都不同。
可为联调记录保留一份最小样本，包括版本、输入、可公开的响应形态、关联 ID 和数据准备条件。一次偶发差异能稳定复现时，把它留在契约或集成测试里。比如旧客户端把 eligibleCount 缺失当作零，新服务在某个分支恰好漏返字段，提供方测试就应验证该分支必须返回计数。
接口变更后可以按三步交付。先让新提供方通过旧消费者契约，再验证新客户端可识别新字段，最后验证部署环境的账号和真实数据。当同一个接口要服务桌面与移动端时，为两者分别保留实际依赖的字段与失败语义。这样删除一个桌面没用到的字段时，仍能发现移动端还有调用。
总结
脚手架提供一条有维护入口的默认路径，联调用协议和真实环境分别验证。一个团队能持续复用的，是这些规则的升级渠道和失败样例。